provrun.spec

Specs: what an agent is, and what one run of it gets.

AgentSpec is portable data: it says what the agent is, and nothing about where it runs, so the same spec can go to an in-process backend now and to Docker or Foundry later. RunSpec is what a stager makes for one run: the staged inputs, where the agent sees them, and where it writes.

class InputSpec

source

InputSpec(uri: str, name: str | None = None, mode: str = 'mounted_snapshot')

One input of an agent: a catalog URI, staged for the agent under /input.

Parameter	Type	Default	Description
`uri`	str	required	The catalog URI of the input
`name`	str \| None	`None`	The name under /input; defaults to the last part of the URI
`mode`	str	`'mounted_snapshot'`	The access mode the run asks the broker for; run_agent refuses pinned_read with RunSettingError, before the run folder is made

class AgentSpec

source

AgentSpec(name: str, backend: str, model: str, prompt: str, instructions: str = '', inputs: list[InputSpec] = <factory>, tools: list[str] = <factory>, settings: dict[str, Any] = <factory>, limits: dict[str, Any] = <factory>, stream: bool = False)

What an agent is: its backend, model, prompt, inputs and tools.

It says nothing of where the agent runs. A setting whose name can carry a credential, such as api_key, raises ValueError.

Parameter	Type	Default	Description
`name`	str	required	The agent’s name; the evidence and the access requests record it
`backend`	str	required	“litellm” or “pydantic-ai”, the name of a backend in the entry point group provrun.backends
`model`	str	required	The model, as the backend names it, such as openai:gpt-4o for pydantic-ai
`prompt`	str	required	The user prompt
`instructions`	str	`''`	The system instructions
`inputs`	list[InputSpec]	`<factory>`	The catalog inputs the agent reads
`tools`	list[str]	`<factory>`	The names of the tools it may call, such as grep_file
`settings`	dict[str, Any]	`<factory>`	Model settings, for example temperature
`limits`	dict[str, Any]	`<factory>`	For example request_limit, retries, timeout in seconds
`stream`	bool	`False`	Ask for the reply in pieces; the evidence still records each whole response

AgentSpec.from_dict

source

AgentSpec.from_dict(d: dict) -> AgentSpec

Check the types of each key and the input URIs, and make the spec.

Raises ValueError or TypeError.

Parameter	Type	Default	Description
`d`	dict	required	The agent section of a run file; an input is a URI or a mapping of InputSpec’s fields
returns	AgentSpec		The checked spec

AgentSpec.to_dict

source

AgentSpec.to_dict() -> dict

The spec as plain values, as run_created records it.

Parameter	Type	Default	Description
returns	dict		Every field, the inputs as mappings too

class StagedInput

source

StagedInput(name: str, uri: str, pinned: str, digest: str, kind: str, host_path: Path, agent_path: str)

One input as a stager staged it for one run.

Parameter	Type	Default	Description
`name`	str	required	Its name under the input folder
`uri`	str	required	The URI as asked for
`pinned`	str	required	The physical URI at a fixed version, as the snapshot pinned it
`digest`	str	required	The SHA-256 of the snapshot, which verify_inputs checks after the run
`kind`	str	required	“file” or “folder”
`host_path`	Path	required	Where the backend reads it
`agent_path`	str	required	Where the agent sees it, for example /input/report.txt

class RunSpec

source

RunSpec(run_id: str, inputs: list[StagedInput], input_dir: Path, output_dir: Path, scratch_dir: Path, agent_input: str = '/input', agent_output: str = '/output', agent_scratch: str = '/scratch', env: dict[str, str] = <factory>)

What a stager makes for one run, and a backend runs.

It holds the staged inputs, where the agent sees them, and where it writes.

Parameter	Type	Default	Description
`run_id`	str	required	The run’s ID
`inputs`	list[StagedInput]	required	The staged inputs
`input_dir`	Path	required	The folder that holds the staged inputs, read-only
`output_dir`	Path	required	The folder the agent writes its results to
`scratch_dir`	Path	required	The agent’s working folder, not part of the bundle
`agent_input`	str	`'/input'`	Where the agent sees input_dir
`agent_output`	str	`'/output'`	Where the agent sees output_dir
`agent_scratch`	str	`'/scratch'`	Where the agent sees scratch_dir
`env`	dict[str, str]	`<factory>`	Environment variables for the agent; no backend reads them yet

class RunSettings

source

RunSettings(org: str, domain: str, env: str, actor: str, allow: tuple[str, ...] = (), bundle_scheme: str | None = None, store: str | None = None)

The run section of a run file: who runs, where, and what else the stub broker allows.

Parameter	Type	Default	Description
`org`	str	required	The org, one part of the run URI
`domain`	str	required	The domain, one part of the run URI
`env`	str	required	The environment, one part of the run URI, such as dev or prod
`actor`	str	required	Who runs it
`allow`	tuple[str, …]	`()`	More URIs the stub broker allows, besides the agent’s inputs
`bundle_scheme`	str \| None	`None`	A logical scheme to write the bundle through; None keeps it in the run folder
`store`	str \| None	`None`	The evidence store, such as sqlite:///evidence.db; the file store if None

RunSettings.from_dict

source

RunSettings.from_dict(d: dict, where: str = 'the run section') -> RunSettings

Check the run section and make the settings. Raises RunFileError.

Parameter	Type	Default	Description
`d`	dict	required	The run section of a run file
`where`	str	`'the run section'`	What to call it in an error
returns	RunSettings		The checked settings

class RunFile

source

RunFile(settings: RunSettings, agent: AgentSpec, telemetry: dict | None = None, experiment: str | None = None)

A checked run file: its run settings and its agent spec.

Parameter	Type	Default	Description
`settings`	RunSettings	required	The run section
`agent`	AgentSpec	required	The agent section
`telemetry`	dict \| None	`None`	The telemetry section, which narrows the operator’s policy
`experiment`	str \| None	`None`	The experiment the run belongs to, experiment://org/team/env/project/name

RunFile.load

source

RunFile.load(path: str | Path) -> RunFile

Read and check a run file.

Raises RunFileError. The telemetry section is checked against the policy, and the experiment is pinned, when the run starts.

Parameter	Type	Default	Description
`path`	str \| Path	required	The run file, in YAML
returns	RunFile		The checked run file