vouch-paper 0.1__py3-none-any.whl

vouch/__init__.py

@@ -0,0 +1,82 @@
+"""vouch: every number in your paper, vouched for by the code that produced it.
+
+Record what an experiment function returns, keyed by its arguments::
+
+    import vouch
+
+    @vouch.track(over="seed")
+    def evaluate(dataset, model, seed=0):
+        ...
+        return {"acc": acc, "loss": loss}
+
+or record values directly::
+
+    vouch.record("cifar.resnet.acc", acc, desc="top-1 test accuracy")
+    vouch.record_all(metrics, prefix="cifar.resnet")
+
+Compute numbers *from* results in ``vouch_values.py``; ``vouch build`` evaluates it::
+
+    @vouch.derive("cifar.gap", fmt=".1f", desc="ResNet minus ViT, points")
+    def gap(v):
+        return 100 * (v["cifar.resnet.acc.mean"] - v["cifar.vit.acc.mean"])
+
+then cite them in LaTeX as ``\\vouch{cifar.gap}``. See SPEC.md.
+
+The public functions load on first use, so ``import vouch`` stays cheap: the
+command line (and the Claude Code hook, run after every edit) pays only for what
+it uses.
+"""
+
+import os as _os
+import sys as _sys
+
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "0+unknown"
+
+_PUBLIC = {
+    "Run": "api", "active_run": "api", "artifact": "api", "claim": "api", "input": "api",
+    "params": "api", "record": "api", "record_all": "api", "run": "api", "table": "api",
+    "alias": "derived", "derive": "derived", "expect": "derived", "track": "tracked",
+    "Stat": "values", "Verdict": "verdict", "all_of": "verdict", "any_of": "verdict",
+    "approx": "verdict", "between": "verdict", "ge": "verdict", "gt": "verdict",
+    "le": "verdict", "lt": "verdict",
+}
+__all__ = sorted(_PUBLIC) + ["__version__"]
+
+
+def __getattr__(name: str):
+    mod = _PUBLIC.get(name)
+    if mod is None:
+        raise AttributeError(f"module 'vouch' has no attribute {name!r}")
+    from importlib import import_module
+    value = getattr(import_module(f"{__name__}.{mod}"), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_PUBLIC))
+
+
+def _is_cli() -> bool:
+    """True when this process is the ``vouch`` command itself, which runs no experiment."""
+    prog = _os.path.basename(_sys.argv[0] if _sys.argv else "").lower()
+    if prog in ("vouch", "vouch.exe", "vouch-script.py"):
+        return True
+    argv = list(getattr(_sys, "orig_argv", []))
+    return "-m" in argv and argv.index("-m") + 1 < len(argv) and \
+        argv[argv.index("-m") + 1] in ("vouch", "vouch.cli")
+
+
+if not _is_cli():
+    # Track which functions the experiment executes, from the moment vouch is
+    # imported (SPEC 8.2), and record figures saved with matplotlib (SPEC 4.7).
+    from .tracing import tracker as _tracker
+
+    _tracker.start()
+
+    from . import figures as _figures
+
+    _figures.install()

vouch/__main__.py

@@ -0,0 +1,4 @@
+from ._entry import main
+import sys
+
+sys.exit(main())

vouch/_entry.py

