brainpick 0.4.2__tar.gz → 0.4.4__tar.gz

{brainpick-0.4.2 → brainpick-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainpick
-Version: 0.4.2
+Version: 0.4.4
 Summary: A turn-key brain stack for agents: compile an OKF markdown bundle into a queryable, servable, visualizable brain.
 Author: Benquemax
 License: MIT

{brainpick-0.4.2 → brainpick-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "brainpick"
-version = "0.4.2"
+version = "0.4.4"
 description = "A turn-key brain stack for agents: compile an OKF markdown bundle into a queryable, servable, visualizable brain."
 readme = "README.md"
 requires-python = ">=3.10"

{brainpick-0.4.2 → brainpick-0.4.4}/src/brainpick/__init__.py

@@ -1,4 +1,4 @@
 """brainpick — a turn-key brain stack for agents."""
 
-__version__ = "0.4.2"
+__version__ = "0.4.4"
 SPEC_VERSION = "0.1"

{brainpick-0.4.2 → brainpick-0.4.4}/src/brainpick/_skill/SKILL.md

@@ -17,7 +17,7 @@ the brain comes up short.
 
 Start every session with one call to get oriented, then search.
 
-## The five MCP tools
+## The six MCP tools
 
 Call these if a `brainpick` MCP server is connected (tools are named `brain_*`):
 
@@ -26,6 +26,7 @@ Call these if a `brainpick` MCP server is connected (tools are named `brain_*`):
 - `brain_read({doc})` — open one doc. `doc` is forgiving: a path (`kuu.md`), a bare stem (`kuu`), or an approximate title. Pass `sections:["Heading"]` to read just parts.
 - `brain_neighbors({doc})` — walk the links around a doc (`depth` 1–3). Find what connects to what.
 - `brain_write({doc, content})` — add a doc, guarded by the repo's contract. See "Writing" below.
+- `brain_show({nodes})` — spotlight a subgraph live in an open brainpick UI: highlight nodes, fly the camera, caption it. "Let me explain" becomes "let me show you." See "Showing the brain" below — **it needs a running `brainpick serve`, unlike the other five.**
 
 Every result carries a `hint` naming a sensible next call. Follow it.
 
@@ -62,6 +63,26 @@ federated:
 - `brain_write` with a bare target writes to the project you are in; qualify it to
   write elsewhere. It never guesses.
 
+## Showing the brain (brain_show)
+
+Use `brain_show` when explaining beats showing — "let me show you" instead of a
+wall of text. It highlights nodes, flies the camera, and drops a caption into
+every **connected** brainpick UI. It never writes the brain.
+
+**It needs a running `brainpick serve`.** The other five tools work over a plain
+stdio MCP connection (`claude mcp add brainpick -- brainpick mcp --root <bundle>`,
+the common setup) because they only read compiled artifacts. `brain_show`
+broadcasts to a live browser — and a stdio-connected MCP server has none attached;
+it builds its own private, unshared state. Call it over stdio today and you get
+back `{"ok": true, "shown": N}` while nothing appears anywhere — a false positive,
+not a "no UI open" signal.
+
+To actually see it: start `brainpick serve --root <bundle>` first (a browser tab
+open to it, or `POST /api/show` with the same body, both work), or connect your
+MCP client over HTTP to that server's `/mcp` endpoint instead of stdio. If you
+called `brain_show` and the human says they saw nothing, don't trust the `"ok"`
+— ask what's actually running before repeating the call.
+
 ## Writing knowledge back (brain_write)
 
 Only write when asked to record knowledge. Follow the wiki's conventions or the

{brainpick-0.4.2 → brainpick-0.4.4}/src/brainpick/cli.py

@@ -229,10 +229,24 @@ def _cmd_integrate(args: argparse.Namespace) -> int:
     return run_integrate(args.target, Path(args.root), dry_run=args.dry_run)
 
 
-def post_show(base_url: str, body: dict, token: str | None = None) -> tuple[dict | None, str | None]:
+def connectable_host(host: str) -> str:
+    """A server may bind 0.0.0.0/:: (everywhere); a client must connect via a
+    real address — shared by the CLI's `show` and brain_show's server-proxy
+    attempt (mcp_server.py) so both resolve a running `brainpick serve` the
+    same way."""
+    return "127.0.0.1" if host in ("0.0.0.0", "::") else host
+
+
+def post_show(base_url: str, body: dict,
+              token: str | None = None) -> tuple[dict | None, str | None, bool]:
     """POST a presentation body to a running server's /api/show (spec/95). Returns
-    (response, None) or (None, instruction) — the CLI is a client here, never
-    resolving locally: the live server resolves and broadcasts to open UIs."""
+    (response, None, False) on success, or (None, instruction, unreachable) — the
+    caller is a client here, never resolving locally: the live server resolves and
+    broadcasts to open UIs. `unreachable` is True only when nothing answered at all
+    (connection refused/DNS/timeout) — a caller that wants to fall back to a local,
+    UI-less presentation must check it, so a server that's up but REJECTS the
+    request (bad auth, bad body) is never mistaken for "no server running" and
+    silently papered over."""
     import json
     import urllib.error
     import urllib.request
@@ -244,17 +258,17 @@ def post_show(base_url: str, body: dict, token: str | None = None) -> tuple[dict
     request = urllib.request.Request(f"{base_url}/api/show", data=data, headers=headers, method="POST")
     try:
         with urllib.request.urlopen(request, timeout=10) as response:  # noqa: S310 (localhost control-plane)
-            return json.loads(response.read().decode("utf-8")), None
+            return json.loads(response.read().decode("utf-8")), None, False
     except urllib.error.HTTPError as error:
         detail = error.read().decode("utf-8", errors="replace")
         try:
             message = json.loads(detail).get("error", detail)
         except (ValueError, AttributeError):
             message = detail
-        return None, f"the server rejected the presentation ({error.code}): {message}"
+        return None, f"the server rejected the presentation ({error.code}): {message}", False
     except urllib.error.URLError as error:
         return None, (f"no brainpick server at {base_url} — start one with 'brainpick serve' "
-                      f"({error.reason})")
+                      f"({error.reason})"), True
 
 
 def _cmd_show(args: argparse.Namespace) -> int:
@@ -265,7 +279,7 @@ def _cmd_show(args: argparse.Namespace) -> int:
     config = load_config(root)
     host = args.host or config.serve.host
     port = args.port or config.serve.port
-    display_host = "127.0.0.1" if host in ("0.0.0.0", "::") else host
+    display_host = connectable_host(host)
     base_url = f"http://{display_host}:{port}"
     token = args.token or (config.serve.token or None)
 
@@ -279,7 +293,7 @@ def _cmd_show(args: argparse.Namespace) -> int:
     if args.clear:
         body["clear"] = True
 
-    result, error = post_show(base_url, body, token)
+    result, error, _unreachable = post_show(base_url, body, token)
     if error is not None:
         if args.json:
             print(to_json({"error": error, "hint": "start the server with: brainpick serve"}))

{brainpick-0.4.2 → brainpick-0.4.4}/src/brainpick/mcp_server.py

@@ -575,38 +575,87 @@ def _single_write(state: ServeState, doc: str, content: str, mode: str = "create
 # -- brain_show ----------------------------------------------------------------------
 
 
-def show_hint(presentation: dict, dropped: list[str]) -> str:
-    """The 'what to do next' line for brain_show (spec/95 small-LLM ergonomics)."""
-    cleared = (not presentation["nodes"] and presentation["focus"] is None
-               and presentation["mode"] is None and presentation["annotation"] is None)
+NO_SERVER_CAVEAT = (" No brainpick serve is running for this bundle, so nothing is actually "
+                    "visible yet — start one with `brainpick serve --root <bundle>`.")
+
+
+def show_hint(shown: int, dropped: list[str], cleared: bool, server_reachable: bool = True) -> str:
+    """The 'what to do next' line for brain_show (spec/95 small-LLM ergonomics).
+    `server_reachable` is False only for the local-fallback path (no running
+    `brainpick serve` answered) — the one case where "live in every open UI" would
+    otherwise be a flat lie, so it earns an honest caveat."""
     if cleared:
-        return "cleared — every open UI dropped its spotlight and caption."
-    shown = len(presentation["nodes"])
-    if shown == 0 and dropped:
-        return ("nothing resolved — no name matched a doc or entity; "
+        base = "cleared — every open UI dropped its spotlight and caption."
+    elif shown == 0 and dropped:
+        base = ("nothing resolved — no name matched a doc or entity; "
                 "check them with brain_search, then brain_show again.")
-    base = (f"showing {shown} node(s) live in every open UI — "
-            "call brain_show again to change it, or with clear:true to dismiss.")
-    if dropped:
-        base += f" (dropped {len(dropped)}: {', '.join(dropped)})"
+    else:
+        base = (f"showing {shown} node(s) live in every open UI — "
+                "call brain_show again to change it, or with clear:true to dismiss.")
+        if dropped:
+            base += f" (dropped {len(dropped)}: {', '.join(dropped)})"
+    if not server_reachable:
+        base += NO_SERVER_CAVEAT
     return base
 
 
+def _proxy_show(state: ServeState, body: dict) -> dict | None:
+    """Try to hand this presentation to an already-running `brainpick serve` for
+    the same bundle root, the same way `brainpick show` (the CLI) already does —
+    it broadcasts to a REAL UI, unlike the stdio MCP process's own private,
+    unattached ServeState. Returns the server's result (with our hint attached),
+    an error dict if a server answered but rejected the request, or None if no
+    server answered at all — the caller's cue to fall back to the local, UI-less
+    presentation (spec/95 follow-up: this proxy is Python-engine-only for now,
+    the Node twin still only does the local fallback — see NO_SERVER_CAVEAT)."""
+    from brainpick.cli import connectable_host, post_show
+
+    base_url = f"http://{connectable_host(state.config.serve.host)}:{state.config.serve.port}"
+    token = state.config.serve.token or None
+    result, error, unreachable = post_show(base_url, body, token)
+    if result is not None:
+        result["hint"] = show_hint(result["shown"], result["dropped"], cleared=bool(body.get("clear")))
+        return result
+    if unreachable:
+        return None
+    return {"ok": False, "dropped": [], "error": error,
+            "hint": "a brainpick serve is running but rejected the presentation — fix the error above, then try again."}
+
+
 def _single_show(state: ServeState, nodes: list[str] | None = None, focus: str | None = None,
                  mode: str | None = None, annotation: str | None = None,
                  clear: bool = False) -> dict:
-    """brain_show's MCP result (spec/95): resolve + broadcast a presentation, then
-    report {ok, shown, dropped, seq, hint}. Never writes — not behind [serve]
-    writes, only the normal auth. Forgiving: unresolved nodes are dropped, listed."""
+    """brain_show's MCP result (spec/95): proxy to a running `brainpick serve` when
+    one answers (it does the real resolving + broadcasting); otherwise fall back to
+    resolving + broadcasting on this process's own orphaned state, honestly caveated
+    since nothing is actually watching it. Never writes — not behind [serve] writes,
+    only the normal auth. Forgiving: unresolved nodes are dropped, listed."""
+    body: dict = {}
+    if nodes is not None:
+        body["nodes"] = nodes
+    if focus is not None:
+        body["focus"] = focus
+    if mode is not None:
+        body["mode"] = mode
+    if annotation is not None:
+        body["annotation"] = annotation
+    if clear:
+        body["clear"] = True
+    proxied = _proxy_show(state, body)
+    if proxied is not None:
+        return proxied
+
     presentation, dropped = state.present(
         nodes=nodes, focus=focus, mode=mode, annotation=annotation, clear=clear,
     )
+    cleared = (not presentation["nodes"] and presentation["focus"] is None
+               and presentation["mode"] is None and presentation["annotation"] is None)
     return {
         "ok": True,
         "shown": len(presentation["nodes"]),
         "dropped": dropped,
         "seq": presentation["seq"],
-        "hint": show_hint(presentation, dropped),
+        "hint": show_hint(len(presentation["nodes"]), dropped, cleared, server_reachable=False),
     }
 
 

{brainpick-0.4.2 → brainpick-0.4.4}/src/brainpick.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainpick
-Version: 0.4.2
+Version: 0.4.4
 Summary: A turn-key brain stack for agents: compile an OKF markdown bundle into a queryable, servable, visualizable brain.
 Author: Benquemax
 License: MIT

{brainpick-0.4.2 → brainpick-0.4.4}/tests/test_e2e_mcp.py

@@ -2,6 +2,7 @@
 import asyncio
 import json
 import re
+import socket
 import sys
 
 import pytest
@@ -103,6 +104,13 @@ async def _scenario(root):
 
 
 def test_mcp_stdio_roundtrip(kotiaurinko):
+    # brain_show now tries a real `brainpick serve` first (spec/95 follow-up) — pin
+    # it to a port nothing binds, so this doesn't depend on whatever else happens to
+    # be listening on the default :4747 on the machine running the suite.
+    with socket.socket() as probe:
+        probe.bind(("127.0.0.1", 0))
+        free_port = probe.getsockname()[1]
+    (kotiaurinko / "brainpick.toml").write_text(f"[serve]\nport = {free_port}\n", encoding="utf-8")
     run_compile(kotiaurinko)
     _run_scenario(_scenario(kotiaurinko))
     text = (kotiaurinko / "uusi-kivi.md").read_text(encoding="utf-8")

{brainpick-0.4.2 → brainpick-0.4.4}/tests/test_e2e_serve.py

@@ -107,7 +107,7 @@ def test_sse_frame_format():
 def test_health(kotiaurinko):
     with TestClient(make_app(kotiaurinko)) as client:
         assert client.get("/api/health").json() == {
-            "impl": "python", "name": "brainpick", "spec_version": "0.1", "version": "0.4.2",
+            "impl": "python", "name": "brainpick", "spec_version": "0.1", "version": "0.4.4",
         }
 
 

{brainpick-0.4.2 → brainpick-0.4.4}/tests/test_federation.py

@@ -352,7 +352,11 @@ def test_write_targets_here_or_declines(tmp_path):
     assert result["ok"] is True and result["path"] == "aurinko:uusi-kivi.md"
 
 
-def test_show_targets_one_brain_and_drops_the_rest(tmp_path):
+def test_show_targets_one_brain_and_drops_the_rest(tmp_path, monkeypatch):
+    # no running `brainpick serve` here — pin brain_show to its local fallback so
+    # this doesn't silently depend on whatever happens to be on :4747 (spec/95 follow-up)
+    monkeypatch.setattr("brainpick.cli.post_show",
+                        lambda base_url, body, token=None: (None, "no server", True))
     brain_set = make_set(tmp_path)
     result = show_payload(brain_set, nodes=["kirja:kahvi.md", "aurinko:kuu.md"])
     assert result["shown"] == 1 and result["dropped"] == ["aurinko:kuu.md"]

{brainpick-0.4.2 → brainpick-0.4.4}/tests/test_mcp_tools.py

@@ -539,9 +539,21 @@ def test_write_henxels_contract_at_repo_root_governs_bundle(monkeypatch, tmp_pat
 # -- brain_show (spec/95): the 6th tool — ephemeral presentations, not write-gated --
 
 
-def test_show_payload_reports_shown_dropped_seq_and_hint(kotiaurinko):
+def _no_server(monkeypatch, reason="[Errno 111] Connection refused"):
+    """Make brain_show's proxy attempt behave as if no `brainpick serve` is
+    listening — every existing local-fallback test needs this so it doesn't
+    silently depend on whatever happens to be bound to 127.0.0.1:4747 on the
+    machine running the suite (spec/95 follow-up: the stdio MCP process has no
+    server of its own to ask, so it must genuinely try one over HTTP first)."""
+    def fake_post_show(base_url, body, token=None):
+        return None, f"no brainpick server at {base_url} — start one with 'brainpick serve' ({reason})", True
+    monkeypatch.setattr("brainpick.cli.post_show", fake_post_show)
+
+
+def test_show_payload_reports_shown_dropped_seq_and_hint(kotiaurinko, monkeypatch):
     from brainpick.mcp_server import show_payload
 
+    _no_server(monkeypatch)
     state = make_state(kotiaurinko)
     queue = state.subscribe()
     result = show_payload(state, nodes=["aurinko.md", "ei-ole"], annotation="hi")
@@ -549,27 +561,113 @@ def test_show_payload_reports_shown_dropped_seq_and_hint(kotiaurinko):
     assert result["shown"] == 1
     assert result["dropped"] == ["ei-ole"]
     assert result["seq"] == 1
-    # the exact hint — pinned so the Node twin stays byte-identical (cross-engine parity)
+    # the exact hint — pinned so the Node twin stays byte-identical (cross-engine parity),
+    # aside from the trailing no-server caveat (Python-only for now, see mcp_server.py)
     assert result["hint"] == (
         "showing 1 node(s) live in every open UI — "
         "call brain_show again to change it, or with clear:true to dismiss. (dropped 1: ei-ole)"
+        " No brainpick serve is running for this bundle, so nothing is actually visible yet"
+        " — start one with `brainpick serve --root <bundle>`."
     )
-    # it broadcasts (the open UIs light up), and never writes / compiles
+    # local fallback still updates its own (UI-less) state so the CLI/tests can introspect it
     assert [name for name, _, _ in drain(queue)] == ["brain.show"]
     assert state.seq == 1
 
 
-def test_show_payload_clear_has_a_dedicated_hint(kotiaurinko):
+def test_show_payload_clear_has_a_dedicated_hint(kotiaurinko, monkeypatch):
     from brainpick.mcp_server import show_payload
 
+    _no_server(monkeypatch)
     state = make_state(kotiaurinko)
     result = show_payload(state, clear=True)
     assert result == {
         "ok": True, "shown": 0, "dropped": [], "seq": 1,
-        "hint": "cleared — every open UI dropped its spotlight and caption.",
+        "hint": ("cleared — every open UI dropped its spotlight and caption."
+                 " No brainpick serve is running for this bundle, so nothing is actually visible yet"
+                 " — start one with `brainpick serve --root <bundle>`."),
     }
 
 
+def test_show_payload_proxies_to_a_running_server_and_never_touches_local_state(kotiaurinko, monkeypatch):
+    """The actual bug fix: when a `brainpick serve` answers, brain_show must use
+    ITS response (a real broadcast to a real UI) and leave the stdio process's
+    own orphaned state untouched — no local seq bump, no local broadcast."""
+    from brainpick.mcp_server import show_payload
+
+    calls = []
+
+    def fake_post_show(base_url, body, token=None):
+        calls.append((base_url, body, token))
+        return {"ok": True, "shown": 2, "dropped": [], "seq": 7}, None, False
+
+    monkeypatch.setattr("brainpick.cli.post_show", fake_post_show)
+    state = make_state(kotiaurinko)
+    queue = state.subscribe()
+
+    result = show_payload(state, nodes=["aurinko.md", "kuu"], annotation="hi", mode="brain")
+
+    assert result == {
+        "ok": True, "shown": 2, "dropped": [], "seq": 7,
+        "hint": "showing 2 node(s) live in every open UI — "
+                "call brain_show again to change it, or with clear:true to dismiss.",
+    }
+    assert len(calls) == 1
+    base_url, body, token = calls[0]
+    assert base_url == "http://127.0.0.1:4747"  # the bundle's default [serve] config
+    assert body == {"nodes": ["aurinko.md", "kuu"], "annotation": "hi", "mode": "brain"}
+    assert token is None  # no token configured for this fixture bundle
+    # the orphaned local state was never touched — the real server did the broadcasting
+    assert drain(queue) == []
+    assert state.presentation_seq == 0
+
+
+def test_show_payload_normalizes_a_wildcard_bind_to_a_connectable_host(kotiaurinko, monkeypatch):
+    """A server can bind 0.0.0.0 (everywhere); a client can't connect TO that
+    address — must resolve to 127.0.0.1 before POSTing, same as `brainpick show`."""
+    from brainpick.config import load_config
+    from brainpick.mcp_server import show_payload
+    from brainpick.serve.state import ServeState
+
+    calls = []
+    monkeypatch.setattr(
+        "brainpick.cli.post_show",
+        lambda base_url, body, token=None: (calls.append(base_url), ({"ok": True, "shown": 0, "dropped": [], "seq": 1}, None, False))[1],
+    )
+    config = load_config(kotiaurinko)
+    config.serve.host = "0.0.0.0"
+    state = ServeState(kotiaurinko, config)
+    state.load()
+
+    show_payload(state, clear=True)
+
+    assert calls == ["http://127.0.0.1:4747"]
+
+
+def test_show_payload_reports_a_server_side_rejection_without_touching_local_state(kotiaurinko, monkeypatch):
+    """A running server that REJECTS the presentation (e.g. a bad bearer token
+    on a non-local bind) must surface as an error, never silently paper over it
+    by falling back to updating the orphaned local state — that would hide a
+    real misconfiguration behind a false 'ok'."""
+    from brainpick.mcp_server import show_payload
+
+    def fake_post_show(base_url, body, token=None):
+        return None, "the server rejected the presentation (401): auth required", False
+
+    monkeypatch.setattr("brainpick.cli.post_show", fake_post_show)
+    state = make_state(kotiaurinko)
+    queue = state.subscribe()
+
+    result = show_payload(state, nodes=["aurinko.md"])
+
+    assert result == {
+        "ok": False, "dropped": [],
+        "error": "the server rejected the presentation (401): auth required",
+        "hint": "a brainpick serve is running but rejected the presentation — fix the error above, then try again.",
+    }
+    assert drain(queue) == []
+    assert state.presentation_seq == 0
+
+
 def test_brain_show_registered_as_sixth_tool_even_when_writes_refused(kotiaurinko):
     import asyncio