polymath-nexus 0.2.0__py3-none-any.whl

nexus/__init__.py

@@ -0,0 +1,104 @@
+"""
+Brain — long-term project memory.
+
+This is the public API surface of the brain. Anything not exported here is
+internal to brain and may change without notice. The surface is intentionally
+small — the brain's value is in the *file format* (markdown + JSONL + date
+stamps + owner attribution), not in any specific Python API.
+
+Long-term contract: nothing inside `nexus.*` imports anything from
+`polymath.*` outside the brain. Enforced by tests/test_brain_decoupling.py.
+
+This boundary is what makes the brain extractable into its own package
+later — when that happens, this exact `__init__.py` becomes the top-level
+of the new `brain` distribution.
+
+────────────────────────────────────────────────────────────────────────
+Quick reference
+
+  # Discovery
+  from nexus import find_brain_root, find_repo_root, current_owner_slug
+
+  # Init
+  from nexus import init_brain_root
+
+  # Reading
+  from nexus import read_context, build_context_injection
+  from nexus import brain_grep, brain_usage
+
+  # Writing
+  from nexus import append_context, write_context
+
+  # Types
+  from nexus import TaskType, CONTEXT_FILES, AuthExpiredError
+
+  # Memory (chunked, embedded — optional, opt-in)
+  from nexus import Chunk, MemoryStore, harvest_session
+"""
+from __future__ import annotations
+
+# ── Discovery ────────────────────────────────────────────────────────────────
+from nexus.discovery import (
+    current_owner_slug,
+    find_brain_root,
+    find_repo_root,
+)
+
+# ── Types (canonical home) ───────────────────────────────────────────────────
+from nexus.types import (
+    ALWAYS_INJECT,
+    CONTEXT_DESCRIPTIONS,
+    CONTEXT_FILES,
+    TASK_CONTEXT_MAP,
+    AuthExpiredError,
+    TaskType,
+)
+
+# ── Config ───────────────────────────────────────────────────────────────────
+from nexus.config import (
+    BRAIN_CACHE_DIR,
+    BRAIN_DIR_NAME,
+    BRAIN_HOME,
+    BRAIN_PROJECTS_DIR,
+    MIRROR_FILES,
+)
+
+# ── Index (read/write) ───────────────────────────────────────────────────────
+from nexus.index import (
+    append_context,
+    brain_grep,
+    brain_usage,
+    build_context_injection,
+    context_dir,
+    create_project,
+    init_brain_root,
+    list_context_files,
+    list_projects,
+    read_context,
+    write_context,
+)
+
+# ── Memory (chunked store, optional) ─────────────────────────────────────────
+from nexus.memory.store import Chunk, MemoryStore
+from nexus.memory.writer import (
+    HarvestResult,
+    harvest_session,
+)
+
+__all__ = [
+    # Discovery
+    "current_owner_slug", "find_brain_root", "find_repo_root",
+    # Types
+    "TaskType", "AuthExpiredError",
+    "CONTEXT_FILES", "CONTEXT_DESCRIPTIONS", "TASK_CONTEXT_MAP", "ALWAYS_INJECT",
+    # Config
+    "BRAIN_HOME", "BRAIN_PROJECTS_DIR", "BRAIN_CACHE_DIR", "BRAIN_DIR_NAME",
+    "MIRROR_FILES",
+    # Index
+    "init_brain_root", "create_project", "list_projects",
+    "context_dir", "list_context_files",
+    "read_context", "write_context", "append_context",
+    "build_context_injection", "brain_grep", "brain_usage",
+    # Memory
+    "Chunk", "MemoryStore", "HarvestResult", "harvest_session",
+]

nexus/cli.py

