learnlance 0.1.0__py3-none-any.whl

learnlance/__init__.py

@@ -0,0 +1,6 @@
+"""learnlance — a learning companion for Claude Code.
+
+After every Claude Code turn, it extracts the concepts you could learn from the
+code that was generated and grows a personal knowledge graph.
+"""
+__version__ = "0.1.0"

learnlance/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

learnlance/cli.py

@@ -0,0 +1,176 @@
+"""learnlance command-line interface."""
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+
+from . import config, graph, hook, insights, install, viz
+
+
+def _cmd_install(args):
+    print(install.install_hook())
+    cfg = config.load_config()
+    backend = cfg.get("backend", "cli")
+    if backend == "cli":
+        if insights.resolve_claude_bin(cfg):
+            print("\nBackend: cli — uses your logged-in `claude` (no API key needed).")
+        else:
+            print("\n⚠  Backend is 'cli' but `claude` wasn't found on PATH.")
+            print("     learnlance config --claude-bin \"C:\\path\\to\\claude.cmd\"")
+    else:
+        if not config.get_api_key(cfg):
+            print("\n⚠  Backend is 'api' but no API key is set:")
+            print("     learnlance config --set-key sk-ant-...   (or export ANTHROPIC_API_KEY)")
+    print("\nDone. New Claude Code sessions will now build your knowledge graph.")
+
+
+def _cmd_uninstall(args):
+    print(install.uninstall_hook())
+
+
+def _cmd_config(args):
+    cfg = config.load_config()
+    changed = False
+    if args.backend is not None:
+        cfg["backend"] = args.backend
+        changed = True
+    if args.claude_bin is not None:
+        cfg["claude_bin"] = args.claude_bin
+        changed = True
+    if args.cli_model is not None:
+        cfg["cli_model"] = args.cli_model
+        changed = True
+    if args.set_key is not None:
+        cfg["api_key"] = args.set_key
+        changed = True
+    if args.model is not None:
+        cfg["model"] = args.model
+        changed = True
+    if args.enable:
+        cfg["enabled"] = True
+        changed = True
+    if args.disable:
+        cfg["enabled"] = False
+        changed = True
+    if args.background is not None:
+        cfg["background"] = args.background == "on"
+        changed = True
+    if args.max_topics is not None:
+        cfg["max_topics_per_turn"] = args.max_topics
+        changed = True
+    if changed:
+        config.save_config(cfg)
+        print("Saved config.")
+    # Show current state (mask the key)
+    shown = dict(cfg)
+    if shown.get("api_key"):
+        shown["api_key"] = shown["api_key"][:7] + "…"
+    key_src = "config" if cfg.get("api_key") else ("env" if config.get_api_key(cfg) else "MISSING")
+    print(f"\nConfig ({config.CONFIG_PATH}):")
+    for k, v in shown.items():
+        print(f"  {k}: {v}")
+    print(f"  api key source: {key_src}")
+
+
+def _cmd_show(args):
+    g = graph.load()
+    path = viz.render_html(g)
+    print(f"Graph written to {path}")
+    if not args.no_open:
+        webbrowser.open(path.as_uri())
+
+
+def _cmd_list(args):
+    g = graph.load()
+    nodes = [n for n in g.get("nodes", {}).values() if not n.get("placeholder")]
+    if not nodes:
+        print("Nothing learned yet. Install the hook and let Claude Code write some code.")
+        return
+    nodes.sort(key=lambda n: (-n.get("count", 0), n["name"].lower()))
+    print(f"{len(nodes)} concepts learned:\n")
+    for n in nodes:
+        print(f"  • {n['name']}  [{n.get('category','')}·{n.get('level','')}]  seen {n.get('count',0)}×")
+        if args.verbose and n.get("explanation"):
+            print(f"      {n['explanation']}")
+
+
+def _cmd_stats(args):
+    g = graph.load()
+    nodes = g.get("nodes", {})
+    real = [n for n in nodes.values() if not n.get("placeholder")]
+    cats: dict[str, int] = {}
+    for n in real:
+        cats[n.get("category", "other")] = cats.get(n.get("category", "other"), 0) + 1
+    print(f"Concepts learned : {len(real)}")
+    print(f"Related links    : {len(g.get('edges', []))}")
+    print(f"Turns analyzed   : {g.get('meta', {}).get('turns', 0)}")
+    print(f"Sessions         : {len(g.get('sessions', {}))}")
+    if cats:
+        print("\nBy category:")
+        for c, n in sorted(cats.items(), key=lambda x: -x[1]):
+            print(f"  {c:18} {n}")
+
+
+def _cmd_hook(args):
+    hook.run_hook()
+
+
+def _cmd_worker(args):
+    hook.run_worker(args.job)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="learnlance",
+        description="Turn what Claude Code builds into a growing knowledge graph.")
+    sub = p.add_subparsers(dest="cmd")
+
+    sub.add_parser("install", help="install the Claude Code Stop hook").set_defaults(func=_cmd_install)
+    sub.add_parser("uninstall", help="remove the Stop hook").set_defaults(func=_cmd_uninstall)
+
+    c = sub.add_parser("config", help="view/set configuration")
+    c.add_argument("--backend", choices=["cli", "api"],
+                   help="cli = use logged-in `claude` (no key); api = Anthropic API")
+    c.add_argument("--claude-bin", dest="claude_bin", metavar="PATH",
+                   help="path to the claude executable (cli backend)")
+    c.add_argument("--cli-model", dest="cli_model", metavar="MODEL",
+                   help="optional model alias for the cli backend, e.g. haiku")
+    c.add_argument("--set-key", dest="set_key", metavar="KEY", help="Anthropic API key (api backend)")
+    c.add_argument("--model", help="model id for the api backend")
+    c.add_argument("--enable", action="store_true")
+    c.add_argument("--disable", action="store_true")
+    c.add_argument("--background", choices=["on", "off"], help="run API work detached")
+    c.add_argument("--max-topics", dest="max_topics", type=int)
+    c.set_defaults(func=_cmd_config)
+
+    s = sub.add_parser("show", help="render + open the HTML knowledge graph")
+    s.add_argument("--no-open", action="store_true", help="just write the file")
+    s.set_defaults(func=_cmd_show)
+
+    l = sub.add_parser("list", help="list learned concepts in the terminal")
+    l.add_argument("-v", "--verbose", action="store_true")
+    l.set_defaults(func=_cmd_list)
+
+    sub.add_parser("stats", help="summary counts").set_defaults(func=_cmd_stats)
+
+    h = sub.add_parser("hook", help="(internal) Stop-hook entry point")
+    h.set_defaults(func=_cmd_hook)
+    w = sub.add_parser("_worker", help=argparse.SUPPRESS)
+    w.add_argument("job")
+    w.set_defaults(func=_cmd_worker)
+
+    return p
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 0
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

