cogrind-workshop 0.1.0__py3-none-any.whl

cogrind_workshop/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""cogrind-workshop — human-facing MCP client for a `cobalt-grinding` server.
+
+Equivalent in role to Claude Desktop or Claude Code: one MCP client
+among many that can drive a running `cobalt-grinding` daemon. No
+business logic; pure transport + rendering.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("cogrind-workshop")
+except PackageNotFoundError:  # editable install before first build
+    __version__ = "0.0.0+local"

cogrind_workshop/__main__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""`python -m cogrind_workshop` entry point. Delegates to the CLI's main()."""
+
+from cogrind_workshop.main import main
+
+if __name__ == "__main__":
+    main()

cogrind_workshop/client.py

@@ -0,0 +1,146 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""MCP-over-HTTP client used by the `cogrind-workshop` CLI.
+
+Wraps the official `mcp` SDK's `streamable_http_client` + `ClientSession`
+in a small synchronous-feeling helper so the CLI's flag handlers don't
+each have to drive an asyncio loop.
+
+This module is pure transport — no rendering, no wiki-specific logic.
+The CLI in `cogrind_workshop.main` consumes it; tests can target this
+module against any MCP server (stub or real).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Callable
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+
+class DaemonUnreachable(RuntimeError):
+    """Raised when no `cobalt-grinding` daemon is reachable at the configured URL."""
+
+
+def _mcp_url(host: str, port: int) -> str:
+    return f"http://{host}:{port}/mcp"
+
+
+def _is_connection_error(exc: BaseException) -> bool:
+    """Recognize the various ways 'daemon not listening' surfaces.
+
+    httpx wraps low-level connection errors; anyio (used by streamable-http)
+    can group them inside a BaseExceptionGroup. We walk the tree to check.
+    """
+    if isinstance(exc, httpx.ConnectError | httpx.ConnectTimeout | ConnectionError | OSError):
+        return True
+    if isinstance(exc, BaseExceptionGroup):
+        return any(_is_connection_error(e) for e in exc.exceptions)
+    cause = exc.__cause__ or exc.__context__
+    return cause is not None and _is_connection_error(cause)
+
+
+@asynccontextmanager
+async def _session(host: str, port: int) -> AsyncIterator[ClientSession]:
+    """Open an MCP session over streamable-HTTP and yield the ClientSession."""
+    url = _mcp_url(host, port)
+    try:
+        async with (
+            streamable_http_client(url) as (read, write, _),
+            ClientSession(read, write) as session,
+        ):
+            await session.initialize()
+            yield session
+    except BaseException as e:
+        if _is_connection_error(e):
+            raise DaemonUnreachable(
+                f"could not reach cobalt-grinding at {url} — start one with: cobalt-grinding"
+            ) from e
+        raise
+
+
+def call_tool(
+    name: str,
+    arguments: dict[str, Any] | None = None,
+    *,
+    host: str = "127.0.0.1",
+    port: int = 7474,
+) -> Any:
+    """Synchronous helper: connect, call one tool, decode the result, disconnect.
+
+    The MCP `call_tool` returns content blocks; for cobalt-grinding's tools the
+    first block is JSON text. This function extracts that and parses it.
+
+    Note: each call opens a fresh MCP session (HTTP connect + initialize
+    handshake). For one-shot CLI invocations (`cogrind-workshop --status`)
+    this is fine — startup cost dominates anyway. A future REPL form will
+    keep a single session open across many tool calls.
+    """
+    return asyncio.run(_call_tool_async(name, arguments or {}, host=host, port=port))
+
+
+async def _call_tool_async(name: str, arguments: dict[str, Any], *, host: str, port: int) -> Any:
+    async with _session(host, port) as session:
+        result = await session.call_tool(name, arguments)
+        return _decode(result)
+
+
+def _decode(result: Any) -> Any:
+    """Pull the first text content block out of a tool-call result and JSON-decode it."""
+    content = getattr(result, "content", None)
+    if not content:
+        return None
+    first = content[0]
+    text = getattr(first, "text", None)
+    if text is None:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text
+
+
+# ---- streaming helper for tail-progress style flows ----
+
+
+async def stream_task(
+    submit_tool: str,
+    submit_args: dict[str, Any],
+    *,
+    on_update: Callable[[dict[str, Any]], None],
+    poll_interval: float = 0.25,
+    timeout_seconds: float | None = None,
+    host: str = "127.0.0.1",
+    port: int = 7474,
+) -> dict[str, Any]:
+    """Submit a long-running tool, poll status, return final task dict.
+
+    `on_update` is called every poll iteration with the current task dict
+    so the caller can render progress.
+    """
+    async with _session(host, port) as session:
+        submit_result = _decode(await session.call_tool(submit_tool, submit_args))
+        task_id = submit_result.get("task_id") if isinstance(submit_result, dict) else None
+        if not task_id:
+            raise RuntimeError(f"{submit_tool} did not return a task_id; got: {submit_result!r}")
+
+        elapsed = 0.0
+        while True:
+            status = _decode(await session.call_tool("wiki.task_status", {"task_id": task_id}))
+            if not isinstance(status, dict):
+                raise RuntimeError(f"unexpected task_status payload: {status!r}")
+            on_update(status)
+            if status.get("status") in ("succeeded", "failed", "cancelled"):
+                return status
+            await asyncio.sleep(poll_interval)
+            elapsed += poll_interval
+            if timeout_seconds is not None and elapsed > timeout_seconds:
+                raise TimeoutError(f"task {task_id} did not finish within {timeout_seconds}s")

