Runtime 레퍼런스¶
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: TransientInvocationError
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 ¶
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.
contract_transition_guard ¶
Serialize probe registration with contract snapshot/publication/restamping.
transition_tool_contract ¶
transition_tool_contract(tool_key: str, *, expected_old_fingerprint: str, expected_new_fingerprint: str) -> None
Carry trusted probes across one accepted contract transition.
lifecycle_guard
async
¶
Serialize lifecycle commits without running probe callbacks under the lock.
Normal lifecycle transitions may invalidate an in-flight probe generation and let its result be discarded at commit time. Destructive operations can request wait_for_inflight to drain already-started probes while preventing new ones from starting. A probe that re-enters a destructive lifecycle operation never waits for itself.
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
¶
AfterExecutionHook¶
schemarouter.AfterExecutionHook
module-attribute
¶
AfterExecutionHook = Callable[[ToolSpec, EndpointSpec, ToolCall, ToolResult], None | Awaitable[None]]
RegistryExecutor¶
schemarouter.RegistryExecutor ¶
RegistryExecutor(registry: ToolRegistry, *, policy: ExecutionPolicy | None = None, authorization_policy: AuthorizationPolicy | None = None, approval_callback: ApprovalCallback | None = None, hooks: ExecutionHooks | None = None, unavailable_cooldown_seconds: float = 30.0, max_offloaded_sync_workers: int = 8)
Executes validated plans using caller-supplied trusted invokers.
has_tool_runtime_state ¶
Return whether any binding or availability state exists for one tool key.
ensure_tool_runtime_state_empty ¶
Fail before publication if a staged key already owns executor runtime state.
is_access_available_for_contract_lazy ¶
is_access_available_for_contract_lazy(tool_key: str, endpoint: str, fingerprint_supplier: Callable[[], str]) -> bool
Skip expensive full-tool fingerprinting when no cooldown exists.
Under the same runtime lock, first check for any cooldown bound to this exact tool and endpoint. Only a relevant entry needs a contract fingerprint to decide whether the cooldown is current, expired, or belongs to an older schema version. Never bypass a matching cooldown. The supplier is not cached across calls or trusted identities.
bind ¶
bind(tool_key: str, invoker: BoundEndpointInvoker, *, expected_fingerprint: str | None = None, offload_sync: bool = False, require_empty_runtime_state: bool = False) -> int
Bind an invoker, optionally pinned to the exact contract it was built for.
Callers that construct an invoker from a particular ToolSpec must pass that spec's fingerprint. If the registry moved before binding, refuse before storing the invoker rather than blessing it for an unrelated contract.
publish_bound_tool ¶
publish_bound_tool(tool: ToolSpec, invoker: BoundEndpointInvoker, *, replace: bool = False, expected_fingerprint: str | None = None, expected_version: int | None = None, offload_sync: bool = False) -> str
Publish one registry contract and trusted binding as one logical transition.
The registry write remains the concurrency authority. If binding fails, rollback is attempted only while the registry still contains the exact contract/version published by this call. A concurrent writer therefore causes a fail-closed outcome instead of being overwritten by rollback.
restamp_binding ¶
Re-point an existing binding at a fingerprint the caller already validated.
Used only after trusted local code amends a contract in a way that
amendment.validate_amendment accepted. The invoker object is neither
accepted nor returned, so the caller never handles a live transport.
expected_fingerprint must be the fingerprint of the amendment that was
actually validated. The current registry entry is re-read and compared
against it rather than trusted outright: if some other writer replaced
the registered spec between validation and this call (a concurrent
thread, or another process on a shared registry), the fingerprints will
no longer match and the binding is left untouched. Re-reading the
registry's fingerprint and stamping it unconditionally would let a
binding go "ready" for a contract that never passed validation.
shutdown_offloaded_sync ¶
Stop accepting router-owned sync offloads without claiming running threads stopped.
purge_tool_runtime_state ¶
Forget trusted binding and bounded availability state for one tool.
bound_keys ¶
Return live trusted-invoker keys without exposing invoker objects.
binding_states ¶
Return privacy-safe binding readiness for registered and orphaned bindings.
validate_parallel_read_only ¶
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.
RunTraceStore¶
schemarouter.RunTraceStore ¶
Bases: Protocol
Structural contract for append-only run-event persistence.
SQLiteRunTraceStore¶
schemarouter.SQLiteRunTraceStore ¶
SQLiteRunTraceStore(path: str | Path, *, timeout: float = 5.0, document_limits: PersistedDocumentLimits | None = None, retention_policy: TraceRetentionPolicy | None = None)
Append-only SQLite store for replayable RunEvent streams.
The store persists the exact RunEvent envelope it receives. SchemaRouter's runtime stream applies structured redaction before persistence by default, including when payload tracing is enabled. Only the explicit raw_trace_payloads escape hatch emits unredacted runtime events. External event producers remain responsible for their own redaction.
prune ¶
Prune traces transactionally according to an explicit retention policy.
Complete runs may be bounded by age and/or count. Incomplete runs are preserved unless stale_incomplete_after_seconds is explicitly set. now is an optional Unix timestamp intended for deterministic operator tooling and tests.
record_run_events¶
schemarouter.record_run_events
async
¶
record_run_events(events: AsyncIterator[RunEvent], *, store: RunTraceStore) -> AsyncIterator[RunEvent]
Persist an event stream and promptly propagate downstream closure upstream.
replay_run_events¶
schemarouter.replay_run_events ¶
Replay detached historical events without re-executing any tool call.
CapabilitySnapshotStore¶
schemarouter.CapabilitySnapshotStore ¶
CapabilitySnapshotStore(snapshot: CapabilityGraphSnapshot, *, graph: CapabilityDependencyGraph | None = None, context: CompatibilityContext | None = None, validator: PublicationValidator | None = None)
Atomic in-process publication of validated immutable capability snapshots.
The store serializes writers with a process-local lock and supports explicit CAS preconditions. Readers receive a deep copy of one complete publication, never a partially rebuilt graph. Runtime health is intentionally outside this store.
compare_and_publish ¶
compare_and_publish(contracts: list[CapabilityContract], *, sources: list[CapabilitySourceRevision] | None = None, builder_version: str | None = None, built_at: datetime | None = None, expected_revision: int | None = None, expected_snapshot_id: str | None = None, force_full_rebuild: bool = False) -> CapabilitySnapshotPublication
Build, validate, and atomically publish a successor snapshot.
Any exception before the final assignment leaves the predecessor publication active. The compatibility context is fixed for the lifetime of the store, so an incremental graph update cannot silently change semantic-equivalence policy.
CapabilitySnapshotPublication¶
schemarouter.CapabilitySnapshotPublication ¶
Bases: StrictModel
CapabilityPublicationConflictError¶
schemarouter.CapabilityPublicationConflictError ¶
Bases: RuntimeError
Raised when a compare-and-swap publication precondition is stale.
RouterInspection¶
schemarouter.RouterInspection ¶
Bases: StrictModel
Live operational snapshot of one SchemaRouter instance.
CapabilityDecisionTraceInspection¶
schemarouter.CapabilityDecisionTraceInspection ¶
Bases: StrictModel
CapabilitySnapshotProvenance¶
schemarouter.CapabilitySnapshotProvenance ¶
Bases: StrictModel
CapabilityDecisionCandidateInspection¶
schemarouter.CapabilityDecisionCandidateInspection ¶
Bases: StrictModel