puremethod 0.1.0__py3-none-any.whl

writer/core.py

@@ -0,0 +1,430 @@
+"""The Writer (06-writer.md): the LLM writes prose; code supplies every number, table,
+figure and citation, and a paper that fails a check is not built (INV-8)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ledger import Ledger
+from llm import LLM, Message
+from purescholar import PureScholar
+
+from .facts import RunFacts, read_facts
+from .latex import assemble, bibliography, disclosure
+from .lint import check_section
+from .macros import Resolver
+from .render import TABLE_SCHEMA, Spec, SpecError, render_figure, render_table
+from .tectonic import DEFAULT_IMAGE, compile_tex
+from .types import BuildResult, PaperOptions, RunContext
+
+ATTEMPTS = 3          # per section, and for compile fixes (§5 steps 5 and 7)
+MAX_SEARCHES = 2      # citation searches the LLM may request per section
+SECTION_TOKENS = 8000  # thinking counts against it on models that always think
+OUTLINE_TOKENS = 2000
+
+SECTION_SCHEMA: dict[str, Any] = {
+    "type": "object", "additionalProperties": False, "required": ["latex"],
+    "properties": {
+        "latex": {"type": "string"},
+        "tables": {"type": "array", "items": TABLE_SCHEMA, "maxItems": 3},
+        "figures": {"type": "array", "items": TABLE_SCHEMA, "maxItems": 3},
+        "searches": {"type": "array", "items": {"type": "string"}, "maxItems": MAX_SEARCHES},
+    },
+}
+OUTLINE_SCHEMA: dict[str, Any] = {
+    "type": "object", "additionalProperties": False, "required": ["title", "sections"],
+    "properties": {
+        "title": {"type": "string"},
+        "sections": {"type": "array", "items": {
+            "type": "object", "additionalProperties": False, "required": ["key", "title"],
+            "properties": {"key": {"type": "string"}, "title": {"type": "string"}}}},
+    },
+}
+FIX_SCHEMA: dict[str, Any] = {
+    "type": "object", "additionalProperties": False, "required": ["sections"],
+    "properties": {"sections": {"type": "object", "additionalProperties": {"type": "string"}}},
+}
+
+RULES = (
+    "Write LaTeX body text only. Rules, checked by code: (1) never write a digit or a "
+    "spelled-out quantity; every number comes from a macro listed in the facts: "
+    "\\pmval{experiment}{metric}, \\pmagg{decision}{metric}, \\pmcmp{decision}, "
+    "\\pmcfg{prereg}{threshold|wall_clock_s|money_usd|seeds}; (2) cite only keys from the "
+    "citation pool, with \\cite{key}; ask for a search if you need another source; (3) put "
+    "tables and figures in only through specs, placed with \\pmtable{id} or \\pmfigure{id}; "
+    "(4) no \\begin{table}, \\includegraphics, \\input, macro definitions or packages; "
+    "(5) use the words 'finding' or 'we find' only where the section is a confirmed finding; "
+    "(6) the digit rule covers names too: write metric names without digits (F-score, not "
+    "F1) and never put run, entry or experiment ids in the text; refer to a hypothesis by "
+    "what it tests; (7) a table or figure spec id uses only letters, digits, _ or -, and "
+    "its metric must be recorded by every decision it lists; a decision with no recorded "
+    "comparison (discarded before it ran) cannot be in a table: describe it in prose."
+)
+
+
+def _last(log: list[str], n: int = 3) -> str:
+    """The last problems, for the reason the user sees (the full log is in `lint_log`)."""
+    return (": " + "; ".join(p[:200] for p in log[-n:])) if log else ""
+
+
+@dataclass
+class _Section:
+    key: str
+    title: str
+    purpose: str
+    allow_findings: bool
+    required_cites: list[str]
+    hypotheses: list[str]
+
+
+class Writer:
+    """Built from a read-only Ledger, an LLM, a PureScholar client and a Tectonic image
+    name (KB-017)."""
+
+    def __init__(self, ledger: Ledger, llm: LLM, purescholar: PureScholar | None,
+                 tectonic_image: str = DEFAULT_IMAGE) -> None:
+        self._ledger = ledger
+        self._llm = llm
+        self._ps = purescholar
+        self._image = tectonic_image
+
+    # ---- interface ---------------------------------------------------------------------
+
+    def build(self, run_id: str, options: PaperOptions, ctx: RunContext) -> BuildResult:
+        facts = read_facts(self._ledger, run_id)
+        pool = dict(facts.citations)
+        sections = self._plan(facts, options)
+        title = self._outline(facts, options, sections, ctx)
+        drafted: dict[str, dict[str, Any]] = {}
+        log: list[str] = []
+        for sec in sections:
+            out, problems = self._draft(facts, options, sec, pool, ctx)
+            log += [f"{sec.key}: {p}" for p in problems]
+            if out is None:
+                return self._failed(f"section {sec.key!r} failed its checks{_last(log)}", log)
+            drafted[sec.key] = out
+        return self._finish(facts, options, title, sections, drafted, pool, ctx, log)
+
+    def revise(self, run_id: str, previous: BuildResult, feedback: list[str],
+               ctx: RunContext) -> BuildResult:
+        """One pass that applies feedback as required changes, then rechecks and compiles."""
+        if not previous.sections:
+            return self._failed("the previous build has no sections to revise", [])
+        facts = read_facts(self._ledger, run_id)
+        saved_opts = json.loads(previous.files["options.json"])
+        options = PaperOptions(**{**saved_opts, "findings": tuple(saved_opts["findings"]),
+                                  "others": tuple(saved_opts["others"])})
+        specs_saved: dict[str, dict[str, Any]] = json.loads(previous.files["specs.json"])
+        pool = dict(facts.citations)
+        sections = self._plan(facts, options)
+        title = str(saved_opts["title"])
+        request = {"feedback": feedback, "sections": previous.sections}
+        reply = self._call(ctx, "Apply every item of the feedback as a required change. "
+                           "Return every section's LaTeX, revised. " + RULES,
+                           LLM.quote(json.dumps(request), "previous paper and feedback"),
+                           FIX_SCHEMA)
+        drafted: dict[str, dict[str, Any]] = {}
+        log: list[str] = []
+        for sec in sections:
+            latex = str(reply["sections"].get(sec.key, previous.sections.get(sec.key, "")))
+            saved = specs_saved.get(sec.key, {})
+            problems = self._check(facts, sec, latex, pool, _specs(saved, facts))
+            if problems:
+                log += [f"{sec.key}: {p}" for p in problems]
+                return self._failed(f"revised section {sec.key!r} failed its checks"
+                                    f"{_last(log)}", log)
+            drafted[sec.key] = {"latex": latex, "tables": list(saved.get("tables", [])),
+                                "figures": list(saved.get("figures", []))}
+        return self._finish(facts, options, title, sections, drafted, pool, ctx, log)
+
+    def bundle(self, run_id: str, build: BuildResult, dest: Path) -> Path:
+        """The run bundle (§4): paper, full ledger export, code, env specs, data sources,
+        citation evidence, README. The ledger export is always included (INV-7)."""
+        dest = Path(dest)
+        if dest.exists() and any(dest.iterdir()):
+            raise FileExistsError(f"{dest} is not empty")
+        facts = read_facts(self._ledger, run_id)
+        paper = dest / "paper"
+        paper.mkdir(parents=True)
+        for name, data in build.files.items():
+            (paper / name).write_bytes(data)
+        self._ledger.export(run_id, dest / "ledger")
+        (dest / "data_sources.json").write_text(json.dumps(facts.data_sources, indent=2),
+                                                encoding="utf-8")
+        used = [facts.citations[k] for k in build.citation_keys if k in facts.citations]
+        (dest / "citations.json").write_text(json.dumps(used, indent=2), encoding="utf-8")
+        (dest / "trace_map.json").write_text(json.dumps(build.trace_map, indent=2),
+                                             encoding="utf-8")
+        (dest / "README.md").write_text(_README.format(status=build.status, run=run_id),
+                                        encoding="utf-8")
+        return dest
+
+    # ---- planning ----------------------------------------------------------------------
+
+    def _plan(self, facts: RunFacts, options: PaperOptions) -> list[_Section]:
+        """The section list is code's, never the LLM's (§5 step 1)."""
+        others = list(options.others)
+        abstract = _Section("abstract", "Abstract", "A short abstract of the whole document.",
+                            options.kind == "paper", [], list(options.findings) + others)
+        if options.kind == "report":
+            return [abstract,
+                _Section("question", "Question", "The research question and why it matters.",
+                         False, [], []),
+                _Section("tried", "What was tried", "Each hypothesis, its baseline and what "
+                         "was run, with a table only for decisions that recorded a "
+                         "comparison.", False, [], others),
+                _Section("stopped", "Why each attempt stopped", "The reason each hypothesis "
+                         "was discarded or left inconclusive.", False, [], others),
+                _Section("conclusion", "Conclusion", "State plainly that no hypothesis was "
+                         "confirmed, and what a next attempt would need.", False, [], []),
+            ]
+        sections = [
+            abstract,
+            _Section("introduction", "Introduction", "The question and the contribution.",
+                     True, [], list(options.findings)),
+            _Section("related", "Related work", "The closest prior work.", False, [], []),
+            _Section("method", "Method", "How hypotheses were tested: pre-registration, staged "
+                     "budgets, baselines run by the system itself.", False, [], []),
+        ]
+        for i, h in enumerate(options.findings, start=1):
+            sections.append(_Section(f"finding{i}", f"Finding {i}", "This confirmed hypothesis, "
+                                     "its evidence and its comparison.", True,
+                                     facts.closest.get(h, [])[:1], [h]))
+        if others:
+            sections.append(_Section("negative", "Negative and exploratory results",
+                                     "Every refuted, inconclusive or discarded hypothesis, "
+                                     "with its reason.", False, [], others))
+        sections.append(_Section("conclusion", "Conclusion", "What was confirmed and its "
+                                 "limits.", True, [], list(options.findings)))
+        return sections
+
+    def _outline(self, facts: RunFacts, options: PaperOptions, sections: list[_Section],
+                 ctx: RunContext) -> str:
+        listing = [{"key": s.key, "title": s.title, "purpose": s.purpose} for s in sections]
+        reply = self._call(ctx, "Propose a paper title and a title for each section. Keep "
+                           "every key, in order; add or remove none. No digits.",
+                           LLM.quote(json.dumps({"idea": facts.idea, "sections": listing}),
+                                     "outline"), OUTLINE_SCHEMA, max_tokens=OUTLINE_TOKENS)
+        titles = {str(s["key"]): str(s["title"]) for s in reply.get("sections", [])}
+        if [s["key"] for s in reply.get("sections", [])] == [s.key for s in sections]:
+            for s in sections:
+                if titles[s.key].strip() and not any(c.isdigit() for c in titles[s.key]):
+                    s.title = titles[s.key].strip()
+        title = str(reply.get("title") or options.title).strip()
+        return title if title and not any(c.isdigit() for c in title) else options.title
+
+    # ---- drafting and checks -----------------------------------------------------------
+
+    def _facts_for(self, facts: RunFacts, sec: _Section, pool: dict[str, Any]
+                   ) -> dict[str, Any]:
+        decisions = [d for d in facts.decisions.values()
+                     if not sec.hypotheses or d.hypothesis in sec.hypotheses]
+        return {
+            "idea": facts.idea,
+            "hypotheses": {h: facts.hypotheses.get(h) for h in sec.hypotheses}
+            or facts.hypotheses,
+            "decisions": [{"decision": d.entry_id, "hypothesis": d.hypothesis,
+                           "stage": d.stage, "outcome": d.outcome,
+                           "reason_code": d.reason_code, "reason": d.reason_text,
+                           "prereg": d.prereg, "experiments": d.experiments,
+                           "metrics": sorted({m["name"] for s in d.experiments
+                                              for m in (facts.experiments[s].metrics
+                                                        if s in facts.experiments else [])})}
+                          for d in decisions],
+            "citation_pool": {k: {"title": r.get("title"), "year": r.get("year"),
+                                  "excerpts": (r.get("excerpts") or [])[:1]}
+                              for k, r in pool.items()},
+            "must_cite": sec.required_cites,
+        }
+
+    def _check(self, facts: RunFacts, sec: _Section, latex: str, pool: dict[str, Any],
+               specs: dict[str, Spec]) -> list[str]:
+        resolver = Resolver(facts)
+        problems = check_section(latex, pool=set(pool), allow_findings=sec.allow_findings,
+                                 required_cites=sec.required_cites,
+                                 macro_problems=resolver.check(latex))
+        for kind, ref in (("table", "\\pmtable{"), ("figure", "\\pmfigure{")):
+            for part in latex.split(ref)[1:]:
+                spec_id = part.split("}", 1)[0]
+                if spec_id not in specs:
+                    problems.append(f"\\pm{kind}{{{spec_id}}} has no spec in this section")
+        return problems
+
+    def _draft(self, facts: RunFacts, options: PaperOptions, sec: _Section,
+               pool: dict[str, Any], ctx: RunContext
+               ) -> tuple[dict[str, Any] | None, list[str]]:
+        log: list[str] = []
+        problems: list[str] = []
+        searched = False
+        for _ in range(ATTEMPTS):
+            data = LLM.quote(json.dumps(self._facts_for(facts, sec, pool)), "run facts")
+            instruction = (f"Write the section '{sec.title}': {sec.purpose} " + RULES +
+                           (" Fix these problems from your previous attempt: "
+                            + "; ".join(problems) if problems else ""))
+            reply = self._call(ctx, instruction, data, SECTION_SCHEMA)
+            if reply.get("searches") and not searched and self._ps is not None:
+                searched = True
+                self._search(list(reply["searches"])[:MAX_SEARCHES], pool, ctx)
+                continue  # redraft with the larger pool
+            specs: dict[str, Spec] = {}
+            problems = []
+            for raw in list(reply.get("tables", [])) + list(reply.get("figures", [])):
+                try:
+                    spec = Spec.parse(raw, facts)
+                    specs[spec.id] = spec
+                except (SpecError, KeyError) as exc:
+                    problems.append(str(exc))
+            latex = str(reply.get("latex", ""))
+            problems += self._check(facts, sec, latex, pool, specs)
+            if not problems:
+                return reply, log
+            log += problems
+        return None, log
+
+    def _search(self, queries: list[str], pool: dict[str, Any], ctx: RunContext) -> None:
+        """§5 step 2: the LLM asks; `writer` searches PureScholar; what resolves joins."""
+        if self._ps is None:
+            return
+        for q in queries:
+            ctx.guard(0.0)  # PureScholar's cost is unmetered (01 §9); time still counts
+            papers, records = asyncio.run(self._ps.search_papers(q, limit=5))
+            cited = []
+            for p in papers:
+                rec = PureScholar.citation_for(p)
+                if not hasattr(rec, "key"):
+                    continue
+                d = dict(rec.__dict__)
+                cited.append(d)
+                pool.setdefault(d["key"], d)
+            for r in records:
+                ctx.record(r, {"request": r.request_body.encode(),
+                               "response": (r.response_body or "").encode()},
+                           citation_records=cited)
+
+    # ---- assembly ----------------------------------------------------------------------
+
+    def _finish(self, facts: RunFacts, options: PaperOptions, title: str,
+                sections: list[_Section], drafted: dict[str, dict[str, Any]],
+                pool: dict[str, Any], ctx: RunContext, log: list[str],
+                fixes_left: int = ATTEMPTS) -> BuildResult:
+        resolver = Resolver(facts)
+        files: dict[str, bytes] = {}
+        body: list[tuple[str, str]] = []
+        abstract = ""
+        for sec in sections:
+            out = drafted[sec.key]
+            latex = str(out["latex"])
+            for raw in list(out.get("tables", [])):
+                spec = Spec.parse(raw, facts)
+                tex, refs = render_table(spec, facts)
+                latex = latex.replace(f"\\pmtable{{{spec.id}}}", tex)
+                resolver.trace_map[f"table:{spec.id}"] = refs
+            for raw in list(out.get("figures", [])):
+                spec = Spec.parse(raw, facts)
+                tex, pdf, refs = render_figure(spec, facts)
+                latex = latex.replace(f"\\pmfigure{{{spec.id}}}", tex)
+                files[f"fig-{spec.id}.pdf"] = pdf
+                resolver.trace_map[f"figure:{spec.id}"] = refs
+            latex = resolver.resolve(latex)
+            if sec.key == "abstract":
+                abstract = latex
+            else:
+                body.append((sec.title, latex))
+        if options.kind == "report":
+            body.append(("Status", "No hypothesis in this run was confirmed. The sections "
+                         "above report what was tried and why each attempt stopped."))
+        from .lint import cite_keys
+
+        used = sorted({k for _, t in body for k in cite_keys(t)})
+        bib = bibliography([pool[k] for k in used if k in pool])
+        tex = assemble(template=options.template, title=title, abstract=abstract,
+                       sections=body, bib=bib,
+                       disclosure_text=disclosure(facts) if options.disclosure else None)
+        files["main.tex"] = tex.encode()
+        files["options.json"] = json.dumps({**options.__dict__, "title": title,
+                                            "findings": list(options.findings),
+                                            "others": list(options.others)}).encode()
+        sections_src = {s.key: str(drafted[s.key]["latex"]) for s in sections}
+        files["specs.json"] = json.dumps(
+            {k: {"tables": list(v.get("tables", [])), "figures": list(v.get("figures", []))}
+             for k, v in drafted.items()}).encode()
+        result = compile_tex(files, self._image)
+        if not result.ok or result.pdf is None:
+            if fixes_left <= 0:
+                failed = self._failed("LaTeX did not compile", log, result.log)
+                failed.files = files
+                return failed
+            fixed = self._call(ctx, "The LaTeX failed to compile. Return every section's "
+                               "LaTeX with the error fixed. " + RULES,
+                               LLM.quote(json.dumps({"error": result.log[-3000:],
+                                                     "sections": sections_src}),
+                                         "compile error and sections"), FIX_SCHEMA)
+            for sec in sections:
+                latex = str(fixed["sections"].get(sec.key, sections_src[sec.key]))
+                specs = _specs(drafted[sec.key], facts)
+                problems = self._check(facts, sec, latex, pool, specs)
+                if problems:  # a fix is checked exactly like a draft (INV-8)
+                    log += [f"{sec.key} (compile fix): {p}" for p in problems]
+                    return self._failed("a compile fix failed the checks", log, result.log)
+                drafted[sec.key] = {**drafted[sec.key], "latex": latex}
+            return self._finish(facts, options, title, sections, drafted, pool, ctx, log,
+                                fixes_left - 1)
+        files["main.pdf"] = result.pdf
+        return BuildResult(status="built", reasons=[], files=files,
+                           trace_map=dict(resolver.trace_map), citation_keys=used,
+                           lint_log=log, compile_log=result.log, sections=sections_src)
+
+    @staticmethod
+    def _failed(reason: str, log: list[str], compile_log: str = "") -> BuildResult:
+        return BuildResult(status="failed", reasons=[reason], files={}, trace_map={},
+                           citation_keys=[], lint_log=log, compile_log=compile_log)
+
+    # ---- LLM calls (INV-6: guard before, record after) -----------------------------------
+
+    def _call(self, ctx: RunContext, instruction: str, data: str, schema: dict[str, Any],
+              max_tokens: int = SECTION_TOKENS) -> dict[str, Any]:
+        messages: list[Message] = [{"role": "system", "content": instruction},
+                                   {"role": "user", "content": data}]
+        ctx.guard(self._llm.max_cost("writer", messages, max_tokens, schema))
+        from llm import LLMError
+
+        try:
+            result = self._llm.complete("writer", messages, max_tokens=max_tokens, schema=schema)
+        except LLMError as exc:
+            for r in exc.records:
+                ctx.record(r, _artifacts(r))
+            raise
+        for r in result.records:
+            ctx.record(r, _artifacts(r))
+        return dict(result.parsed)
+
+
+def _specs(drafted: dict[str, Any], facts: RunFacts) -> dict[str, Spec]:
+    raws = list(drafted.get("tables", [])) + list(drafted.get("figures", []))
+    return {s.id: s for s in (Spec.parse(r, facts) for r in raws)}
+
+
+def _artifacts(record: Any) -> dict[str, bytes]:
+    return {"request": json.dumps(record.request).encode(),
+            "response": (record.response or "").encode()}
+
+
+_README = """# Run bundle
+
+Run: `{run}`. Paper build status: {status}.
+
+| Path | Contents |
+|---|---|
+| `paper/` | LaTeX sources, figures, `main.pdf` when built, `options.json` |
+| `ledger/` | The full run ledger, its referenced artifacts, rejections, chain report |
+| `data_sources.json` | Every pre-registered data set: source, licence, role, digest |
+| `citations.json` | The citation records behind the references, with their evidence |
+| `trace_map.json` | For each number, table and figure, the ledger entries behind it |
+
+Every number in the paper is computed from `ledger/ledger.jsonl`. Code bundles and
+environment specs are artifacts under `ledger/artifacts/`, named by their digests.
+"""

writer/facts.py

@@ -0,0 +1,162 @@
+"""What the ledger says, in the shape the writer needs (06-writer.md §5 step 1).
+
+Everything here is read from ledger entries; nothing comes from an LLM. Experiments carry
+an `arm` field (`treatment` or `baseline`) set by `loop` when it starts them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from statistics import mean, stdev
+from typing import Any
+
+from ledger import Entry, Ledger
+
+
+@dataclass
+class Experiment:
+    started_id: str
+    finished_id: str | None
+    arm: str
+    seed: int | None
+    status: str | None
+    metrics: list[dict[str, Any]]
+    artifacts: dict[str, str]
+
+
+@dataclass
+class Decision:
+    entry_id: str
+    hypothesis: str
+    stage: str
+    outcome: str
+    reason_code: str | None
+    reason_text: str
+    prereg: str | None
+    experiments: list[str]
+    comparison: dict[str, Any]
+
+
+@dataclass
+class RunFacts:
+    run_id: str
+    idea: str
+    entries: dict[str, Entry]
+    hypotheses: dict[str, dict[str, Any]] = field(default_factory=dict)
+    preregs: dict[str, dict[str, Any]] = field(default_factory=dict)
+    experiments: dict[str, Experiment] = field(default_factory=dict)
+    finished_to_started: dict[str, str] = field(default_factory=dict)
+    decisions: dict[str, Decision] = field(default_factory=dict)
+    citations: dict[str, dict[str, Any]] = field(default_factory=dict)  # key -> record
+    closest: dict[str, list[str]] = field(default_factory=dict)  # hypothesis -> cite keys
+    models: dict[str, set[str]] = field(default_factory=dict)    # "provider/model" -> roles
+    data_sources: list[dict[str, Any]] = field(default_factory=list)
+
+    # ---- queries -----------------------------------------------------------------------
+
+    def decision_for(self, hypothesis: str) -> Decision | None:
+        """The last decision recorded for a hypothesis."""
+        found = [d for d in self.decisions.values() if d.hypothesis == hypothesis]
+        return found[-1] if found else None
+
+    def values(self, decision_id: str, metric: str, arm: str,
+               role: str | None = None) -> list[float]:
+        d = self.decisions[decision_id]
+        out: list[float] = []
+        for sid in d.experiments:
+            exp = self.experiments.get(sid)
+            if exp is None or exp.arm != arm:
+                continue
+            for m in exp.metrics:
+                if m["name"] == metric and (role is None or m["data_role"] == role):
+                    out.append(float(m["value"]))
+        return out
+
+    def role_for(self, decision_id: str) -> str:
+        """Confirmation decisions report held-out metrics; earlier ones selection metrics."""
+        return "held_out" if self.decisions[decision_id].stage == "confirm" else "selection"
+
+    def summary(self, decision_id: str, metric: str, arm: str
+                ) -> tuple[float, float, int] | None:
+        vals = self.values(decision_id, metric, arm, self.role_for(decision_id))
+        if not vals:
+            return None
+        return mean(vals), (stdev(vals) if len(vals) > 1 else 0.0), len(vals)
+
+    def unit(self, decision_id: str, metric: str) -> str:
+        for sid in self.decisions[decision_id].experiments:
+            exp = self.experiments.get(sid)
+            for m in exp.metrics if exp else []:
+                if m["name"] == metric:
+                    return str(m.get("unit") or "")
+        return ""
+
+    def trace(self, decision_id: str) -> list[str]:
+        """The entries behind a decision: the decision, its pre-registration, and its
+        experiments (started and finished)."""
+        d = self.decisions[decision_id]
+        ids = [d.entry_id] + ([d.prereg] if d.prereg else [])
+        for sid in d.experiments:
+            ids.append(sid)
+            exp = self.experiments.get(sid)
+            if exp and exp.finished_id:
+                ids.append(exp.finished_id)
+        return ids
+
+
+def _records(payload: dict[str, Any], key: str) -> Iterable[dict[str, Any]]:
+    value = payload.get(key) or []
+    return [r for r in value if isinstance(r, dict) and r.get("key")]
+
+
+def read_facts(ledger: Ledger, run_id: str) -> RunFacts:
+    entries = list(ledger.entries(run_id))
+    by_id = {e.entry_id: e for e in entries}
+    created = next((e for e in entries if e.type == "run.created"), None)
+    facts = RunFacts(run_id=run_id, idea=str(created.payload["idea"]) if created else "",
+                     entries=by_id)
+    for e in entries:
+        p = e.payload
+        if e.type == "hypothesis.proposed":
+            facts.hypotheses[e.entry_id] = {"statement": p["statement"], "kind": p["kind"]}
+        elif e.type in ("prereg.registered", "prereg.amended"):
+            base = dict(facts.preregs.get(p.get("supersedes", ""), {}))
+            base.update(p.get("changes", {}) if e.type == "prereg.amended" else p)
+            facts.preregs[e.entry_id] = base
+            if e.type == "prereg.registered":
+                for ds in p.get("evaluation_data", []):
+                    if ds not in facts.data_sources:
+                        facts.data_sources.append(ds)
+        elif e.type == "experiment.started":
+            facts.experiments[e.entry_id] = Experiment(
+                started_id=e.entry_id, finished_id=None, arm=str(p.get("arm", "treatment")),
+                seed=p.get("seed"), status=None, metrics=[], artifacts={})
+        elif e.type == "experiment.finished":
+            exp = facts.experiments.get(p["experiment"])
+            if exp is not None:
+                exp.finished_id, exp.status = e.entry_id, p["status"]
+                exp.metrics, exp.artifacts = list(p.get("metrics", [])), dict(p["artifacts"])
+                facts.finished_to_started[e.entry_id] = exp.started_id
+        elif e.type == "decision.made":
+            facts.decisions[e.entry_id] = Decision(
+                entry_id=e.entry_id, hypothesis=p["hypothesis"], stage=p["stage"],
+                outcome=p["outcome"], reason_code=p.get("reason_code"),
+                reason_text=p["reason_text"], prereg=p.get("prereg"),
+                experiments=list(p.get("experiments", [])),
+                comparison=dict(p.get("comparison", {})))
+        elif e.type == "call.recorded":
+            if p["source"] == "purescholar":
+                for rec in _records(p, "citation_records"):
+                    facts.citations.setdefault(rec["key"], rec)
+            elif p["source"] == "llm":
+                rec = p.get("record", {})
+                name = f"{rec.get('provider')}/{rec.get('model')}"
+                facts.models.setdefault(name, set()).add(str(rec.get("role")))
+        elif e.type == "hypothesis.novelty":
+            keys = []
+            for rec in _records(p, "closest"):
+                facts.citations.setdefault(rec["key"], rec)
+                keys.append(rec["key"])
+            facts.closest[p["hypothesis"]] = keys
+    return facts