learnlance/config.py

@@ -0,0 +1,76 @@
+"""Configuration + on-disk paths for learnlance.
+
+Everything lives under ~/.learnlance (override with LEARNLANCE_HOME).
+No third-party dependencies anywhere in this package on purpose: the hook must
+run reliably in whatever environment Claude Code launches it in.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+HOME = Path(os.environ.get("LEARNLANCE_HOME", str(Path.home() / ".learnlance")))
+CONFIG_PATH = HOME / "config.json"
+GRAPH_PATH = HOME / "graph.json"
+HTML_PATH = HOME / "graph.html"
+STATE_PATH = HOME / "state.json"
+INSIGHTS_DIR = HOME / "insights"
+WORK_DIR = HOME / "work"
+LOG_PATH = HOME / "learnlance.log"
+
+DEFAULTS = {
+    "enabled": True,
+    # How insights are generated:
+    #   "cli" -> shell out to the `claude` CLI you're already logged into
+    #            (NO API key needed — uses your Claude Code subscription auth).
+    #   "api" -> direct Anthropic API call (needs an API key).
+    "backend": "cli",
+    "claude_bin": "",  # path to the `claude` executable ("" => auto-detect on PATH)
+    "cli_model": "",  # optional model alias for the CLI (e.g. "haiku"); "" => default
+    # Used only by the "api" backend:
+    "model": "claude-haiku-4-5-20251001",
+    "api_key": "",  # empty => fall back to ANTHROPIC_API_KEY env var
+    "max_topics_per_turn": 5,
+    "background": True,  # run the work detached so Claude Code stays snappy
+    "min_chars": 40,  # skip trivial edits (renames, one-liners) to save calls
+    "max_input_chars": 14000,  # cap the code we send per turn
+}
+
+# Env flag set on any `claude` process we spawn, so the Stop hook it fires can
+# recognize it's a learnlance-triggered call and bail instead of recursing.
+REENTRY_FLAG = "LEARNLANCE_ACTIVE"
+
+
+def ensure_home() -> None:
+    HOME.mkdir(parents=True, exist_ok=True)
+    INSIGHTS_DIR.mkdir(parents=True, exist_ok=True)
+    WORK_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def load_config() -> dict:
+    cfg = dict(DEFAULTS)
+    if CONFIG_PATH.exists():
+        try:
+            cfg.update(json.loads(CONFIG_PATH.read_text(encoding="utf-8")))
+        except Exception:
+            pass
+    return cfg
+
+
+def save_config(cfg: dict) -> None:
+    ensure_home()
+    CONFIG_PATH.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+
+
+def get_api_key(cfg: dict) -> str:
+    return (cfg.get("api_key") or "").strip() or os.environ.get("ANTHROPIC_API_KEY", "").strip()
+
+
+def log(msg: str) -> None:
+    try:
+        ensure_home()
+        with LOG_PATH.open("a", encoding="utf-8") as fh:
+            fh.write(msg.rstrip() + "\n")
+    except Exception:
+        pass

learnlance/graph.py

@@ -0,0 +1,208 @@
+"""Persistent knowledge graph. Nodes = concepts you've encountered, edges =
+relationships between them. Stored as a single JSON file so it's easy to inspect,
+back up, or version.
+
+Connectivity model — how the graph stays "one connected web" instead of islands:
+  * related    : the model names adjacent/umbrella concepts for each topic. If a
+                 related concept isn't a node yet we add a light placeholder;
+                 when you later actually learn it, the placeholder is upgraded in
+                 place, so separately-learned clusters fuse at that shared node.
+  * co-occurs  : concepts learned in the same turn are linked.
+  * shared-tag : every concept carries tags; a new concept links to EXISTING
+                 concepts (from any past session) that share a tag. This is what
+                 connects the graph globally, based on relatedness.
+Each unordered pair has exactly one edge, whose `type` is the strongest relation
+seen and whose `weight` grows each time the relationship is reinforced.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from . import config
+
+# Stronger relation wins the edge's displayed type; weight still accumulates.
+_PRIORITY = {"co-occurs": 3, "related": 2, "shared-tag": 1}
+# Cap how many existing same-tag neighbours a new concept links to per tag,
+# so a popular tag doesn't turn the graph into a hairball.
+_MAX_TAG_NEIGHBOURS = 3
+
+
+def slug(name: str) -> str:
+    s = re.sub(r"[^a-z0-9]+", "-", (name or "").lower()).strip("-")
+    return s or "unknown"
+
+
+def _norm_tag(tag: str) -> str:
+    return slug(tag)
+
+
+def load(path: Path | None = None) -> dict:
+    path = path or config.GRAPH_PATH
+    if path.exists():
+        try:
+            g = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            g = {}
+    else:
+        g = {}
+    g.setdefault("nodes", {})
+    g.setdefault("edges", [])
+    g.setdefault("sessions", {})
+    g.setdefault("tag_index", {})
+    g.setdefault("meta", {"turns": 0})
+    return g
+
+
+def save(graph: dict, path: Path | None = None) -> None:
+    path = path or config.GRAPH_PATH
+    config.ensure_home()
+    path.write_text(json.dumps(graph, indent=2), encoding="utf-8")
+
+
+# --------------------------------------------------------------------------- #
+# edges
+# --------------------------------------------------------------------------- #
+def _pair_key(a: str, b: str) -> str:
+    return "::".join(sorted((a, b)))
+
+
+def _find_edge(graph: dict, a: str, b: str) -> dict | None:
+    key = _pair_key(a, b)
+    for e in graph["edges"]:
+        if _pair_key(e["source"], e["target"]) == key:
+            return e
+    return None
+
+
+def _link(graph: dict, a: str, b: str, etype: str, tag: str | None = None) -> None:
+    if a == b or a not in graph["nodes"] or b not in graph["nodes"]:
+        return
+    e = _find_edge(graph, a, b)
+    if e is None:
+        graph["edges"].append({
+            "source": a, "target": b, "type": etype, "weight": 1,
+            "tags": ([tag] if tag else []),
+        })
+        return
+    e["weight"] = e.get("weight", 1) + 1
+    if _PRIORITY.get(etype, 0) > _PRIORITY.get(e.get("type", "related"), 0):
+        e["type"] = etype
+    if tag and tag not in e.setdefault("tags", []):
+        e["tags"].append(tag)
+
+
+# --------------------------------------------------------------------------- #
+# nodes / tags
+# --------------------------------------------------------------------------- #
+def _placeholder(nid: str, name: str, when: str) -> dict:
+    return {
+        "id": nid, "name": name, "category": "other", "level": "",
+        "explanation": "", "count": 0, "first_seen": when, "last_seen": when,
+        "examples": [], "tags": [], "placeholder": True,
+    }
+
+
+def _register_tags(graph: dict, nid: str, tags: list[str]) -> list[str]:
+    """Add node to the tag index; return the normalized tags."""
+    norm = []
+    for t in tags:
+        nt = _norm_tag(t)
+        if not nt:
+            continue
+        norm.append(nt)
+        bucket = graph["tag_index"].setdefault(nt, [])
+        if nid not in bucket:
+            bucket.append(nid)
+    return norm
+
+
+def update(graph: dict, insights: dict, context: dict) -> list[str]:
+    """Merge one turn's insights into the graph. Returns names of NEW topics."""
+    when = context.get("when", "")
+    session = context.get("session", "")
+    cwd = context.get("cwd", "")
+    files = context.get("files", [])
+    did = insights.get("did", "")
+
+    graph["meta"]["turns"] = graph.get("meta", {}).get("turns", 0) + 1
+
+    new_names: list[str] = []
+    touched_ids: list[str] = []
+
+    for t in insights.get("topics", []):
+        name = (t.get("name") or "").strip()
+        if not name:
+            continue
+        nid = slug(name)
+        node = graph["nodes"].get(nid)
+        was_placeholder = bool(node and node.get("placeholder"))
+        if node is None or was_placeholder:
+            if node is None:
+                new_names.append(name)
+                node = _placeholder(nid, name, when)
+                graph["nodes"][nid] = node
+            # Upgrade placeholder -> real concept (fuses clusters at this node).
+            node["placeholder"] = False
+            node["category"] = t.get("category", node.get("category", "other"))
+            node["level"] = t.get("level", node.get("level", ""))
+
+        node["count"] += 1
+        node["last_seen"] = when
+        if len(t.get("explanation", "")) > len(node.get("explanation", "")):
+            node["explanation"] = t.get("explanation", "")
+
+        # tags: union over time, and index for cross-session linking
+        incoming = _register_tags(graph, nid, t.get("tags", []) or [])
+        node_tags = node.setdefault("tags", [])
+        for nt in incoming:
+            if nt not in node_tags:
+                node_tags.append(nt)
+
+        node["examples"] = (node.get("examples", []) + [{
+            "did": did, "why_here": t.get("why_here", ""),
+            "files": files, "when": when, "session": session,
+        }])[-8:]
+
+        touched_ids.append(nid)
+
+        # 1) explicit related concepts (create light placeholders as needed)
+        for rel in t.get("related", []) or []:
+            rname = (rel or "").strip()
+            if not rname:
+                continue
+            rid = slug(rname)
+            if rid not in graph["nodes"]:
+                graph["nodes"][rid] = _placeholder(rid, rname, when)
+            _link(graph, nid, rid, "related")
+
+        # 2) shared-tag links to EXISTING concepts across all past sessions
+        linked_this_node: set[str] = set()
+        for nt in incoming:
+            bucket = graph["tag_index"].get(nt, [])
+            # prefer the most-reinforced existing real neighbours
+            neighbours = [
+                b for b in bucket
+                if b != nid and not graph["nodes"].get(b, {}).get("placeholder")
+            ]
+            neighbours.sort(key=lambda b: -graph["nodes"].get(b, {}).get("count", 0))
+            for b in neighbours[:_MAX_TAG_NEIGHBOURS]:
+                if b in linked_this_node:
+                    continue
+                linked_this_node.add(b)
+                _link(graph, nid, b, "shared-tag", tag=nt)
+
+    # 3) concepts learned together this turn
+    for i in range(len(touched_ids)):
+        for j in range(i + 1, len(touched_ids)):
+            _link(graph, touched_ids[i], touched_ids[j], "co-occurs")
+
+    if session:
+        s = graph["sessions"].setdefault(session, {"cwd": cwd, "topics": [], "first": when})
+        s["last"] = when
+        for nid in touched_ids:
+            if nid not in s["topics"]:
+                s["topics"].append(nid)
+
+    return new_names