@@ -0,0 +1,223 @@
+"""
+`nexus` — standalone CLI for the long-term brain.
+
+No LLM dependencies. Pure stdlib + nexus. Works with `pip install nexus`
+(brain-only) or as a dependency of polymath.
+
+Subcommands:
+    nexus init                          Create brain/ in cwd
+    nexus show [bucket] [--since DATE] [--until DATE] [--by OWNER] [-q PATTERN]
+                                        Search the brain. Grep-first.
+    nexus usage                         Counts per bucket + per owner
+    nexus own                           Print which slug you'll write as
+    nexus learn-from "<correction>"     Append to rules/<you>.md (deliberate)
+    nexus sync                          Regenerate the AI-tool mirror files
+    nexus unmirror                      Remove the AI-tool mirror files
+    nexus spec                          Print the SPEC.md format contract
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from nexus.discovery import current_owner_slug, find_brain_root, find_repo_root
+from nexus.index import (
+    append_context, brain_grep, brain_usage, context_dir, create_project,
+    init_brain_root,
+)
+from nexus.mirrors import regenerate_mirrors, remove_mirrors
+
+
+def _cmd_init(args) -> int:
+    base = init_brain_root(Path(args.cwd) if args.cwd else None)
+    repo = find_repo_root() or base.parent
+    report = regenerate_mirrors(repo_root=repo, force=getattr(args, "force", False))
+    print(f"✓ Brain initialised at {base}")
+    if report.written:
+        for tool, path in report.written.items():
+            print(f"  ↳ mirrored to {path.relative_to(repo)} (for {tool})")
+    elif not report.skipped:
+        print("  (brain is empty; mirrors will be generated after first write)")
+    _print_skipped(report, repo)
+    print(f"\nYour owner slug: {current_owner_slug()}")
+    print("\nNext: `nexus learn-from \"your first rule\"`")
+    return 0
+
+
+def _cmd_show(args) -> int:
+    project = args.project or ""
+    hits = brain_grep(
+        project,
+        pattern=args.pattern or "",
+        since=args.since or "",
+        until=args.until or "",
+        by=args.by or "",
+        ctx_name=args.bucket or "",
+    )
+    if not hits:
+        print("(no matches)")
+        return 0
+    if args.json:
+        print(json.dumps(hits, indent=2))
+        return 0
+    for h in hits:
+        print(f"{h['file']:40s}  {h['text']}")
+    return 0
+
+
+def _cmd_usage(args) -> int:
+    project = args.project or ""
+    stats = brain_usage(project)
+    if args.json:
+        print(json.dumps(stats, indent=2))
+        return 0
+    print(f"Total entries: {stats['total_entries']}\n")
+    if stats["buckets"]:
+        print("By bucket:")
+        for k, v in sorted(stats["buckets"].items(), key=lambda kv: -kv[1]):
+            print(f"  {k:12s}  {v}")
+    if stats["owners"]:
+        print("\nBy owner:")
+        for k, v in sorted(stats["owners"].items(), key=lambda kv: -kv[1]):
+            print(f"  {k:12s}  {v}")
+    return 0
+
+
+def _cmd_own(args) -> int:
+    """Print owner slug and the timezone we'll record on writes."""
+    from nexus.memory.store import _local_tz_name
+    print(f"owner: {current_owner_slug()}")
+    print(f"tz:    {_local_tz_name()}")
+    return 0
+
+
+def _cmd_learn_from(args) -> int:
+    text = args.text or ""
+    if not text:
+        print("usage: nexus learn-from \"<rule>\"", file=sys.stderr)
+        return 2
+    project = args.project or ""
+    brain = find_brain_root()
+    if brain is None and not project:
+        # Need either a brain/ in cwd or a project name for personal scope.
+        print("error: no brain/ found in this repo. Run `nexus init` first,\n"
+              "or use --project <name> for personal-scope brains.", file=sys.stderr)
+        return 1
+    if not brain and project:
+        create_project(project)
+    owner = current_owner_slug()
+    written = append_context(project, "rules", text, by_owner=True, author=owner)
+    print(f"✓ Logged to {written.relative_to(written.parents[2]) if len(written.parents) >= 3 else written}")
+    _dt = __import__("datetime").datetime
+    today = _dt.now().astimezone().strftime("%Y-%m-%d")
+    print(f"  - [{today} {owner}] {text}")
+    return 0
+
+
+def _print_skipped(report, repo: Path) -> None:
+    """Tell the user about mirror files we refused to overwrite. Silence
+    here would look like the mirror simply worked."""
+    for tool, path in report.backed_up.items():
+        print(f"  ↳ saved your old {tool} file to {path.relative_to(repo)}")
+    if not report.skipped:
+        return
+    for tool, path in report.skipped.items():
+        print(f"  skipped {path.relative_to(repo)} — you wrote this, not nexus")
+    print("  Move its content into brain/, or run with --force to hand it "
+          "over (your version is saved as a .bak first).")
+
+
+def _cmd_sync(args) -> int:
+    repo = find_repo_root() or (find_brain_root() or Path.cwd()).parent
+    report = regenerate_mirrors(args.project or "", repo_root=repo, force=args.force)
+    if not report.written and not report.skipped:
+        print("(brain is empty; nothing to mirror)")
+        return 0
+    for tool, path in report.written.items():
+        print(f"✓ {tool}: {path.relative_to(repo)}")
+    _print_skipped(report, repo)
+    return 0
+
+
+def _cmd_unmirror(args) -> int:
+    report = remove_mirrors(force=args.force)
+    for p in report.removed:
+        print(f"removed {p}")
+    for p in report.skipped:
+        print(f"kept {p} — you wrote this, not nexus")
+    if report.skipped:
+        print("Pass --force to delete it anyway.")
+    if not report.removed and not report.skipped:
+        print("(no mirror files present)")
+    return 0
+
+
+def _cmd_spec(args) -> int:
+    spec = Path(__file__).resolve().parent / "SPEC.md"
+    if spec.exists():
+        print(spec.read_text())
+        return 0
+    print(f"SPEC.md not found at {spec}", file=sys.stderr)
+    return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="nexus",
+        description="Long-term, team-shareable project brain.",
+    )
+    p.add_argument("--project", default="", help="project name (personal scope)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="create brain/ in cwd")
+    p_init.add_argument("--cwd", default="", help="target directory (default: cwd)")
+    p_init.add_argument("--force", action="store_true",
+                        help="take over mirror files you wrote by hand (saves a .bak)")
+    p_init.set_defaults(func=_cmd_init)
+
+    p_show = sub.add_parser("show", help="search the brain (grep-first)")
+    p_show.add_argument("bucket", nargs="?", default="", help="one of: rules logic code stack data goals decisions glossary personas")
+    p_show.add_argument("--since", default="", help="YYYY-MM-DD lower bound")
+    p_show.add_argument("--until", default="", help="YYYY-MM-DD upper bound")
+    p_show.add_argument("--by", default="", help="owner slug")
+    p_show.add_argument("-q", "--pattern", default="", help="substring filter (case-insensitive)")
+    p_show.add_argument("--json", action="store_true", help="emit JSON")
+    p_show.set_defaults(func=_cmd_show)
+
+    p_usage = sub.add_parser("usage", help="counts per bucket and per owner (read-only)")
+    p_usage.add_argument("--json", action="store_true")
+    p_usage.set_defaults(func=_cmd_usage)
+
+    p_own = sub.add_parser("own", help="print which owner slug you'll write as")
+    p_own.set_defaults(func=_cmd_own)
+
+    p_learn = sub.add_parser("learn-from", help="log a correction to rules/<you>.md")
+    p_learn.add_argument("text", nargs="?", default="", help="the rule to log")
+    p_learn.set_defaults(func=_cmd_learn_from)
+
+    p_sync = sub.add_parser("sync", help="regenerate AI-tool mirror files")
+    p_sync.add_argument("--force", action="store_true",
+                        help="take over mirror files you wrote by hand (saves a .bak)")
+    p_sync.set_defaults(func=_cmd_sync)
+
+    p_unmirror = sub.add_parser("unmirror", help="remove AI-tool mirror files")
+    p_unmirror.add_argument("--force", action="store_true",
+                            help="also delete mirror files nexus did not write")
+    p_unmirror.set_defaults(func=_cmd_unmirror)
+
+    p_spec = sub.add_parser("spec", help="print the brain SPEC.md")
+    p_spec.set_defaults(func=_cmd_spec)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nexus/config.py

@@ -0,0 +1,45 @@
+"""
+Brain-owned configuration. Independent of polymath.config — that's the
+whole point of the decoupling.
+
+Brain data has two homes:
+  1. In-repo:  <repo>/brain/                  ← the canonical, shared brain
+  2. Personal: $POLYMATH_BRAIN_HOME or ~/.brain/projects/<name>/
+                                              ← personal scratch / no-repo
+                                                projects
+
+Long-term contract: BRAIN_HOME lives at ~/.brain/, NOT ~/.polymath/. The
+brain owns its own home directory — it must not depend on Polymath being
+installed to find its own data.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def _brain_home() -> Path:
+    """Personal-scope brain root. Override via $POLYMATH_BRAIN_HOME."""
+    override = os.environ.get("POLYMATH_BRAIN_HOME")
+    if override:
+        return Path(override).expanduser().resolve()
+    return Path.home() / ".brain"
+
+
+BRAIN_HOME = _brain_home()
+BRAIN_PROJECTS_DIR = BRAIN_HOME / "projects"
+BRAIN_CACHE_DIR = BRAIN_HOME / "cache"
+
+# In-repo brain folder name. Always exactly "brain" — this is part of the
+# format SPEC and tools downstream rely on the name. Do not parameterise.
+BRAIN_DIR_NAME = "brain"
+
+# Mirror file names. These are what tools downstream auto-discover. The
+# brain writes them; we never read them back (the brain is the source of
+# truth, the mirrors are derived artifacts).
+MIRROR_FILES = {
+    "claude":  "CLAUDE.md",
+    "agents":  "AGENTS.md",
+    "cursor":  ".cursor/rules/brain.mdc",
+    "copilot": ".github/copilot-instructions.md",
+}

nexus/discovery.py

@@ -0,0 +1,77 @@
+"""
+Brain discovery — find a brain in the cwd hierarchy, or fall back to
+personal/no-repo scope.
+
+This is intentionally a small, dependency-free module. Anything that needs
+to locate a brain (brain CLI, Polymath orchestrator, third-party tool)
+calls into here. Long-term-stable: the discovery rules are part of the
+SPEC.
+"""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from nexus.config import BRAIN_DIR_NAME, BRAIN_PROJECTS_DIR
+
+
+def find_brain_root(start: Path | None = None) -> Path | None:
+    """
+    Walk upward from `start` looking for a `brain/` directory. Mirrors
+    git's discovery semantics. Returns the absolute path or None.
+
+    Resolution: every parent up to the filesystem root. The first match
+    wins. This means nested repos containing a `brain/` folder are
+    discovered correctly from a sub-directory.
+    """
+    cwd = Path(start or Path.cwd()).resolve()
+    for directory in [cwd, *cwd.parents]:
+        candidate = directory / BRAIN_DIR_NAME
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def current_owner_slug() -> str:
+    """
+    Derive a stable owner slug for the current user. Used to namespace
+    per-owner files (rules/ayushi.md, decisions/akhil.md) so two devs
+    writing simultaneously never collide.
+
+    Resolution order:
+      1. $POLYMATH_BRAIN_OWNER (explicit override)
+      2. git config user.email → local part → sanitised slug
+      3. $USER
+      4. "anon" (never empty)
+    """
+    override = os.environ.get("POLYMATH_BRAIN_OWNER", "").strip()
+    if override:
+        return _slugify(override)
+
+    email = ""
+    try:
+        email = subprocess.run(
+            ["git", "config", "--get", "user.email"],
+            capture_output=True, text=True, timeout=2,
+        ).stdout.strip()
+    except Exception:
+        email = ""
+    raw = email.split("@")[0] if email else os.environ.get("USER", "")
+    return _slugify(raw or "anon")
+
+
+def _slugify(raw: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", (raw or "anon").lower()).strip("-")
+    return slug or "anon"
+
+
+def find_repo_root(start: Path | None = None) -> Path | None:
+    """Walk upward looking for `.git/`. Used to anchor mirror files at the
+    repo root (CLAUDE.md, AGENTS.md, etc.)."""
+    cwd = Path(start or Path.cwd()).resolve()
+    for directory in [cwd, *cwd.parents]:
+        if (directory / ".git").exists():
+            return directory
+    return None