@@ -0,0 +1,48 @@
+"""The ``vouch`` command's entry point.
+
+Claude Code runs ``vouch hook claude`` after *every* file edit, most of them not to
+a ``.tex`` file. Those return here, having imported nothing but ``json``; only a
+tex edit (and every other command) loads the real command line.
+"""
+
+import sys
+
+
+def main() -> int:
+    argv = sys.argv[1:]
+    if argv == ["hook", "claude"]:
+        data = "" if sys.stdin is None or sys.stdin.isatty() else sys.stdin.read()
+        if ".tex" not in data:                       # not a tex edit: nothing to check
+            return 0
+        from .edithook import run_edit_hook
+        code, text = run_edit_hook(data)
+        if text:
+            sys.stderr.write(text)
+        return code
+    from .cli import main as cli_main
+    try:
+        return cli_main(argv)
+    except OSError as exc:
+        if not _stdout_closed(exc):
+            raise
+        import os                          # `vouch ls | head`: the reader went away
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 1
+
+
+def _stdout_closed(exc: OSError) -> bool:
+    """A write to a pipe whose reader exited: BrokenPipeError on POSIX, EINVAL on Windows."""
+    if isinstance(exc, BrokenPipeError):
+        return True
+    import errno
+    if exc.errno != errno.EINVAL:
+        return False
+    try:
+        sys.stdout.flush()
+    except OSError:
+        return True
+    return False
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

vouch/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1'
+__version_tuple__ = version_tuple = (0, 1)
+
+__commit_id__ = commit_id = None

vouch/agents.py