learnlance/hook.py

@@ -0,0 +1,192 @@
+"""Stop-hook entry point. Reads the hook JSON from stdin, and (by default) hands
+the slow API work to a detached background process so Claude Code never waits.
+
+Rule #1: this must NEVER break the user's Claude Code session. Everything is
+wrapped so we always exit 0, no matter what goes wrong.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+
+from . import config, graph, insights, transcript, viz
+
+
+def _now() -> str:
+    return _dt.datetime.now().isoformat(timespec="seconds")
+
+
+def _load_state() -> dict:
+    if config.STATE_PATH.exists():
+        try:
+            return json.loads(config.STATE_PATH.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+    return {}
+
+
+def _save_state(state: dict) -> None:
+    config.ensure_home()
+    config.STATE_PATH.write_text(json.dumps(state), encoding="utf-8")
+
+
+def run_hook() -> None:
+    """Invoked as `learnlance hook` from Claude Code's Stop hook."""
+    # Re-entry guard: the CLI backend launches a headless `claude`, which fires
+    # its own Stop hook. Bail immediately so we never recurse.
+    if os.environ.get(config.REENTRY_FLAG):
+        return
+
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return  # nothing usable on stdin
+
+    cfg = config.load_config()
+    if not cfg.get("enabled", True):
+        return
+
+    if not _backend_ready(cfg):
+        return
+
+    if cfg.get("background", True):
+        _spawn_worker(payload)
+    else:
+        process(payload)
+
+
+def _backend_ready(cfg: dict) -> bool:
+    """Check the configured backend can actually run; log why if not."""
+    backend = cfg.get("backend", "cli")
+    if backend == "api":
+        if not config.get_api_key(cfg):
+            config.log(f"[{_now()}] skipped: backend=api but no API key configured")
+            return False
+        return True
+    # cli backend
+    if not insights.resolve_claude_bin(cfg):
+        config.log(f"[{_now()}] skipped: backend=cli but `claude` not found on PATH")
+        return False
+    return True
+
+
+def _spawn_worker(payload: dict) -> None:
+    """Write the payload to a temp file and launch a detached worker process."""
+    try:
+        config.ensure_home()
+        job = config.WORK_DIR / f"job-{uuid.uuid4().hex}.json"
+        job.write_text(json.dumps(payload), encoding="utf-8")
+        cmd = [sys.executable, "-m", "learnlance", "_worker", str(job)]
+        kwargs: dict = {
+            "stdin": subprocess.DEVNULL,
+            "stdout": subprocess.DEVNULL,
+            "stderr": subprocess.DEVNULL,
+            "cwd": str(Path(__file__).resolve().parent.parent),
+        }
+        if os.name == "nt":
+            # DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP
+            kwargs["creationflags"] = 0x00000008 | 0x00000200
+        else:
+            kwargs["start_new_session"] = True
+        subprocess.Popen(cmd, **kwargs)
+    except Exception as e:  # fall back to inline so we still learn something
+        config.log(f"[{_now()}] spawn failed ({e}); running inline")
+        process(payload)
+
+
+def run_worker(job_path: str) -> None:
+    try:
+        payload = json.loads(Path(job_path).read_text(encoding="utf-8"))
+    except Exception:
+        return
+    try:
+        process(payload)
+    finally:
+        try:
+            Path(job_path).unlink()
+        except Exception:
+            pass
+
+
+def process(payload: dict) -> None:
+    """The actual work: parse transcript -> insights -> graph -> html."""
+    try:
+        cfg = config.load_config()
+        if not _backend_ready(cfg):
+            return
+        api_key = config.get_api_key(cfg)
+
+        tpath = payload.get("transcript_path", "")
+        session = payload.get("session_id", "") or "unknown"
+        cwd = payload.get("cwd", "")
+        if not tpath:
+            return
+
+        state = _load_state()
+        sstate = state.get(session, {})
+        since = sstate.get("last_uuid")
+
+        entries = transcript.read_entries(tpath)
+        if not entries:
+            return
+        gen = transcript.collect_new_generation(entries, since)
+
+        # Always advance the cursor so we never reprocess the same turn.
+        state[session] = {"last_uuid": gen["last_uuid"], "updated": _now()}
+        _save_state(state)
+
+        edits = gen["edits"]
+        total_chars = sum(len(e["code"]) for e in edits)
+        if not edits or total_chars < int(cfg.get("min_chars", 40)):
+            config.log(f"[{_now()}] {session[:8]}: no substantive code this turn, skipped")
+            return
+
+        blob = transcript.build_input_blob(gen, int(cfg.get("max_input_chars", 14000)))
+        result = insights.generate(cfg, api_key, blob)
+        if not result.get("topics"):
+            config.log(f"[{_now()}] {session[:8]}: nothing learnable")
+            return
+
+        g = graph.load()
+        files = sorted({e["file"] for e in edits})
+        new_names = graph.update(
+            g, result,
+            {"when": _now(), "session": session, "cwd": cwd, "files": files},
+        )
+        graph.save(g)
+        viz.render_html(g)
+        _write_recap(session, result, new_names, cwd)
+
+        # Best-effort: shown in Claude Code transcript view.
+        names = ", ".join(t["name"] for t in result["topics"])
+        print(f"🧠 learnlance: {result.get('did','')} — learned/reinforced: {names}")
+    except Exception as e:  # never surface a failure to the user's session
+        config.log(f"[{_now()}] ERROR in process: {e!r}")
+
+
+def _write_recap(session: str, result: dict, new_names: list, cwd: str) -> None:
+    try:
+        md = config.INSIGHTS_DIR / f"{session}.md"
+        lines = []
+        if not md.exists():
+            lines.append(f"# Learning recap — session `{session[:12]}`\n")
+            if cwd:
+                lines.append(f"_Project: {cwd}_\n")
+        lines.append(f"\n## {_now()}\n")
+        lines.append(f"**What happened:** {result.get('did','')}\n")
+        for t in result["topics"]:
+            tag = " 🌱 *new*" if t["name"] in new_names else ""
+            lines.append(f"\n### {t['name']}{tag}  \n`{t.get('category','')}` · `{t.get('level','')}`\n")
+            lines.append(f"{t.get('explanation','')}\n")
+            if t.get("why_here"):
+                lines.append(f"> _Here:_ {t['why_here']}\n")
+        with md.open("a", encoding="utf-8") as fh:
+            fh.write("\n".join(lines) + "\n")
+    except Exception as e:
+        config.log(f"[{_now()}] recap write failed: {e!r}")