secondbrain-py 0.2.1__py3-none-any.whl

brain/cli_claude.py

@@ -0,0 +1,81 @@
+"""brain claude install-skill — install the Claude Code skill into ~/.claude/skills/brain/."""
+import sys
+from importlib.resources import files as resource_files
+from pathlib import Path
+
+import typer
+
+from .errors import BrainError
+
+
+class SkillInstallError(BrainError):
+    """Raised when the Claude skill install can't proceed."""
+
+
+_DEFAULT_TARGET_ROOT = Path.home() / ".claude" / "skills"
+_SKILL_DIR_NAME = "brain"
+_SKILL_FILENAME = "SKILL.md"
+
+
+def install_skill(
+    target_root: Path | None = None,
+    force: bool = False,
+    uninstall: bool = False,
+) -> None:
+    """Install (or uninstall) the brain Claude Code skill."""
+    root = target_root if target_root is not None else _DEFAULT_TARGET_ROOT
+    skill_dir = root / _SKILL_DIR_NAME
+    target = skill_dir / _SKILL_FILENAME
+
+    if uninstall:
+        _uninstall(skill_dir, target)
+        return
+
+    src_bytes = _read_skill_template()
+    _install(target, skill_dir, src_bytes, force=force)
+
+
+def _read_skill_template() -> bytes:
+    """Read SKILL.md from package data."""
+    res = resource_files("brain.templates.skill") / _SKILL_FILENAME
+    return res.read_bytes()
+
+
+def _install(target: Path, skill_dir: Path, src_bytes: bytes, *, force: bool) -> None:
+    """Write src_bytes to target, creating skill_dir as needed."""
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    if target.is_file():
+        if target.read_bytes() == src_bytes:
+            print(f"skill up to date: {target}")
+            return
+        if not force:
+            typer.confirm(
+                f"{target} differs from the packaged SKILL.md. Overwrite?",
+                abort=True,
+            )
+    target.write_bytes(src_bytes)
+    print(f"skill installed: {target}")
+
+
+def _uninstall(skill_dir: Path, target: Path) -> None:
+    """Remove SKILL.md and rmdir the brain/ dir if empty."""
+    target_removed = False
+    if target.is_file():
+        target.unlink()
+        print(f"removed {target}")
+        target_removed = True
+
+    if skill_dir.is_dir():
+        remaining = list(skill_dir.iterdir())
+        if remaining:
+            print(
+                f"warning: {skill_dir} not empty — leaving it in place "
+                f"({len(remaining)} other entries)",
+                file=sys.stderr,
+            )
+        else:
+            skill_dir.rmdir()
+            print(f"removed {skill_dir}")
+
+    if not target_removed and not skill_dir.is_dir():
+        print("nothing to uninstall")

brain/cli_connect.py

