Python API

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, 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_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, ...]	()

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'