brain-wiki 0.1.0.dev0__py3-none-any.whl

brainwiki/cli/__init__.py

@@ -0,0 +1,7 @@
+"""Command-line interface (design doc 07 §2)."""
+
+from __future__ import annotations
+
+from brainwiki.cli._main import main
+
+__all__ = ["main"]

brainwiki/cli/_cmd_bench.py

@@ -0,0 +1,101 @@
+"""bench: run the evaluation suites (design doc 11)."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from brainwiki.errors import UsageError
+
+_SUITES = ("retrieval", "lint", "consolidation", "perf", "agent")
+_DEFAULT_SUITES = ["retrieval", "lint", "perf"]
+_ENV = ("BRAIN_WIKI_CONFIG", "BRAIN_WIKI_STATE_DIR", "BRAIN_WIKI_CACHE_DIR", "BRAIN_WIKI_DATA_DIR")
+
+
+def _parse_sizes(raw: str) -> list[int]:
+    sizes = []
+    for item in (s.strip().lower() for s in raw.split(",") if s.strip()):
+        try:
+            sizes.append(int(float(item[:-1]) * 1000) if item.endswith("k") else int(item))
+        except ValueError as exc:
+            raise UsageError(f"bad size {item!r}; use e.g. 1k, 10k or 200") from exc
+    if not sizes or min(sizes) < 50:
+        raise UsageError("sizes must be at least 50 notes")
+    return sizes
+
+
+@contextmanager
+def _isolated_state(base: Path) -> Iterator[None]:
+    """Keep bench indexes, runs, and user config away from the user's own brain-wiki state."""
+    saved = {k: os.environ.get(k) for k in (*_ENV, "BRAIN_WIKI_BRAIN")}
+    os.environ["BRAIN_WIKI_CONFIG"] = str(base / "config.toml")
+    for key, sub in zip(_ENV[1:], ("state", "cache", "data"), strict=True):
+        os.environ[key] = str(base / sub)
+    os.environ.pop("BRAIN_WIKI_BRAIN", None)
+    try:
+        yield
+    finally:
+        for key, value in saved.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+def bench(args: Any) -> int:
+    from brainwiki.bench import report, suites
+
+    if args.compare:
+        text, regressions = report.compare(Path(args.compare[0]), Path(args.compare[1]))
+        print(text)
+        return 1 if regressions else 0
+    names = args.suites or _DEFAULT_SUITES
+    unknown = [n for n in names if n not in _SUITES]
+    if unknown:
+        raise UsageError(f"unknown suite(s) {', '.join(unknown)}; choose from {', '.join(_SUITES)}")
+    sizes = _parse_sizes(args.sizes)
+    backends = [b.strip() for b in (args.backends or "").split(",") if b.strip()]
+    out = Path(args.out) if args.out else Path(tempfile.mkdtemp(prefix="brain-bench-"))
+    work = out / "work"
+    if work.exists():
+        shutil.rmtree(work)  # generated brains from an earlier run in the same --out
+    work.mkdir(parents=True)
+
+    results = []
+    with _isolated_state(work / ".state"):
+        for name in names:
+            started = time.monotonic()
+            if name in ("retrieval", "perf"):
+                result = getattr(suites, name)(work, sizes[0])
+                for size in sizes[1:]:
+                    extra = getattr(suites, name)(work, size)
+                    result.metrics += extra.metrics
+                    result.details.update({f"{k}@{size}": v for k, v in extra.details.items()})
+            elif name == "lint":
+                result = suites.lint_suite(work)
+            else:
+                result = getattr(suites, name)(work, backends)
+            result.details["seconds"] = round(time.monotonic() - started, 1)
+            results.append(result)
+            if not args.quiet:
+                print(f"{name}: {result.status} ({result.details['seconds']} s)", flush=True)
+
+    command = " ".join(["brain bench", *names, "--sizes", args.sizes])
+    if backends:
+        command += " --backends " + ",".join(backends)
+    data = report.build(results, command=command, sizes=sizes, backends=backends)
+    results_path, report_path = report.write(out, data)
+    print(report.table(data))
+    failures = report.hard_failures(data)
+    if failures:
+        print(f"\n{len(failures)} hard target(s) failed:")
+        for m in failures[:20]:
+            print(f"  {m['suite']} {m['case']} {m['metric']} = {m['value']} (target {m['target']})")
+    print(f"\nResults: {results_path}\nReport:  {report_path}")
+    return 1 if failures else 0