@@ -0,0 +1,214 @@
+"""``vouch init --agents``: teach Claude Code (or any agent) to use vouch (SPEC §13.5).
+
+Three optional parts, each shown as a diff before anything is written:
+
+* **skill** -- ``.claude/skills/vouch/SKILL.md``: workflows for recording results,
+  writing a results paragraph, handling changed values and converting a paper. It
+  loads only when relevant, so it costs no context otherwise.
+* **rules** -- a short block in ``CLAUDE.md`` (or ``AGENTS.md``) between
+  ``<!-- vouch -->`` markers, updated in place.
+* **hook** -- a PostToolUse hook in ``.claude/settings.json`` running ``vouch hook
+  claude`` after every edit, so a typed number or a mistyped key is caught in the
+  same turn. ``--stop-gate`` adds a Stop hook running ``vouch check --strict``.
+* **mcp** (only when asked for) -- ``.mcp.json`` registering ``vouch mcp``, the same
+  lookups as tools for any MCP client.
+"""
+
+from __future__ import annotations
+
+import difflib
+import json
+import shutil
+import sys
+from pathlib import Path
+
+PARTS = ("skill", "rules", "hook")          # the default set
+OPTIONAL = ("mcp",)                           # .mcp.json: the MCP server, for any MCP client
+MARK_START, MARK_END = "<!-- vouch -->", "<!-- /vouch -->"
+
+SKILL = r"""---
+name: vouch
+description: Use when writing or editing LaTeX in a project that has vouch.toml (a paper whose numbers come from experiments), when writing experiment code whose results go into a paper, or when the user mentions results, numbers, tables, claims, figures or vouch. Every number is cited from a recorded run, never typed.
+---
+
+# vouch: every number in the paper comes from a run
+
+The paper never contains a typed number. Experiments record values; the paper
+cites them as `\vouch{key}`; `vouch check` proves each one exists and is fresh.
+Numbers computed from other numbers live in `vouch_values.py`. A number that
+doesn't exist yet is a placeholder (`vouch.expect`), never a guess.
+
+Start by reading `.vouch/CATALOG.md`: every citable key, one per line.
+
+## Record results in an experiment
+
+Decorate the function that computes the result; every call is recorded, keyed by
+the function and its arguments:
+
+```python
+import vouch
+
+@vouch.track(over="seed")                     # seeds -> mean ± std, per call results kept
+def evaluate(dataset: str, model: str, seed: int = 0) -> dict:
+    ...
+    return {"acc": acc, "loss": loss}           # -> evaluate.<dataset>.<model>.acc / .loss / .time
+```
+
+- Descriptions and formats for families of keys go in `vouch.toml` `[metrics]`
+  (`"*.acc" = { fmt = ".1pct", better = "higher", desc = "top-1 test accuracy" }`),
+  not repeated in code. Every new metric needs a desc and `better=`.
+- A single number: `vouch.record(key, value, desc=...)`; a dict: `vouch.record_all(d, prefix=...)`.
+- Multi-seed results: `over="seed"` or `vouch.Stat.of(per_seed)` -- never a hand-computed mean.
+- Data read: `vouch.input(path)`; files written: `vouch.artifact(path)`; figures saved
+  with matplotlib inside the run are tracked automatically.
+- Run the script normally. `vouch status` lists stale runs with their re-run command.
+
+## Write a results paragraph
+
+1. Find each number: `vouch search "vit accuracy cifar"` or the catalog.
+2. Paste exactly what `vouch cite KEY` prints (`\vouch{...}`, or `\vouch[.2pct]{...}`
+   for another precision; `.mean`, `.std`, `.n` for parts of a mean ± std).
+3. Differences, ratios, "2x": never compute them. `vouch compare A B --write` adds a
+   `@vouch.derive` and a `@vouch.claim` to `vouch_values.py`; then `vouch build` and
+   cite the derived key.
+4. "Outperforms", "in every seed", "significantly": back them with a claim and wrap
+   the prose: `\vouchclaim{key}{ResNet outperforms ViT}`. Write "significantly" only
+   if `vouch compare` reports p < 0.05.
+5. A number no run has produced yet: cite `\vouch{new.key}` anyway, add
+   `vouch.expect("new.key", desc=..., producer="python ...")` to `vouch_values.py`,
+   and tell the user the experiment is owed (`vouch todo`). Never invent it.
+6. `vouch build`, then `vouch check --strict` must pass.
+
+## Handle changed values
+
+`vouch changes` lists cited values that moved since someone last read their prose,
+with each citing sentence. Re-read every sentence; fix any the new value makes
+wrong ("the best", "roughly doubles"); report SUSPICIOUS changes to the user (they
+may be bugs). Only the user acknowledges: never run `vouch ack` or `vouch accept`
+yourself.
+
+## Convert an existing paper
+
+`vouch suggest` classifies every typed number: replaceable (exactly one recorded
+value prints like it), ambiguous, or NO SOURCE (nothing recorded prints like it).
+`vouch suggest --apply` rewrites only the replaceable ones. Show the user every NO
+SOURCE number: each needs a run that records it, or removal.
+
+## Cheat sheet
+
+| | |
+|---|---|
+| `vouch search WORDS` / `vouch cite KEY` | find a key / the exact snippet |
+| `vouch compare A B [--write]` | arithmetic, significance, derive + claim code |
+| `vouch todo` | values the paper cites that no run recorded yet |
+| `vouch build` | evaluate `vouch_values.py`, regenerate the LaTeX and the catalog |
+| `vouch check --strict [--json]` | the gate; `--json` lists issues in the order to fix them |
+| `vouch changes` | cited values that moved (the user acks, not you) |
+| `vouch trace KEY` | where a value came from |
+| `vouch explore` | browse everything in a web page |
+
+Never edit `.vouch/` or the generated `vouch-values.tex` / `vouch-tables/` by hand.
+"""
+
+RULES = """<!-- vouch -->
+## Numbers in the paper (vouch)
+- Never type an empirical number into LaTeX. Find it (`vouch search`, `.vouch/CATALOG.md`), then paste what `vouch cite KEY` prints.
+- If it doesn't exist: record it in the experiment, `@vouch.derive` it, or `vouch.expect()` it and tell the user it is owed.
+- Never compute with numbers in prose (differences, ratios, "2x"): `vouch compare A B --write`, then cite the derived key.
+- Qualitative comparisons ("outperforms", "all seeds") go in `\\vouchclaim` backed by a claim.
+- Before finishing: `vouch build` and `vouch check --strict` must pass.
+- If `vouch changes` lists anything: re-read each cited sentence, fix wrong text, and report SUSPICIOUS changes to the user.
+- Never run `vouch ack` or `vouch accept` without the user's approval. Never edit `.vouch/` or generated files.
+<!-- /vouch -->
+"""
+
+
+def _hook_command(sub: str) -> tuple[str, bool]:
+    """(command, portable): ``vouch hook ...`` if vouch is on PATH, else this Python."""
+    if shutil.which("vouch"):
+        return f"vouch hook {sub}", True
+    return f'"{sys.executable}" -m vouch hook {sub}', False
+
+
+def _with_hook(settings: dict, event: str, matcher: str | None, command: str) -> dict:
+    hooks = settings.setdefault("hooks", {})
+    groups = hooks.setdefault(event, [])
+    for g in groups:
+        if any(h.get("command") == command for h in g.get("hooks", [])):
+            return settings
+    group: dict = {"hooks": [{"type": "command", "command": command}]}
+    if matcher:
+        group = {"matcher": matcher, **group}
+    groups.append(group)
+    return settings
+
+
+def planned(root: Path, parts: list[str], stop_gate: bool = False) -> dict[Path, tuple[str, str]]:
+    """{path: (old text, new text)} for the files ``init --agents`` would write."""
+    out: dict[Path, tuple[str, str]] = {}
+
+    def old(p: Path) -> str:
+        try:
+            return p.read_text(encoding="utf-8")
+        except OSError:
+            return ""
+    if "skill" in parts:
+        p = root / ".claude" / "skills" / "vouch" / "SKILL.md"
+        out[p] = (old(p), SKILL)
+    if "rules" in parts:
+        p = root / "CLAUDE.md"
+        if not p.exists() and (root / "AGENTS.md").exists():
+            p = root / "AGENTS.md"
+        text = old(p)
+        if MARK_START in text and MARK_END in text:
+            a, rest = text.split(MARK_START, 1)
+            _, b = rest.split(MARK_END, 1)
+            new = a + RULES.rstrip("\n") + b
+        else:
+            new = (text.rstrip("\n") + "\n\n" if text.strip() else "") + RULES
+        out[p] = (text, new)
+    if "hook" in parts:
+        cmd, portable = _hook_command("claude")
+        p = root / ".claude" / ("settings.json" if portable else "settings.local.json")
+        text = old(p)
+        try:
+            settings = json.loads(text) if text.strip() else {}
+        except ValueError:
+            settings = None
+        if settings is not None:
+            settings = _with_hook(settings, "PostToolUse", "Edit|Write|MultiEdit", cmd)
+            if stop_gate:
+                settings = _with_hook(settings, "Stop", None, _hook_command("stop")[0])
+            out[p] = (text, json.dumps(settings, indent=2) + "\n")
+    if "mcp" in parts:
+        p = root / ".mcp.json"
+        text = old(p)
+        try:
+            cfg = json.loads(text) if text.strip() else {}
+        except ValueError:
+            cfg = None
+        if cfg is not None:
+            cmd, portable = _hook_command("")
+            entry = ({"command": "vouch", "args": ["mcp"]} if portable else
+                     {"command": sys.executable, "args": ["-m", "vouch", "mcp"]})
+            servers = cfg.setdefault("mcpServers", {})
+            if servers.get("vouch") != entry:
+                servers["vouch"] = entry
+                out[p] = (text, json.dumps(cfg, indent=2) + "\n")
+    return {p: (a, b) for p, (a, b) in out.items() if a != b}
+
+
+def diff(root: Path, changes: dict[Path, tuple[str, str]]) -> str:
+    chunks = []
+    for p, (a, b) in changes.items():
+        rel = p.relative_to(root).as_posix()
+        chunks += difflib.unified_diff(a.splitlines(keepends=True), b.splitlines(keepends=True),
+                                       fromfile=f"a/{rel}" if a else "/dev/null",
+                                       tofile=f"b/{rel}")
+    return "".join(chunks)
+
+
+def write(changes: dict[Path, tuple[str, str]]) -> None:
+    for p, (_, text) in changes.items():
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text, encoding="utf-8", newline="\n")