provrun.context

The run context: the identity of one run and the parts it uses.

provrun is the caller of record. It makes the run ID and opens the evidence before anything else happens, and it closes the evidence and commits the bundle after everything else. Every other part takes the context, so no part can run outside a run.

A run keeps its files in one folder::

<runs root>/<run_id>/evidence/   the evidence, see provrun.evidence
<runs root>/<run_id>/output/     what the agent wrote
<runs root>/<run_id>/input/      the staged inputs, not part of the bundle
<runs root>/<run_id>/scratch/    the agent's working space, not part of the bundle

The bundle is the evidence and the output folders. At the end of a run they are written through provcat under the run URI, <bundle_scheme>://<org>/<domain>/<env>/<run_id>, and committed in one commit, if the run sets bundle_scheme. Otherwise they stay in the run folder. Code deep inside a tool finds the run with current_run().

find_run

source

find_run(run: str | Path, root: str | Path | None = None, *, ids_only: bool = False) -> Path

The folder of a run, as provevi.find_run finds it. Raises RunNotFound.

Parameter	Type	Default	Description
`run`	str \| Path	required	A run ID under the root, or the path of a run folder
`root`	str \| Path \| None	`None`	The runs root; None is provevi’s default runs root
`ids_only`	bool	`False`	Take run as a run ID only, never as a path
returns	Path		The run’s folder

current_run

source

current_run() -> RunContext

The run that is going on, for code deep inside a tool or a backend.

A run is active inside RunContext.active, which an in-process backend enters around the agent.

Parameter	Type	Default	Description
returns	RunContext		The context of the run that is active here; RuntimeError when none is

class Bundle

source

Bundle(folder: Path, uri: str | None = None, pinned: str | None = None, note: str = '')

Where the bundle of a run went.

Parameter	Type	Default	Description
`folder`	Path	required	The run folder
`uri`	str \| None	`None`	The run URI, if the bundle was written through provcat
`pinned`	str \| None	`None`	The commit, if the store has commits
`note`	str	`''`	A note on the bundle, such as why it stayed in the run folder or was not pinned

class RunContext

source

RunContext(run_id: str, org: str, domain: str, env: str, actor: str, folder: Path, recorder: EvidenceRecorder, broker: Broker, resolver: Resolver, catalog: Catalog | None = None, bundle_scheme: str | None = None, status: str = 'open', trace: dict = <factory>, telemetry: Any = None, on_text: Any = None, pieces: Any = None)

One run: its identity, its folder, its evidence recorder and the parts it uses.

Every part of a run takes it. RunContext.open makes one.

Parameter	Type	Default	Description
`run_id`	str	required	The run’s ID, such as run-20260101T000000Z-0a1b2c3d
`org`	str	required	The org, the first part of the run URI
`domain`	str	required	The domain, the second part
`env`	str	required	The environment, the third part, such as dev or prod
`actor`	str	required	Who runs it; each event records it
`folder`	Path	required	The run folder, /<run_id>
`recorder`	EvidenceRecorder	required	Writes the run’s evidence; every part calls its emit or step
`broker`	Broker	required	Decides each input request
`resolver`	Resolver	required	Makes each granted input’s snapshot
`catalog`	Catalog \| None	`None`	The catalog that the bundle is written through
`bundle_scheme`	str \| None	`None`	The provcat scheme for run URIs, for example “run”
`status`	str	`'open'`	“open”, then “completed” or “failed” once finish has run
`trace`	dict	`<factory>`	The trace and span IDs of the run’s root span
`telemetry`	Any	`None`	The run’s provrun.telemetry.Telemetry, when run_agent runs it
`on_text`	Any	`None`	Called with each piece of a streamed reply, as it comes
`pieces`	Any	`None`	The pieces of the model request in hand, a provrun.backends.Pieces

RunContext.text

source

RunContext.text(piece: str) -> None

Hand on a piece of a streamed reply, as it comes, to on_text.

The evidence does not record pieces: it records each whole response.

Parameter	Type	Default	Description
`piece`	str	required	One piece of a streamed reply; an empty piece is dropped

RunContext.open

source

RunContext.open(*, org: str, domain: str, env: str, actor: str, broker: Broker, resolver: Resolver, catalog: Catalog | None = None, runs_root: Path | None = None, mode: str | None = None, bundle_scheme: str | None = None, run_id: str | None = None, data: dict | None = None, store: EvidenceStore | None = None, trace: dict | None = None, sinks: list | None = None) -> RunContext

Make the run ID and the run folder, and write run_created.

A bad setting raises RunSettingError before the folder is made.

Parameter	Type	Default	Description
`org`	str	required	The org, one part of a URI
`domain`	str	required	The domain, one part of a URI
`env`	str	required	The environment, one part of a URI; dev makes the evidence mode lenient by default
`actor`	str	required	Who runs it
`broker`	Broker	required	Decides each input request
`resolver`	Resolver	required	Makes each granted input’s snapshot
`catalog`	Catalog \| None	`None`	The catalog that the bundle is written through
`runs_root`	Path \| None	`None`	The folder that holds run folders; None is provevi’s default runs root
`mode`	str \| None	`None`	The evidence mode, “strict” or “lenient”; None is lenient in dev and strict elsewhere
`bundle_scheme`	str \| None	`None`	A logical scheme to write the bundle through; None keeps it in the run folder
`run_id`	str \| None	`None`	The run’s ID; None makes a new one
`data`	dict \| None	`None`	More data for run_created, such as the agent spec
`store`	EvidenceStore \| None	`None`	The provevi store for the evidence; None is the file store
`trace`	dict \| None	`None`	The trace and span IDs of the run’s root span, which run_created and the run’s last event record
`sinks`	list \| None	`None`	More sinks that get each evidence line from run_created on, such as a live feed
returns	RunContext		The open run, with run_created written

RunContext.active

source

RunContext.active() -> Iterator[RunContext]

Make this the run that current_run gives, inside a with block.

Parameter	Type	Default	Description
returns	Iterator[RunContext]		This context, which current_run gives until the block ends

RunContext.finish

source

RunContext.finish(error: BaseException | None = None) -> Bundle

Write run_completed or run_failed, close the evidence, and write the bundle.

A run can finish once: a second finish raises RuntimeError. An EvidenceError from writing or closing the evidence is raised once the bundle is written; in strict mode, a bundle that cannot be written raises EvidenceError too.

Parameter	Type	Default	Description
`error`	BaseException \| None	`None`	The error that failed the run; None for a run that completed
returns	Bundle		Where the bundle went