factor_agent.events

The events file: what a campaign is doing, appended as it happens, for anyone watching the run.

A campaign appends one event per line to events.jsonl in its run directory: a JSON object with the file’s schema version ("schema"), the event’s type ("type"), the time it happened ("time", UTC, ISO 8601) and the event’s fields. The file is append-only, and the campaign never reads it: it takes no part in a resume, a replay or the run’s snapshot, so deleting it loses the record of what happened but changes no result. A resume that drops a round a crash left half written says so in its resume event instead of removing that round’s events.

The event types, defined here once and read back by read:

• start and resume (Start, Resume): the campaign’s process id and host, the code versions, the rounds already written, the stop conditions (round and trial limits, patience) and the admission limits; a resume also names the round it dropped;

• plan (Plan): a round’s research directions in slot order, its quota, the plan’s issues and its Picked parents;

• call_start and call_end (CallStart, CallEnd): every LLM call, with its role, the proposal group and the slots it concerns; its end names the call file it wrote, how long it took, its tokens as far as the provider’s reply reports them, and whether the reply was cut off at the output limit or empty;

• gate (GateOutcome): every version of a slot’s candidate the parser and the Gate checked, passed or refused with the reasons and hints;

• review (ReviewVerdict): the reviewer’s verdict on a slot, with its reason;

• evaluation (EvaluationStart): the Evaluator starts on the round’s candidates the reviewer found consistent;

• admission (AdmissionOutcome): a slot’s outcome after evaluation, with the t threshold in force and the metrics;

• round_end (RoundEnd): a round’s trials are written;

• stop (Stopped): the run stopped, as the state file records it.

A slot is a candidate’s place in its round, from 0, in the order of the round’s research directions (and of the round’s lines in the ledger). A value the campaign holds as NaN or infinite is written as null.

Classes

AdmissionOutcome	A slot's outcome after evaluation.
CallEnd	An LLM call came back, or failed.
CallStart	An LLM call was sent.
EvaluationStart	The Evaluator starts on round round's slots: the candidates the reviewer found consistent.
Event	What every event has: the time it happened (UTC).
Events	The events file of one run directory, appended to by a campaign; safe to use from several threads.
GateOutcome	One version of a slot's candidate checked by the parser and the Gate.
Plan	Round round's research directions, in slot order, the quota by mechanism type and the plan's issues.
Resume	A campaign opened a run directory it had opened before; dropped is the round it drops, if any.
ReviewVerdict	The reviewer's verdict on a slot's candidate, with its reason; rewrite when it judged a rewrite.
RoundEnd	Round round's trials are written, accepted of them accepted.
Start	A campaign opened its run directory, with what it runs on and when it stops.
Stopped	The run stopped: by the stop condition, reason its sentence, as the state file records them.

Functions

read	The events in the file at path, in order; an empty list when there is none.
reply_facts	What a call's CallEnd says of its reply: tokens, truncation and emptiness, as far as the reply reports them.