Inspect: explore, search, cite, ls, trace, document, status, todo¶
vouch explore¶
Browse recorded values in a local web page; copy the LaTeX that cites them.
| Flag | Meaning |
|---|---|
--port N |
port on 127.0.0.1 (default 8765) |
--open |
open it in the browser |
--html FILE |
write a self-contained snapshot instead of serving |
--json |
print the data the page shows |
Values grouped the way the code is: script → function → key, with a
copy-citation button on every row.
Clicking a row opens its provenance: description, call, per-seed results, and
where it's cited.
The page serves at http://127.0.0.1:8765/ and:
- Groups tracked values under their function, recorded values under the function the call is in (or "top level"), parameters in their own group, and derived values under their definition.
- Copies citations:
\vouch{key}for a value,\vouchclaim{key}{desc}for a claim,\vouchtable{key}for a table (plus a wholetabulararound it),\includegraphics[...]{...}for a figure. - Searches keys, descriptions, function names, function docstrings, call arguments and values (press
/to focus). Filters show all, cited, or not-cited keys. - Shows context: under a function's header, if it has a docstring, its first line shows underneath -- read fresh from the current source, never something vouch invents.
- Updates live: it checks every two seconds whether anything it shows has changed.
- Stays local and read-only: binds to 127.0.0.1 only, rejects requests with the wrong
Host, and never runs project code. ?q=WORDSopens the page with a search;?open=KEYopens it on one key, expanded.
vouch search¶
Find keys by words: key segments, descriptions, run ids, units, and a tracked call's function and arguments.
$ vouch search "vit accuracy cifar"
cifar.vit.acc 72.4 ± 1.1% top-1 test accuracy, mean ± std over seeds (cifar_vit, CHANGED)
cifar.vit.acc.std 1.1% …std subfield
cifar.resnet_vs_vit.pts 20.8 ResNet minus ViT top-1, percentage points (derived)
Ranking is BM25 over a document per key, stdlib-only, with a small built-in synonym list (acc/accuracy, lr/learning rate, std/deviation, n/seeds/samples, time/how long/took, …).
A paper may call a thing by another name than its keys do: a stage renamed in
the prose, say, with its keys kept because a rename would break their history.
Map the paper's word to the keys' words in vouch.toml:
vouch search anchor then finds the hull keys, table columns included. A
synonym counts as the word itself, and only one way: vouch search hull is
unchanged.
When a hit's producing function has a docstring, its first line is appended as a quick sanity check -- read fresh from the current source, not a description vouch generated.
vouch cite¶
The exact LaTeX to cite a key, and what it renders as.
$ vouch cite cifar.resnet.acc
\vouch{cifar.resnet.acc} → 93.2 ± 0.4\% (default fmt .1pct)
\vouch[.2pct]{cifar.resnet.acc} → 93.21 ± 0.41\%
top-1 test accuracy on CIFAR-10, mean ± std over seeds · higher is better · fresh · run cifar_resnet
subfields: .mean 93.2\% · .std 0.4\% · .n 5 · .ci95 [92.7, 93.7]
context "averages top-1 accuracy over 5 seeds, held-out test split"
The context line only appears when the producing function has a docstring.
vouch ls¶
List recorded keys, with rendered value, description, run, freshness and citation count.
| Flag | Meaning |
|---|---|
PATTERN |
substring or glob (e.g. 'cifar.*.acc') |
--cited |
only keys the paper cites |
--uncited |
only keys the paper doesn't cite |
--all |
also list each mean ± std's subfields (.mean, .std, .n, …) |
--json |
every key, subfields included |
Numbers inside keys sort in numeric order.
vouch trace¶
The full provenance chain for a key, a figure, a script, any other file a run
wrote or read, or a file:line.
TARGET is a key, a figure path, a script path, a data path, or file:line in a
paper's .tex. --code lists every code unit the target depends on.
A table key has no single value: its trace gives the table's shape, the pattern of its
cell keys, and its rows with each cell as the paper prints it, up to 40 rows. --json
has every row, as table.body.
$ vouch trace ablation
ablation table · 2 rows × 3 columns
desc the drop of each arm
cells ablation.<id>.<column>
columns id drop n
row a 50% 3
row b 25% 40
recorded experiments/ablation.py:12 in run ablation
...
A data path is any file a run wrote (vouch.artifact, vouch run --out), registered
(vouch import) or read (vouch.input, --input): a results table, a model, a built
package. The trace names the run that wrote it, whether the file on disk is still what
that run wrote, and the runs and derived values that read it.
$ vouch trace export/dist/mylib-1.1.0-py3-none-any.whl
export/dist/mylib-1.1.0-py3-none-any.whl file
written by run export (fresh)
command vouch run export --dep export/build.py --out export/dist/... -- python export/build.py
when 2026-10-14 17:52 UTC · git d9c8f14
file as the run wrote it (sha256 3f0a9c1b2e47)
$ vouch trace paper/figures/learning_curve.pdf
paper/figures/learning_curve.pdf figure
saved experiment.py:98 in run experiment (fresh)
command python experiment.py
when 2026-09-19 13:05 UTC
file as the run saved it
cited paper/main.tex:47
vouch document¶
A real-values summary of a script: its own docstrings, next to the actual
value of every key its functions produced. For sharing a script with someone,
or coming back to it months later. Unlike everything else on this page, it
needs no [[paper]] in vouch.toml -- it reads only the run store.
$ vouch document experiment.py
## experiment.py
Learning curves: a linear model against k-nearest neighbours.
last run 2026-09-19 13:04 UTC · git 20d39fe (clean) · fresh
### evaluate
Train one model on n_train points; return (test accuracy, train accuracy).
evaluate.knn.n_train_640.acc 87.3 ± 1.4% test accuracy of knn (n_train_640) cited 1×
Nothing here is invented: every docstring is read fresh from the source,
verbatim, and every value already passed through a run vouch verified. With no
SCRIPT argument, it summarizes every script that has at least one recorded
run. --md FILE writes the same content as a Markdown snapshot.
vouch status¶
Freshness per run, git-status style, with the exact re-run command and the units that changed.
--no-env skips the package-version drift check.
It also shows the runs that are recording right now. A run writes its record only when
it ends, so a long one used to look stale, with a re-run command, the whole time it
ran. Now its line says running since 2026-10-21 16:48 (process 1234) instead. A run
whose process was killed before it could end shows as interrupted, until it is next
recorded. --json lists both under running, each with alive.
The last line says when the edit hook (vouch hook claude) last checked a paper file,
and what it found: edit hook: last ran 2026-10-21 17:02 on paper/main.tex: no problems.
The hook says nothing when all is well, so this is how to tell that it is running.
vouch todo¶
Values the paper cites that no run has recorded yet (vouch.expect).
Lists each pending key with its producer command, so an agent or author knows
exactly what to run.