# Python API

> Generated signatures of the public AQVEN Python package.

[Read in the browser](https://aqvenstudio.com/reference/python-api/)

<!-- Generated by tools/generate_reference.py. Do not edit this file by hand. -->

The names below come from `aqven.__all__`. Import them from `aqven`. Signatures reflect the installed package used to generate this page.

## AppAccess

`class AppAccess` · `aqven.app.local_app`

- `def guard(self, app: 'ASGIApp') -> 'ASGIApp'`

## AqvenClient

`class AqvenClient` · `aqven.client.api`

- `async def aclose(self) -> 'None'`
- `async def start_run(self, request: 'RunStartRequest') -> 'RunStarted'`
- `async def get_run(self, run_id: 'RunId') -> 'RunSnapshot'`
- `async def list_runs(self, *, flow_id: 'str | None' = None, status: 'RunStatus | None' = None, series_id: 'str | None' = None, assignee: 'str | None' = None, deadline_before: 'datetime | None' = None, overdue: 'bool | None' = None, since: 'datetime | None' = None, until: 'datetime | None' = None, sort: 'RunSort | None' = None, cursor: 'str | None' = None, limit: 'int' = 20) -> 'Page[RunSummary]'`
- `async def get_execution(self, run_id: 'RunId', address: 'ExecutionAddress', *, include_payloads: 'IncludePayloads' = 'truncated') -> 'ExecutionDetail'`
- `async def resume(self, run_id: 'RunId', request: 'ResumeRequest') -> 'ResumeResult'`
- `async def fork(self, run_id: 'RunId', request: 'ForkRequest') -> 'RunForked'`
- `async def cancel(self, run_id: 'RunId', reason: 'str') -> 'RunStatus'`
- `async def series_start(self, request: 'SeriesStartRequest') -> 'SeriesStarted'`
- `async def series_get(self, series_id: 'SeriesId', wait_seconds: 'int' = 0, include_cases: 'bool' = False) -> 'SeriesGetResult'`
- `async def series_outputs(self, request: 'SeriesOutputsRequest', *, include_holdout: 'bool' = False) -> 'SeriesOutputsPage'`
- `async def series_cancel(self, series_id: 'SeriesId', reason: 'str | None' = None) -> 'SeriesSummaryView'`
- `async def upload_blob(self, data: 'bytes', media_type: 'str', name: 'str | None' = None) -> 'MediaValue'`
- `async def download_blob(self, media: 'MediaValue') -> 'bytes'`
- `async def run_events(self, run_id: 'RunId', *, after_seq: 'int' = 0) -> 'AsyncIterator[RunEvent]'`

## CancelRequest

`class CancelRequest` · `aqven.runtime.runs`

| Field | Type | Required | Default |
| --- | --- | --- | --- |
| `reason` | `string` | Yes | `—` |


## CheckReport

`class CheckReport` · `aqven.check.report`

| Field | Type | Default |
| --- | --- | --- |
| `diagnostics` | `tuple[aqven.diagnostics.Diagnostic, ...]` | `—` |
| `project` | `aqven.loader.project.LoadedProject \| None` | `—` |


## ExecutionAddress

`class ExecutionAddress` · `aqven.runtime.address`

| Field | Type | Required | Default |
| --- | --- | --- | --- |
| `node_id` | `string` | Yes | `—` |
| `branch_key` | `string \| null` | Yes | `—` |
| `iteration` | `integer \| null` | Yes | `—` |
| `item_index` | `integer \| null` | Yes | `—` |


## FlowHandle

`class FlowHandle` · `aqven.runtime.project`

| Field | Type | Default |
| --- | --- | --- |
| `flow_id` | `aqven.spec.names.FlowId` | `—` |
| `input_model` | `type[I]` | `—` |
| `output_model` | `type[O]` | `—` |
| `project` | `ForwardRef('Project', is_class=True, owner=<class 'aqven.runtime.project.FlowHandle'>)` | `—` |

- `async def run(self, input: 'I', options: 'RunOptions | None' = None) -> 'RunResult[O]'`
- `async def start(self, input: 'I', options: 'RunOptions | None' = None) -> 'Run[O]'`

## HumanWait

`class HumanWait` · `aqven.runtime.human`

| Field | Type | Required | Default |
| --- | --- | --- | --- |
| `address` | `ExecutionAddress` | Yes | `—` |
| `wait_kind` | `'form' \| 'tool_approval'` | Yes | `—` |
| `attempt` | `integer` | Yes | `—` |
| `state` | `'waiting' \| 'resolved' \| 'timed_out'` | Yes | `—` |
| `assignee` | `string` | Yes | `—` |
| `waiting_since` | `string` | Yes | `—` |
| `deadline_at` | `string` | Yes | `—` |
| `on_timeout` | `'fail' \| 'default' \| 'escalate'` | Yes | `—` |
| `form_type_id` | `string` | Yes | `—` |


## HumanWaitDetail

`class HumanWaitDetail` · `aqven.runtime.human`

| Field | Type | Required | Default |
| --- | --- | --- | --- |
| `address` | `ExecutionAddress` | Yes | `—` |
| `wait_kind` | `'form' \| 'tool_approval'` | Yes | `—` |
| `attempt` | `integer` | Yes | `—` |
| `state` | `'waiting' \| 'resolved' \| 'timed_out'` | Yes | `—` |
| `assignee` | `string` | Yes | `—` |
| `waiting_since` | `string` | Yes | `—` |
| `deadline_at` | `string` | Yes | `—` |
| `on_timeout` | `'fail' \| 'default' \| 'escalate'` | Yes | `—` |
| `form_type_id` | `string` | Yes | `—` |
| `form_schema` | `JsonObject` | Yes | `—` |
| `suspend_data` | `ValueRef \| null` | Yes | `—` |
| `attempts` | `HumanWaitAttempt[]` | Yes | `—` |
| `resolved_by` | `string \| null` | Yes | `—` |
| `answer_ref` | `ValueRef \| null` | Yes | `—` |
| `ignored_answers` | `IgnoredAnswer[]` | Yes | `—` |


## LocalAppOptions

`class LocalAppOptions` · `aqven.app.local_app`

| Field | Type | Default |
| --- | --- | --- |
| `studio` | `bool \| None` | `None` |
| `host` | `str \| None` | `None` |
| `port` | `int \| None` | `None` |
| `api` | `<class 'bool'>` | `True` |
| `mcp` | `<class 'bool'>` | `True` |
| `chat` | `<class 'bool'>` | `True` |
| `watch` | `<class 'bool'>` | `True` |
| `access` | `aqven.app.local_app.AppAccess \| None` | `factory` |
| `data_dir` | `pathlib.Path \| None` | `None` |
| `studio_dist` | `pathlib.Path \| None` | `None` |
| `dev_origin` | `str \| None` | `None` |
| `engine` | `aqven.app.engine_host.EngineHost \| None` | `None` |


## LocalTokenAccess

`class LocalTokenAccess` · `aqven.app.local_app`

| Field | Type | Default |
| --- | --- | --- |
| `token` | `<class 'str'>` | `factory` |
| `port` | `<class 'int'>` | `0` |
| `dev_origins` | `tuple[str, ...]` | `()` |

- `def policy(self) -> 'LocalAccessPolicy'`
- `def guard(self, app: 'ASGIApp') -> 'ASGIApp'`

## Project

`class Project` · `aqven.runtime.project`

| Field | Type | Default |
| --- | --- | --- |
| `root` | `<class 'pathlib.Path'>` | `—` |
| `report` | `ForwardRef('CheckReport', is_class=True, owner=<class 'aqven.runtime.project.Project'>)` | `—` |

- `def from_report(cls, report: 'CheckReport') -> 'Self'`
- `def load(cls, root: 'Path') -> 'Self'`
- `def from_package(cls, package: 'str') -> 'Self'`
- `def flow(self, flow_id: 'str') -> 'FlowHandle[BaseModel, BaseModel]'`
- `def flow_typed(self, flow_id: 'str', input_model: 'type[I]', output_model: 'type[O]') -> 'FlowHandle[I, O]'`
- `def loaded_project(self) -> 'LoadedProject'`
- `def engine(self) -> 'LocalEngine'`
- `def compiled(self) -> 'CompiledProject'`
- `def loaded_flow(self, flow_id: 'str') -> 'LoadedFlow'`

## ProjectInvalid

`class ProjectInvalid` · `aqven.runtime.project`


## ResumeRequest

`class ResumeRequest` · `aqven.runtime.human`

| Field | Type | Required | Default |
| --- | --- | --- | --- |
| `address` | `ExecutionAddress` | Yes | `—` |
| `attempt` | `integer` | Yes | `—` |
| `payload` | `JsonValue` | Yes | `—` |
| `client_op_id` | `string` | Yes | `—` |


## ResumeResult

`class ResumeResult` · `aqven.runtime.human`

| Field | Type | Required | Default |
| --- | --- | --- | --- |
| `outcome` | `'accepted' \| 'replayed' \| 'sent'` | Yes | `—` |
| `status` | `'queued' \| 'running' \| 'suspended' \| 'completed' \| 'failed' \| 'cancelled'` | Yes | `—` |
| `address` | `ExecutionAddress` | Yes | `—` |
| `attempt` | `integer` | Yes | `—` |


## Run

`class Run` · `aqven.runtime.project`

| Field | Type | Default |
| --- | --- | --- |
| `run_id` | `aqven.runtime.address.RunId` | `—` |
| `output_model` | `type[O]` | `—` |
| `engine` | `ForwardRef('LocalEngine', is_class=True, owner=<class 'aqven.runtime.project.Run'>)` | `—` |

- `async def status(self) -> 'RunStatus'`
- `async def waits(self) -> 'tuple[HumanWait, ...]'`
- `async def wait_detail(self, address: 'ExecutionAddress') -> 'HumanWaitDetail'`
- `async def resume(self, request: 'ResumeRequest') -> 'ResumeResult'`
- `def events(self, after_seq: 'int' = 0) -> 'AsyncIterator[RunEvent]'`
- `async def result(self) -> 'RunResult[O]'`
- `async def cancel(self, reason: 'str') -> 'RunStatus'`
- `async def fork(self, from_address: 'ExecutionAddress') -> 'Run[O]'`

## RunContext

`class RunContext` · `aqven.runtime.options`

| Field | Type | Required | Default |
| --- | --- | --- | --- |
| `date` | `string \| null` | No | `None` |
| `time_zone` | `string \| null` | No | `None` |
| `locale` | `string \| null` | No | `None` |
| `tenant_id` | `string \| null` | No | `None` |


## RunEvent

Type alias.

## RunId

`def RunId(x, /)`

NewType creates simple unique types with almost zero runtime overhead.

## RunOptions

`class RunOptions` · `aqven.runtime.options`

| Field | Type | Default |
| --- | --- | --- |
| `mode` | `RunMode` | `'live'` |
| `context` | `aqven.runtime.options.RunContext \| None` | `None` |
| `cassettes` | `aqven.runtime.options.CassetteConfig \| None` | `None` |
| `human_answers` | `tuple[aqven.runtime.human.ScriptedAnswer, ...]` | `()` |
| `limits` | `aqven.spec.common.Limits \| None` | `None` |
| `tool_http` | `httpx2.AsyncBaseTransport \| None` | `None` |
| `mcp_stubs` | `tuple[aqven.runtime.replay.McpToolStub, ...]` | `()` |
| `blobs` | `aqven.runtime.steps.BlobStore \| None` | `None` |
| `faults` | `tuple[aqven.runtime.replay.ProviderFault, ...]` | `()` |
| `models` | `aqven.runtime.options.ModelProfile \| None` | `None` |
| `outputs` | `tuple[aqven.runtime.overrides.NodeOutputOverride, ...]` | `()` |
| `agent_overrides` | `collections.abc.Mapping[aqven.spec.names.NodeId, aqven.spec.names.AgentId]` | `factory` |


## RunResult

`class RunResult` · `aqven.runtime.options`

| Field | Type | Required | Default |
| --- | --- | --- | --- |
| `run_id` | `string` | Yes | `—` |
| `status` | `'queued' \| 'running' \| 'suspended' \| 'completed' \| 'failed' \| 'cancelled'` | Yes | `—` |
| `output` | `BaseModel \| null` | Yes | `—` |
| `error` | `RunError \| null` | Yes | `—` |
| `cost_usd` | `number \| string` | Yes | `—` |
| `tokens_in` | `integer` | Yes | `—` |
| `tokens_out` | `integer` | Yes | `—` |


## RuntimeSettings

`class RuntimeSettings` · `aqven.app.environment`

| Field | Type | Default |
| --- | --- | --- |
| `studio` | `<class 'bool'>` | `True` |
| `host` | `<class 'str'>` | `'127.0.0.1'` |
| `port` | `<class 'int'>` | `5180` |
| `open_browser` | `<class 'bool'>` | `False` |


## ServerOptions

`class ServerOptions` · `aqven.server.app`

| Field | Type | Default |
| --- | --- | --- |
| `access_token` | `<class 'str'>` | `factory` |
| `port` | `int \| None` | `None` |
| `guard` | `<class 'bool'>` | `True` |
| `studio_dist` | `pathlib.Path \| None` | `None` |
| `serve_studio` | `<class 'bool'>` | `True` |
| `serve_api` | `<class 'bool'>` | `True` |
| `dev_origin` | `str \| None` | `None` |
| `blob_directory` | `pathlib.Path \| None` | `None` |
| `watch` | `<class 'bool'>` | `True` |
| `watch_debounce_ms` | `<class 'int'>` | `250` |
| `mcp_url` | `str \| None` | `None` |
| `compiler` | `aqven.server.workspace.ProjectCompiler \| None` | `None` |
| `environ` | `collections.abc.Mapping[str, str]` | `factory` |
| `shutdown_signal` | `asyncio.locks.Event \| None` | `None` |


## check_project

`def check_project(root: 'Path') -> 'CheckReport'`

## create_app

`def create_app(root: 'Path', facade: 'EngineFacade', settings: 'SettingsStore', extra_routers: 'Sequence[APIRouter]' = (), *, options: 'ServerOptions | None' = None, extensions: 'ServerExtensions | None' = None, blobs: 'BlobFiles | None' = None, workspace: 'ProjectWorkspace | None' = None, series: 'SeriesJobs | None' = None, probes: 'StatusProbes | None' = None, writer: 'WriteService | None' = None) -> 'FastAPI'`

## create_local_app

`def create_local_app(root: 'Path', options: 'LocalAppOptions | None' = None, environ: 'Mapping[str, str] | None' = None) -> 'FastAPI'`

## create_mcp_server

`def create_mcp_server(root: 'Path', *, engine: 'EngineFacade | None' = None, write: 'bool' = True, python: 'str' = 'sys.executable') -> 'MCPServer'`

## export_openapi

`def export_openapi(target: 'Path', app: 'FastAPI | None' = None) -> 'Path'`

## load_project_env

`def load_project_env(root: 'Path', environ: 'MutableMapping[str, str] | None' = None) -> 'bool'`

Load the project `.env` file into the environment of the process.

## local_app_lifespan

`def local_app_lifespan(app: 'FastAPI') -> 'AsyncGenerator[None]'`

## node_address

`def node_address(node_id: 'str', *, branch_key: 'str | None' = None, iteration: 'int | None' = None, item_index: 'int | None' = None) -> 'ExecutionAddress'`

## openapi_text

`def openapi_text(app: 'FastAPI') -> 'str'`

## runtime_settings

`def runtime_settings(environ: 'Mapping[str, str] | None' = None, defaults: 'RuntimeSettings | None' = None) -> 'RuntimeSettings'`
