provrun.runner

Run one agent spec from start to end.

Before the run folder is made, the broker decides the run’s experiment, if it names one, and provrun pins it if the broker allows it. Then the steps, each of which writes its evidence:

Open the run context, and record the broker’s decision on the experiment. A refusal fails the run here.
Ask the broker for each input.
Resolve each grant to a snapshot.
Stage the snapshots.
Run the backend.
Check that the inputs did not change, and collect the outputs.
Finish the run and write the bundle.

A failure at any step writes run_failed, and the bundle is still written.

A program runs a run file the way provr run does::

outcome = run_file_sync(RunFile.load("run.yaml"), catalog=Catalog.open())
outcome.to_dict()

run_agent takes the parts one by one, and the broker, resolver, stager and backend can be passed in.

class RunOutcome

source

RunOutcome(run_id: str, status: str, folder: Path, bundle: Bundle, result: RunResult | None = None, artifacts: list[Artifact] | None = None, error: BaseException | None = None, mlflow: dict | None = None)

What a run gives back: its ID, status, folder and bundle, and its result or error.

run_agent raises, and gives no outcome, for the errors its docstring lists.

Parameter	Type	Default	Description
`run_id`	str	required	The run’s ID
`status`	str	required	“completed” or “failed”
`folder`	Path	required	The run folder
`bundle`	Bundle	required	Where the bundle went
`result`	RunResult \| None	`None`	What the backend returned; None if the run failed before or in the backend
`artifacts`	list[Artifact] \| None	`None`	The files in the output folder, a failed run’s too; None if none were collected
`error`	BaseException \| None	`None`	The Exception that failed the run; None for a run that completed
`mlflow`	dict \| None	`None`	Where the sealed run was copied in MLflow, when the policy approves a place

RunOutcome.to_dict

source

RunOutcome.to_dict() -> dict

Give the summary that provr run prints, as plain values.

It has mlflow only when the run was to be copied into MLflow.

Parameter	Type	Default	Description
returns	dict		The run ID, status, folder, bundle URI, pin, note and error, and mlflow when there is a copy

run_agent

source

async run_agent(agent: AgentSpec, *, catalog: Catalog, org: str, domain: str, env: str, actor: str, allow: list[str] | None = None, broker: Broker | None = None, resolver: Resolver | None = None, stager: Stager | None = None, backend: Backend | None = None, runs_root: Path | None = None, mode: str | None = None, bundle_scheme: str | None = None, store: EvidenceStore | None = None, policy: TelemetryPolicy | str | Path | None = None, telemetry: dict | None = None, feed: Any = None, experiment: str | None = None, parent_run: str | None = None) -> RunOutcome

Run one agent spec once, and seal its evidence and bundle.

provrun.telemetry says what a run does with the policy.

A bad setting, a telemetry section that widens the policy, or an unknown backend raises RunSettingError before the run folder is made; so does a telemetry problem in strict mode. Any later Exception fails the run, and the outcome holds it, but for these, which are raised as the run ends:

EvidenceError, when finishing the run fails: in strict mode, an event that could not be written, such as run_completed, or a bundle that could not be written; in either mode, evidence that could not be sealed;
CancelledError, for a cancel;
another BaseException that is not an Exception.

An error while the run opens, once its folder is made, such as a store that cannot open the run or, in strict mode, a run_created that cannot be written, is raised too: the folder is left, and there is no outcome.

A cancel before the run opens, while the telemetry is set up, the broker decides the experiment, the experiment is pinned or the parent run is checked, leaves no run folder and no run_failed. A cancel after that, or another BaseException, is raised once the run is sealed, with run_failed. A BaseException of its own kind is recorded as itself. A KeyboardInterrupt or SystemExit raised in the agent reaches the run as a cancel: asyncio raises it out of the backend’s task, run_failed records CancelledError, and the caller gets the KeyboardInterrupt or SystemExit.

The run asks the broker for the experiment first, in the mode pinned_read, and records the decision once it opens. A refusal is recorded as access_denied, and the run fails without reading the experiment. Otherwise the run pins it through catalog, so the catalog’s checks and hooks see it, and run_created records the URI, the pin and the SHA-256 of its file. An experiment that cannot be pinned raises RunSettingError before the run folder is made.

parent_run must be a run in the same evidence store, or under runs_root for the file store, or RunSettingError is raised; a store that cannot read runs back is not checked.

Parameter	Type	Default	Description
`agent`	AgentSpec	required	The agent to run
`catalog`	Catalog	required	The catalog that resolves and snapshots the inputs, pins the experiment and takes the bundle
`org`	str	required	The run’s org, one part of the run URI
`domain`	str	required	The run’s domain, one part of the run URI
`env`	str	required	The run’s environment, one part of the run URI; dev makes the evidence mode lenient by default
`actor`	str	required	Who runs it; each event records it
`allow`	list[str] \| None	`None`	More URIs that the default StubBroker allows; unused when broker is given
`broker`	Broker \| None	`None`	Decides each request; None is a StubBroker that allows the spec’s inputs, the URIs in allow, and the experiment if it has no selector or a commit ID
`resolver`	Resolver \| None	`None`	Makes each input’s snapshot; None is a ProvcatResolver on catalog
`stager`	Stager \| None	`None`	Stages the snapshots for the agent; None is an InProcessStager
`backend`	Backend \| None	`None`	Runs the agent; None loads the backend that the spec names
`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
`store`	EvidenceStore \| None	`None`	The provevi store for the evidence; None is the file store in the run folder
`policy`	TelemetryPolicy \| str \| Path \| None	`None`	The operator’s telemetry policy, or its file; None is the file that PROVRUN_TELEMETRY_POLICY names, else a policy that approves nothing
`telemetry`	dict \| None	`None`	A run file’s telemetry section, which narrows the policy
`feed`	Any	`None`	A provrun.live.LiveFeed, which gets each event and each piece of a streamed reply as they come; start_run makes one
`experiment`	str \| None	`None`	The URI of the experiment that the run belongs to
`parent_run`	str \| None	`None`	The ID of the run that started this one, which run_created records
returns	RunOutcome		The outcome, completed or failed; a failed run’s outcome holds its error, but for the errors raised

run_file

source

async run_file(rf: RunFile, *, catalog: Catalog, runs_root: Path | None = None, mode: str | None = None, bundle_scheme: str | Literal[False] | None = None, **parts: Any) -> RunOutcome

Run a checked run file through run_agent.

The other keyword arguments, **parts, go to run_agent: broker, resolver, stager, backend, store, policy, feed, parent_run and experiment. run_agent gets the run file’s settings, telemetry section and experiment; an experiment argument takes the place of the run file’s. Without store, the run file’s store setting opens one, and without that the file store is used. run_agent’s errors are raised as it raises them.

Parameter	Type	Default	Description
`rf`	RunFile	required	The run file, as RunFile.load returns it
`catalog`	Catalog	required	The catalog, as run_agent takes it
`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 \| Literal[False] \| None	`None`	Takes the place of the run file’s; False writes no bundle through the catalog
`parts`	Any		broker, resolver, stager, backend, store, policy, feed, parent_run or experiment, passed to run_agent
returns	RunOutcome		The outcome, as run_agent gives it

run_file_sync

source

run_file_sync(rf: RunFile, **kw: Any) -> RunOutcome

Run a checked run file, for a caller with no event loop running.

The keyword arguments, **kw, are those of run_file, such as catalog.

Parameter	Type	Default	Description
`rf`	RunFile	required	The run file, as RunFile.load returns it
`kw`	Any		The keyword arguments of run_file, such as catalog
returns	RunOutcome		The outcome, as run_file gives it