brainwiki/cli/_cmd_browse.py

@@ -0,0 +1,281 @@
+"""Small browsing commands in the Obsidian CLI's style (design doc 07 §2.2).
+
+Targets resolve like wikilinks; every line names the exact path, the handle for the next
+command. Listings share --count, --paths, --limit, and --cursor.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from brainwiki.cli._output import emit
+from brainwiki.engine import Engine, open_engine
+from brainwiki.index import node_filters, parse_cursor
+
+_NOTE_KINDS = ["note", "hub"]
+_STATUSES = ["active", "superseded"]
+
+
+def _engine(args: Any) -> Engine:
+    return open_engine(args.brain, host=getattr(args, "as_host", None))
+
+
+def _note_where(engine: Engine) -> tuple[str, list[Any]]:
+    return node_filters(engine, _NOTE_KINDS, _STATUSES, None)
+
+
+def _listing(
+    args: Any,
+    rows: list[dict[str, Any]],
+    line: Callable[[dict[str, Any]], str],
+    *,
+    empty: str,
+    path_key: str = "path",
+) -> int:
+    """Print a list with the shared flags; JSON carries the page plus the total."""
+    total = len(rows)
+    offset = parse_cursor(getattr(args, "cursor", None))
+    limit = getattr(args, "limit", None) or total
+    page = rows[offset : offset + limit]
+    more = offset + len(page) < total
+    data = {"total": total, "items": page, "next_cursor": str(offset + len(page)) if more else None}
+    if getattr(args, "count", False):
+        emit(args, data, str(total))
+        return 0
+    if getattr(args, "paths", False):
+        text = "\n".join(dict.fromkeys(str(r[path_key]) for r in page if r.get(path_key)))
+    else:
+        text = "\n".join(line(r) for r in page) or empty
+        if more:
+            text += f"\n… {total - offset - len(page)} more (--cursor {offset + len(page)})"
+    emit(args, data, text)
+    return 0
+
+
+def topics(args: Any) -> int:
+    """The topic tree: slug, title, notes, and sub-topics indented below."""
+    from brainwiki.errors import NotFound
+    from brainwiki.index import topic_rows
+
+    with _engine(args) as engine:
+        engine.scan()
+        rows = {r["slug"]: r for r in topic_rows(engine)}
+    if args.topic and args.topic not in rows:
+        raise NotFound(f"no topic {args.topic!r}")
+    starts = (
+        [args.topic] if args.topic else sorted(s for s, r in rows.items() if r["parent"] is None)
+    )
+    items: list[dict[str, Any]] = []
+
+    def walk(slug: str, depth: int) -> None:
+        items.append({**rows[slug], "depth": depth})
+        for child in sorted(s for s, r in rows.items() if r["parent"] == slug):
+            walk(child, depth + 1)
+
+    for slug in starts:
+        walk(slug, 0)
+
+    def line(r: dict[str, Any]) -> str:
+        own = f"{r['notes']} note{'' if r['notes'] == 1 else 's'}"
+        if r["sub_topics"]:
+            own += f", {r['total_notes']} with sub-topics"
+        return f"{'  ' * r['depth']}- {r['slug']}: {r['title']}  ({own})  [{r['path']}]"
+
+    return _listing(args, items, line, empty="(no topics)")
+
+
+def notes(args: Any) -> int:
+    from brainwiki.index import format_search_text, search
+
+    with _engine(args) as engine:
+        result = search(
+            engine,
+            "",
+            limit=args.limit,
+            topics=args.topic,
+            types=args.types,
+            tags=args.tags,
+            sort=args.sort,
+            cursor=args.cursor,
+            count_only=args.count,
+            facets=args.facets,
+            intent="none",
+        )
+    if args.count and not args.json and not args.facets:
+        print(result["total"])
+        return 0
+    emit(args, result, format_search_text(result, "paths" if args.paths else "text"))
+    return 0
+
+
+def recent(args: Any) -> int:
+    args.topic, args.types, args.tags, args.sort, args.facets = None, None, None, "recent", False
+    from brainwiki.index import format_search_text, search
+
+    with _engine(args) as engine:
+        result = search(
+            engine,
+            "",
+            limit=args.limit,
+            since=args.since,
+            cursor=args.cursor,
+            count_only=args.count,
+        )
+    if args.count and not args.json:
+        print(result["total"])
+        return 0
+    emit(args, result, format_search_text(result, "paths" if args.paths else "text"))
+    return 0
+
+
+def outline(args: Any) -> int:
+    from brainwiki.format import parse_document
+    from brainwiki.index import resolve_target
+
+    with _engine(args) as engine:
+        node = resolve_target(engine, args.target)
+        doc = parse_document(node["path"], engine.store.read_text(node["path"]))
+    headings = [{"line": line, "level": level, "text": text} for line, level, text in doc.headings]
+    text = "\n".join(
+        [f"{node['title']}  [{node['path']}]"]
+        + [f"{'  ' * (h['level'] - 1)}- {h['text']}  (line {h['line']})" for h in headings]
+    )
+    emit(args, {"path": node["path"], "headings": headings}, text)
+    return 0
+
+
+def links(args: Any) -> int:
+    """Everything a note links to: typed relations and body links, resolved or not."""
+    from brainwiki.index import resolve_target
+
+    with _engine(args) as engine:
+        node = resolve_target(engine, args.target)
+        rows = []
+        for edge in engine.db.execute(
+            """SELECT e.verb, e.rel, e.raw_target, e.line, n.id, n.title, n.path
+               FROM edges e LEFT JOIN nodes n ON n.id = e.other
+               WHERE e.declared_in = ? ORDER BY e.line""",
+            (node["id"],),
+        ):
+            rows.append(
+                {
+                    "relation": edge["verb"],
+                    "target": edge["raw_target"],
+                    "line": edge["line"],
+                    "id": edge["id"],
+                    "title": edge["title"],
+                    "path": edge["path"],
+                    "resolved": edge["id"] is not None,
+                }
+            )
+    return _listing(
+        args,
+        rows,
+        lambda r: (
+            f'- {r["relation"]} "{r["title"]}" ({r["path"]})'
+            if r["path"]
+            else f"- {r['relation']} [[{r['target']}]]"
+            + ("" if r["resolved"] else " (unresolved)")
+            + f"  line {r['line']}"
+        ),
+        empty="No links.",
+    )
+
+
+def backlinks(args: Any) -> int:
+    from brainwiki.index import resolve_target
+
+    with _engine(args) as engine:
+        node = resolve_target(engine, args.target)
+        rows, seen = [], set()
+        for edge in engine.db.execute(
+            """SELECT e.verb, n.id, n.title, n.path
+               FROM edges e JOIN nodes n ON n.id = e.declared_in
+               WHERE e.other = ? AND e.declared_in != ?
+               ORDER BY e.rel = 'links_to', n.updated DESC""",
+            (node["id"], node["id"]),
+        ):
+            key = (edge["id"], edge["verb"])
+            if key in seen:
+                continue
+            seen.add(key)
+            rows.append(
+                {
+                    "relation": edge["verb"],
+                    "id": edge["id"],
+                    "title": edge["title"],
+                    "path": edge["path"],
+                }
+            )
+    return _listing(
+        args,
+        rows,
+        lambda r: f'- {r["relation"]} "{r["title"]}" ({r["path"]})',
+        empty="No backlinks.",
+    )
+
+
+def _counts(args: Any, select: str, source: str, what: str) -> int:
+    with _engine(args) as engine:
+        where, params = _note_where(engine)
+        rows = [
+            {"name": r["k"], "count": r["c"]}
+            for r in engine.db.execute(
+                f"SELECT {select} AS k, COUNT(DISTINCT n.id) AS c FROM {source} WHERE {where} "  # noqa: S608
+                f"AND {select} IS NOT NULL GROUP BY {select} ORDER BY c DESC, k",
+                params,
+            )
+        ]
+    return _listing(
+        args,
+        rows,
+        lambda r: f"{r['name']}  {r['count']}" if args.counts else str(r["name"]),
+        empty=f"No {what}.",
+        path_key="name",
+    )
+
+
+def tags(args: Any) -> int:
+    return _counts(args, "lower(t.value)", "nodes n, json_each(n.tags) t", "tags")
+
+
+def types(args: Any) -> int:
+    return _counts(args, "n.type", "nodes n", "types")
+
+
+def orphans(args: Any) -> int:
+    """Notes nothing else links to (hubs are entry points, so they are not listed)."""
+    with _engine(args) as engine:
+        where, params = _note_where(engine)
+        rows = []
+        for row in engine.db.execute(
+            f"""SELECT n.id, n.title, n.path, n.type FROM nodes n WHERE {where} AND n.kind = 'note'
+                AND NOT EXISTS (SELECT 1 FROM edges e JOIN nodes s ON s.id = e.declared_in
+                                WHERE e.other = n.id AND e.declared_in != n.id)
+                ORDER BY n.path""",  # noqa: S608
+            params,
+        ):
+            rows.append(dict(row))
+    return _listing(args, rows, lambda r: f'- "{r["title"]}" ({r["path"]})', empty="No orphans.")
+
+
+def unresolved(args: Any) -> int:
+    """Links and relations that resolve to no note."""
+    with _engine(args) as engine:
+        where, params = _note_where(engine)
+        rows = [
+            {"target": r["raw_target"], "path": r["path"], "line": r["line"], "relation": r["verb"]}
+            for r in engine.db.execute(
+                f"""SELECT e.raw_target, e.line, e.verb, n.path FROM edges e
+                    JOIN nodes n ON n.id = e.declared_in
+                    WHERE e.other IS NULL AND {where} ORDER BY e.raw_target, n.path, e.line""",  # noqa: S608
+                params,
+            )
+        ]
+    return _listing(
+        args,
+        rows,
+        lambda r: f"[[{r['target']}]]  {r['path']}:{r['line']} ({r['relation']})",
+        empty="Every link resolves.",
+    )

brainwiki/cli/_cmd_consolidate.py

@@ -0,0 +1,108 @@
+"""consolidate, review."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from brainwiki.cli._output import emit
+from brainwiki.engine import open_engine
+from brainwiki.errors import UsageError
+
+
+def consolidate(args: Any) -> int:
+    from brainwiki.consolidate import pipeline
+
+    host = getattr(args, "as_host", None)
+    with open_engine(args.brain, host=host) as engine:
+        if args.apply_file:
+            if not args.run:
+                raise UsageError("--apply needs --run RUN (the id from --prepare)")
+            raw = (
+                sys.stdin.read()
+                if args.apply_file == "-"
+                else Path(args.apply_file).read_text(encoding="utf-8")
+            )
+            try:
+                payload = json.loads(raw)
+            except ValueError as exc:
+                raise UsageError(f"{args.apply_file} is not JSON: {exc}") from exc
+            result = pipeline.apply_run(
+                engine,
+                args.run,
+                payload,
+                engine.profile,
+                dry_run=args.dry_run,
+                agent=host,
+                backend="agent",
+            )
+            emit(args, result.to_json(), result.format_text())
+            return 0 if result.status in ("applied", "review", "dry_run") else 1
+        if args.prepare:
+            packet = pipeline.prepare(
+                engine, engine.profile, topic=args.topic, max_episodes=args.max_episodes
+            )
+            if packet is None:
+                emit(args, {"run": None, "pending": 0}, "Nothing to consolidate.")
+                return 0
+            text = pipeline.instructions() + "\n" + packet.model_text() + "\n"
+            if args.out:
+                Path(args.out).write_text(text, encoding="utf-8")
+                emit(args, {"run": packet.run, "out": args.out}, f"{packet.run}: wrote {args.out}")
+            else:
+                emit(
+                    args,
+                    {
+                        "run": packet.run,
+                        "instructions": pipeline.instructions(),
+                        "packet": packet.data,
+                    },
+                    text,
+                )
+            return 0
+        raise UsageError(
+            "consolidation runs in your agent's session: ask it to consolidate the brain. "
+            "To drive it yourself, run `brain consolidate --prepare`, then `--apply OPS.json --run RUN`"
+        )
+
+
+def review(args: Any) -> int:
+    from brainwiki.consolidate import list_proposals, load_proposal, pipeline
+
+    with open_engine(args.brain, host=getattr(args, "as_host", None)) as engine:
+        if args.action == "list":
+            items = list_proposals(engine)
+            text = "\n".join(
+                f"{p['run']}  {p.get('agent') or ''}  {p.get('created') or ''}" for p in items
+            )
+            emit(args, items, text or "No proposals.")
+            return 0
+        if not args.run:
+            raise UsageError(f"brain review {args.action} needs a run id")
+        from brainwiki.write import edits
+
+        if edits.is_edit_proposal(engine, args.run):
+            if args.action == "show":
+                text = edits.show_proposal(engine, args.run)
+                emit(args, {"run": args.run, "type": "edit-proposal"}, text)
+                return 0
+            if args.action == "accept":
+                record = edits.accept_proposal(engine, args.run)
+                emit(args, record.to_json(), f"Accepted {args.run} as {record.run}.")
+                return 0
+            record = edits.reject_proposal(engine, args.run)
+            emit(args, record.to_json(), f"Rejected {args.run}; the note is unchanged.")
+            return 0
+        if args.action == "show":
+            _, ops, agent, text = load_proposal(engine, args.run)
+            emit(args, {"run": args.run, "agent": agent, "ops": ops}, text)
+            return 0
+        if args.action == "accept":
+            result = pipeline.accept_review(engine, args.run, engine.profile)
+            emit(args, result.to_json(), result.format_text())
+            return 0 if result.status == "applied" else 1
+        record = pipeline.reject_review(engine, args.run)
+        emit(args, record.to_json(), f"Rejected {args.run}; its episodes stay pending.")
+    return 0

