research-diff 0.1.0__py3-none-any.whl

research_diff/extract.py

@@ -0,0 +1,327 @@
+"""A research project's state as one JSON-able dict, read from markers in its own files.
+
+THE MARKERS. One grammar, wherever it is written:
+
+    H2: A larger batch helps on small datasets        <- a definition: an id (Q, H, E, R or C and a number) and a title
+    answers: Q1                                       <- links, on the lines right after it
+    status: supported
+
+In Markdown the definition may be a heading or a list item. In LaTeX it goes in a comment (`% C1: …`), and the claim's
+paragraph gives its sources (`\\cite{…}`). In a script, notebook or config it is a comment: `# research-diff: E5 tests
+H2`. A YAML/JSON/TOML config may instead carry a `research:` block: `{id: E5, tests: [H2], results: out/e5.json}`;
+the results file (JSON or CSV) becomes the result `E5.results` with its numbers as metrics.
+
+The map is built from markers only, so the same files give the same map. `research-diff suggest` asks an LLM to
+propose markers for what is untagged; it never writes them.
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import re
+import tomllib
+from collections import defaultdict
+from pathlib import PurePosixPath
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from system_diff.config import segment_rx
+from system_diff.extract import glob_rx
+
+RELS = {"answers": "answers", "tests": "tests", "of": "of", "supports": "supports", "weakens": "weakens",
+        "relies on": "relies on", "relies": "relies on", "depends on": "relies on", "based on": "relies on"}
+ATTRS = ("status", "metrics", "results", "sources", "source", "expects")
+KEYS = "|".join(sorted(list(RELS) + list(ATTRS), key=len, reverse=True))
+ATTR_RX = re.compile(rf"^\s*(?:[-*+]\s+)?\**({KEYS})\**\s*:\s*(.+?)\s*$", re.I)
+COMMENT_RX = re.compile(r"(?:#|//|%)\s*research-diff:\s*(.+)$", re.M)
+CITE_RX = re.compile(r"\\(?:cite[pt]?|citeauthor|citeyear)\*?(?:\[[^\]]*\])*\{([^}]+)\}")
+NUM_RX = re.compile(r"^-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?$")
+
+
+def _def_rx(kinds: Dict[str, str]) -> re.Pattern:
+    letters = "".join(sorted(kinds))
+    return re.compile(rf"^\s*(?:#+\s*|[-*+]\s+|>\s*)*\**([{letters}]\d+[a-z]?)\**\s*[:.)\u2014-]\s*(.+?)\s*$")
+
+
+def _ids(text: str, kinds: Dict[str, str]) -> List[str]:
+    letters = "".join(sorted(kinds))
+    return re.findall(rf"\b([{letters}]\d+[a-z]?(?:\.results)?)\b", text)
+
+
+def _metrics(text: str) -> Dict[str, float]:
+    out = {}
+    for part in re.split(r"[,;]", text):
+        if "=" in part or ":" in part:
+            k, v = re.split(r"[=:]", part, maxsplit=1)
+            v = v.strip().rstrip("%")
+            if NUM_RX.match(v):
+                out[k.strip()] = float(v)
+    return out
+
+
+class Model:
+    """Nodes, links and warnings as they are read; first definition names a node, later ones add to it."""
+
+    def __init__(self, kinds: Dict[str, str]):
+        self.kinds = kinds
+        self.nodes: Dict[str, dict] = {}
+        self.links: set = set()
+
+    def node(self, nid: str, title: str = "", where: str = "") -> dict:
+        kind = "result" if "." in nid else self.kinds.get(nid[0], "note")   # E1.results, E1.mlflow.ab12cd34
+        n = self.nodes.setdefault(nid, {"kind": kind, "title": "", "status": "", "files": [], "metrics": {},
+                                        "sources": []})
+        if title and not n["title"]:
+            n["title"] = title
+        if where and where not in n["files"]:
+            n["files"].append(where)
+        return n
+
+    def attr(self, nid: str, key: str, value: str, where: str) -> None:
+        key = key.lower()
+        n = self.node(nid, where=where)
+        if key in RELS:
+            for target in _ids(value, self.kinds):
+                self.links.add((nid, RELS[key], target))
+        elif key == "status":
+            n["status"] = value.strip().lower().rstrip(".")
+        elif key == "metrics":
+            n["metrics"].update(_metrics(value))
+        elif key == "expects":
+            n.setdefault("expects", []).append(value.strip())
+        elif key in ("sources", "source"):
+            n["sources"] = sorted(set(n["sources"]) | {s.strip() for s in re.split(r"[,;]", value) if s.strip()})
+
+
+def read_lines(m: Model, lines: Iterable[str], where: str, def_rx: re.Pattern) -> List[Tuple[str, int, int]]:
+    """Definitions and their attribute lines. Returns (id, first line, last line) of each definition."""
+    found: List[Tuple[str, int, int]] = []
+    current: Optional[str] = None
+    for i, line in enumerate(lines, 1):
+        if not line.strip():
+            continue  # a heading is usually followed by a blank line before its `status:` and links
+        d = def_rx.match(line)
+        a = ATTR_RX.match(line)
+        if d and not a:
+            current = d.group(1)
+            m.node(current, d.group(2).strip(" *"), where)
+            found.append((current, i, i))
+        elif a and current:
+            m.attr(current, a.group(1), a.group(2), where)
+            found[-1] = (found[-1][0], found[-1][1], i)
+        elif line.lstrip().startswith("#") and current:
+            current = None   # a new heading ends the definition's attributes
+    return found
+
+
+def read_comment(m: Model, text: str, where: str, def_rx: re.Pattern) -> None:
+    """`research-diff: E5 tests H2` / `research-diff: E5: title` / `research-diff: status: done` in a comment."""
+    last: Optional[str] = None
+    for body in COMMENT_RX.findall(text):
+        d = def_rx.match(body)
+        rel = re.match(rf"^([A-Za-z]\d+[a-z]?)\s+({'|'.join(RELS)})\s+(.+)$", body.strip(), re.I)
+        if rel:
+            last = rel.group(1)
+            m.node(last, where=where)
+            m.attr(last, rel.group(2), rel.group(3), where)
+        elif d:
+            last = d.group(1)
+            m.node(last, d.group(2), where)
+        elif last:
+            a = ATTR_RX.match(body)
+            if a:
+                m.attr(last, a.group(1), a.group(2), where)
+
+
+def _mini_yaml_block(text: str) -> Optional[dict]:
+    """The `research:` block of a YAML file: one level of `key: value` (lists as [a, b] or `- a` lines)."""
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        m = re.match(r"^(\s*)research\s*:\s*$", line)
+        if not m:
+            continue
+        indent, out, key = len(m.group(1)), {}, None
+        for nxt in lines[i + 1:]:
+            if not nxt.strip() or nxt.lstrip().startswith("#"):
+                continue
+            ind = len(nxt) - len(nxt.lstrip())
+            if ind <= indent:
+                break
+            item = re.match(r"^\s*-\s*(.+)$", nxt)
+            kv = re.match(r"^\s*([A-Za-z_ ]+?)\s*:\s*(.*)$", nxt)
+            if item and key:
+                out.setdefault(key, [])
+                if isinstance(out[key], list):
+                    out[key].append(item.group(1).strip().strip("'\""))
+            elif kv:
+                key, val = kv.group(1).strip(), kv.group(2).strip()
+                if val.startswith("[") and val.endswith("]"):
+                    out[key] = [x.strip().strip("'\"") for x in val[1:-1].split(",") if x.strip()]
+                elif val:
+                    out[key] = val.strip("'\"")
+        return out
+    return None
+
+
+def config_block(text: str, path: str) -> Optional[dict]:
+    try:
+        if path.endswith(".json"):
+            data = json.loads(text)
+            return data.get("research") if isinstance(data, dict) and isinstance(data.get("research"), dict) else None
+        if path.endswith(".toml"):
+            data = tomllib.loads(text)
+            return data.get("research") if isinstance(data.get("research"), dict) else None
+    except (ValueError, tomllib.TOMLDecodeError):
+        return None
+    return _mini_yaml_block(text)
+
+
+def read_results(text: str, path: str) -> Dict[str, float]:
+    """The numbers of a results file: a JSON object (nested keys joined by '.') or a CSV's last row."""
+    out: Dict[str, float] = {}
+    if path.endswith(".json"):
+        try:
+            data = json.loads(text)
+        except ValueError:
+            return {}
+
+        def walk(prefix: str, v: Any) -> None:
+            if isinstance(v, bool):
+                return
+            if isinstance(v, (int, float)):
+                out[prefix] = float(v)
+            elif isinstance(v, dict):
+                for k, x in v.items():
+                    walk(f"{prefix}.{k}" if prefix else str(k), x)
+        walk("", data)
+    elif path.endswith((".csv", ".tsv")):
+        rows = list(csv.DictReader(io.StringIO(text), delimiter="\t" if path.endswith(".tsv") else ","))
+        for k, v in (rows[-1] if rows else {}).items():
+            if k and v and NUM_RX.match(v.strip()):
+                out[k.strip()] = float(v)
+    return out
+
+
+def _resolve(base: str, ref: str, files: set) -> Optional[str]:
+    for cand in (str(PurePosixPath(base).parent / ref), ref):
+        norm = str(PurePosixPath(cand))
+        parts: List[str] = []
+        for p in norm.split("/"):
+            if p == "..":
+                if parts:
+                    parts.pop()
+            elif p and p != ".":
+                parts.append(p)
+        joined = "/".join(parts)
+        if joined in files:
+            return joined
+    return None
+
+
+def extract(source, cfg: Dict[str, Any]) -> dict:
+    """The research map of one source (a commit, a snapshot of the working tree, or a folder)."""
+    kinds = cfg["kinds"]
+    def_rx = _def_rx(kinds)
+    skip = segment_rx(cfg["skip"])
+    ignore = [glob_rx(p) for p in cfg.get("ignore", [])]
+    files = [f for f in source.files if not skip.search(f) and not any(r.match(f) for r in ignore)]
+    fileset = set(source.files)
+    pick = lambda globs: [f for f in files if any(glob_rx(g).match(f) for g in globs)]  # noqa: E731
+    m = Model(kinds)
+    warnings: List[str] = []
+
+    for f, text in source.read_many(pick(cfg["notes"])).items():
+        read_lines(m, text.splitlines(), f, def_rx)
+    for f, text in source.read_many(pick(cfg["paper"])).items():
+        lines = text.splitlines()
+        comments = [(re.search(r"(?<!\\)%(.*)$", ln) or [None, ""])[1] for ln in lines]
+        for nid, first, last in read_lines(m, comments, f, def_rx):
+            # A claim's sources: the citations of the paragraph its marker sits in.
+            lo = first
+            while lo > 1 and lines[lo - 2].strip():
+                lo -= 1
+            hi = last
+            while hi < len(lines) and lines[hi].strip():
+                hi += 1
+            cites = {k.strip() for ln in lines[lo - 1:hi] for ks in CITE_RX.findall(ln) for k in ks.split(",")}
+            if cites:
+                n = m.node(nid)
+                n["sources"] = sorted(set(n["sources"]) | cites)
+    for f, text in source.read_many(pick(cfg["scripts"]) + pick(cfg["configs"])).items():
+        read_comment(m, text, f, def_rx)
+        block = config_block(text, f) if f in pick(cfg["configs"]) else None
+        if not block or not block.get("id"):
+            continue
+        nid = str(block["id"])
+        m.node(nid, str(block.get("title") or ""), f)
+        for key in ("tests", "answers", "relies on", "supports", "weakens"):
+            val = block.get(key) or block.get(key.replace(" ", "_"))
+            if val:
+                m.attr(nid, key, ", ".join(val) if isinstance(val, list) else str(val), f)
+        if block.get("status"):
+            m.attr(nid, "status", str(block["status"]), f)
+        for ref in ([block["results"]] if isinstance(block.get("results"), str) else block.get("results") or []):
+            path = _resolve(f, ref, fileset)
+            if path is None:
+                warnings.append(f"{nid}: results file {ref} is not in the repository")
+                continue
+            r = m.node(f"{nid}.results", "", path)   # its box shows the file under the id
+            r["metrics"].update(read_results(source.read(path), path))
+            m.links.add((f"{nid}.results", "of", nid))
+
+    from .trackers import run_nodes
+    for f, text in source.read_many([x for x in cfg.get("runs", []) if x in fileset]).items():
+        for run in run_nodes(text):
+            rid = f"{run['experiment']}.{run['source']}.{str(run['run'])[:8]}"
+            r = m.node(rid, str(run.get("name") or ""), f)
+            r["metrics"].update({k: float(v) for k, v in (run.get("metrics") or {}).items()})
+            m.links.add((rid, "of", run["experiment"]))
+
+    nodes = m.nodes
+    for src, rel, dst in sorted(m.links):
+        if dst not in nodes:
+            warnings.append(f"{src} {rel} {dst}, which is not defined anywhere")
+    by = defaultdict(list)
+    for src, rel, dst in m.links:
+        by[(rel, dst)].append(src)
+        by[(src, rel)].append(dst)
+    for nid, n in sorted(nodes.items()):
+        if n["kind"] == "experiment" and not by[(nid, "tests")]:
+            warnings.append(f"{nid} tests no hypothesis")
+        if n["kind"] == "hypothesis" and not by[("tests", nid)] and n["status"] in ("", "open"):
+            warnings.append(f"{nid} is open and no experiment tests it")
+        if n["kind"] == "claim":
+            basis = by[(nid, "relies on")] + by[("supports", nid)]
+            if not basis:
+                warnings.append(f"{nid} relies on nothing: no result or hypothesis backs it")
+            for b in by[(nid, "relies on")]:
+                if nodes.get(b, {}).get("status") == "refuted":
+                    warnings.append(f"{nid} relies on {b}, which is refuted")
+            for w in by[("weakens", nid)]:
+                warnings.append(f"{nid} is weakened by {w}")
+        for e in n.get("expects", []):
+            warnings += check_expect(nid, e, nodes)
+    return {"ref": source.label, "nodes": {k: nodes[k] for k in sorted(nodes, key=_order)},
+            "links": [list(x) for x in sorted(m.links)], "warnings": sorted(set(warnings))}
+
+
+def _order(nid: str) -> tuple:
+    m = re.match(r"([A-Za-z])(\d+)([a-z]?)(.*)", nid)
+    return ("QHERC".find(m.group(1)), int(m.group(2)), m.group(3), m.group(4)) if m else (9, 0, "", nid)
+
+
+EXPECT_RX = re.compile(r"^(\S+)\s+(\S+)\s*(>=|<=|==|>|<)\s*(-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?)\s*$")
+OPS = {">": lambda a, b: a > b, ">=": lambda a, b: a >= b, "<": lambda a, b: a < b, "<=": lambda a, b: a <= b,
+       "==": lambda a, b: abs(a - b) < 1e-12}
+
+
+def check_expect(nid: str, expect: str, nodes: Dict[str, dict]) -> List[str]:
+    """`expects: E1.results acc.b32 > 0.85` on a claim: a warning when the number is missing or does not meet it."""
+    m = EXPECT_RX.match(expect)
+    if not m:
+        return [f"{nid}: cannot read `expects: {expect}` (write: RESULT METRIC > NUMBER)"]
+    target, metric, op, want = m.group(1), m.group(2), m.group(3), float(m.group(4))
+    got = nodes.get(target, {}).get("metrics", {}).get(metric)
+    if got is None:
+        return [f"{nid} expects {target} {metric} {op} {want:g}, but {target} has no {metric}"]
+    return [] if OPS[op](got, want) else [f"{nid} expects {target} {metric} {op} {want:g}, but it is {got:g}"]

