공개 API

최상위 schemarouter package는 일반 사용자를 위한 안정적인 public surface를 제공합니다.

SchemaRouter

schemarouter.SchemaRouter

SchemaRouter(*, analyzer: QueryAnalyzer | None = None, http_client: AsyncClient | None = None, policy: ExecutionPolicy | None = None, authorization_policy: AuthorizationPolicy | None = None, authorization_audit_hook: AuthorizationAuditHook | None = None, authorization_audit_delivery_mode: AuthorizationAuditDeliveryMode = 'best_effort', approval_callback: ApprovalCallback | None = None, execution_hooks: ExecutionHooks | None = None, registry: ToolRegistry | None = None, adapter_registry: AdapterRegistry | None = None, network_policy: NetworkPolicy | None = None, structural_retrieval: bool = False, unavailable_cooldown_seconds: float = 30.0)

Bases: NativeProviderConvenienceMixin

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

provider_profiles property

provider_profiles: ProviderProfileRegistry

Compatibility view of the process-local provider profile registry.

provider_profile_registry property

provider_profile_registry: ProviderProfileRegistry

Return the process-local provider profile registry.

authorization_audit_delivery_status

authorization_audit_delivery_status() -> AuthorizationAuditDeliveryStatus

Return privacy-safe health counters for the configured audit sink.

aclose async

aclose() -> None

Stop router-owned background tasks without closing caller-owned resources.

inspect

inspect(*, decision_traces: Sequence[CapabilityDecisionTrace] = ()) -> 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.

register_schema_watch

register_schema_watch(tool_key: str, *, interval_seconds: float = 300.0, apply_compatible: bool = True, schema_headers: dict[str, str] | None = None, trusted_headers: dict[str, str] | None = None, mcp_client_factory: MCPClientFactory | None = None, timeout_seconds: float = RUNTIME_DEFAULTS.transport_timeout_seconds) -> None

Register one remote structured source for periodic schema refresh.

aremove_tool async

aremove_tool(tool_key: str) -> ToolSpec

Atomically remove one capability and all router-owned runtime state.

remove_tool

remove_tool(tool_key: str) -> ToolSpec

Synchronous wrapper for :meth:aremove_tool.

add_bound_tool

add_bound_tool(tool: ToolSpec, invoker: BoundEndpointInvoker, *, replace: bool = False, offload_sync: bool = False) -> str

Register a canonical ToolSpec and bind one trusted invoker.

This is the explicit escape hatch for SDKs and protocol clients that do not expose a safely introspectable Python signature. The ToolSpec remains the complete model-visible contract; client objects, credentials, and transport state stay inside trusted invoker state.

native_schema_watch_snapshots

native_schema_watch_snapshots() -> tuple[NativeSchemaWatchSnapshot, ...]

Return bounded watcher degradation state without exception messages.

arefresh_native_schema async

arefresh_native_schema(tool_key: str, *, apply_compatible: bool = True) -> SchemaRefreshResult

Re-introspect one caller-owned native data source.

add_sqlite_database

