puremethod 0.1.0__py3-none-any.whl

writer/lint.py

@@ -0,0 +1,85 @@
+"""Checks before compiling (06-writer.md §5 step 5, INV-1, INV-2, INV-4, INV-5)."""
+
+from __future__ import annotations
+
+import re
+
+# Commands the LLM may not use: anything that reads or writes files, defines or redefines
+# macros, or builds tables and graphics itself (tables and figures come from code).
+FORBIDDEN = re.compile(
+    r"\\(input|include|includeonly|write|immediate|openout|openin|read|catcode|def|edef|"
+    r"gdef|xdef|let|newcommand|renewcommand|providecommand|DeclareRobustCommand|csname|"
+    r"usepackage|documentclass|begin\{(tabular|table|figure|tikzpicture|verbatim)|"
+    r"includegraphics|special|directlua|ShellEscape|bibliography|addbibresource)"
+    r"(?![A-Za-z])")  # not \b: `\write18` (shell escape) has a digit right after the name
+
+# Removed before looking for numbers: the macros, references, labels and citations whose
+# arguments may hold digits (the KB allowlist).
+_ALLOWED = re.compile(
+    r"\\pm(?:val|agg|cmp|cfg)\{[^{}]*\}(?:\{[^{}]*\})?"
+    r"|\\pm(?:table|figure)\{[^{}]*\}"
+    r"|\\(?:cite|citep|citet|ref|eqref|autoref|label)\{[^{}]*\}")
+_DIGIT = re.compile(r"\d")
+_NUMBER_WORDS = (r"zero|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|"
+                 r"twenty|thirty|forty|fifty|hundred|thousand|million|billion|half|double|"
+                 r"twice|triple|thrice|several-fold")
+_UNIT_WORDS = (r"percent|per\s*cent|percentage|points?|times|fold|seeds?|epochs?|ms|"
+               r"milliseconds?|seconds?|minutes?|hours?|layers?|parameters|samples|nodes|"
+               r"steps|iterations|x|%")
+_SPELLED = re.compile(rf"\b({_NUMBER_WORDS})\b[\s-]*({_UNIT_WORDS})\b", re.IGNORECASE)
+# Multipliers are quantity claims on their own ("twice as fast", "a threefold gain").
+_MULTIPLIER = re.compile(r"\b(twice|thrice|double[sd]?|triple[sd]?|halve[sd]?|"
+                         r"\w+fold)\b", re.IGNORECASE)
+_CITE = re.compile(r"\\cite[pt]?\{([^{}]*)\}")
+_FINDING = re.compile(r"\b(we\s+find|we\s+found|finding|findings|our\s+results\s+show|"
+                      r"we\s+demonstrate|demonstrates?\s+that|proves?\s+that|"
+                      r"establish(?:es)?\s+that|confirm(?:s|ed)?\s+that)\b", re.IGNORECASE)
+
+
+def forbidden(latex: str) -> list[str]:
+    return [f"forbidden command \\{m.group(1)}" for m in FORBIDDEN.finditer(latex)]
+
+
+def bare_numbers(latex: str) -> list[str]:
+    """Digits outside the allowlist, and spelled-out quantities with a unit (INV-1)."""
+    stripped = _ALLOWED.sub(" ", latex)
+    problems = []
+    for m in _DIGIT.finditer(stripped):
+        start = max(m.start() - 20, 0)
+        problems.append(f"bare number near: ...{stripped[start:m.end() + 20].strip()}...")
+        break  # one example per section is enough for a retry prompt
+    for m in _SPELLED.finditer(stripped):
+        problems.append(f"spelled-out quantity: {m.group(0)!r}")
+    for m in _MULTIPLIER.finditer(stripped):
+        problems.append(f"multiplier without a macro: {m.group(0)!r}")
+    return problems
+
+
+def cite_keys(latex: str) -> list[str]:
+    keys = []
+    for m in _CITE.finditer(latex):
+        keys += [k.strip() for k in m.group(1).split(",") if k.strip()]
+    return keys
+
+
+def unknown_citations(latex: str, pool: set[str]) -> list[str]:
+    return [f"citation key {k!r} is not in the citation pool" for k in cite_keys(latex)
+            if k not in pool]
+
+
+def finding_wording(latex: str) -> list[str]:
+    m = _FINDING.search(latex)
+    return [f"findings wording ({m.group(0)!r}) outside a confirmed finding"] if m else []
+
+
+def check_section(latex: str, *, pool: set[str], allow_findings: bool,
+                  required_cites: list[str], macro_problems: list[str]) -> list[str]:
+    problems = forbidden(latex) + bare_numbers(latex) + unknown_citations(latex, pool)
+    problems += macro_problems
+    if not allow_findings:
+        problems += finding_wording(latex)
+    used = set(cite_keys(latex))
+    for key in required_cites:
+        if key not in used:
+            problems.append(f"must cite the closest prior work {key!r}")
+    return problems

