codegraph-network 0.1.0__py3-none-any.whl

codegraph/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

codegraph/bench.py

@@ -0,0 +1,93 @@
+"""`codegraph bench`: does the graph answer real tasks cheaper than reading files, and does semantic
+search find symbols that lexical search misses?
+
+Tasks file (YAML, or JSON which is a subset of it):
+
+    - task: "where do we check a user's credentials on login"
+      expect: [authenticate_user, auth.py:Session.open]
+
+`expect` entries are anything `context()` accepts (name, qualname or file:name). Per task we measure
+  recall      share of expected symbols inside the top-k results, lexical-only vs hybrid
+  tokens      what an agent reads with the graph (the hybrid search output plus context() of every
+              expected symbol it found) vs reading every file that contains an expected symbol
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .indexer import index_repo
+from .queries import Graph, toks
+
+
+@dataclass
+class TaskResult:
+    task: str
+    expected: int
+    unresolved: list[str] = field(default_factory=list)
+    lexical_found: int = 0
+    hybrid_found: int = 0
+    graph_tokens: int = 0
+    file_tokens: int = 0
+
+
+def load_tasks(path: str | Path) -> list[dict]:
+    text = Path(path).read_text()
+    try:
+        import yaml
+        data = yaml.safe_load(text)
+    except ImportError:
+        try:
+            data = json.loads(text)
+        except ValueError as e:
+            raise SystemExit("bench: reading YAML needs PyYAML (pip install 'codegraph[bench]'); "
+                             f"as JSON the file failed to parse: {e}") from None
+    if not isinstance(data, list) or not all(isinstance(t, dict) and "task" in t for t in data):
+        raise SystemExit("bench: the tasks file must be a list of {task: ..., expect: [symbols]}")
+    return data
+
+
+def run_task(g: Graph, spec: dict, k: int) -> TaskResult:
+    expect = [str(e) for e in spec.get("expect") or []]
+    res = TaskResult(str(spec["task"]), len(expect))
+    wanted: dict[str, set[int]] = {}
+    for e in expect:
+        rows = g._find(e)
+        if rows:
+            wanted[e] = {r["id"] for r in rows}
+        else:
+            res.unresolved.append(e)
+    lex_ids = {r["id"] for r in g._search_rows(res.task, k)}
+    hyb = g._hybrid_rows(res.task, k)
+    hyb_ids = {r["id"] for r, _ in hyb}
+    res.lexical_found = sum(1 for ids in wanted.values() if ids & lex_ids)
+    found = [e for e, ids in wanted.items() if ids & hyb_ids]
+    res.hybrid_found = len(found)
+    res.graph_tokens = toks(g.search(res.task, k)) + sum(toks(g.context(e)) for e in found)
+    files = {r["file"] for ids in wanted.values() for r in g._rows_by_id(ids)}
+    res.file_tokens = g._file_tokens(files)
+    return res
+
+
+def run(root: str | Path, tasks_path: str | Path, k: int = 10) -> str:
+    index_repo(root)
+    g = Graph(root)
+    try:
+        semantic = g._semantic() is not None
+        results = [run_task(g, t, k) for t in load_tasks(tasks_path)]
+    finally:
+        g.close()
+    out = [f"codegraph bench  top-{k}  semantic index: {'yes' if semantic else 'NO (hybrid == lexical)'}", ""]
+    for r in results:
+        out.append(f"- {r.task}")
+        out.append(f"    recall   lexical {r.lexical_found}/{r.expected}   hybrid {r.hybrid_found}/{r.expected}"
+                   f"   tokens graph ~{r.graph_tokens} vs files ~{r.file_tokens}")
+        if r.unresolved:
+            out.append(f"    not in index: {', '.join(r.unresolved)}")
+    exp = sum(r.expected - len(r.unresolved) for r in results) or 1
+    lex, hyb = sum(r.lexical_found for r in results), sum(r.hybrid_found for r in results)
+    gt, ft = sum(r.graph_tokens for r in results), sum(r.file_tokens for r in results)
+    out += ["", f"recall   lexical {lex}/{exp} ({lex / exp:.0%})   hybrid {hyb}/{exp} ({hyb / exp:.0%})",
+            f"tokens   graph ~{gt} vs reading files ~{ft}" + (f"  ({ft / gt:.1f}x fewer)" if gt else "")]
+    return "\n".join(out)

codegraph/cli.py

@@ -0,0 +1,128 @@
+"""Command line front end. Argument parsing is derived from the shared tool registry."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .indexer import index_repo
+from .install import PLATFORMS, hook_install, hook_uninstall, install, uninstall
+from .queries import Graph
+from .tools import CLI_ALIASES, CLI_FLAGS, TOOLS
+
+# 0 answered, 3 the name matches several symbols, 4 it matches none: scripts can branch without parsing text
+EXIT_CODES = {"ok": 0, "ambiguous": 3, "missing": 4}
+
+# the reindex tool is presented under a friendlier name
+CLI_NAME = {"reindex": "index"}
+
+
+def _cli_name(tool_name: str) -> str:
+    return CLI_NAME.get(tool_name, tool_name)
+
+
+# every spelling a tool answers to on the command line
+CLI_SPELLINGS = {t.name: (_cli_name(t.name), *CLI_ALIASES.get(t.name, ())) for t in TOOLS}
+
+
+def _cli_name(tool_name: str) -> str:
+    return CLI_NAME.get(tool_name, tool_name)
+
+
+def _tool_for(spelling: str):
+    for tool in TOOLS:
+        if spelling in CLI_SPELLINGS[tool.name]:
+            return tool
+    raise KeyError(spelling)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="codegraph",
+        description="Graph-based code understanding for LLMs",
+        epilog="run 'codegraph <tool> --help' for the arguments of one tool")
+    ap.add_argument("-r", "--root", default=".", help="repository root (default: cwd)")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("serve", help="run the MCP server over stdio")
+    bench = sub.add_parser("bench", help="measure tokens and recall (lexical vs hybrid) on a tasks file")
+    bench.add_argument("tasks", help="YAML/JSON list of {task: ..., expect: [symbols]}")
+    bench.add_argument("-k", type=int, default=10, help="results per search (default 10)")
+
+    inst = sub.add_parser("install", help="wire codegraph into coding assistants (skill, MCP config, guidance)")
+    inst.add_argument("platform", nargs="?", default="all", choices=(*PLATFORMS, "all"),
+                      help="which assistant to configure (default: all)")
+    inst.add_argument("--no-hooks", action="store_true", help="skip the Claude Code Glob|Grep hint hook")
+    inst.add_argument("--uninstall", action="store_true", help="remove what install wrote")
+    hk = sub.add_parser("hook", help="keep the index fresh from git: post-commit/checkout/merge hooks")
+    hk.add_argument("action", choices=("install", "uninstall"))
+
+    for tool in TOOLS:
+        spellings = CLI_SPELLINGS[tool.name]
+        p = sub.add_parser(spellings[0], aliases=spellings[1:],
+                           help=tool.summary, description=tool.summary)
+        for param in tool.params:
+            if param.default is None:
+                p.add_argument("value", help=param.help or param.name)
+                continue
+            flag, short = CLI_FLAGS.get(param.name, (param.name, None))
+            opts = [f"--{flag}"] + ([short] if short else [])
+            if param.type == "bool":
+                p.add_argument(*opts, action="store_true", help=param.help)
+            elif param.type == "int":
+                p.add_argument(*opts, type=int, default=param.default, help=param.help)
+            else:
+                p.add_argument(*opts, default=param.default, help=param.help)
+    return ap
+
+
+def _kwargs(tool, args) -> dict:
+    out = {}
+    for param in tool.params:
+        if param.default is None:
+            out[param.name] = args.value
+            continue
+        flag = CLI_FLAGS.get(param.name, (param.name, None))[0]
+        v = getattr(args, flag.replace("-", "_"))
+        out[param.name] = int(v) if param.type == "int" and v is not None else v
+    return out
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+
+    if args.cmd == "serve":
+        from .server import main as serve
+        return serve(args.root)
+
+    if args.cmd == "bench":
+        from .bench import run as bench
+        print(bench(args.root, args.tasks, args.k))
+        return None
+
+    if args.cmd in ("install", "hook"):
+        if args.cmd == "hook":
+            lines = (hook_install if args.action == "install" else hook_uninstall)(args.root)
+        elif args.uninstall:
+            lines = uninstall(args.root)
+        else:
+            lines = install(args.root, args.platform, hooks=not args.no_hooks)
+        print("\n".join(lines))
+        return None
+
+    if args.cmd == "index":
+        print(json.dumps(index_repo(args.root, args.force), indent=2, sort_keys=True))
+        return None
+
+    index_repo(args.root)  # cheap when nothing changed
+    tool = _tool_for(args.cmd)
+    graph = Graph(args.root)
+    graph.status = "ok"
+    try:
+        print(getattr(graph, tool.name)(**_kwargs(tool, args)))
+        return EXIT_CODES[graph.status]
+    finally:
+        graph.close()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codegraph/community.py