add_sqlite_database(connection: Any, *, database_name: str = 'sqlite', namespace: str | None = None, tables: set[str] | tuple[str, ...] | list[str] | None = None, max_default_rows: int = 100, max_discovery_relations: int = 128, max_columns_per_relation: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Introspect and register a caller-owned SQLite database as read-only capabilities.

The live connection remains in trusted process-local invokers and is never persisted or copied into ToolSpec metadata. One ToolSpec is registered per selected table/view. The generated invokers support bounded projected SELECT operations only; callers cannot supply arbitrary SQL text through the model-visible contract.

add_sqlalchemy_database

add_sqlalchemy_database(engine: Any, *, database_name: str, namespace: str | None = None, schemas: tuple[str | None, ...] | list[str | None] | None = None, tables: set[str] | tuple[str, ...] | list[str] | None = None, include_views: bool = True, max_default_rows: int = 100, remote: bool = True, max_discovery_relations: int = 128, max_columns_per_relation: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Introspect and register a caller-owned SQLAlchemy Engine.

SQLAlchemy performs dialect-specific schema discovery and parameter binding while the live Engine, connection URL, credentials, pools, and driver state remain process-local. The generated model-visible contract contains only relation/column metadata and bounded projected read operations.

aadd_vector_store async

aadd_vector_store(backend: Any, embed_query: Any, *, database_name: str, namespace: str | None = None, collections: set[str] | tuple[str, ...] | list[str] | None = None, default_top_k: int = RUNTIME_DEFAULTS.vector_top_k, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_fields_per_collection: int = RUNTIME_DEFAULTS.max_fields_per_collection, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Discover and register a caller-owned vector store as bounded search capabilities.

add_vector_store

add_vector_store(backend: Any, embed_query: Any, *, database_name: str, namespace: str | None = None, collections: set[str] | tuple[str, ...] | list[str] | None = None, default_top_k: int = RUNTIME_DEFAULTS.vector_top_k, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_fields_per_collection: int = RUNTIME_DEFAULTS.max_fields_per_collection, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Synchronous wrapper for :meth:aadd_vector_store.

aadd_native_vector_store async

aadd_native_vector_store(backend_name: str, resource: Any, embed_query: Any, *, database_name: str, namespace: str | None = None, collections: set[str] | tuple[str, ...] | list[str] | None = None, backend_options: Mapping[str, Any] | None = None, default_top_k: int = RUNTIME_DEFAULTS.vector_top_k, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_fields_per_collection: int = RUNTIME_DEFAULTS.max_fields_per_collection, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Register a native vector backend through the descriptor registry.

add_native_vector_store

add_native_vector_store(backend_name: str, resource: Any, embed_query: Any, *, database_name: str, namespace: str | None = None, collections: set[str] | tuple[str, ...] | list[str] | None = None, backend_options: Mapping[str, Any] | None = None, default_top_k: int = RUNTIME_DEFAULTS.vector_top_k, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_fields_per_collection: int = RUNTIME_DEFAULTS.max_fields_per_collection, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Synchronous wrapper for :meth:aadd_native_vector_store.

aadd_graph_store async

aadd_graph_store(backend: Any, *, database_name: str, namespace: str | None = None, graphs: set[str] | tuple[str, ...] | list[str] | None = None, default_limit: int = RUNTIME_DEFAULTS.collection_limit, default_max_hops: int = RUNTIME_DEFAULTS.graph_max_hops, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_schema_items_per_graph: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Discover and register a caller-owned property-graph or RDF backend.

add_graph_store

add_graph_store(backend: Any, *, database_name: str, namespace: str | None = None, graphs: set[str] | tuple[str, ...] | list[str] | None = None, default_limit: int = RUNTIME_DEFAULTS.collection_limit, default_max_hops: int = RUNTIME_DEFAULTS.graph_max_hops, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_schema_items_per_graph: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Synchronous wrapper for :meth:aadd_graph_store.

aadd_record_store async

aadd_record_store(backend: Any, *, database_name: str, namespace: str | None = None, sources: set[str] | tuple[str, ...] | list[str] | None = None, default_limit: int = RUNTIME_DEFAULTS.collection_limit, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_fields_per_source: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Discover and register document/search/key-value/time-series sources.

add_record_store

add_record_store(backend: Any, *, database_name: str, namespace: str | None = None, sources: set[str] | tuple[str, ...] | list[str] | None = None, default_limit: int = RUNTIME_DEFAULTS.collection_limit, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_fields_per_source: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Synchronous wrapper for :meth:aadd_record_store.

aadd_native_graph_store async

aadd_native_graph_store(backend_name: str, resource: Any, *, database_name: str, namespace: str | None = None, graphs: set[str] | tuple[str, ...] | list[str] | None = None, backend_options: Mapping[str, Any] | None = None, default_limit: int = RUNTIME_DEFAULTS.collection_limit, default_max_hops: int = RUNTIME_DEFAULTS.graph_max_hops, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_schema_items_per_graph: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Register a native graph backend through the descriptor registry.

add_native_graph_store

add_native_graph_store(backend_name: str, resource: Any, *, database_name: str, namespace: str | None = None, graphs: set[str] | tuple[str, ...] | list[str] | None = None, backend_options: Mapping[str, Any] | None = None, default_limit: int = RUNTIME_DEFAULTS.collection_limit, default_max_hops: int = RUNTIME_DEFAULTS.graph_max_hops, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_schema_items_per_graph: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Synchronous wrapper for :meth:aadd_native_graph_store.

aadd_native_record_store async

aadd_native_record_store(backend_name: str, resource: Any, *, database_name: str, namespace: str | None = None, sources: set[str] | tuple[str, ...] | list[str] | None = None, backend_options: Mapping[str, Any] | None = None, default_limit: int = RUNTIME_DEFAULTS.collection_limit, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_fields_per_source: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Register a native record backend through the descriptor registry.

add_native_record_store

add_native_record_store(backend_name: str, resource: Any, *, database_name: str, namespace: str | None = None, sources: set[str] | tuple[str, ...] | list[str] | None = None, backend_options: Mapping[str, Any] | None = None, default_limit: int = RUNTIME_DEFAULTS.collection_limit, remote: bool = True, max_discovery_sources: int = RUNTIME_DEFAULTS.max_discovery_sources, max_fields_per_source: int = 256, max_generated_bytes: int = RUNTIME_DEFAULTS.max_generated_bytes) -> tuple[str, ...]

Synchronous wrapper for :meth:aadd_native_record_store.

amend_capability

amend_capability(tool_key: str, amended: ToolSpec) -> str

Declare or annotate the result contract of an already registered capability.

Trusted local code may add output-field declarations and annotate their meaning: semantic IDs, aliases, paths, units, normalization, qualifiers, identifier flags, provenance and licence. It may not change execution identity or validation shape; see amendment.validate_amendment.

This is more than cosmetic annotation. Accepted aspects can change what the caller receives and which routes are reachable:

• path / result_path on an existing field re-point which value a sanctioned field name resolves to. Projection is the redaction boundary for a field-selecting call, so amending these can move previously unprojected response content into the answer under the same field name.
• unit and unit_normalization change how a numeric value is rescaled before it reaches the caller, on the result path (see RegistryExecutor._normalize_projected_units in executor.py).
• source_type, license, and unit feed evidence availability (evidence.py), which the executor enforces as a hard gate. An amendment can unblock an evidence-gated route by declaration alone, with no change to what the underlying source actually returns.
• Declaring a semantic ID or unit can also change routing outright: it may make a cross-provider fallback compatible that previously was not.

Because of this, amend_capability is trusted local code, at the same grade as RegistryExecutor.bind(). It must never be reachable from a decision backend, remote content, or model output.

The execution binding is carried across the amendment, so a capability SchemaRouter imported on the application's behalf stays executable. The invoker is never exposed to the caller.

If the capability was already bound and re-stamping the binding fails — only possible if another writer replaced the registered spec between validation and this call, e.g. a concurrent thread or another process on a shared registry — this raises BindingDriftError immediately instead of returning a key whose binding will only be discovered stale at execution time. The amendment itself is still registered; call RegistryExecutor.bind() again to recover.

bind_existing

bind_existing(tool_key: str, config: TrustedBindingConfig, *, expected_fingerprint: str | None = None) -> BindingReconciliationItem

Bind one persisted capability without mutating its schema document.

rehydrate_bindings

rehydrate_bindings(resolver: BindingResolver, *, required_tools: Sequence[str] | None = None, strict: bool = False) -> BindingReconciliationReport

Re-establish trusted process-local bindings for persisted registry state.

register_provider_profile

register_provider_profile(profile: ProviderProfile, *, replace: bool = False) -> str

Register declarative provider identity metadata.

resolve_provider

resolve_provider(provider: str, *, methods: set[str] | list[str] | tuple[str, ...] | None = None) -> ProviderResolution

Resolve one provider identity into known access methods without network I/O.

discover_provider

discover_provider(provider: str, *, backend: ProviderDiscoveryBackend | None = None, limit: int = 8) -> ProviderDiscoveryProposal

Propose provider identities without registering or granting authority.

Built-in discovery is deterministic and local. A caller may supply a trusted discovery backend (for example one backed by an internal catalog or web search), but its candidates remain inert until explicitly approved or registered.

approve_provider_candidate

approve_provider_candidate(candidate: ProviderDiscoveryCandidate, *, expected_digest: str, replace: bool = False) -> str

Register one reviewed discovery candidate after a digest check.

load_provider_profile_plugins

load_provider_profile_plugins(*, allowlist: set[str] | list[str] | tuple[str, ...], replace: bool = False) -> tuple[str, ...]

Load explicitly trusted installed provider-profile plugins.

add_provider async

add_provider(provider: str, *, methods: set[str] | list[str] | tuple[str, ...] | None = None, trusted_headers_by_method: Mapping[str, Mapping[str, str]] | None = None, replace: bool = False, timeout: float = RUNTIME_DEFAULTS.transport_timeout_seconds, require_all: bool = False) -> ProviderRegistrationResult

Register safely usable access methods for one provider.

add_langchain_tool

add_langchain_tool(tool: Any, *, name: str | None = None, namespace: str | None = None, provider: str | None = None, access_mode: str | None = None, read_only: bool | None = None, destructive: bool | None = None, remote: bool = True, replace: bool = False) -> str

Import and bind one LangChain BaseTool-like object.

SchemaRouter trusts only the tool's declared input/output schemas plus the explicit local authority classification supplied here. Descriptions and foreign metadata do not grant read/write permission.

add_llamaindex_tool

add_llamaindex_tool(tool: Any, *, name: str | None = None, namespace: str | None = None, provider: str | None = None, access_mode: str | None = None, read_only: bool | None = None, destructive: bool | None = None, remote: bool = True, replace: bool = False) -> str

Import and bind one LlamaIndex BaseTool-like object.

add_http_tool

add_http_tool(tool: ToolSpec, *, base_url: str, provider: str | None = None, access_mode: str | None = None, trusted_headers: dict[str, str] | None = None, timeout: float = RUNTIME_DEFAULTS.transport_timeout_seconds, max_response_bytes: int = RUNTIME_DEFAULTS.max_response_bytes, replace: bool = False) -> str

Register and bind a trusted declarative HTTP/JSON ToolSpec.

The supplied ToolSpec is the machine-readable manifest. Authentication remains only in trusted_headers and is never copied into model-visible schema metadata.

add_mcp_client_factory async

add_mcp_client_factory(client_factory: MCPBoundClientFactory, *, name: str | None = None, namespace: str | None = None, provider: str | None = None, access_mode: str | None = None, transport: str = 'custom', transport_fingerprint: str | None = None, replace: bool = False, timeout: float = RUNTIME_DEFAULTS.transport_timeout_seconds, discovery_limits: MCPDiscoveryLimits | None = None) -> ToolSpec

Import MCP tools through a trusted transport-neutral client factory.

The factory owns transport, credentials, subprocesses, sockets, or in-process state. None of that trusted state is copied into the model-visible ToolSpec.

add_mcp_stdio async

add_mcp_stdio(command: str, *, args: Sequence[str] = (), env: Mapping[str, str] | None = None, cwd: str | None = None, allowed_commands: Sequence[str] = (), name: str | None = None, namespace: str | None = None, provider: str | None = None, access_mode: str | None = None, replace: bool = False, timeout: float = RUNTIME_DEFAULTS.transport_timeout_seconds, discovery_limits: MCPDiscoveryLimits | None = None) -> ToolSpec

Spawn a trusted local MCP stdio server and register its advertised tools.

probe_url async

probe_url(url: str, *, kind: SourceKind = 'auto', name: str | None = None, namespace: str | None = None, provider: 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: MCPClientFactory | None = None, mcp_discovery_limits: MCPDiscoveryLimits | None = None, allow_active_probes: bool = False, openapi_external_refs: bool = False, openapi_ref_max_depth: int = RUNTIME_DEFAULTS.openapi_ref_max_depth, openapi_ref_max_documents: int = RUNTIME_DEFAULTS.openapi_ref_max_documents, openapi_ref_max_bytes: int = RUNTIME_DEFAULTS.openapi_ref_max_bytes, timeout: float = RUNTIME_DEFAULTS.transport_timeout_seconds) -> SourceProbeResult

Diagnose a structured URL source without mutating the registry or bindings.

arefresh_schema async

arefresh_schema(tool_key: str, *, apply_compatible: bool = True, schema_headers: dict[str, str] | None = None, trusted_headers: dict[str, str] | None = None, mcp_client_factory: MCPClientFactory | None = None, mcp_discovery_limits: MCPDiscoveryLimits | None = None, timeout: float = RUNTIME_DEFAULTS.transport_timeout_seconds, _expected_fingerprint: str | None = None, _expected_source_identity: StructuredSourceIdentity | None = None, _accept_candidate_fingerprint: str | None = None, _accept_candidate_source_identity: str | None = None, _apply_guard: Callable[[], Any] | None = None) -> SchemaRefreshResult

Reinspect a registered remote schema and apply only proven-compatible drift.

refresh_schema

refresh_schema(tool_key: str, *, apply_compatible: bool = True, schema_headers: dict[str, str] | None = None, trusted_headers: dict[str, str] | None = None, mcp_client_factory: MCPClientFactory | None = None, mcp_discovery_limits: MCPDiscoveryLimits | None = None, timeout: float = RUNTIME_DEFAULTS.transport_timeout_seconds) -> SchemaRefreshResult

Synchronous wrapper for :meth:arefresh_schema.

plan

plan(request: PlanRequest | str) -> ExecutionPlan

Schema-aware planning under any active trusted principal context.

aplan async

aplan(request: PlanRequest | str) -> ExecutionPlan

Async schema-aware planning under any active trusted principal context.

plan_authorized

plan_authorized(request: PlanRequest | str, *, principal: PrincipalContext) -> ExecutionPlan

Plan with one explicitly supplied trusted principal.

aplan_authorized async

aplan_authorized(request: PlanRequest | str, *, principal: PrincipalContext) -> ExecutionPlan

Async counterpart to :meth:plan_authorized.

retrieve_routes

retrieve_routes(request: PlanRequest | str, *, k: int = 5) -> CapabilityRouteRetrieval

Return lightweight Top-K route references under active authorization.

aretrieve_routes async

aretrieve_routes(request: PlanRequest | str, *, k: int = 5) -> CapabilityRouteRetrieval

Async counterpart to :meth:retrieve_routes.

retrieve_routes_authorized

retrieve_routes_authorized(request: PlanRequest | str, *, principal: PrincipalContext, k: int = 5) -> CapabilityRouteRetrieval

Retrieve route references for one explicitly supplied principal.

aretrieve_routes_authorized async

aretrieve_routes_authorized(request: PlanRequest | str, *, principal: PrincipalContext, k: int = 5) -> CapabilityRouteRetrieval

Async counterpart to :meth:retrieve_routes_authorized.

retrieve

retrieve(request: PlanRequest | str, *, k: int = 5) -> CapabilityRetrieval

Return Top-K typed capabilities under any active principal context.

aretrieve async

aretrieve(request: PlanRequest | str, *, k: int = 5) -> CapabilityRetrieval

Async counterpart to :meth:retrieve.

retrieve_authorized

retrieve_authorized(request: PlanRequest | str, *, principal: PrincipalContext, k: int = 5) -> CapabilityRetrieval

Retrieve capabilities for one explicitly supplied trusted principal.

retrieve_adaptive

retrieve_adaptive(request: PlanRequest | str, *, history: SuccessfulCapabilityHistory | None = None, history_weight: float = 0.0, exposure: SessionSchemaExposure | None = None, k: int = 5) -> CapabilityRetrieval

Retrieve with optional post-authorization history/context transforms.

aretrieve_adaptive async

aretrieve_adaptive(request: PlanRequest | str, *, history: SuccessfulCapabilityHistory | None = None, history_weight: float = 0.0, exposure: SessionSchemaExposure | None = None, k: int = 5) -> CapabilityRetrieval

Async counterpart to :meth:retrieve_adaptive.

aretrieve_authorized async

aretrieve_authorized(request: PlanRequest | str, *, principal: PrincipalContext, k: int = 5) -> CapabilityRetrieval

Async counterpart to :meth:retrieve_authorized.

reretrieve_state_aware

reretrieve_state_aware(request: PlanRequest | str, *, execution_state: TypedExecutionState, k: int = 5, state_requirements: dict[str, list[CapabilityFieldContract]] | None = None, state_preconditions: dict[str, list[CapabilityPrecondition]] | None = None) -> StateConditionedCapabilityRetrieval

Backfill over the same authorization-scoped surface as normal retrieval.

areretrieve_state_aware async

areretrieve_state_aware(request: PlanRequest | str, *, execution_state: TypedExecutionState, k: int = 5, state_requirements: dict[str, list[CapabilityFieldContract]] | None = None, state_preconditions: dict[str, list[CapabilityPrecondition]] | None = None) -> StateConditionedCapabilityRetrieval

Async counterpart to :meth:reretrieve_state_aware.

retrieve_state_aware

retrieve_state_aware(request: PlanRequest | str, *, execution_state: TypedExecutionState, k: int = 5, state_requirements: dict[str, list[CapabilityFieldContract]] | None = None, state_preconditions: dict[str, list[CapabilityPrecondition]] | None = None) -> StateAwareCapabilityRetrieval

Retrieve from the same authorization-scoped surface as normal retrieval.

aretrieve_state_aware async

aretrieve_state_aware(request: PlanRequest | str, *, execution_state: TypedExecutionState, k: int = 5, state_requirements: dict[str, list[CapabilityFieldContract]] | None = None, state_preconditions: dict[str, list[CapabilityPrecondition]] | None = None) -> StateAwareCapabilityRetrieval

Async counterpart to :meth:retrieve_state_aware.

plan_executable

plan_executable(request: PlanRequest | str) -> ExecutionPlan

Plan only across authorized routes with a ready local binding.

aplan_executable async

aplan_executable(request: PlanRequest | str) -> ExecutionPlan

Async counterpart to :meth:plan_executable.

plan_executable_authorized

plan_executable_authorized(request: PlanRequest | str, *, principal: PrincipalContext) -> ExecutionPlan

Plan executable routes for one explicitly supplied principal.

aplan_executable_authorized async

aplan_executable_authorized(request: PlanRequest | str, *, principal: PrincipalContext) -> ExecutionPlan

Async counterpart to :meth:plan_executable_authorized.

retrieve_executable

retrieve_executable(request: PlanRequest | str, *, k: int = 5) -> CapabilityRetrieval

Return Top-K authorized capabilities with a ready local binding.

aretrieve_executable async

aretrieve_executable(request: PlanRequest | str, *, k: int = 5) -> CapabilityRetrieval

Async counterpart to :meth:retrieve_executable.

retrieve_executable_authorized

retrieve_executable_authorized(request: PlanRequest | str, *, principal: PrincipalContext, k: int = 5) -> CapabilityRetrieval

Retrieve executable capabilities for one explicitly supplied principal.

aretrieve_executable_authorized async

aretrieve_executable_authorized(request: PlanRequest | str, *, principal: PrincipalContext, k: int = 5) -> CapabilityRetrieval

Async counterpart to :meth:retrieve_executable_authorized.

AdapterRegistry

schemarouter.AdapterRegistry

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

Ordered registry for structured capability-source adapters.

auto_candidates

auto_candidates(*, allow_active_probes: bool = False) -> tuple[SourceAdapter, ...]

Return adapters eligible for generic auto discovery.

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, schema_validators: dict[str, str] | None = None, trusted_headers: dict[str, str] | None = None, mcp_client_factory: Any | None = None, mcp_discovery_limits: 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, network_policy: NetworkPolicy = TRUSTED_INTERNAL_NETWORK_POLICY)

AdapterLoadResult

schemarouter.AdapterLoadResult dataclass

AdapterLoadResult(tool: ToolSpec, invoker: Any | None = None, probe_diagnostics: tuple[AdapterProbeDiagnostic, ...] = ())

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. Explicit allow/deny rules are authoritative; require_approval is an additional gate and does not grant mutation/destructive/unclassified authority by itself. Existing allow_* flags remain the default category authority.

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, ...]

PairwiseDecisionBackend

schemarouter.PairwiseDecisionBackend

PairwiseDecisionBackend(scorer: PairwiseScoreCallable, *, min_score: float = 0.0, min_margin: float = 0.0, option_text: DecisionOptionTextCallable | None = None)

Bounded decision backend driven by query-option pair scores.

The scorer receives one (query, option_text) pair for every locally authorized option and must return one confidence score in [0, 1] for every pair. SchemaRouter ranks those scores locally and maps positions back to the original opaque option IDs.

Option metadata is not forwarded by default. A custom option_text callback is trusted application code and controls its own disclosure. Execution authority never leaves the bounded DecisionRequest.

CallableDecisionBackend

schemarouter.CallableDecisionBackend

CallableDecisionBackend(model: DecisionCallable)

Provider-neutral adapter for hosted or local bounded-decision models.

DecisionBackendPluginInfo

schemarouter.DecisionBackendPluginInfo dataclass

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

Metadata-only description of an installed decision-backend plugin.

discover_decision_backend_plugins

schemarouter.discover_decision_backend_plugins

discover_decision_backend_plugins() -> tuple[DecisionBackendPluginInfo, ...]

Discover installed decision-backend plugins without importing plugin code.

load_decision_backend_plugin

schemarouter.load_decision_backend_plugin

load_decision_backend_plugin(name: str, *, config: Mapping[str, Any] | None = None) -> DecisionBackend

Explicitly import and construct one installed decision-backend plugin.

Loading an entry point executes trusted installed Python code. Discovery never imports plugin code; loading requires an exact plugin name so installed plugins are not executed implicitly.

ContractAmendmentError

schemarouter.ContractAmendmentError

Bases: RegistrationError

Raised when a proposed local contract amendment exceeds what is amendable.

ProviderProfile

schemarouter.ProviderProfile

Bases: StrictModel

Provider-level identity resolved into existing SchemaRouter ingestion methods.

ProviderResolution

schemarouter.ProviderResolution

Bases: StrictModel

ProviderRegistrationResult

schemarouter.ProviderRegistrationResult

Bases: StrictModel

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.

build_capability_artifact_from_graph

schemarouter.build_capability_artifact_from_graph

build_capability_artifact_from_graph(*, graph: CapabilityDependencyGraph, capabilities: list[CapabilityContract], sources: list[CapabilityArtifactSource] | None = None, provenance: dict[str, str] | None = None, context: CompatibilityContext | None = None) -> CapabilityGraphArtifact

migrate_capability_artifact

schemarouter.migrate_capability_artifact

migrate_capability_artifact(document: str, *, document_limits: DocumentLimits | None = None) -> CapabilityArtifactMigrationResult

migrate_capability_snapshot

schemarouter.migrate_capability_snapshot

migrate_capability_snapshot(document: str, *, document_limits: DocumentLimits | None = None) -> CapabilitySnapshotMigrationResult

CapabilityDecisionTrace

schemarouter.CapabilityDecisionTrace

Bases: StrictModel

build_capability_decision_trace

schemarouter.build_capability_decision_trace

build_capability_decision_trace(candidates: list[CapabilityDecisionCandidateInput], *, snapshot_id: str | None = None, registry_version: int | None = None, lineage: CapabilityLineage | None = None, enabled: bool = True) -> CapabilityDecisionTrace | None

Aggregate already-computed host-visible decision results.

This function is intentionally not a policy engine. It never changes candidate eligibility, routing order, fallback authority, or execution authority.

render_capability_decision_trace

schemarouter.render_capability_decision_trace

render_capability_decision_trace(trace: CapabilityDecisionTrace, *, detailed: bool = False) -> dict[str, object]

Render a privacy-safe compact or detailed inspection document.

inspect_capability_decision_trace

schemarouter.inspect_capability_decision_trace

inspect_capability_decision_trace(trace: CapabilityDecisionTrace) -> CapabilityDecisionTraceInspection

Return a compact privacy-safe decision trace summary.

ProviderProfileRegistry

schemarouter.ProviderProfileRegistry

ProviderProfileRegistry()

Deterministic provider/alias resolver.

Profiles are convenience metadata only. They never contain credentials or executable Python objects and they compile into the existing source-adapter/binding surfaces.

register_many

register_many(profiles: Iterable[ProviderProfile], *, replace: bool = False) -> tuple[str, ...]

Register a profile batch atomically against one coherent registry snapshot.

discover

discover(identifier: str, *, external_candidates: Iterable[ProviderDiscoveryCandidate] = (), limit: int = 8) -> ProviderDiscoveryProposal

Return inspectable candidates without registering or probing anything.

approve_discovery_candidate

approve_discovery_candidate(candidate: ProviderDiscoveryCandidate, *, expected_digest: str, replace: bool = False) -> str

Register one reviewed candidate after an exact profile-digest check.

ProviderAccessMethod

schemarouter.ProviderAccessMethod

Bases: StrictModel

Declarative description of one known way to reach a provider.

update_capability_dependency_graph

schemarouter.update_capability_dependency_graph

update_capability_dependency_graph(graph: CapabilityDependencyGraph, previous_capabilities: list[CapabilityContract], capabilities: list[CapabilityContract], *, context: CompatibilityContext | None = None) -> CapabilityDependencyGraph

Incrementally rebuild edges incident to added, removed, or changed contracts.

The compatibility context is assumed to be unchanged. If semantic equivalences or unit-conversion policy changes, callers must perform a full build because such a context change can affect edges between otherwise unchanged capabilities.

dependency_strongly_connected_components

schemarouter.dependency_strongly_connected_components

dependency_strongly_connected_components(graph: CapabilityDependencyGraph) -> tuple[tuple[str, ...], ...]

Return deterministic SCCs using an iterative Tarjan traversal.

validate_capability_publication

schemarouter.validate_capability_publication

validate_capability_publication(publication: CapabilitySnapshotPublication, *, context: CompatibilityContext | None = None) -> None

Validate graph/snapshot integrity without executing capabilities.

validate_capability_artifact

schemarouter.validate_capability_artifact

validate_capability_artifact(artifact: CapabilityGraphArtifact) -> CapabilityGraphArtifact

validate_capability_snapshot

schemarouter.validate_capability_snapshot

validate_capability_snapshot(snapshot: CapabilityGraphSnapshot) -> CapabilityGraphSnapshot

serialize_capability_snapshot

schemarouter.serialize_capability_snapshot

serialize_capability_snapshot(snapshot: CapabilityGraphSnapshot | CapabilitySnapshotDocument) -> str