phase 5.1 + 5.2 + 5.3: quickstart CLI + entity install/up/paths + Anthropic adapter

5.1 — `python -m zhub up`:
  one-shot bring-up. picks a free port, optionally starts a Cloudflare
  tunnel, auto-detects an available brain, publishes, prints URL +
  KEY in copy-pasteable format. Ctrl-C tears the lot down cleanly.
  also `python -m zhub doctor` — environment + creds + cloudflared
  check using the shipped entity recipes. new dispatcher at
  zhub/__main__.py with subcommands: up, server, doctor.

5.2 — entity expansion:
  added ## install, ## up, ## paths sections to zhub/entity.md so an
  AI installing zhub fetches it once and knows the whole flow,
  default disk locations, env-var conventions. note that the file
  ships in the package — `zhub/entity.md` — so it can be read before
  any hub is running.

5.3 — AnthropicAdapter:
  5th brain in zhub/brains/. Anthropic Messages API streaming has its
  own SSE shape (event/data pairs, content_block_delta with text_delta);
  adapter normalizes to the same ChatChunk surface as the other four.
  registered in REGISTRY after Cerebras. detection via ANTHROPIC_API_KEY
  env. tests mock httpx; no real network in CI.

127/127 pytest now.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Zawwarsami16

CLAUDE.md