@@ -0,0 +1,77 @@
+"""Community detection over the structural graph: groups of symbols that belong together.
+
+Weighted label propagation, stdlib only. Leiden/Louvain give slightly better modularity but need a
+dependency (igraph/networkx); for "which cluster is this symbol in" label propagation is enough, runs
+in near-linear time and is deterministic (fixed visiting order, ties broken by smallest label).
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+
+CONF_WEIGHT = {"extracted": 1.0, "inferred": 0.6, "ambiguous": 0.25}
+_FRESH = 1 << 40  # label space for nodes with no previous community
+MIN_SIZE = 3  # smaller groups are folded into the neighbouring community they connect to most
+MAX_SWEEPS = 12
+
+
+def label_propagation(nodes: list[int], edges: list[tuple[int, int, float]],
+                      hub_degree: int = 200, init: dict[int, int] | None = None) -> dict[int, int]:
+    """Return {node: community id}. Nodes with more than `hub_degree` neighbours (utility hubs such as
+    a logger) vote for nobody and are not voted for, so they cannot glue unrelated areas together."""
+    adj: dict[int, dict[int, float]] = defaultdict(lambda: defaultdict(float))
+    for a, b, w in edges:
+        if a != b:
+            adj[a][b] += w
+            adj[b][a] += w
+    hubs = {n for n, nb in adj.items() if len(nb) > hub_degree}
+    order = sorted(nodes, key=lambda n: (-len(adj.get(n, ())), n))  # dense areas settle first
+    if init:  # warm start: keep last run's grouping, new nodes start alone (offset avoids clashes)
+        label = {n: init[n] if init.get(n, -1) >= 0 else _FRESH + n for n in nodes}
+    else:
+        label = {n: n for n in nodes}
+    for _ in range(MAX_SWEEPS):
+        moved = 0
+        for n in order:
+            if n in hubs or n not in adj:
+                continue
+            votes: dict[int, float] = defaultdict(float)
+            for m, w in adj[n].items():
+                if m not in hubs:
+                    votes[label[m]] += w
+            if not votes:
+                continue
+            best = min(votes, key=lambda lb: (-votes[lb], lb))
+            if best != label[n] and votes[best] > votes.get(label[n], 0.0):
+                label[n] = best
+                moved += 1
+        if not moved:
+            break
+    # fold tiny groups into their strongest neighbour, then renumber 0..k-1 by size
+    size: dict[int, int] = defaultdict(int)
+    for lb in label.values():
+        size[lb] += 1
+    for n in order:
+        if size[label[n]] < MIN_SIZE and n in adj:
+            votes = defaultdict(float)
+            for m, w in adj[n].items():
+                if size[label[m]] >= MIN_SIZE:
+                    votes[label[m]] += w
+            if votes:
+                size[label[n]] -= 1
+                label[n] = min(votes, key=lambda lb: (-votes[lb], lb))
+                size[label[n]] += 1
+    ranked = sorted({lb for lb in label.values()}, key=lambda lb: (-size[lb], lb))
+    renum = {lb: i for i, lb in enumerate(ranked)}
+    return {n: renum[lb] for n, lb in label.items()}
+
+
+def detect(db) -> dict:
+    """Assign symbols.community from the edge table. Singletons (no edges) get -1."""
+    ids = [r[0] for r in db.execute("SELECT id FROM symbols")]
+    edges = [(s, d, CONF_WEIGHT.get(c, 0.6)) for s, d, c in db.execute("SELECT src, dst, conf FROM edges")]
+    prev = {r[0]: r[1] for r in db.execute("SELECT id, community FROM symbols")}
+    label = label_propagation(ids, edges, init=prev)
+    linked = {x for a, b, _ in edges for x in (a, b)}
+    db.executemany("UPDATE symbols SET community=? WHERE id=?",
+                   [(label[i] if i in linked else -1, i) for i in ids])
+    return {"communities": len({label[i] for i in linked}), "linked_symbols": len(linked)}

codegraph/docs.py

@@ -0,0 +1,141 @@
+"""Non-code inputs: Markdown, SQL schemas and (with the `pdf` extra) PDFs.
+
+Static like the code parser: no LLM, nothing leaves the machine. Each document becomes symbols the
+rest of the graph already understands, so search, outline, PageRank and communities work on them:
+
+  - Markdown heading  -> `section`, nested by heading level; `code spans` in its body become
+                         `mentions` edges to the code symbols they name
+  - SQL CREATE ...    -> `table` / `view` / `function` / `procedure`; FROM / JOIN / REFERENCES
+                         inside the statement become `mentions` edges to other SQL objects
+  - PDF page          -> `section` carrying the page text (line numbers are page numbers)
+"""
+from __future__ import annotations
+
+import importlib.util
+import io
+import re
+
+from .parser import Parsed, Sym
+
+DOC_EXT = {".md": "markdown", ".markdown": "markdown", ".sql": "sql"}
+if importlib.util.find_spec("pypdf"):
+    DOC_EXT[".pdf"] = "pdf"
+DOC_LANGS = frozenset(DOC_EXT.values())
+
+HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
+FENCE = re.compile(r"^\s*(```|~~~)")
+CODE_SPAN = re.compile(r"`([^`\n]+)`")
+DOTTED = re.compile(r"[A-Za-z_]\w*(?:(?:\.|::|->)[A-Za-z_]\w*)*")
+MD_LINK = re.compile(r"\]\(([^)#\s]+)(?:#[^)]*)?\)")
+
+SQL_CREATE = re.compile(
+    r"\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:(?:GLOBAL\s+|LOCAL\s+)?(?:TEMP|TEMPORARY)\s+|MATERIALIZED\s+)?"
+    r"(TABLE|VIEW|FUNCTION|PROCEDURE)\s+(?:IF\s+NOT\s+EXISTS\s+)?([\w.\"`\[\]]+)", re.I)
+SQL_REF = re.compile(r"\b(?:FROM|JOIN|REFERENCES|INTO|UPDATE)\s+([\w.\"`\[\]]+)", re.I)
+SQL_COMMENT = re.compile(r"--[^\n]*|/\*.*?\*/", re.S)
+SQL_KEYWORDS = frozenset("select set values lateral unnest generate_series".split())
+MIN_MENTION = 3  # shorter names are noise (`i`, `db`) and would link to anything
+PDF_TEXT = 2000  # characters of a page kept as its searchable doc
+
+
+def _first_line(text: str, n: int = 200) -> str:
+    for line in text.splitlines():
+        line = line.strip()
+        if line:
+            return line[:n]
+    return ""
+
+
+def _mentions(text: str) -> list[str]:
+    """Identifiers named in `code spans`. `Store.resolve()` yields Store and resolve."""
+    out: dict[str, None] = {}
+    for span in CODE_SPAN.findall(text):
+        for dotted in DOTTED.findall(span):
+            for part in re.split(r"\.|::|->", dotted):
+                if len(part) >= MIN_MENTION:
+                    out[part] = None
+    return list(out)
+
+
+def parse_markdown(src: bytes, stem: str) -> Parsed:
+    lines = src.decode("utf-8", errors="replace").splitlines()
+    heads: list[tuple[int, int, str]] = []  # (line, level, title)
+    in_fence = False
+    for n, line in enumerate(lines, 1):
+        if FENCE.match(line):
+            in_fence = not in_fence
+        elif not in_fence and (m := HEADING.match(line)):
+            heads.append((n, len(m.group(1)), m.group(2)))
+    p = Parsed()
+    stack: list[tuple[int, Sym]] = []  # (level, symbol) of the open ancestors
+    for k, (n, level, title) in enumerate(heads):
+        while stack and stack[-1][0] >= level:
+            stack.pop()
+        # a section runs until the next heading of the same or a higher level
+        end = next((m - 1 for m, lv, _ in heads[k + 1:] if lv <= level), len(lines))
+        parent = stack[-1][1] if stack else None
+        body = "\n".join(lines[n:end])
+        sym = Sym(id=k, name=title, qualname=f"{parent.qualname} > {title}" if parent else title,
+                  kind="section", start=n, end=max(end, n), sig="#" * level + " " + title,
+                  doc=_first_line(body), parent=parent.id if parent else None)
+        p.syms.append(sym)
+        stack.append((level, sym))
+        p.refs.extend((k, name, "mentions") for name in _mentions(body))
+    # relative links to other files: resolved against the file set like an import
+    p.imports.extend(dict.fromkeys(MD_LINK.findall("\n".join(lines))))
+    return p
+
+
+def _strip_sql_comments(text: str) -> str:
+    """Blank comments but keep newlines, so line numbers still match the file."""
+    return SQL_COMMENT.sub(lambda m: re.sub(r"[^\n]", " ", m.group(0)), text)
+
+
+def _sql_name(raw: str) -> str:
+    return re.sub(r"[\"`\[\]]", "", raw).rsplit(".", 1)[-1]
+
+
+def parse_sql(src: bytes, stem: str) -> Parsed:
+    text = _strip_sql_comments(src.decode("utf-8", errors="replace"))
+    total = text.count("\n") + 1
+    found = list(SQL_CREATE.finditer(text))
+    p = Parsed()
+    for k, m in enumerate(found):
+        name = _sql_name(m.group(2))
+        start = text.count("\n", 0, m.start()) + 1
+        stop = found[k + 1].start() if k + 1 < len(found) else len(text)
+        # ponytail: a statement runs to the next CREATE; `;` inside $$ bodies makes `;` unusable.
+        # Trailing ALTER / INSERT statements attach to the object above them.
+        body = text[m.end():stop]
+        end = max(start, start + text.count("\n", m.start(), stop) - (1 if stop < len(text) else 0))
+        kind = m.group(1).lower()
+        p.syms.append(Sym(id=k, name=name, qualname=name, kind=kind, start=start, end=min(end, total),
+                          sig=" ".join(m.group(0).split()), doc="", parent=None))
+        seen = {name}
+        for r in SQL_REF.finditer(body):
+            ref = _sql_name(r.group(1))
+            if ref.lower() not in SQL_KEYWORDS and ref not in seen and len(ref) >= 2:
+                seen.add(ref)
+                p.refs.append((k, ref, "mentions"))
+    return p
+
+
+def parse_pdf(src: bytes, stem: str) -> Parsed:
+    from pypdf import PdfReader  # optional extra, see DOC_EXT
+
+    p = Parsed()
+    for n, page in enumerate(PdfReader(io.BytesIO(src)).pages, 1):
+        text = " ".join((page.extract_text() or "").split())
+        if not text:
+            continue
+        title = f"{stem} p{n}: {text[:60]}"
+        p.syms.append(Sym(id=len(p.syms), name=title, qualname=title, kind="section", start=n, end=n,
+                          sig=f"page {n}", doc=text[:PDF_TEXT], parent=None))
+    return p
+
+
+PARSERS = {"markdown": parse_markdown, "sql": parse_sql, "pdf": parse_pdf}
+
+
+def parse_doc(src: bytes, lang: str, stem: str) -> Parsed:
+    return PARSERS[lang](src, stem)

codegraph/embed.py

@@ -0,0 +1,221 @@
+"""Optional semantic layer: local embeddings of symbols, a content-hash vector cache and "similar" links.
+
+Everything here is optional. Without numpy and an embedding provider (`pip install codegraph[embed]`),
+`load_embedder()` returns None and the rest of codegraph behaves exactly as it does without this module.
+
+No network at query time: the default provider runs a small local ONNX model through fastembed (the
+model files are downloaded once, on first indexing). Providers sit behind the tiny `Embedder` protocol,
+so another backend is a class with three members, selected with CODEGRAPH_EMBED=module:factory.
+"""
+from __future__ import annotations
+
+import hashlib
+import importlib
+import importlib.util
+import os
+from typing import Protocol
+
+from .links import is_test_path
+from .store import TARGET_KINDS_CALL, Store, split_words
+
+DEFAULT_MODEL = "BAAI/bge-small-en-v1.5"
+TEXT_VERSION = "1"  # bump when symbol_text() changes: every cached vector is then recomputed
+EMBED_KINDS = tuple(sorted(TARGET_KINDS_CALL))  # variables / fields / modules are noise, not concepts
+BATCH = 128
+SIM_K = 5  # neighbours per symbol
+SIM_THRESHOLD = 0.85  # cosine; tuned on this repo's own code (bge-small): below it, mostly generic noise
+SIM_CHUNK = 256  # rows of the similarity matrix computed at once: bounds memory at chunk x N floats
+
+
+class Embedder(Protocol):
+    """What codegraph needs from an embedding backend. Vectors must be L2-normalised float32."""
+
+    name: str  # identifies model + settings; part of every cache key, so changing it re-embeds
+
+    def embed_passages(self, texts: list[str]): ...  # -> ndarray (len(texts), dim)
+
+    def embed_query(self, text: str): ...  # -> ndarray (dim,)
+
+
+class FastEmbedder:
+    """fastembed / ONNX. The model is loaded on first use, so a no-change reindex never pays for it."""
+
+    def __init__(self, model: str = DEFAULT_MODEL):
+        self.name = f"fastembed:{model}"
+        self._model_name = model
+        self._model = None
+
+    def _load(self):
+        if self._model is None:
+            from fastembed import TextEmbedding
+            self._model = TextEmbedding(self._model_name)
+        return self._model
+
+    def embed_passages(self, texts):
+        import numpy as np
+        return np.asarray(list(self._load().passage_embed(texts)), dtype=np.float32)
+
+    def embed_query(self, text):
+        import numpy as np
+        return np.asarray(next(iter(self._load().query_embed([text]))), dtype=np.float32)
+
+
+def load_embedder() -> Embedder | None:
+    """The configured provider, or None when semantic search is unavailable or switched off.
+
+    CODEGRAPH_EMBED: unset / "fastembed" (default), "off", or "package.module:factory".
+    CODEGRAPH_EMBED_MODEL picks another fastembed model.
+    """
+    spec = os.environ.get("CODEGRAPH_EMBED", "fastembed").strip()
+    if spec.lower() in ("off", "0", "none", "false", ""):
+        return None
+    if importlib.util.find_spec("numpy") is None:
+        return None
+    if ":" in spec:
+        mod, _, attr = spec.partition(":")
+        return getattr(importlib.import_module(mod), attr)()
+    if importlib.util.find_spec("fastembed") is None:
+        return None
+    return FastEmbedder(os.environ.get("CODEGRAPH_EMBED_MODEL", DEFAULT_MODEL))
+
+
+def symbol_text(r) -> str:
+    """What gets embedded: the name as words, the qualified name, the signature and the doc line."""
+    parts = [r["kind"], split_words(r["name"]), r["qualname"], r["sig"] or "", r["doc"] or ""]
+    return ". ".join(p for p in parts if p)[:400]
+
+
+def text_hash(embedder: Embedder, text: str) -> str:
+    return hashlib.sha1(f"{TEXT_VERSION}|{embedder.name}|{text}".encode()).hexdigest()
+
+
+def _ph(n: int) -> str:
+    return ",".join("?" * n)
+
+
+def embed_pending(store: Store, embedder: Embedder, progress=None) -> list[int]:
+    """Embed every symbol that has no vector yet; vectors already cached by content are reused.
+    Returns the ids of the symbols that were newly linked to a vector."""
+    import numpy as np
+    db = store.db
+    if store.get_meta("embed_model") != embedder.name:  # other model: nothing cached is comparable
+        db.execute("DELETE FROM sym_vec")
+        db.execute("DELETE FROM links WHERE kind='similar'")
+        store.set_meta("embed_model", embedder.name)
+    rows = db.execute(
+        f"SELECT s.id, s.name, s.qualname, s.kind, s.sig, s.doc FROM symbols s "
+        f"LEFT JOIN sym_vec v ON v.sym_id = s.id WHERE v.sym_id IS NULL AND s.kind IN ({_ph(len(EMBED_KINDS))})",
+        EMBED_KINDS).fetchall()
+    if not rows:
+        return []
+    hashes = [text_hash(embedder, symbol_text(r)) for r in rows]
+    known: set[str] = set()
+    uniq = list(dict.fromkeys(hashes))
+    for i in range(0, len(uniq), 500):
+        chunk = uniq[i:i + 500]
+        known |= {r[0] for r in db.execute(f"SELECT hash FROM vec_cache WHERE hash IN ({_ph(len(chunk))})", chunk)}
+    todo = {h: symbol_text(r) for r, h in zip(rows, hashes, strict=True) if h not in known}
+    items = list(todo.items())
+    for i in range(0, len(items), BATCH):
+        batch = items[i:i + BATCH]
+        vecs = embedder.embed_passages([t for _, t in batch]).astype(np.float32)
+        db.executemany("INSERT OR REPLACE INTO vec_cache VALUES(?,?)",
+                       [(h, vecs[j].tobytes()) for j, (h, _) in enumerate(batch)])
+        if progress and (i // BATCH) % 10 == 0:
+            progress(f"embedded {min(i + BATCH, len(items))}/{len(items)} symbols")
+    db.executemany("INSERT OR REPLACE INTO sym_vec VALUES(?,?)", [(r["id"], h) for r, h in zip(rows, hashes, strict=True)])
+    db.execute("DELETE FROM vec_cache WHERE hash NOT IN (SELECT hash FROM sym_vec)")
+    store.commit()
+    return [r["id"] for r in rows]
+
+
+def load_matrix(db):
+    """(ids, unit-norm float32 matrix) of every embedded symbol, or (None, None) when there are none."""
+    import numpy as np
+    rows = db.execute("SELECT v.sym_id, c.vec FROM sym_vec v JOIN vec_cache c ON c.hash = v.hash "
+                      "ORDER BY v.sym_id").fetchall()
+    if not rows:
+        return None, None
+    ids = np.fromiter((r[0] for r in rows), dtype=np.int64, count=len(rows))
+    mat = np.vstack([np.frombuffer(r[1], dtype=np.float32) for r in rows])
+    return ids, mat
+
+
+def build_similar(store: Store, k: int = SIM_K, threshold: float = SIM_THRESHOLD,
+                  only: set[int] | None = None) -> int:
+    """Top-k nearest neighbours above `threshold`, as `similar` links. Brute-force cosine, chunked.
+
+    `only` restricts the queries to those symbols (their links are replaced, everyone else's kept),
+    which is what an edit to one file needs; None rebuilds every link.
+
+    Skipped: pairs already tied together by a structural edge (a call or an inheritance says more than
+    "looks alike"), a symbol's own ancestors, same-named overloads, and test-to-test pairs (test names
+    all resemble each other, which tells you nothing).
+    """
+    import numpy as np
+    db = store.db
+    if only is None:
+        db.execute("DELETE FROM links WHERE kind='similar'")
+    ids, mat = load_matrix(db)
+    if ids is None or len(ids) < 2:
+        store.set_meta("similar_n", "0")
+        return 0
+    linked = {(a, b) for a, b in db.execute("SELECT src, dst FROM edges")}
+    linked |= {(b, a) for a, b in linked}
+    info = {r["id"]: (r["parent"], r["file"], r["name"]) for r in db.execute("SELECT id, parent, file, name FROM symbols")}
+
+    def ancestors(i: int) -> set[int]:
+        out, p = set(), info[i][0]
+        while p is not None and p not in out:
+            out.add(p)
+            p = info.get(p, (None,))[0]
+        return out
+
+    seen = {(a, b) if a < b else (b, a) for a, b in db.execute("SELECT src, dst FROM links WHERE kind='similar'")}
+    queries = np.arange(len(ids)) if only is None else np.flatnonzero(np.isin(ids, list(only)))
+    kk = min(k + 1, len(ids))
+    rows = []
+    for start in range(0, len(queries), SIM_CHUNK):
+        qi = queries[start:start + SIM_CHUNK]
+        sims = mat[qi] @ mat.T
+        sims[np.arange(len(qi)), qi] = -1.0  # not its own neighbour
+        top = np.argpartition(-sims, kk - 1, axis=1)[:, :kk]
+        for r, i in enumerate(qi):
+            a = int(ids[i])
+            for j in top[r]:
+                s = float(sims[r, j])
+                b = int(ids[j])
+                key = (a, b) if a < b else (b, a)
+                if s < threshold or key in seen or (a, b) in linked:
+                    continue
+                if info[a][1:] == info[b][1:] or b in ancestors(a) or a in ancestors(b):
+                    continue  # overloads of one name in one file / a class and its own member
+                if is_test_path(info[a][1]) and is_test_path(info[b][1]):
+                    continue
+                seen.add(key)
+                rows.append((key[0], key[1], "similar", s, ""))
+    db.executemany("INSERT INTO links VALUES(?,?,?,?,?)", rows)
+    store.set_meta("similar_n", str(len(ids)))
+    return len(rows)
+
+
+FULL_REBUILD_FRACTION = 0.2  # past this much churn a full pass is cheaper than patching
+
+
+def update(store: Store, progress=None) -> dict:
+    """Bring vectors and `similar` links up to date. Instant when nothing is pending."""
+    embedder = load_embedder()
+    if embedder is None:
+        return {"enabled": False}
+    new_ids = embed_pending(store, embedder, progress)
+    n = store.db.execute("SELECT COUNT(*) FROM sym_vec").fetchone()[0]
+    built = store.get_meta("similar_n")
+    if built is None or len(new_ids) > FULL_REBUILD_FRACTION * max(n, 1):
+        similar = build_similar(store)
+    elif new_ids:
+        similar = build_similar(store, only=set(new_ids))
+    else:
+        store.set_meta("similar_n", str(n))  # deletions only: their links went with the symbols
+        similar = -1  # -1: unchanged
+    store.commit()
+    return {"enabled": True, "model": embedder.name, "embedded": len(new_ids), "vectors": n, "similar": similar}