Runtime reference

RunConfig

schemarouter.RunConfig

Bases: StrictModel

Per-run metadata and execution controls.

ExecutionBudget

schemarouter.ExecutionBudget

Bases: StrictModel

Trusted per-run execution limits.

Logical tool calls are counted once. Attempts, remote attempts, and cost units are counted for every actual invoker attempt, including retries.

RetryPolicy

schemarouter.RetryPolicy

Bases: StrictModel

Deterministic retry policy applied at the trusted executor boundary.

NonRetryableInvocationError

schemarouter.NonRetryableInvocationError

Bases: ExecutionError, RuntimeError

Raised when repeating the same invocation cannot safely recover.

Also remains a RuntimeError for compatibility with built-in invoker callers that historically caught deterministic runtime failures directly.

InvocationUnavailableError

schemarouter.InvocationUnavailableError

Bases: ExecutionError, RuntimeError

Raised when an otherwise valid access path is temporarily unavailable.

Executors may retry the same read-only route and a precompiled fallback route may use this marker to move to another trusted access path. Policy/schema/authorization failures must never be translated to this error.

AccessHealthMonitor

schemarouter.AccessHealthMonitor

AccessHealthMonitor(executor: RegistryExecutor)

Explicit background health checks for registered read-only access paths.

Probes are trusted local callbacks. The monitor never invents probes from remote metadata and never invokes a registered data endpoint on its own. Probe success reopens an access path; probe failure extends only the bounded availability cooldown.

HealthProbeSnapshot

schemarouter.HealthProbeSnapshot dataclass

HealthProbeSnapshot(tool: str, endpoint: str, status: HealthStatus, last_checked_at: datetime | None = None, last_error_type: str | None = None)

RunEvent

schemarouter.RunEvent

Bases: StrictModel

Typed event envelope emitted by SchemaRouter streaming APIs.

ExecutionHooks

schemarouter.ExecutionHooks dataclass

ExecutionHooks(*, before_call: Iterable[BeforeExecutionHook] = (), after_call: Iterable[AfterExecutionHook] = ())

Ordered trusted local hooks around one validated tool-call execution.

Hooks receive detached model snapshots. They cannot transform the executable ToolCall or the ToolResult returned to the caller. Returning any non-None value is rejected by the executor.

ExecutionHookError

schemarouter.ExecutionHookError

Bases: ExecutionError

Raised when a trusted execution hook violates or fails its contract.

BeforeExecutionHook

schemarouter.BeforeExecutionHook module-attribute

BeforeExecutionHook = Callable[[ToolSpec, EndpointSpec, ToolCall], None | Awaitable[None]]

AfterExecutionHook

schemarouter.AfterExecutionHook module-attribute

AfterExecutionHook = Callable[[ToolSpec, EndpointSpec, ToolCall, ToolResult], None | Awaitable[None]]

RegistryExecutor

schemarouter.RegistryExecutor

RegistryExecutor(registry: ToolRegistry, *, policy: ExecutionPolicy | None = None, approval_callback: ApprovalCallback | None = None, hooks: ExecutionHooks | None = None, unavailable_cooldown_seconds: float = 30.0)

Executes validated plans using caller-supplied trusted invokers.

bound_keys

bound_keys() -> tuple[str, ...]

Return live trusted-invoker keys without exposing invoker objects.

binding_states

binding_states() -> dict[str, str]

Return privacy-safe binding readiness for registered and orphaned bindings.

validate_parallel_read_only

validate_parallel_read_only(plan: ExecutionPlan) -> None

Fail before launching tasks unless every primary group has a trusted read-only route.

RunTrace

schemarouter.RunTrace

Bases: StrictModel

Validated replayable snapshot of one SchemaRouter run event stream.

replay

replay() -> tuple[RunEvent, ...]

Return detached events in their original validated order.

RunTraceStore

schemarouter.RunTraceStore

Bases: Protocol

Structural contract for append-only run-event persistence.

SQLiteRunTraceStore

schemarouter.SQLiteRunTraceStore

SQLiteRunTraceStore(path: str | Path, *, timeout: float = 5.0)

Append-only SQLite store for replayable RunEvent streams.

The store persists the exact RunEvent envelope it receives. Payloads are therefore redacted when the source stream uses the default RunConfig, but explicit include_payloads=True data will also be persisted and must be protected by the application.

record_run_events

schemarouter.record_run_events async

record_run_events(events: AsyncIterator[RunEvent], *, store: RunTraceStore) -> AsyncIterator[RunEvent]

Persist an event stream before yielding each event to downstream consumers.

replay_run_events

schemarouter.replay_run_events

replay_run_events(store: RunTraceStore, run_id: str) -> Iterator[RunEvent]

Replay detached historical events without re-executing any tool call.