@@ -87,8 +87,12 @@ Tests: `pytest -v`. The e2e tests spin up the hub in-process and run the full pu
 - **Phase 4.0** ✅ — `zhub/brains/` package: `BrainAdapter` ABC + four streaming adapters (Ollama, Groq, OpenAI, Cerebras). `detect()` walks them in priority order. `examples/multi_brain_publisher.py` exposes `--brain auto|ollama|groq|openai|cerebras` so the brain underneath any zhub publisher is one CLI flag away from a swap. External clients (Pocket/Loki/curl/MCP) see no change; key stays stable across brain swaps via persistence.
 - **Phase 4.1** ✅ — Entity v2: operator-extensible. `POST/GET /entity/extend` and `DELETE /entity/extend/{id}` (auth: any registered publisher's bearer key). Extensions persist in SQLite (`entity_extensions` table), surface inline in `/entity/<section>` and at the title-matched code under `/entity/errors/<code>`, and live alongside shipped recipes (shipped wins on canonical conflicts). Caps: 8KB per body, 200 per hub. Each hub now grows its own institutional memory.
 - **Phase 4.2** ✅ — Pre-resolve streaming mode for tool calls. Header `X-Zhub-Stream-Tools: pre-resolve` + `stream:true` runs the full non-streaming auto-resolve loop internally, then emits the resolved final text as one SSE chunk + done. Trades stream-latency for tool-call correctness in streaming mode. The non-streaming auto-resolve loop is now a shared helper (`_run_autoresolve_loop`) used by both code paths. True per-token tool_call delta passthrough = future Phase 4.2b (needs brain-adapter + publisher-SDK changes to surface tool_call deltas).
+- **Phase 5.0** ✅ — Cleanup: removed ZAI/Loki coupling. zhub stays neutral substrate. Specifically: deleted `examples/zai_publish.py` + `examples/ZAI_PUBLISH.md`, deleted `kotlin/src/main/kotlin/com/zawwar/zhub/loki/` and `kotlin/LOKI_INTEGRATION.md`, scrubbed named-user references in README + mcp_server docstring + `__init__.py` + `connect_demo.py` + `orchestrate_demo.py`. Anyone embedding zhub uses the generic primitives; bridges to specific products live in those products' own repos.
+- **Phase 5.1** ✅ — `python -m zhub up` one-shot quickstart: spawns hub on a free port, optionally Cloudflare tunnel, auto-detects brain, publishes, prints URL+KEY. `python -m zhub doctor` checks Python version, deps, optional cloudflared, brain credentials in env. New `zhub/__main__.py` dispatcher (subcommands: `up`, `server`, `doctor`). The "anyone can easily do it" gate.
+- **Phase 5.2** ✅ — Entity expansion: added `## install`, `## up`, `## paths` sections to `entity.md`. Header notes the file ships with the package so an AI installing zhub can read it locally before any hub is running.
+- **Phase 5.3** ✅ — `AnthropicAdapter` brain (5th adapter). Anthropic Messages API has its own SSE shape (`event:`/`data:` pairs, `content_block_delta` with `text_delta`); adapter normalizes to `ChatChunk` like the others. Registered in REGISTRY after Cerebras.
 
-**Next (not started):** real ZAI integration via `zai_publish.py`, multi-tier API keys, full tool_call streaming (4.2b), MCP resources/prompts surface.
+**Next (not started):** true tool_call delta streaming through SSE (4.2b), multi-tier API keys, capability-only WS connections (a "tool provider" usable by any AI on the hub, not tied to one publisher), MCP resources/prompts surface.
 
 ## 6. File layout (what's where)
 

tests/test_brains_anthropic.py

@@ -0,0 +1,104 @@
+"""Tests for the Anthropic brain adapter."""
+
+from typing import Iterable
+
+import httpx
+import pytest
+
+from zhub.brains.base import ChatChunk
+from zhub.brains.anthropic import AnthropicAdapter
+
+
+class _FakeStream:
+    def __init__(self, lines: Iterable[str]):
+        self._lines = list(lines)
+
+    async def aiter_lines(self):
+        for line in self._lines:
+            yield line
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        return None
+
+
+class _FakeAsyncClient:
+    def __init__(self, lines: Iterable[str]):
+        self._lines = list(lines)
+        self.last_call: dict | None = None
+
+    def stream(self, method, url, **kw):
+        self.last_call = {"method": method, "url": url, **kw}
+        return _FakeStream(self._lines)
+
+    async def aclose(self):
+        pass
+
+
+def test_try_init_none_without_key(monkeypatch):
+    monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+    assert AnthropicAdapter.try_init() is None
+
+
+def test_try_init_returns_adapter_when_probe_succeeds(monkeypatch):
+    class R:
+        status_code = 200
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-xyz")
+    monkeypatch.setattr(httpx, "get",
+                        lambda url, headers=None, timeout=None: R())
+    adapter = AnthropicAdapter.try_init()
+    assert adapter is not None
+    assert adapter.name == "anthropic"
+    assert adapter.api_key == "sk-ant-xyz"
+
+
+@pytest.mark.asyncio
+async def test_stream_parses_anthropic_sse():
+    """Anthropic Messages API streams `event:` + `data:` SSE pairs.
+    The relevant event types are `content_block_delta` (text deltas)
+    and `message_stop` (terminal)."""
+    lines = [
+        'event: message_start',
+        'data: {"type":"message_start","message":{"id":"msg_x"}}',
+        '',
+        'event: content_block_delta',
+        'data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hi "}}',
+        '',
+        'event: content_block_delta',
+        'data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"there"}}',
+        '',
+        'event: message_delta',
+        'data: {"type":"message_delta","delta":{"stop_reason":"end_turn"}}',
+        '',
+        'event: message_stop',
+        'data: {"type":"message_stop"}',
+        '',
+    ]
+    fake = _FakeAsyncClient(lines)
+    adapter = AnthropicAdapter(api_key="sk-ant-xyz",
+                               model="claude-sonnet-4-5",
+                               http=fake)
+    out = [c async for c in adapter.stream(
+        [{"role": "user", "content": "hi"}], system="be brief"
+    )]
+    deltas = [c.delta for c in out if c.delta]
+    assert "".join(deltas) == "Hi there"
+    assert out[-1].done is True
+    assert out[-1].finish_reason == "end_turn"
+
+    body = fake.last_call["json"]
+    headers = fake.last_call["headers"]
+    assert body["model"] == "claude-sonnet-4-5"
+    assert body["stream"] is True
+    assert body["system"] == "be brief"
+    assert body["messages"][-1] == {"role": "user", "content": "hi"}
+    assert headers["x-api-key"] == "sk-ant-xyz"
+    assert headers["anthropic-version"]
+
+
+def test_anthropic_in_default_registry():
+    from zhub.brains import REGISTRY
+    names = [c.name for c in REGISTRY]
+    assert "anthropic" in names

tests/test_brains_registry.py

@@ -37,7 +37,7 @@ def test_registry_holds_classes_in_priority_order():
     The four shipped adapters land in this order: Ollama, Groq, OpenAI,
     Cerebras."""
     names = [cls.name for cls in REGISTRY]
-    assert names == ["ollama", "groq", "openai", "cerebras"]
+    assert names == ["ollama", "groq", "openai", "cerebras", "anthropic"]
 
 
 def test_detect_returns_first_available(monkeypatch):

tests/test_cli_up.py

@@ -0,0 +1,116 @@
+"""Test the `python -m zhub up` quickstart command.
+
+The `up` command's job: in one shot, bring up a hub + (optionally) a
+brain publisher, and print URL + key + ready-to-paste BYOK config so
+any user (or AI installing zhub) can be reachable in one terminal.
+
+For tests: invoke as a subprocess with --no-tunnel and a fake brain
+registered via env-var injected into a shim, on a free port. Verify
+stdout contains URL, key, and a BYOK summary.
+"""
+
+import asyncio
+import os
+import socket
+import subprocess
+import sys
+import textwrap
+import time
+
+import pytest
+
+try:
+    import fastapi  # noqa
+    import uvicorn  # noqa
+    import httpx  # noqa
+    DEPS_AVAILABLE = True
+except ImportError:
+    DEPS_AVAILABLE = False
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("", 0))
+        return s.getsockname()[1]
+
+
+@pytest.mark.asyncio
+async def test_up_command_with_fake_brain_prints_url_and_key(tmp_path):
+    """`python -m zhub up --port <free> --no-tunnel --name testpub --brain fake`
+    should boot a hub, publish, and emit URL/key on stdout."""
+    if not DEPS_AVAILABLE:
+        pytest.skip("fastapi/uvicorn/httpx not installed")
+    port = _free_port()
+    repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+    shim = tmp_path / "fake_brain_shim.py"
+    shim.write_text(textwrap.dedent(f"""
+        import sys
+        sys.path.insert(0, {repo_root!r})
+        from zhub.brains.base import BrainAdapter, ChatChunk
+        import zhub.brains as _brains
+
+        class FakeBrain(BrainAdapter):
+            name = "fake"
+            label = "fake test brain"
+
+            @classmethod
+            def try_init(cls):
+                return cls()
+
+            async def stream(self, messages, *, system=None, temperature=0.7,
+                             max_tokens=2048, tools=None):
+                yield ChatChunk(delta="ok", done=True, finish_reason="stop")
+
+        _brains.REGISTRY = [FakeBrain]
+
+        import runpy, sys as _sys
+        _sys.argv = ["zhub", "up", "--port", "{port}",
+                     "--no-tunnel", "--name", "testpub",
+                     "--brain", "fake",
+                     "--db", {str(tmp_path / "up.db")!r}]
+        runpy.run_module("zhub", run_name="__main__")
+    """))
+
+    env = dict(os.environ)
+    env["PYTHONUNBUFFERED"] = "1"
+
+    proc = await asyncio.create_subprocess_exec(
+        sys.executable, str(shim),
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env=env,
+    )
+
+    stdout_buf: list[str] = []
+    api_key = None
+    deadline = time.time() + 12.0
+    try:
+        while time.time() < deadline:
+            line = await asyncio.wait_for(proc.stdout.readline(), timeout=4.0)
+            if not line:
+                break
+            text = line.decode().rstrip()
+            stdout_buf.append(text)
+            if text.startswith("KEY:"):
+                api_key = text.removeprefix("KEY:").strip()
+            if api_key and any(s.startswith("URL:") for s in stdout_buf):
+                break
+
+        full = "\n".join(stdout_buf)
+        assert any(s.startswith("URL:") for s in stdout_buf), \
+            f"no URL line printed; stdout={full!r}"
+        assert api_key and api_key.startswith("zk_"), \
+            f"no key extracted; stdout={full!r}"
+
+        # And the hub really should be reachable on that port now
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            r = await client.get(f"http://127.0.0.1:{port}/healthz")
+        assert r.status_code == 200
+    finally:
+        proc.terminate()
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=3.0)
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()

zhub/__main__.py

@@ -0,0 +1,54 @@
+"""`python -m zhub` — top-level CLI dispatcher.
+
+Subcommands:
+    up        one-shot: hub + (optional) tunnel + brain publisher; prints URL/key
+    server    same as `python -m zhub.server` (for backwards compat)
+    doctor    inspect the current install + entity recipes for common issues
+
+Default `python -m zhub` (no args) prints the usage line.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+_USAGE = """\
+usage: python -m zhub <command> [options]
+
+commands:
+  up         start hub + tunnel + brain publisher in one go (recommended)
+  server     start just the hub server (legacy entry point)
+  doctor     diagnose the install using shipped entity recipes
+
+run `python -m zhub <command> --help` for command-specific options.
+"""
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = list(argv if argv is not None else sys.argv[1:])
+    if not args or args[0] in ("-h", "--help"):
+        print(_USAGE)
+        return
+    cmd, rest = args[0], args[1:]
+    if cmd == "server":
+        # Defer to the existing server entry point with the rest of argv.
+        sys.argv = ["zhub.server"] + rest
+        from zhub.server import main as server_main
+        server_main()
+        return
+    if cmd == "up":
+        from zhub.cli_up import run as up_run
+        up_run(rest)
+        return
+    if cmd == "doctor":
+        from zhub.cli_doctor import run as doctor_run
+        doctor_run(rest)
+        return
+    print(f"unknown command: {cmd!r}\n", file=sys.stderr)
+    print(_USAGE, file=sys.stderr)
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

zhub/brains/__init__.py

@@ -20,13 +20,15 @@
 from .groq import GroqAdapter
 from .openai import OpenAIAdapter
 from .cerebras import CerebrasAdapter
+from .anthropic import AnthropicAdapter
 
 
 REGISTRY: list[type[BrainAdapter]] = [
     OllamaAdapter,
     GroqAdapter,
     OpenAIAdapter,
     CerebrasAdapter,
+    AnthropicAdapter,
 ]
 
 
@@ -55,5 +57,6 @@ def list_available() -> list[BrainAdapter]:
 __all__ = [
     "BrainAdapter", "ChatChunk", "REGISTRY",
     "detect", "list_available",
-    "OllamaAdapter", "GroqAdapter", "OpenAIAdapter", "CerebrasAdapter",
+    "OllamaAdapter", "GroqAdapter", "OpenAIAdapter",
+    "CerebrasAdapter", "AnthropicAdapter",
 ]