cogrind_workshop/formatters.py

@@ -0,0 +1,236 @@
+# SPDX-FileCopyrightText: 2026 Gary Frattarola <garyf@parkviewlab.ai>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Terminal output rendering for the cogrind-workshop CLI.
+
+The CLI is just an MCP client; what makes it *feel* like a CLI lives here
+— Rich tables, progress lines, colored status badges. Anything that
+takes a tool-call result dict and prints something pretty.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+
+def format_status(status: dict[str, Any], console: Console) -> None:
+    """Pretty-print the result of `wiki.status`."""
+    table = Table(title=f"cobalt-grinding — {status.get('wiki_dir', '?')}", show_header=False)
+    table.add_column("key")
+    table.add_column("value")
+
+    table.add_row("version", str(status.get("version", "?")))
+    table.add_row("milestone", str(status.get("milestone", "?")))
+    # Be defensive: if a future / older daemon returns null for uptime, we
+    # don't want the CLI to crash with a TypeError on `:.1f` format.
+    uptime = status.get("daemon", {}).get("uptime_seconds")
+    table.add_row("uptime (s)", f"{uptime:.1f}" if isinstance(uptime, int | float) else "?")
+    table.add_row("wiki exists", _yes_no(bool(status.get("wiki_exists"))))
+    table.add_row("pages indexed", str(status.get("pages_indexed", 0)))
+    table.add_row("lance tables", ", ".join(status.get("lance_tables", []) or []))
+
+    embed = status.get("embedding", {}) or {}
+    table.add_row("embedding", f"{embed.get('provider')}:{embed.get('model')} (dim={embed.get('dim')})")
+
+    mutex = status.get("corpus_mutex", {}) or {}
+    if mutex.get("locked"):
+        table.add_row("corpus mutex", f"[yellow]locked by {mutex.get('holder')}[/yellow]")
+    else:
+        table.add_row("corpus mutex", "[green]free[/green]")
+
+    tasks = status.get("tasks", {}) or {}
+    summary = ", ".join(f"{k}={v}" for k, v in tasks.items())
+    table.add_row("tasks", summary)
+
+    console.print(table)
+
+
+def format_index_result(task: dict[str, Any], console: Console) -> None:
+    """Pretty-print a finished `wiki.index` task."""
+    final_status = task.get("status", "?")
+    result = task.get("result", {}) or {}
+
+    if final_status == "succeeded":
+        console.print(
+            f"\n[green]done[/green] in {result.get('duration_seconds', 0):.2f}s — "
+            f"scanned {result.get('scanned', 0)}, "
+            f"inserted {result.get('inserted', 0)}, "
+            f"updated {result.get('updated', 0)}, "
+            f"skipped {result.get('skipped', 0)}, "
+            f"deleted {result.get('deleted', 0)}, "
+            f"failed {result.get('failed', 0)}"
+            f"{', cancelled' if result.get('cancelled') else ''}"
+        )
+        for path, msg in result.get("failures", []) or []:
+            console.print(f"  [red]fail[/red] {path}: {msg}")
+    elif final_status == "cancelled":
+        console.print("[yellow]cancelled[/yellow]")
+    else:
+        console.print(f"[red]task {final_status}[/red]: {task.get('error', '?')}")
+
+
+def format_progress_line(task: dict[str, Any], console: Console) -> None:
+    """One-line progress update suitable for printing as a task is running."""
+    status = task.get("status", "?")
+    progress = task.get("progress") or {}
+    if status == "running" and progress:
+        bits = ", ".join(f"{k}={v}" for k, v in progress.items())
+        console.print(f"  [dim]running[/dim] — {bits}")
+    elif status == "queued":
+        console.print("  [dim]queued[/dim]")
+
+
+def format_ingest_result(result: dict[str, Any], console: Console) -> None:
+    """Pretty-print a finished `wiki.ingest` response.
+
+    The orchestrator returns `IngestResult.to_dict()` — source page id,
+    section pages (multi-file), entity/glossary pages, link count, and
+    skipped/error flags. We render a compact summary; full payload is
+    available via `console.print_json(data=result)` if a user wants it.
+    """
+    if "error" in result:
+        console.print(f"[red]ingest_error[/red]: {result.get('message', '?')}")
+        return
+    if result.get("skipped"):
+        console.print(
+            f"[yellow]skipped[/yellow] — {result.get('skip_reason', 'no-change')}: "
+            f"{result.get('source_id', '?')}"
+        )
+        return
+
+    table = Table(title="wiki.ingest", show_header=False)
+    table.add_column("key")
+    table.add_column("value")
+    table.add_row("source id", str(result.get("source_id", "?")))
+    table.add_row("page path", str(result.get("page_path", "?")))
+    table.add_row("location", str(result.get("location_uri", "?")))
+    table.add_row("kind", str(result.get("location_kind", "?")))
+    table.add_row("files ingested", str(result.get("files_ingested", 0)))
+    section_pages = result.get("section_pages_written") or []
+    if section_pages:
+        table.add_row("section pages", str(len(section_pages)))
+    entities = result.get("entity_pages_written") or []
+    if entities:
+        table.add_row("entities written", str(len(entities)))
+    glossary = result.get("glossary_pages_written") or []
+    if glossary:
+        table.add_row("glossary written", str(len(glossary)))
+    table.add_row("links added", str(result.get("links_added", 0)))
+    ignored = result.get("files_ignored") or []
+    if ignored:
+        truncated_marker = " (truncated)" if result.get("truncated") else ""
+        table.add_row(
+            f"ignored files{truncated_marker}",
+            ", ".join(ignored[:6]) + (f", +{len(ignored) - 6} more" if len(ignored) > 6 else ""),
+        )
+    console.print(table)
+
+
+def format_search_result(result: dict[str, Any], console: Console) -> None:
+    """Pretty-print `wiki.search` response: ranked hits + optional expansion."""
+    if "error" in result:
+        console.print(f"[red]retrieve_error[/red]: {result.get('message', '?')}")
+        return
+    query = result.get("query", "")
+    hits = result.get("hits") or []
+    if not hits:
+        console.print(f"[yellow]no hits[/yellow] for {query!r} — gap_detected")
+        return
+
+    table = Table(title=f"wiki.search — {query!r}")
+    table.add_column("score", width=7)
+    table.add_column("type", width=10)
+    table.add_column("id")
+    table.add_column("title")
+    table.add_column("snippet", overflow="ellipsis", max_width=60)
+    for h in hits:
+        score = h.get("score", 0.0)
+        table.add_row(
+            f"{score:.2f}" if isinstance(score, int | float) else str(score),
+            str(h.get("type", "?")),
+            str(h.get("id", "?")),
+            str(h.get("title", "?")),
+            (h.get("snippet") or "").replace("\n", " "),
+        )
+    console.print(table)
+
+    expanded = result.get("expanded_node_ids") or []
+    if expanded:
+        console.print(
+            f"[dim]+ {len(expanded)} expanded node(s):[/dim] "
+            + ", ".join(expanded[:6])
+            + (f", +{len(expanded) - 6} more" if len(expanded) > 6 else "")
+        )
+    if result.get("truncated_expansion"):
+        console.print("[dim](expansion truncated at smalt's per-hop cap)[/dim]")
+
+
+def format_ask_result(result: dict[str, Any], console: Console) -> None:
+    """Pretty-print `wiki.ask` response: cited answer + validation flags."""
+    if "error" in result:
+        console.print(f"[red]converse_error[/red]: {result.get('message', '?')}")
+        return
+
+    question = result.get("question", "")
+    answer = result.get("answer", "")
+    # `question` is user input and `answer` is LLM output — both opaque
+    # text that may contain `[...]` patterns (notably `[page:<id>]`
+    # citation tokens). Escape so rich doesn't interpret them as markup.
+    console.print(f"[bold]Q:[/bold] {escape(question)}\n")
+    console.print(f"[bold]A:[/bold] {escape(answer)}\n")
+
+    citations = result.get("citations") or []
+    if citations:
+        console.print("[dim]citations:[/dim]")
+        for c in citations:
+            pid = c.get("page_id", "?")
+            valid = c.get("valid", False)
+            mark = "[green]✓[/green]" if valid else "[red]✗[/red]"
+            console.print(f"  {mark} {escape(f'[page:{pid}]')}")
+    invalid = result.get("invalid_citations") or []
+    if invalid:
+        joined = ", ".join(invalid)
+        console.print(
+            f"[red]warning[/red]: LLM cited {len(invalid)} page id(s) not in the "
+            f"corpus — likely hallucination: {escape(joined)}"
+        )
+    if result.get("gap_detected"):
+        console.print(
+            "[yellow]gap_detected[/yellow] — the corpus didn't help. "
+            'Consider `cogrind-workshop --report-gap "..."` to flag it for Research.'
+        )
+    if result.get("truncated_context"):
+        console.print("[dim](some page bodies were truncated for the LLM context)[/dim]")
+
+
+def format_gaps_list(result: dict[str, Any], console: Console) -> None:
+    """Pretty-print `wiki.find_gaps` response: list of open knowledge gaps."""
+    if "error" in result:
+        console.print(f"[red]retrieve_error[/red]: {result.get('message', '?')}")
+        return
+    gaps = result.get("gaps") or []
+    if not gaps:
+        console.print("[green]no open gaps[/green]")
+        return
+    table = Table(title=f"open gaps ({len(gaps)})")
+    table.add_column("id")
+    table.add_column("query")
+    table.add_column("created", overflow="ellipsis", max_width=20)
+    table.add_column("why", overflow="ellipsis", max_width=30)
+    for g in gaps:
+        table.add_row(
+            str(g.get("id", "?")),
+            str(g.get("query", "?")),
+            str(g.get("created_at", "?")),
+            str(g.get("why", "") or ""),
+        )
+    console.print(table)
+
+
+def _yes_no(b: bool) -> str:
+    return "[green]yes[/green]" if b else "[red]no[/red]"