brainwiki/cli/_cmd_core.py

@@ -0,0 +1,155 @@
+"""version, init, list, brains, doctor, setup."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from brainwiki.cli._output import emit
+from brainwiki.config import (
+    load_user_config,
+    open_brain,
+    register_brain,
+    set_value,
+    unregister_brain,
+)
+from brainwiki.errors import Conflict, NotFound, UsageError
+
+
+def version(args: Any) -> int:
+    from brainwiki import FORMAT_VERSION, __version__
+
+    emit(
+        args,
+        {"version": __version__, "format": FORMAT_VERSION},
+        f"brain-wiki {__version__} (format {FORMAT_VERSION})",
+    )
+    return 0
+
+
+def init(args: Any) -> int:
+    from brainwiki.config import registration_conflict
+    from brainwiki.lifecycle import init_brain, init_git
+
+    target = Path(args.path).expanduser()
+    if not args.no_register:
+        problem = registration_conflict(args.name or target.resolve().name, target)
+        if problem:
+            raise Conflict(problem)
+    root = init_brain(target, args.name)
+    brain = open_brain(root)
+    name = args.name or brain.manifest.name or root.name
+    if not args.no_register:
+        register_brain(name, root)
+    git_problem = init_git(root, name) if args.git else None
+    if not args.git:
+        git_line = "\n  tip: `brain init --git` or `git init` to track changes"
+    elif git_problem:
+        git_line = f"\n  git: {git_problem}; commit the brain's files yourself"
+    else:
+        git_line = "\n  git: initialized, with a first commit"
+    emit(
+        args,
+        {
+            "path": str(root),
+            "name": name,
+            "id": brain.id,
+            "registered": not args.no_register,
+            "git": bool(args.git) and git_problem is None,
+        },
+        f"Created brain {name!r} at {root}\n  id: {brain.id}"
+        + ("" if args.no_register else "\n  registered in the user config")
+        + git_line,
+    )
+    return 0
+
+
+def list_(args: Any) -> int:
+    from brainwiki.index import format_brain_list, list_brains
+
+    host = getattr(args, "as_host", None)
+    result = list_brains(host, explicit=args.brain)
+    emit(args, result, format_brain_list(result, owner=host is None))
+    return 0
+
+
+def brains(args: Any) -> int:
+    user = load_user_config()
+    action, rest = args.action, args.args
+    if action == "list":
+        return list_(args)
+    if action == "add":
+        if len(rest) != 2:
+            raise UsageError("brain brains add NAME PATH")
+        brain = open_brain(Path(rest[1]))
+        register_brain(rest[0], brain.root, make_default=None)
+        emit(
+            args,
+            {"name": rest[0], "path": str(brain.root)},
+            f"Registered {rest[0]!r} -> {brain.root}",
+        )
+        return 0
+    if action == "remove":
+        if len(rest) != 1:
+            raise UsageError("brain brains remove NAME")
+        path = user.brains.get(rest[0])
+        if not unregister_brain(rest[0]):
+            raise NotFound(f"no brain named {rest[0]!r}")
+        if args.purge_state and path and (path / "brain.toml").exists():
+            from brainwiki.config import cache_dir, state_dir
+
+            brain_id = open_brain(path).id
+            for base in (state_dir(), cache_dir()):
+                shutil.rmtree(base / "brains" / brain_id, ignore_errors=True)
+        emit(
+            args,
+            {"removed": rest[0]},
+            f"Removed {rest[0]!r} from the user config (the brain folder is untouched)",
+        )
+        return 0
+    if action == "rename":
+        if len(rest) != 2 or rest[0] not in user.brains:
+            raise UsageError("brain brains rename OLD NEW")
+        path = user.brains[rest[0]]
+        was_default = user.default == rest[0]
+        unregister_brain(rest[0])
+        register_brain(rest[1], path, make_default=was_default)
+        emit(args, {"renamed": rest}, f"Renamed {rest[0]!r} to {rest[1]!r}")
+        return 0
+    if action == "default":
+        if len(rest) != 1 or rest[0] not in user.brains:
+            raise UsageError("brain brains default NAME (a registered brain)")
+        set_value("default", rest[0])
+        emit(args, {"default": rest[0]}, f"Default brain is now {rest[0]!r}")
+        return 0
+    raise UsageError(f"unknown action {action}")
+
+
+def doctor(args: Any) -> int:
+    from brainwiki.doctor import run_doctor
+
+    report = run_doctor()
+    lines = [f"brain-wiki {report['version']} on {report['device']}"]
+    for b in report["brains"]:
+        mark = "ok" if b.get("ok") else "PROBLEM"
+        lines.append(
+            f"  brain {b['name']}: {b['path']} [{mark}] notes={b.get('notes', '?')} pending={b.get('pending_episodes', '?')}"
+        )
+    for h in report["hosts"]:
+        if h.get("installed"):
+            lines.append(
+                f"  host {h['id']}: installed, {'connected' if h.get('connected') else 'not connected'}"
+            )
+    sq = report["sqlite"]
+    lines.append(f"  sqlite {sq['version']} fts5={sq['fts5']} trigram={sq['trigram']}")
+    for p in report["problems"]:
+        lines.append(f"  ! {p['message']}" + (f"  (fix: {p['fix']})" if p.get("fix") else ""))
+    emit(args, report, "\n".join(lines))
+    return 1 if any(p.get("severity") == "error" for p in report["problems"]) else 0
+
+
+def setup(args: Any) -> int:
+    from brainwiki.setup_wizard import run_wizard
+
+    return run_wizard(args)