writer/latex.py

@@ -0,0 +1,62 @@
+"""Document assembly: templates, bibliography and the disclosure statement (§5 step 6)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .facts import RunFacts
+from .macros import latex_escape
+
+PREAMBLE = {
+    "article": "\\documentclass[11pt]{article}\n\\usepackage[margin=1in]{geometry}\n",
+    "ieeetran": "\\documentclass[conference]{IEEEtran}\n",
+}
+PACKAGES = ("\\usepackage{graphicx}\n\\usepackage{booktabs}\n\\usepackage{amsmath}\n"
+            "\\usepackage[hidelinks]{hyperref}\n")
+
+
+def bibliography(records: list[dict[str, Any]]) -> str:
+    """`thebibliography` from citation records only (INV-2): no record, no entry."""
+    items = []
+    for r in records:
+        authors = ", ".join(r.get("authors") or []) or "Anonymous"
+        parts = [latex_escape(authors), f"\\emph{{{latex_escape(str(r.get('title') or ''))}}}"]
+        if r.get("venue"):
+            parts.append(latex_escape(str(r["venue"])))
+        if r.get("year"):
+            parts.append(str(r["year"]))
+        ident = str(r.get("id") or "")
+        kind = r.get("id_kind")
+        if kind == "doi":
+            parts.append(f"doi:\\nolinkurl{{{ident}}}")
+        elif kind == "openalex":
+            parts.append(f"OpenAlex {latex_escape(ident)}")
+        elif r.get("url"):
+            parts.append(f"\\url{{{r['url']}}}")
+        items.append(f"\\bibitem{{{r['key']}}} " + ". ".join(parts) + ".")
+    if not items:
+        return ""
+    return "\\begin{thebibliography}{99}\n" + "\n".join(items) + "\n\\end{thebibliography}\n"
+
+
+def disclosure(facts: RunFacts) -> str:
+    """A fixed statement built from the ledger's LLM call records, not written by an LLM."""
+    if not facts.models:
+        return ("\\paragraph{Disclosure} This document was produced with puremethod. No "
+                "language model calls are recorded in its run ledger.\n")
+    uses = "; ".join(f"\\texttt{{{latex_escape(m)}}} ({latex_escape(', '.join(sorted(r)))})"
+                     for m, r in sorted(facts.models.items()))
+    return ("\\paragraph{Disclosure} This document was produced with puremethod, an automated "
+            "research system. Language models used, with their roles: " + uses + ". Every "
+            "reported number is computed from the run ledger, and the full ledger is in the "
+            "run bundle.\n")
+
+
+def assemble(*, template: str, title: str, abstract: str, sections: list[tuple[str, str]],
+             bib: str, disclosure_text: str | None) -> str:
+    body = "\n\n".join(f"\\section{{{latex_escape(name)}}}\n{text}" for name, text in sections)
+    return (PREAMBLE[template] + PACKAGES +
+            f"\\title{{{latex_escape(title)}}}\n\\author{{puremethod}}\n\\date{{}}\n"
+            "\\begin{document}\n\\maketitle\n"
+            f"\\begin{{abstract}}\n{abstract}\n\\end{{abstract}}\n\n{body}\n\n"
+            + (disclosure_text or "") + "\n" + bib + "\\end{document}\n")