@@ -0,0 +1,285 @@
+"""`brain connect` auto-link suggestion sub-app (Plan 07).
+
+Thin Typer orchestration over :mod:`brain.connect`: list the review queue,
+refresh candidates, accept (optionally writing the wikilink into the source
+vault file), reject, and show stats. All scoring + SQL + writeback primitives
+live in :mod:`brain.connect`; this module only maps results to Rich/Typer
+output and the plain :mod:`brain.errors` exceptions to ``typer.Exit``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import psycopg
+import typer
+from rich.table import Table
+
+from . import connect as connect_mod
+from .config import Config
+from .db import connect
+from .errors import (
+    ConnectError,
+    IdPrefixAmbiguous,
+    IdPrefixNotFound,
+    IdPrefixNotHex,
+    IdPrefixTooShort,
+)
+from .format import console, emit_json
+
+# Default rows shown by ``brain connect list`` / the bare ``brain connect``.
+_LIST_DEFAULT_LIMIT = 20
+
+connect_app = typer.Typer(
+    name="connect",
+    help=(
+        "Proactive auto-link suggestions: surface note pairs that share "
+        "entities / semantics but aren't linked yet, then accept (write the "
+        "wikilink) or reject each one."
+    ),
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+
+
+def _suggestion_json(row: connect_mod.SuggestionRow) -> dict[str, Any]:
+    """Serialize a suggestion row for ``--json`` output."""
+    return {
+        "id": row.id,
+        "source_doc_id": row.source_doc_id,
+        "target_doc_id": row.target_doc_id,
+        "source_title": row.source_title,
+        "target_title": row.target_title,
+        "score": round(row.score, 6),
+        "graph_score": None if row.graph_score is None else round(row.graph_score, 6),
+        "embed_score": None if row.embed_score is None else round(row.embed_score, 6),
+        "status": row.status,
+        "suggested_at": row.suggested_at,
+    }
+
+
+def _fmt_leg(value: float | None) -> str:
+    """Render a leg score (graph / embed) or an em dash when absent."""
+    return "—" if value is None else f"{value:.2f}"
+
+
+def _render_list(*, limit: int, json_output: bool, show_all: bool) -> None:
+    """Shared body for the bare ``brain connect`` and ``brain connect list``."""
+    cfg = Config.load()
+    status = None if show_all else "pending"
+    with connect(cfg.database_url) as conn:
+        rows = connect_mod.iter_suggestions(conn, status=status, limit=limit)
+    if json_output:
+        emit_json([_suggestion_json(r) for r in rows])
+        return
+    if not rows:
+        typer.echo("no suggestions" if show_all else "no pending suggestions")
+        return
+    title = "Link suggestions" if show_all else "Pending link suggestions"
+    table = Table(title=title)
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Source title")
+    table.add_column("Target title")
+    table.add_column("Score", justify="right")
+    table.add_column("Graph", justify="right")
+    table.add_column("Embed", justify="right")
+    if show_all:
+        table.add_column("Status")
+    for r in rows:
+        cells = [
+            r.id[:8],
+            r.source_title,
+            r.target_title,
+            f"{r.score:.3f}",
+            _fmt_leg(r.graph_score),
+            _fmt_leg(r.embed_score),
+        ]
+        if show_all:
+            cells.append(r.status)
+        table.add_row(*cells)
+    console.print(table)
+
+
+@connect_app.callback(invoke_without_command=True)
+def connect_default(
+    ctx: typer.Context,
+    limit: int = typer.Option(
+        _LIST_DEFAULT_LIMIT, "--limit", "-n", help="Max suggestions to show."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead."),
+    show_all: bool = typer.Option(
+        False, "--all", help="Show every status, not just pending."
+    ),
+) -> None:
+    """Show the pending suggestion queue (alias for ``brain connect list``)."""
+    if ctx.invoked_subcommand is not None:
+        return
+    _render_list(limit=limit, json_output=json_output, show_all=show_all)
+
+
+@connect_app.command("list")
+def connect_list(
+    limit: int = typer.Option(
+        _LIST_DEFAULT_LIMIT, "--limit", "-n", help="Max suggestions to show."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead."),
+    show_all: bool = typer.Option(
+        False, "--all", help="Show every status, not just pending."
+    ),
+) -> None:
+    """List the link-suggestion review queue (pending by default)."""
+    _render_list(limit=limit, json_output=json_output, show_all=show_all)
+
+
+@connect_app.command("refresh")
+def connect_refresh(
+    doc: str | None = typer.Option(
+        None, "--doc", help="Limit refresh to a single source doc (id prefix)."
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Compute candidates without writing to the DB."
+    ),
+) -> None:
+    """Recompute auto-link candidates and upsert pending suggestions.
+
+    Blends an entity-graph affinity leg with an embedding affinity leg (RRF),
+    drops already-linked and below-threshold pairs, and persists the top
+    suggestions per source doc. Accepted/rejected rows are never overwritten.
+    """
+    cfg = Config.load()
+    try:
+        with connect(cfg.database_url) as conn:
+            conn.autocommit = True
+            result = connect_mod.refresh_suggestions(
+                conn, cfg, doc_prefix=doc, dry_run=dry_run
+            )
+    except (
+        IdPrefixTooShort,
+        IdPrefixNotHex,
+        IdPrefixNotFound,
+        IdPrefixAmbiguous,
+        ConnectError,
+    ) as exc:
+        typer.secho(str(exc), fg="red", err=True)
+        raise typer.Exit(code=1) from exc
+    prefix = "would write" if dry_run else "wrote"
+    typer.echo(
+        f"scanned {result.source_docs} source doc(s); "
+        f"{result.candidates} candidate pair(s); "
+        f"{prefix} {result.written} suggestion(s)"
+    )
+
+
+def _resolve(conn: psycopg.Connection[Any], prefix: str) -> str:
+    """Resolve a suggestion-id prefix or exit non-zero with a message."""
+    try:
+        return connect_mod.resolve_suggestion_prefix(conn, prefix)
+    except ConnectError as exc:
+        typer.secho(str(exc), fg="red", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@connect_app.command("accept")
+def connect_accept(
+    suggestion_id: str = typer.Argument(..., help="Suggestion id prefix (>= 6 chars)."),
+    write: bool = typer.Option(
+        False, "--write", help="Insert the wikilink into the source vault file."
+    ),
+) -> None:
+    """Mark a suggestion accepted; with ``--write``, insert the wikilink.
+
+    The wikilink is appended (path-form alias) under a ``## See Also`` section
+    at the end of the source doc's vault file. The write is idempotent — a
+    repeated accept never duplicates the link.
+    """
+    cfg = Config.load()
+    with connect(cfg.database_url) as conn:
+        conn.autocommit = True
+        resolved = _resolve(conn, suggestion_id)
+        try:
+            ctx = connect_mod.load_action_context(conn, resolved)
+        except ConnectError as exc:
+            typer.secho(str(exc), fg="red", err=True)
+            raise typer.Exit(code=1) from exc
+        # Write the wikilink FIRST so a write failure (missing file / IO error)
+        # leaves the suggestion pending rather than frozen accepted-without-link.
+        written = _write_wikilink(cfg, ctx) if write else False
+        try:
+            connect_mod.set_suggestion_status(conn, resolved, "accepted")
+        except ConnectError as exc:
+            typer.secho(str(exc), fg="red", err=True)
+            raise typer.Exit(code=1) from exc
+    suffix = "  (wikilink written)" if written else (
+        "  (wikilink already present)" if write else ""
+    )
+    typer.echo(f"✓ accepted {resolved[:8]}{suffix}")
+
+
+def _write_wikilink(cfg: Config, action: connect_mod.ActionResult) -> bool:
+    """Insert the accepted suggestion's wikilink into the source vault file.
+
+    Returns ``True`` when a new link was written, ``False`` when it was already
+    present. Exits non-zero when the source/target vault paths are missing
+    (the link can't be located) so the user gets clear feedback.
+    """
+    if action.source_vault_path is None:
+        typer.secho(
+            "cannot write wikilink: source doc has no vault file",
+            fg="red",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    if action.target_vault_path is None:
+        typer.secho(
+            "cannot write wikilink: target doc has no vault path",
+            fg="red",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    source_file = Path(cfg.vault_path) / action.source_vault_path
+    if not source_file.is_file():
+        typer.secho(
+            f"cannot write wikilink: source vault file not found at {source_file}",
+            fg="red",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    wikilink = connect_mod.build_see_also_wikilink(
+        action.target_vault_path, action.target_title
+    )
+    return connect_mod.append_see_also_link(source_file, wikilink)
+
+
+@connect_app.command("reject")
+def connect_reject(
+    suggestion_id: str = typer.Argument(..., help="Suggestion id prefix (>= 6 chars)."),
+) -> None:
+    """Mark a suggestion rejected; it is frozen and not re-proposed on refresh."""
+    cfg = Config.load()
+    with connect(cfg.database_url) as conn:
+        conn.autocommit = True
+        resolved = _resolve(conn, suggestion_id)
+        try:
+            connect_mod.set_suggestion_status(conn, resolved, "rejected")
+        except ConnectError as exc:
+            typer.secho(str(exc), fg="red", err=True)
+            raise typer.Exit(code=1) from exc
+    typer.echo(f"✓ rejected {resolved[:8]}")
+
+
+@connect_app.command("stats")
+def connect_stats(
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead."),
+) -> None:
+    """Show pending / accepted / rejected suggestion counts."""
+    cfg = Config.load()
+    with connect(cfg.database_url) as conn:
+        counts = connect_mod.suggestion_counts(conn)
+    if json_output:
+        emit_json(counts)
+        return
+    typer.echo(
+        f"pending {counts['pending']}  "
+        f"accepted {counts['accepted']}  "
+        f"rejected {counts['rejected']}"
+    )

brain/cli_demo.py

@@ -0,0 +1,266 @@
+"""`brain demo` CLI sub-app — a zero-Ollama taste test with a synthetic corpus.
+
+Thin Typer orchestration over :mod:`brain.demo`: the bare ``brain demo``
+provisions an isolated throwaway Postgres (or seeds a caller-supplied
+``--database-url``), seeds the 22-doc synthetic Larkspur corpus with the
+deterministic :class:`~brain.demo.embedder.DemoEmbedder`, and runs the hero
+query inline. Sub-commands ``query`` / ``status`` / ``teardown`` operate the
+running sandbox. All provisioning + search primitives live in
+:mod:`brain.demo`; this module only maps them to Rich/Typer output.
+"""
+from __future__ import annotations
+
+import logging
+import shutil
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import datetime
+
+import typer
+
+from . import demo as demo_mod
+from .errors import BrainError
+from .format import console, emit_json, search_table
+from .search import SearchResult
+
+# The headline query a first-time visitor sees ranked results for.
+HERO_QUERY = "compliance horror stories"
+
+# Valid host-port range for --port. Below 1024 needs root; above 65535 is not a
+# port at all (an unbounded value would overflow deep inside socket.bind()).
+_MIN_PORT = 1024
+_MAX_PORT = 65535
+
+# Follow-up query prompts printed after the hero query so the visitor keeps
+# exploring (the show + teardown lines are appended dynamically).
+_NEXT_STEPS: tuple[str, ...] = (
+    'brain demo query "SOC 2 evidence request"',
+    'brain demo query "PCI scope creep"',
+    'brain demo query "vendor risk" --source gmail',
+    'brain demo query "GDPR deletion request"',
+)
+
+# The exact guidance when Docker is missing and no --database-url was supplied.
+_DOCKER_MISSING_MSG = (
+    "Docker not found — brain demo needs Docker, or pass --database-url "
+    "<postgres-url> to seed an existing empty database."
+)
+
+demo_app = typer.Typer(
+    name="demo",
+    help=(
+        "Zero-Ollama taste test: spin up a throwaway Postgres, seed a synthetic "
+        "compliance corpus, and search it — see ranked results in under two "
+        "minutes with no personal data and no model downloads."
+    ),
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+
+
+def _fail(message: str) -> None:
+    """Print an error and exit non-zero (mirrors the cli_connect idiom)."""
+    typer.secho(message, fg="red", err=True)
+    raise typer.Exit(code=1)
+
+
+@contextmanager
+def _quiet_internal_logs() -> Iterator[None]:
+    """Silence brain's INFO/WARNING logs for a clean demo transcript.
+
+    The seed path emits operational warnings (e.g. the Krisp hook noting no
+    ``gws`` runner) that are irrelevant to a first-time visitor and make the
+    marketing demo look noisy. Real errors (ERROR+) still surface. The prior
+    level is restored on exit so this never leaks into a longer-lived process
+    (e.g. cross-test contamination under pytest).
+    """
+    logger = logging.getLogger("brain")
+    previous = logger.level
+    logger.setLevel(logging.ERROR)
+    try:
+        yield
+    finally:
+        logger.setLevel(previous)
+
+
+def _render_results(
+    results: list[SearchResult], *, json_output: bool, query: str
+) -> None:
+    """Render hero/query results as JSON or a Rich table titled with ``query``."""
+    if json_output:
+        emit_json(
+            [
+                {
+                    "id": r.document_id,
+                    "title": r.title,
+                    "source_kind": r.source_kind,
+                    "snippet": r.snippet,
+                    "score": r.score,
+                    "content_type": r.content_type,
+                    "tags": r.tags,
+                }
+                for r in results
+            ]
+        )
+        return
+    if not results:
+        typer.echo("(no results)")
+        return
+    console.print(search_table(results, title=f"brain demo · {query!r}"))
+
+
+def _print_next_steps(results: list[SearchResult]) -> None:
+    """Print the "Try these next" block after the inline hero query."""
+    console.print("\n[bold]Try these next:[/bold]")
+    for suggestion in _NEXT_STEPS:
+        console.print(f"  [cyan]{suggestion}[/cyan]")
+    if results:
+        short_id = results[0].document_id[:8]
+        console.print(
+            f"  [cyan]brain show {short_id}[/cyan]"
+            "   # read the top hit in full (in your own brain)"
+        )
+    console.print("  [cyan]brain demo teardown[/cyan]   # remove the sandbox when done")
+
+
+def _resolve_default_database_url(port: int, database_url: str | None) -> str:
+    """Resolve the DB URL for the default flow: caller-supplied or provisioned.
+
+    With ``--database-url`` the demo seeds that database and never touches
+    Docker (the CI / power-user seam). Otherwise Docker is required: absent, we
+    exit with actionable guidance; present, we auto-bump off a busy port and
+    provision the isolated sandbox.
+    """
+    if database_url is not None:
+        return database_url
+    if shutil.which("docker") is None:
+        _fail(_DOCKER_MISSING_MSG)
+    resolved_port = demo_mod.resolve_port(port)
+    typer.echo(f"Provisioning the demo Postgres on port {resolved_port} …")
+    return demo_mod.provision(resolved_port)
+
+
+@demo_app.callback(invoke_without_command=True)
+def demo_default(
+    ctx: typer.Context,
+    port: int = typer.Option(
+        demo_mod.DEFAULT_DEMO_PORT, "--port", min=_MIN_PORT, max=_MAX_PORT,
+        help="Host port for the demo Postgres (auto-bumps if busy).",
+    ),
+    with_embeddings: bool = typer.Option(
+        False, "--with-embeddings",
+        help="Also build vector embeddings + HNSW index (default: FTS-only).",
+    ),
+    database_url: str | None = typer.Option(
+        None, "--database-url",
+        help="Seed this existing empty Postgres instead of provisioning Docker.",
+    ),
+    json_output: bool = typer.Option(
+        False, "--json", help="Emit the hero-query results as JSON."
+    ),
+) -> None:
+    """Provision, seed, and run the hero query inline (the default flow)."""
+    if ctx.invoked_subcommand is not None:
+        return
+    try:
+        with _quiet_internal_logs():
+            resolved_url = _resolve_default_database_url(port, database_url)
+            typer.echo("Seeding the synthetic Larkspur corpus (22 docs, no Ollama) …")
+            report = demo_mod.seed_demo(resolved_url, with_embeddings=with_embeddings)
+            typer.echo(
+                f"Seeded {report.ingested} new doc(s) "
+                f"({report.skipped} already present).\n"
+            )
+            results = demo_mod.query_demo(
+                resolved_url,
+                HERO_QUERY,
+                limit=5,
+                with_embeddings=with_embeddings,
+            )
+    except BrainError as exc:
+        _fail(str(exc))
+    _render_results(results, json_output=json_output, query=HERO_QUERY)
+    if not json_output:
+        _print_next_steps(results)
+
+
+@demo_app.command("query")
+def demo_query(
+    query: str = typer.Argument(..., help="Search text to run over the demo corpus."),
+    limit: int = typer.Option(5, "--limit", "-n", min=1),
+    source: str | None = typer.Option(
+        None, "--source", help="Filter by source kind (manual/krisp/slack/gmail)."
+    ),
+    tag: str | None = typer.Option(None, "--tag", help="Filter by tag."),
+    person: str | None = typer.Option(
+        None, "--person", help="Filter by a participant name (e.g. 'Priya Okafor')."
+    ),
+    after: datetime | None = typer.Option(
+        None, "--after", formats=["%Y-%m-%d", "%Y-%m-%dT%H:%M:%S"],
+        help="Only docs dated on or after this ISO date.",
+    ),
+    with_embeddings: bool = typer.Option(
+        False, "--with-embeddings", help="Use the vector leg too (default: FTS-only)."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead."),
+    port: int = typer.Option(
+        demo_mod.DEFAULT_DEMO_PORT, "--port", min=_MIN_PORT, max=_MAX_PORT,
+        help="Host port of the demo Postgres.",
+    ),
+    database_url: str | None = typer.Option(
+        None, "--database-url", help="Query this Postgres instead of the demo container."
+    ),
+) -> None:
+    """Search the seeded demo corpus (the running sandbox, or --database-url)."""
+    resolved_url = database_url or demo_mod.demo_database_url(port)
+    try:
+        results = demo_mod.query_demo(
+            resolved_url,
+            query,
+            limit=limit,
+            source=source,
+            tag=tag,
+            person=person,
+            after=after,
+            with_embeddings=with_embeddings,
+        )
+    except BrainError as exc:
+        _fail(str(exc))
+    _render_results(results, json_output=json_output, query=query)
+
+
+@demo_app.command("status")
+def demo_status(
+    port: int = typer.Option(
+        demo_mod.DEFAULT_DEMO_PORT, "--port", min=_MIN_PORT, max=_MAX_PORT,
+        help="Host port of the demo Postgres.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead."),
+) -> None:
+    """Report whether the demo sandbox is running and how many docs it holds."""
+    snapshot = demo_mod.status(port)
+    if json_output:
+        emit_json(
+            {
+                "running": snapshot.running,
+                "container": snapshot.container,
+                "database_url": snapshot.database_url,
+                "doc_count": snapshot.doc_count,
+            }
+        )
+        return
+    if not snapshot.running:
+        typer.echo("demo: not running (run `brain demo` to start it)")
+        return
+    docs = "unknown" if snapshot.doc_count is None else str(snapshot.doc_count)
+    typer.echo(f"demo: running · container {snapshot.container} · {docs} doc(s)")
+
+
+@demo_app.command("teardown")
+def demo_teardown() -> None:
+    """Destroy the demo sandbox and its data (`docker compose down -v`)."""
+    try:
+        demo_mod.teardown()
+    except BrainError as exc:
+        _fail(str(exc))
+    typer.echo("demo: torn down (container + volume removed)")