factor_agent.web.run_view

Read a run directory as the frontend shows it, without writing to it.

list_runs(root) finds every run directory under a folder: a directory holding a snapshot.json, which a campaign writes on its first start, before its first round. RunView.read(run_dir) reads one run. Callers never see the run directory’s files; this module and its private modules alone know them, and read them while a campaign may be writing them:

• The state file decides how many rounds are written. The campaign appends a round’s trials to the ledger before it rewrites the state, so ledger rounds beyond the state’s count are not read until the state catches up, and a ledger line a crash cut short is skipped.

• NaN and infinite values in the ledger (a correlation with an empty pool, say) read as None, so a view converts to strict JSON.

• The run list reads of each run only what it shows; a run whose files cannot be read is listed as unreadable, with the reason.

• The events file (factor_agent.events) tells what the run is doing: its phase, its calls and their tokens, its process, and the settings it was opened with. A run a campaign without events wrote has none of this but the calls of its round in progress, counted from its call files.

• The round in progress is replayed from the events since the run was last opened: its calls, and a pending trial per slot of its plan. A round a resume dropped left its events before the resume, so it is not among them. A run without events has no round in progress to show.

• An LLM call is read by the number of its call file, from the file itself: tokens, truncation and the model’s reasoning are the provider’s reply’s; what it concerned (round, slots) only the events file says.

• A resumed run keeps the stop of its previous open in its state file until it stops again. With events, a stop counts only when a stop event follows the latest start or resume. Without, it counts only when the state file was written after the run’s latest open and no LLM call ended after it: a resumed run that has asked the LLM since, or has written no state since it was opened, has not stopped.

• A round’s t threshold (one per round, since a round’s candidates are judged at the same trial count) is the one its admission events give. Without them it is the one its refusals quote, carried over from the round before when the round quotes none; an accepted factor says which. The correlation limit is the one the run was last opened with, or without events the one a refusal quotes. Either is None while nothing gives it.

• The process that opened the run last is looked for only on the host it ran on; on another host it is unknown, never gone.

• An Acceptance report is acceptance/<segment>[_<digest>].json; one that records opens of the hold-out is a hold-out report. The opens are the hold-out lock’s. A report written before the contribution table or the selection flag existed reads with None for them: nothing it lacks is made up.

• A collision is read from a refusal’s text: the Gate’s rewrite, refinement of parameters only or shared subtree is a code collision with each factor it names, admission’s correlation above the limit a ranking collision. The Gate’s refusal of a duplicate of the run’s own earlier candidate is not.

• The diagnosis is read from the trials by rules private to this package, their thresholds fixed there, each finding counting trials (not attempts: a trial is counted once whichever of its versions met the problem).

• A trial the Evaluator scored is placed on the admission map by its partial-IC t in its direction (the sign of its training IC, as admission reads it) and its largest absolute correlation with an existing factor. The trials it never scored are grouped by the stage that refused them and the reason: reasons that differ only in their numbers, or in the reply or code they quote, are one reason.

• A trial, and an accepted factor, is intraday when the graph the Gate built for it holds a session aggregation: an operator of the run’s snapshotted operator file whose class is a SessionAggregation. A run whose snapshot records no intraday dataset has none.

• A round’s plan is its latest Plan event, unless a resume dropped the round since (_plans); a run without events reads a written round’s slots from the ledger and has no Picked parents. A trial’s Lineage is computed from the ledger with the admission settings the run was last opened with, the defaults without events. A round’s Trial graph is its trial_graph/round_NN.json, ranked again by the graph’s pick order; a round without the file has none.

• The memory’s versions are the distiller’s files memory/round_NN.md, each written before round NN, so after round NN - 1. A version after the first is compared with the one before it line by line.

Classes

AdmissionLimits	The least coverage and decile monotonicity admission required, as the run's last start recorded them.
RunSummary	What the run list shows of a run.
RunView	A read-only snapshot of one run: its summary, the trials of its written rounds, its accepted factors and its memory.

Functions

find_run	The run directory list_runs(root) names name, None when it names none so.
list_runs	The runs under root, the latest written first.
run_version	A text that changes whenever the run in run_dir writes, cheap to read: a page polls it before reading the run.