writer/macros.py

@@ -0,0 +1,114 @@
+"""Numeric macros, resolved by code from the ledger (06-writer.md §4, INV-1, INV-3).
+
+`\\pmval{<experiment>}{<metric>}`, `\\pmagg{<decision>}{<metric>}`, `\\pmcmp{<decision>}`,
+`\\pmcfg{<prereg>}{<field>}`. Values print with three significant figures and their unit;
+`\\pmagg` prints mean ± standard deviation and n (KB-017). `\\pmagg` summarises the
+treatment arm, on the data role its stage decides on (held-out at `confirm`).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+
+from .facts import RunFacts
+
+MACRO_RE = re.compile(r"\\pm(val|agg|cmp|cfg)\{([^{}]*)\}(?:\{([^{}]*)\})?")
+NO_UNIT = {"", "none", "fraction", "ratio", "count", "1"}
+
+
+class MacroError(ValueError):
+    """A macro that does not resolve to ledger data."""
+
+
+def sig3(value: float) -> str:
+    """Three significant figures, LaTeX-ready (scientific form outside 1e-3 to 1e4)."""
+    if value == 0 or not math.isfinite(value):
+        return "0" if value == 0 else str(value)
+    exp = math.floor(math.log10(abs(value)))
+    if exp >= 4 or exp < -3:
+        mant = value / 10 ** exp
+        return f"${mant:.2f}\\times10^{{{exp}}}$"
+    digits = 2 - exp  # round to three significant figures, also above the decimal point
+    return f"{round(value, digits):.{max(digits, 0)}f}"
+
+
+def latex_escape(text: str) -> str:
+    repl = {"\\": r"\textbackslash{}", "&": r"\&", "%": r"\%", "$": r"\$", "#": r"\#",
+            "_": r"\_", "{": r"\{", "}": r"\}", "~": r"\textasciitilde{}",
+            "^": r"\textasciicircum{}"}
+    return "".join(repl.get(c, c) for c in text)
+
+
+def _with_unit(number: str, unit: str) -> str:
+    return number if unit.lower() in NO_UNIT else f"{number}~{latex_escape(unit)}"
+
+
+@dataclass
+class Resolver:
+    facts: RunFacts
+    trace_map: dict[str, list[str]] = field(default_factory=dict)
+
+    def resolve(self, latex: str) -> str:
+        return MACRO_RE.sub(lambda m: self._one(m.group(1), m.group(2), m.group(3)), latex)
+
+    def check(self, latex: str) -> list[str]:
+        """Every macro in the text resolves (INV-1); returns the problems."""
+        problems = []
+        for m in MACRO_RE.finditer(latex):
+            try:
+                self._one(m.group(1), m.group(2), m.group(3), dry=True)
+            except MacroError as exc:
+                problems.append(str(exc))
+        return problems
+
+    def _one(self, kind: str, a: str, b: str | None, *, dry: bool = False) -> str:
+        f = self.facts
+        a = a.strip()
+        b = b.strip() if b else None
+        if kind == "val":
+            started = f.finished_to_started.get(a, a)
+            exp = f.experiments.get(started)
+            if exp is None or b is None:
+                raise MacroError(f"\\pmval{{{a}}}: no such experiment")
+            hit = [m for m in exp.metrics if m["name"] == b]
+            if not hit:
+                raise MacroError(f"\\pmval{{{a}}}{{{b}}}: metric not recorded")
+            out = _with_unit(sig3(float(hit[0]["value"])), str(hit[0].get("unit", "")))
+            refs = [exp.started_id] + ([exp.finished_id] if exp.finished_id else [])
+        elif kind in ("agg", "cmp"):
+            if a not in f.decisions:
+                raise MacroError(f"\\pm{kind}{{{a}}}: no such decision")
+            if kind == "agg":
+                if b is None:
+                    raise MacroError(f"\\pmagg{{{a}}}: metric missing")
+                s = f.summary(a, b, "treatment")
+                if s is None:
+                    raise MacroError(f"\\pmagg{{{a}}}{{{b}}}: no treatment values")
+                m, sd, n = s
+                out = _with_unit(f"{sig3(m)}~$\\pm$~{sig3(sd)}", f.unit(a, b)) + f" ($n={n}$)"
+            else:
+                cmp_ = f.decisions[a].comparison
+                if "value" not in cmp_:
+                    raise MacroError(f"\\pmcmp{{{a}}}: the decision recorded no comparison")
+                out = sig3(float(cmp_["value"]))
+            refs = f.trace(a)
+        elif kind == "cfg":
+            pre = f.preregs.get(a)
+            if pre is None or b is None:
+                raise MacroError(f"\\pmcfg{{{a}}}: no such pre-registration")
+            value = {"threshold": pre.get("comparison", {}).get("threshold"),
+                     "wall_clock_s": pre.get("budget", {}).get("wall_clock_s"),
+                     "money_usd": pre.get("budget", {}).get("money_usd_estimate"),
+                     "seeds": len(pre.get("seeds", {}).get("values", []))}.get(b)
+            if value is None:
+                raise MacroError(f"\\pmcfg{{{a}}}{{{b}}}: unknown field")
+            out = sig3(float(value)) if b != "seeds" else str(int(value))
+            refs = [a]
+        else:  # pragma: no cover - the regex admits only the four kinds
+            raise MacroError(kind)
+        if not dry:
+            key = f"pm{kind}:{a}" + (f":{b}" if b else "")
+            self.trace_map[key] = refs
+        return out

writer/render.py

@@ -0,0 +1,120 @@
+"""Tables and figures rendered by code from ledger data (06-writer.md §5 step 4).
+
+The LLM gives a spec: which decisions, which metric, a caption. Every value comes from the
+ledger; the trace map records the entries behind each table and figure (INV-3).
+"""
+
+from __future__ import annotations
+
+import io
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from .facts import RunFacts
+from .macros import NO_UNIT, latex_escape, sig3
+
+_ID = re.compile(r"^[A-Za-z0-9_-]{1,40}$")
+TABLE_SCHEMA: dict[str, Any] = {
+    "type": "object", "additionalProperties": False,
+    "required": ["id", "caption", "metric", "decisions"],
+    "properties": {"id": {"type": "string"}, "caption": {"type": "string"},
+                   "metric": {"type": "string"},
+                   "decisions": {"type": "array", "items": {"type": "string"},
+                                 "minItems": 1, "maxItems": 12}},
+}
+
+
+class SpecError(ValueError):
+    """A table or figure spec that cannot be rendered from the ledger."""
+
+
+@dataclass(frozen=True)
+class Spec:
+    id: str
+    caption: str
+    metric: str
+    decisions: tuple[str, ...]
+
+    @staticmethod
+    def parse(raw: dict[str, Any], facts: RunFacts) -> Spec:
+        spec = Spec(id=str(raw["id"]), caption=str(raw["caption"]), metric=str(raw["metric"]),
+                    decisions=tuple(str(d) for d in raw["decisions"]))
+        if not _ID.match(spec.id):
+            raise SpecError(f"spec id {spec.id!r} must be letters, digits, _ or -")
+        for d in spec.decisions:
+            if d not in facts.decisions:
+                raise SpecError(f"spec {spec.id}: {d!r} is not a decision of this run")
+            if facts.summary(d, spec.metric, "treatment") is None:
+                raise SpecError(f"spec {spec.id}: no {spec.metric!r} values for {d!r}")
+        return spec
+
+
+def _label(facts: RunFacts, decision: str) -> str:
+    d = facts.decisions[decision]
+    statement = facts.hypotheses.get(d.hypothesis, {}).get("statement", d.hypothesis)
+    text = str(statement)
+    return text if len(text) <= 60 else text[:57] + "..."
+
+
+def _cell(s: tuple[float, float, int] | None) -> str:
+    return f"{sig3(s[0])} $\\pm$ {sig3(s[1])}" if s else "--"
+
+
+def render_table(spec: Spec, facts: RunFacts) -> tuple[str, list[str]]:
+    rows, refs = [], []
+    for d in spec.decisions:
+        t = facts.summary(d, spec.metric, "treatment")
+        b = facts.summary(d, spec.metric, "baseline")
+        dec = facts.decisions[d]
+        rows.append(f"{latex_escape(_label(facts, d))} & {latex_escape(dec.stage)}"
+                    f" & {_cell(t)} & {_cell(b)} & {latex_escape(dec.outcome)} \\\\")
+        refs += facts.trace(d)
+    unit = facts.unit(spec.decisions[0], spec.metric)
+    shown = unit.lower() not in NO_UNIT
+    head = latex_escape(spec.metric) + (f" ({latex_escape(unit)})" if shown else "")
+    body = "\n".join(rows)
+    tex = (f"\\begin{{table}}[t]\\centering\\small\n\\caption{{{latex_escape(spec.caption)}}}"
+           f"\\label{{tab:{spec.id}}}\n\\begin{{tabular}}{{p{{4.2cm}}lllr}}\\toprule\n"
+           f"Hypothesis & Stage & Treatment {head} & Baseline & Decision \\\\ \\midrule\n"
+           f"{body}\n\\bottomrule\\end{{tabular}}\n\\end{{table}}")
+    return tex, refs
+
+
+def render_figure(spec: Spec, facts: RunFacts) -> tuple[str, bytes, list[str]]:
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    labels, t_mean, t_sd, b_mean, b_sd, refs = [], [], [], [], [], []
+    for i, d in enumerate(spec.decisions, start=1):
+        t = facts.summary(d, spec.metric, "treatment")
+        b = facts.summary(d, spec.metric, "baseline")
+        labels.append(f"H{i}")
+        t_mean.append(t[0] if t else 0.0)
+        t_sd.append(t[1] if t else 0.0)
+        b_mean.append(b[0] if b else 0.0)
+        b_sd.append(b[1] if b else 0.0)
+        refs += facts.trace(d)
+    fig, ax = plt.subplots(figsize=(4.0, 2.6), dpi=150)
+    x = range(len(labels))
+    width = 0.38
+    ax.bar([i - width / 2 for i in x], t_mean, width, yerr=t_sd, label="treatment",
+           color="#4C72B0", capsize=3)
+    ax.bar([i + width / 2 for i in x], b_mean, width, yerr=b_sd, label="baseline",
+           color="#B0B0B0", capsize=3)
+    ax.set_xticks(list(x), labels)
+    unit = facts.unit(spec.decisions[0], spec.metric)
+    ax.set_ylabel(spec.metric + (f" ({unit})" if unit.lower() not in NO_UNIT else ""))
+    ax.legend(frameon=False, fontsize=7)
+    fig.tight_layout()
+    buf = io.BytesIO()
+    fig.savefig(buf, format="pdf", metadata={"CreationDate": None})
+    plt.close(fig)
+    key = "; ".join(f"H{i}: {latex_escape(_label(facts, d))}"
+                    for i, d in enumerate(spec.decisions, start=1))
+    tex = (f"\\begin{{figure}}[t]\\centering\n\\includegraphics[width=\\linewidth]"
+           f"{{fig-{spec.id}.pdf}}\n\\caption{{{latex_escape(spec.caption)} ({key})}}"
+           f"\\label{{fig:{spec.id}}}\n\\end{{figure}}")
+    return tex, buf.getvalue(), refs

writer/tectonic.py

@@ -0,0 +1,79 @@
+"""Tectonic in Docker (06-writer.md §5 step 7, KB-017).
+
+The image is built from a pinned Tectonic release whose archive is checked against its
+SHA-256. The TeX bundle is fetched on first use and cached in a Docker volume.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from .types import CompilerUnavailable
+
+TECTONIC_VERSION = "0.17.0"
+TECTONIC_SHA256 = "8533d07f9ccbd7a65824b9e0459041bca34af1eb33daba48f59215593753a3b7"
+TECTONIC_URL = ("https://github.com/tectonic-typesetting/tectonic/releases/download/"
+                f"tectonic%40{TECTONIC_VERSION}/"
+                f"tectonic-{TECTONIC_VERSION}-x86_64-unknown-linux-musl.tar.gz")
+DEFAULT_IMAGE = f"pm-tectonic:{TECTONIC_VERSION}"
+CACHE_VOLUME = "pm-tectonic-cache"
+
+DOCKERFILE = f"""FROM python:3.11-slim
+RUN python - <<'PY'
+import hashlib, io, tarfile, urllib.request
+data = urllib.request.urlopen("{TECTONIC_URL}", timeout=120).read()
+assert hashlib.sha256(data).hexdigest() == "{TECTONIC_SHA256}", "tectonic checksum mismatch"
+with tarfile.open(fileobj=io.BytesIO(data)) as t:
+    t.extract("tectonic", "/usr/local/bin", filter="data")
+PY
+RUN chmod 0755 /usr/local/bin/tectonic
+WORKDIR /doc
+"""
+
+
+@dataclass
+class CompileResult:
+    ok: bool
+    pdf: bytes | None
+    log: str
+
+
+def _docker(*args: str, timeout: float = 600, stdin: str | None = None
+            ) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(["docker", *args], capture_output=True, text=True,  # noqa: S603, S607
+                              check=False, timeout=timeout, input=stdin)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        raise CompilerUnavailable(f"docker: {type(exc).__name__}") from None
+
+
+def ensure_image(image: str = DEFAULT_IMAGE) -> None:
+    if _docker("image", "inspect", image, timeout=60).returncode == 0:
+        return
+    with tempfile.TemporaryDirectory(prefix="pm-tectonic-") as ctx:
+        Path(ctx, "Dockerfile").write_text(DOCKERFILE, encoding="utf-8")
+        out = _docker("build", "-t", image, ctx, timeout=1800)
+    if out.returncode != 0:
+        raise CompilerUnavailable(f"building {image} failed: {(out.stdout + out.stderr)[-800:]}")
+
+
+def compile_tex(files: dict[str, bytes], image: str = DEFAULT_IMAGE) -> CompileResult:
+    """Compile `main.tex` with the given files; network only for the TeX bundle cache."""
+    ensure_image(image)
+    with tempfile.TemporaryDirectory(prefix="pm-paper-") as work:
+        for name, data in files.items():
+            Path(work, name).write_bytes(data)
+        out = _docker("run", "--rm", "-v", f"{Path(work).resolve()}:/doc", "-w", "/doc",
+                      "-v", f"{CACHE_VOLUME}:/root/.cache", image,
+                      "tectonic", "-X", "compile", "--keep-logs", "main.tex", timeout=900)
+        log_path = Path(work, "main.log")
+        log = (log_path.read_text(encoding="utf-8", errors="replace")
+               if log_path.exists() else "")
+        log = (out.stdout + out.stderr + "\n" + log)[-20000:]
+        pdf_path = Path(work, "main.pdf")
+        if out.returncode == 0 and pdf_path.exists():
+            return CompileResult(ok=True, pdf=pdf_path.read_bytes(), log=log)
+        return CompileResult(ok=False, pdf=None, log=log)