research_diff/graph.py

@@ -0,0 +1,94 @@
+"""The research map and diff as pictures, drawn by system-diff's renderer: a column per kind (questions, hypotheses,
+experiments, results, claims), a blue band on what is supported, a dashed box around what is refuted, and lines for
+what links to what: grey for links, blue for supports, amber for weakens."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from system_diff import pictures
+
+EDGE_KIND = {"supports": "data", "weakens": "network"}
+LEGEND = [("band", "new", "supported"), ("dashed", "", "refuted"),
+          ("line", "call", "links"), ("line", "data", "supports"), ("line", "network", "weakens")]
+
+
+def _node(nid: str, n: dict, status: str = "") -> dict:
+    sub = " · ".join(x for x in (n["status"], f"{len(n['sources'])} sources" if n["sources"] else "") if x)
+    lines = [{"text": f"{k} = {v:.4g}", "code": True} for k, v in list(n["metrics"].items())[:4]]
+    style = "new" if n["status"] == "supported" else "legacy" if n["status"] == "refuted" else ""
+    node = {"id": nid, "col": n["kind"], "title": f"{nid} {n['title']}".strip(), "sub": sub or (n["files"][0] if n["files"] else ""),
+            "type": "store" if n["kind"] == "result" else "component", "style": style, "lines": lines}
+    if status:
+        node["status"] = status
+    return node
+
+
+def map_graph(bp: dict, cfg: Dict[str, Any]) -> dict:
+    nodes = [_node(k, n) for k, n in bp["nodes"].items() if n["kind"] in {c[0] for c in cfg["picture"]["columns"]}]
+    ids = {n["id"] for n in nodes}
+    edges = [{"from": s, "to": t, "kind": EDGE_KIND.get(r, "call")} for s, r, t in bp["links"] if s in ids and t in ids]
+    styles = {n["style"] for n in nodes}
+    kinds = {e["kind"] for e in edges}
+    legend = [x for x in LEGEND if (x[0] == "band" and "new" in styles) or (x[0] == "dashed" and "legacy" in styles)
+              or (x[0] == "line" and x[1] in kinds)]
+    warn = bp.get("warnings") or []
+    return {"columns": cfg["picture"]["columns"], "nodes": nodes, "edges": edges, "legend": legend,
+            "footer": [f"{len(warn)} warning{'' if len(warn) == 1 else 's'}: " + "; ".join(warn[:3])
+                       + (" …" if len(warn) > 3 else "")] if warn else []}
+
+
+def map_svg(bp: dict, cfg: Dict[str, Any]) -> str:
+    return pictures.map_svg(map_graph(bp, cfg), label="Research map")
+
+
+def diff_graph(d: dict, a: dict, b: dict, cfg: Dict[str, Any]) -> Optional[dict]:
+    """What changed, lit, with the ideas it links to beside it; None when nothing changed."""
+    status: Dict[str, str] = {}
+    lines: Dict[str, List[dict]] = {}
+    links_changed: Dict[tuple, str] = {}
+    word = {"add": "added", "remove": "removed", "change": "changed"}
+    for c in d["changes"]:
+        op = word[c["op"]]
+        if c["entity"] in ("question", "hypothesis", "experiment", "result", "claim"):
+            status[c["id"]] = op
+        elif c["entity"] in ("status", "title"):
+            status.setdefault(c["id"], "changed")
+            if c["entity"] == "status":
+                lines.setdefault(c["id"], []).append({"text": c["label"].split(": ", 1)[1], "status": "changed"})
+        elif c["entity"] == "metric":
+            nid = c["id"].split(" ", 1)[0]
+            status.setdefault(nid, "changed")
+            lines.setdefault(nid, []).append({"text": c["label"].split(" ", 1)[1], "code": True, "status": op})
+        elif c["entity"] == "link":
+            s, rest = c["id"].split(" ", 1)
+            rel, t = rest.rsplit(" ", 1)
+            links_changed[(s, rel, t)] = op
+    hot = set(status) | {x for (s, _r, t) in links_changed for x in (s, t)}
+    if not hot:
+        return None
+    both = {**a["nodes"], **b["nodes"]}
+    near = set(hot)
+    for s, r, t in b["links"]:
+        if s in hot or t in hot:
+            near |= {s, t}
+    nodes = []
+    for nid in both:
+        if nid in near and both[nid]["kind"] in {c[0] for c in cfg["picture"]["columns"]}:
+            n = _node(nid, both[nid], status.get(nid, "same"))
+            if nid in lines:
+                n["lines"] = lines[nid]
+            nodes.append(n)
+    ids = {n["id"] for n in nodes}
+    edges = [{"from": s, "to": t, "kind": EDGE_KIND.get(r, "call"), "status": op}
+             for (s, r, t), op in links_changed.items() if s in ids and t in ids]
+    seen = {(e["from"], e["to"]) for e in edges}
+    edges += [{"from": s, "to": t, "kind": EDGE_KIND.get(r, "call"), "status": "same"} for s, r, t in b["links"]
+              if s in ids and t in ids and (s, t) not in seen]
+    new_w = [c["id"] for c in d["changes"] if c["entity"] == "warning" and c["op"] == "add"]
+    return {"columns": cfg["picture"]["columns"], "nodes": nodes, "edges": edges,
+            "footer": ["New warning: " + "; ".join(new_w)] if new_w else []}
+
+
+def diff_svg(d: dict, a: dict, b: dict, cfg: Dict[str, Any]) -> Optional[str]:
+    g = diff_graph(d, a, b, cfg)
+    return pictures.map_svg(g, diff=True, label="Research diff") if g else None

research_diff/mcp_server.py

@@ -0,0 +1,112 @@
+"""`research-diff mcp`: research-diff as an MCP server over stdio (extra: pip install "research-diff[mcp]").
+
+research_map and research_diff read; log_result writes a result marker into the research log (a Markdown file in the
+repository, so it is on the map, in git, and in the next diff); checkpoint marks what the person has understood."""
+from __future__ import annotations
+
+import re
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from system_diff.pictures import write_if_changed
+from system_diff.sources import git, repo_root
+
+from . import compare as cmp
+from . import graph
+
+try:  # the MCP SDK's 2.x name; 1.x called it FastMCP
+    from mcp.server.mcpserver import MCPServer as Server
+except ImportError:  # pragma: no cover
+    from mcp.server.fastmcp import FastMCP as Server
+
+INSTRUCTIONS = (
+    "research-diff keeps a map of this research: questions (Q), hypotheses (H), experiments (E), results (R) and claims "
+    "(C), from markers in the notes, configs, scripts and paper. After an iteration, call research_diff and tell the "
+    "person what changed, from its plan only. Record an experiment's outcome with log_result. Call checkpoint only "
+    "when the person says they have understood the current state."
+)
+LOG = "research/log.md"
+
+
+def _out(root: Path) -> Path:
+    d = Path(git("rev-parse", "--absolute-git-dir", cwd=root).strip()) / "research-diff" / "mcp"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def tool_map(root: Path, at: str = ".") -> Dict[str, Any]:
+    bp, cfg, label = cmp.read(root, at)
+    path = _out(root) / "research.svg"
+    write_if_changed(path, graph.map_svg(bp, cfg))
+    return {"of": label, "picture": str(path), "warnings": bp["warnings"],
+            "nodes": [{"id": k, "kind": n["kind"], "title": n["title"], "status": n["status"], "metrics": n["metrics"]}
+                      for k, n in bp["nodes"].items()],
+            "links": [" ".join(x) for x in bp["links"]]}
+
+
+def tool_diff(root: Path, base: str = "checkpoint", head: str = ".") -> Dict[str, Any]:
+    if head == ".":
+        cmp.sync_trackers(root)
+    c = cmp.compare(root, base, head)
+    svg = graph.diff_svg(c.diff, c.before, c.after, c.cfg)
+    path = _out(root) / "diff.svg"
+    if svg:
+        write_if_changed(path, svg)
+    elif path.is_file():
+        path.unlink()
+    return {"from": c.base, "headline": c.diff["headline"], "plan": c.diff["plan"], "changes": len(c.diff["changes"]),
+            "warnings": c.diff["warnings"], "picture": str(path) if svg else None}
+
+
+def tool_log(root: Path, experiment: str, metrics: Dict[str, float], title: str = "", supports: List[str] = (),
+             weakens: List[str] = (), note: str = "", log: str = LOG) -> Dict[str, Any]:
+    bp, _cfg, _ = cmp.read(root, ".")
+    taken = [int(m.group(1)) for k in bp["nodes"] for m in [re.match(r"R(\d+)$", k)] if m]
+    rid = f"R{max(taken, default=0) + 1}"
+    lines = [f"## {rid}: {title or 'a run of ' + experiment} ({time.strftime('%Y-%m-%d')})", "", f"of: {experiment}",
+             "metrics: " + ", ".join(f"{k}={v:g}" for k, v in metrics.items())]
+    lines += [f"supports: {', '.join(supports)}"] if supports else []
+    lines += [f"weakens: {', '.join(weakens)}"] if weakens else []
+    lines += ["", note] if note else []
+    path = root / log
+    path.parent.mkdir(parents=True, exist_ok=True)
+    before = path.read_text(encoding="utf-8") if path.is_file() else "# Research log\n\nResults, newest last. Written by research-diff's log_result.\n"
+    with open(path, "w", encoding="utf-8", newline="\n") as f:
+        f.write(before.rstrip("\n") + "\n\n" + "\n".join(lines) + "\n")
+    return {"recorded": rid, "in": log}
+
+
+def build() -> Server:
+    server = Server("research-diff", instructions=INSTRUCTIONS)
+
+    @server.tool()
+    def research_map(at: str = ".") -> Dict[str, Any]:
+        """Every question, hypothesis, experiment, result and claim, their statuses, metrics and links, the open
+        warnings, and the picture's path. `at`: a commit, or "." for the working tree."""
+        return tool_map(repo_root(), at)
+
+    @server.tool()
+    def research_diff(base: str = "checkpoint", head: str = ".") -> Dict[str, Any]:
+        """What changed in the research from `base` ("checkpoint": what the person last marked as understood) to
+        `head` ("." the working tree): one sentence, the exact plan, new warnings and the picture's path."""
+        return tool_diff(repo_root(), base, head)
+
+    @server.tool()
+    def log_result(experiment: str, metrics: Dict[str, float], title: str = "", supports: Optional[List[str]] = None,
+                   weakens: Optional[List[str]] = None, note: str = "") -> Dict[str, Any]:
+        """Record what an experiment produced, as a result marker in research/log.md: its metrics, and the hypotheses
+        or claims it supports or weakens. Only for a run that actually happened."""
+        return tool_log(repo_root(), experiment, metrics, title, supports or [], weakens or [], note)
+
+    @server.tool()
+    def checkpoint(ref: str = "") -> Dict[str, Any]:
+        """Mark the working tree (or `ref`) as understood by the person. Only when they say so."""
+        sha = cmp.checkpoint(repo_root(), ref or None)
+        return {"checkpoint": sha[:9]}
+
+    return server
+
+
+def main() -> None:
+    build().run("stdio")

