Planning과 registry 레퍼런스¶
ToolRegistry¶
schemarouter.ToolRegistry ¶
Bases: Protocol
Structural contract for pluggable tool registries.
Read methods must return detached snapshots (or immutable equivalents) so callers cannot mutate registry state without going through a versioned write operation.
InMemoryRegistry¶
schemarouter.InMemoryRegistry ¶
Versioned, collision-safe in-memory tool catalog with snapshot reads.
replace_if_fingerprint ¶
Atomically replace one tool only if the caller still owns its snapshot.
SQLiteRegistry¶
schemarouter.SQLiteRegistry ¶
SQLiteRegistry(path: str | Path, *, timeout: float = 5.0, document_limits: PersistedDocumentLimits | None = None)
Persistent versioned tool catalog backed by SQLite.
Tool specifications are stored as Pydantic JSON rather than pickle so reopening a registry never imports or executes arbitrary Python objects. Writes use BEGIN IMMEDIATE transactions and bump the registry version exactly once per successful logical mutation.
replace_if_fingerprint ¶
Atomically replace one persisted tool if its fingerprint and version match.
SchemaPlanner¶
schemarouter.SchemaPlanner ¶
SchemaPlanner(registry: ToolRegistry, analyzer: QueryAnalyzer | None = None, *, decision_backend: DecisionBackend | None = None, decision_policy: DecisionPolicy | None = None, candidate_recall_backend: DecisionBackend | None = None, candidate_recall_limit: int = 4, candidate_fit_backend: DecisionBackend | None = None, operation_fit_backend: DecisionBackend | None = None, endpoint_disambiguation_backend: DecisionBackend | None = None, candidate_index: bool = True, structural_retrieval: bool = False, availability_predicate: Callable[[ToolSpec, EndpointSpec], bool] | None = None)
Schema-aware planner with sync and async query-analysis paths.
retrieve_routes ¶
Return lightweight Top-K route references without materializing schemas.
aretrieve_routes
async
¶
Async counterpart to :meth:retrieve_routes.
retrieve ¶
Return Top-K registered capabilities without planning or execution.
aretrieve
async
¶
Async counterpart to :meth:retrieve.
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, additional_availability_predicate: Callable[[ToolSpec, EndpointSpec], bool] | None = None) -> StateConditionedCapabilityRetrieval
Return the best K state-eligible capabilities from the visible ranked surface.
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, additional_availability_predicate: Callable[[ToolSpec, EndpointSpec], bool] | 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, additional_availability_predicate: Callable[[ToolSpec, EndpointSpec], bool] | None = None) -> StateAwareCapabilityRetrieval
Return Top-K capabilities filtered by explicit observable typed state.
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, additional_availability_predicate: Callable[[ToolSpec, EndpointSpec], bool] | None = None) -> StateAwareCapabilityRetrieval
Async counterpart to :meth:retrieve_state_aware.
retrieve_routes_with_additional_availability ¶
retrieve_routes_with_additional_availability(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool], *, k: int = 5) -> CapabilityRouteRetrieval
Retrieve Top-K route references under one extra local visibility rule.
aretrieve_routes_with_additional_availability
async
¶
aretrieve_routes_with_additional_availability(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool], *, k: int = 5) -> CapabilityRouteRetrieval
Async counterpart to :meth:retrieve_routes_with_additional_availability.
retrieve_with_additional_availability ¶
retrieve_with_additional_availability(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool], *, k: int = 5, executable_only: bool = False) -> CapabilityRetrieval
Retrieve Top-K capabilities under one additional local availability rule.
aretrieve_with_additional_availability
async
¶
aretrieve_with_additional_availability(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool], *, k: int = 5, executable_only: bool = False) -> CapabilityRetrieval
Async counterpart to :meth:retrieve_with_additional_availability.
retrieve_with_scoped_schema ¶
retrieve_with_scoped_schema(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool], endpoint_transform: Callable[[ToolSpec, EndpointSpec], EndpointSpec | None], *, k: int = 5, executable_only: bool = False, analysis_registry: ToolRegistry | None = None) -> CapabilityRetrieval
Retrieve under local availability and a non-authoritative visible schema view.
aretrieve_with_scoped_schema
async
¶
aretrieve_with_scoped_schema(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool], endpoint_transform: Callable[[ToolSpec, EndpointSpec], EndpointSpec | None], *, k: int = 5, executable_only: bool = False, analysis_registry: ToolRegistry | None = None) -> CapabilityRetrieval
Async counterpart to :meth:retrieve_with_scoped_schema.
plan_with_scoped_schema ¶
plan_with_scoped_schema(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool], endpoint_transform: Callable[[ToolSpec, EndpointSpec], EndpointSpec | None], *, analysis_registry: ToolRegistry | None = None) -> ExecutionPlan
Plan using a bounded visible schema while preserving authoritative identities.
aplan_with_scoped_schema
async
¶
aplan_with_scoped_schema(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool], endpoint_transform: Callable[[ToolSpec, EndpointSpec], EndpointSpec | None], *, analysis_registry: ToolRegistry | None = None) -> ExecutionPlan
Async counterpart to :meth:plan_with_scoped_schema.
plan_with_additional_availability ¶
plan_with_additional_availability(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool]) -> ExecutionPlan
Plan with one extra local availability predicate.
aplan_with_additional_availability
async
¶
aplan_with_additional_availability(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool]) -> ExecutionPlan
Async counterpart to :meth:plan_with_additional_availability.
ExecutionPlan¶
schemarouter.ExecutionPlan ¶
Bases: StrictModel
PlanCoverage¶
schemarouter.PlanCoverage ¶
Bases: StrictModel
Structured semantic-field coverage for one execution plan.
SemanticFieldRequirement¶
schemarouter.SemanticFieldRequirement ¶
Bases: StrictModel
One query-matched semantic field requirement used for plan coverage.
QueryAnalyzer¶
schemarouter.QueryAnalyzer ¶
Bases: Protocol
KeywordAnalyzer¶
schemarouter.KeywordAnalyzer ¶
Offline default analyzer. It never invents values or tool names.
ModelQueryAnalyzer¶
schemarouter.ModelQueryAnalyzer ¶
ModelQueryAnalyzer(model: ModelCallable, *, max_catalog_endpoints: int = 128, max_registry_retries: int = 2)
Provider-neutral model-assisted analyzer.
The supplied model callable receives only structured data. Its output is treated as untrusted and projected onto the exact detached registry snapshot shown to the model.
If the registry changes while a model call is in flight, the whole analysis is retried against a fresh snapshot up to max_registry_retries times. Persistent churn fails closed instead of rebinding model intent to a replacement schema.
SchemaDiffReport¶
schemarouter.SchemaDiffReport ¶
Bases: StrictModel
Machine-readable explanation for a schema fingerprint change.
Compatibility is intentionally conservative. A report may explain why two fingerprints differ, but it never authorizes an old plan or binding to execute against a new schema.
SchemaChange¶
schemarouter.SchemaChange ¶
Bases: StrictModel
One semantic difference between two trusted schema snapshots.
compare_endpoint_specs¶
schemarouter.compare_endpoint_specs ¶
Explain semantic differences between endpoint snapshots.
This function is diagnostic only. The executor still requires an exact current fingerprint.
compare_tool_specs¶
schemarouter.compare_tool_specs ¶
Explain why two tool fingerprints differ without weakening drift checks.
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 ¶
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.
PolicyRule¶
schemarouter.PolicyRule
dataclass
¶
PolicyRule(effect: PolicyEffect, operation: str = '*', name: str | None = None, remote: bool | None = None, read_only: bool | None = None, destructive: bool | None = None, unclassified: bool | None = None)
Trusted local operation rule.
The operation pattern uses shell-style wildcard matching against tool.endpoint. Rules are evaluated in declaration order and the first matching rule wins. Optional side-effect predicates constrain a pattern without exposing credentials or model-visible policy state.
PolicyDecision¶
schemarouter.PolicyDecision
dataclass
¶
PolicyDecision(effect: PolicyEffect, source: Literal['rule', 'default'], operation: str, rule_name: str | None = None, reason: str = '')
Resolved local authority for one concrete tool call.
CapabilityContract¶
schemarouter.CapabilityContract ¶
Bases: StrictModel
CapabilityFieldContract¶
schemarouter.CapabilityFieldContract ¶
Bases: StrictModel
Provider-neutral field requirement/production contract.
CapabilityDependencyGraph¶
schemarouter.CapabilityDependencyGraph ¶
Bases: StrictModel
build_capability_dependency_graph¶
schemarouter.build_capability_dependency_graph ¶
build_capability_dependency_graph(capabilities: list[CapabilityContract], *, context: CompatibilityContext | None = None) -> CapabilityDependencyGraph
Build contract-compatible edges using semantic indexes.
The index is only a conservative prefilter. Every emitted edge is still decided by
:func:compare_capability_composition, preserving type, unit, qualifier, and
explicit semantic-equivalence semantics.
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.
StateAwareCapabilityRetrieval¶
schemarouter.StateAwareCapabilityRetrieval ¶
Bases: StrictModel
StateConditionedCapabilityRetrieval¶
schemarouter.StateConditionedCapabilityRetrieval ¶
Bases: StrictModel
Eligible Top-K plus explicit state rejections from the ranked candidate surface.