Public API

The top-level schemarouter package exposes the stable public surface intended for normal users.

SchemaRouter

schemarouter.SchemaRouter

SchemaRouter(*, analyzer: QueryAnalyzer | None = None, http_client: AsyncClient | None = None, policy: ExecutionPolicy | None = None, approval_callback: ApprovalCallback | None = None, execution_hooks: ExecutionHooks | None = None, registry: ToolRegistry | None = None, adapter_registry: AdapterRegistry | None = None, unavailable_cooldown_seconds: float = 30.0)

High-level facade for schema-aware planning and execution.

inspect

inspect() -> RouterInspection

Return a privacy-safe live operational snapshot.

mark_access_unavailable

mark_access_unavailable(tool_key: str, endpoint: str, *, cooldown_seconds: float | None = None) -> None

Mark one trusted access path temporarily unavailable.

mark_access_available

mark_access_available(tool_key: str, endpoint: str) -> None

Clear temporary unavailability for one trusted access path.

unavailable_access_paths

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

Return access paths currently held in the bounded cooldown window.

register_health_probe

register_health_probe(tool_key: str, endpoint: str, probe: HealthProbe) -> None

Register a trusted local health probe for one read-only access path.

plan

plan(request: PlanRequest | str) -> ExecutionPlan

Schema-aware planning without requiring a currently bound invoker.

aplan async

aplan(request: PlanRequest | str) -> ExecutionPlan

Async schema-aware planning without requiring a currently bound invoker.

plan_executable

plan_executable(request: PlanRequest | str) -> ExecutionPlan

Plan only across routes that are currently executable by this router instance.

aplan_executable async

aplan_executable(request: PlanRequest | str) -> ExecutionPlan

Async counterpart to :meth:plan_executable.

AdapterRegistry

schemarouter.AdapterRegistry

AdapterRegistry(adapters: list[SourceAdapter] | None = None)

Ordered registry for structured capability-source adapters.

AdapterContext

schemarouter.AdapterContext dataclass

AdapterContext(url: str, name: str | None = None, namespace: str | None = None, provider: str | None = None, access_mode: str | None = None, base_url: str | None = None, schema_headers: dict[str, str] | None = None, trusted_headers: dict[str, str] | None = None, mcp_client_factory: Any | None = None, openapi_external_refs: bool = False, openapi_ref_max_depth: int = 3, openapi_ref_max_documents: int = 8, openapi_ref_max_bytes: int = 10 * 1024 * 1024, timeout: float = 20.0, http_client: AsyncClient | None = None)

AdapterLoadResult

schemarouter.AdapterLoadResult dataclass

AdapterLoadResult(tool: ToolSpec, invoker: Any | None = None)

OPTIMADESourceAdapter

schemarouter.OPTIMADESourceAdapter

ConfiguredSchemaRouter

schemarouter.ConfiguredSchemaRouter

ConfiguredSchemaRouter(router: SchemaRouter, config: RunConfig)

SchemaRouter with an immutable default RunConfig.

PlanRequest

schemarouter.PlanRequest

Bases: StrictModel

ToolResult

schemarouter.ToolResult

Bases: StrictModel

ExecutionPolicy

schemarouter.ExecutionPolicy dataclass

ExecutionPolicy(allow_mutations: bool = False, allow_destructive: bool = False, allow_unclassified_remote: bool = False, approval_mode: ApprovalMode = 'never', rules: tuple[PolicyRule, ...] = ())

Local execution authority for side effects and optional per-call approval.

Fine-grained rules are trusted local configuration and are evaluated before the legacy category switches. Existing allow_* flags remain the default behavior when no rule matches.

evaluate

evaluate(tool: ToolSpec, endpoint: EndpointSpec, call: ToolCall) -> PolicyDecision

Resolve authority without executing the call.

A matching trusted rule may narrow or explicitly grant authority. If no rule matches, the historical category-level fail-closed behavior is preserved.

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.

ApprovalDeniedError

schemarouter.ApprovalDeniedError

Bases: PolicyViolationError

Raised when a call requiring trusted local approval is not approved.

ExecutionBudgetExceededError

schemarouter.ExecutionBudgetExceededError

Bases: PolicyViolationError

Raised before execution would exceed a trusted local run budget.

MCPClientFactory

schemarouter.MCPClientFactory

Bases: Protocol

Trusted factory for an authenticated MCP client lifecycle.

OpenAPICompatibilityReport

schemarouter.OpenAPICompatibilityReport

Bases: StrictModel

Machine-readable summary of SchemaRouter's OpenAPI import fidelity.

AdapterPluginInfo

schemarouter.AdapterPluginInfo dataclass

AdapterPluginInfo(name: str, value: str, distribution: str | None = None, version: str | None = None)

Metadata-only description of an installed adapter plugin.

RegistryInspection

schemarouter.RegistryInspection

Bases: StrictModel

Snapshot summary of a tool registry.

ToolInspection

schemarouter.ToolInspection

Bases: StrictModel

Derived operational view of one registered tool.

EndpointInspection

schemarouter.EndpointInspection

Bases: StrictModel

Derived operational view of one registered endpoint.

TraceInspection

schemarouter.TraceInspection

Bases: StrictModel

Compact operational summary of one persisted run trace.

inspect_registry

schemarouter.inspect_registry

inspect_registry(registry: ToolRegistry) -> RegistryInspection

inspect_tool

schemarouter.inspect_tool

inspect_tool(registry: ToolRegistry, key: str) -> ToolInspection

inspect_trace

schemarouter.inspect_trace

inspect_trace(store: RunTraceStore, run_id: str) -> TraceInspection

inspect_traces

schemarouter.inspect_traces

inspect_traces(store: RunTraceStore, *, complete: bool | None = None) -> tuple[TraceInspection, ...]