research_diff/readme.py

@@ -0,0 +1,38 @@
+"""The README's generated research map: the picture, and the warnings that stand open."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from system_diff.pictures import write_if_changed
+
+from . import compare, graph
+
+
+def section(bp: dict, cfg: dict) -> str:
+    r = cfg["readme"]
+    warn = "".join(f"- {w}\n" for w in bp["warnings"])
+    return (f"{r['begin']}\n![Research map, generated from the notes, configs, results and paper]({r['image'] or r['svg']})\n\n"
+            + (f"<details><summary>{len(bp['warnings'])} open warning{'' if len(bp['warnings']) == 1 else 's'}"
+               f"</summary>\n\n{warn}\n</details>\n" if warn else "")
+            + f"{r['end']}")
+
+
+def run(root: Path, config_path: Optional[str] = None, check: bool = False) -> int:
+    bp, cfg, _ = compare.read(root, ".", config_path)
+    r = cfg["readme"]
+    path, image = root / r["file"], root / r["svg"]
+    text = path.read_text(encoding="utf-8")
+    if r["begin"] not in text or r["end"] not in text:
+        print(f"{path} has no {r['begin']} … {r['end']} section: add the two lines where the map goes")
+        return 1
+    start, end = text.index(r["begin"]), text.index(r["end"]) + len(r["end"])
+    new_text, svg = text[:start] + section(bp, cfg) + text[end:], graph.map_svg(bp, cfg)
+    if check:
+        current = new_text == text and image.is_file() and image.read_text(encoding="utf-8") == svg
+        print("README research map " + ("is current" if current else "is out of date"))
+        return 0 if current else 1
+    image.parent.mkdir(parents=True, exist_ok=True)
+    changed = write_if_changed(image, svg) | write_if_changed(path, new_text)
+    print("README research map " + ("updated" if changed else "already current"))
+    return 0