writer/types.py

@@ -0,0 +1,61 @@
+"""Writer types (06-writer.md §3, §4)."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+Template = Literal["article", "ieeetran"]
+Kind = Literal["paper", "report"]
+
+
+class RunContext(Protocol):
+    """Provided by `loop` (06-writer.md §3): limits before, records after, every call."""
+
+    def guard(self, max_cost_usd: float) -> None:
+        """Raise if a call with this maximum cost would break the run's limits."""
+        ...
+
+    def record(self, call_record: Any, artifacts: dict[str, bytes], *,
+               citation_records: list[dict[str, Any]] | None = None) -> None:
+        """Hand one LLM or PureScholar call to `loop` for the ledger."""
+        ...
+
+
+@dataclass(frozen=True)
+class PaperOptions:
+    title: str
+    template: Template = "article"
+    disclosure: bool = True
+    kind: Kind = "paper"
+    findings: tuple[str, ...] = ()          # hypothesis entry ids with `confirm` decisions
+    others: tuple[str, ...] = ()            # negative and exploratory hypothesis ids
+
+
+@dataclass
+class BuildResult:
+    status: Literal["built", "failed"]
+    reasons: list[str]
+    files: dict[str, bytes]                 # main.tex, refs, figures, main.pdf (when built)
+    trace_map: dict[str, list[str]]
+    citation_keys: list[str]
+    lint_log: list[str] = field(default_factory=list)
+    compile_log: str = ""
+    sections: dict[str, str] = field(default_factory=dict)  # LLM LaTeX per section key
+
+    def digests(self) -> dict[str, str]:
+        return {name: "sha256:" + hashlib.sha256(data).hexdigest()
+                for name, data in self.files.items()}
+
+    @property
+    def pdf(self) -> bytes | None:
+        return self.files.get("main.pdf")
+
+
+class WriterError(Exception):
+    """Base error: a fault that is not a failed build (a failed build returns `failed`)."""
+
+
+class CompilerUnavailable(WriterError):
+    """Docker or the Tectonic image cannot be used."""