Planning and registry reference¶
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.
SQLiteRegistry¶
schemarouter.SQLiteRegistry ¶
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.
SchemaPlanner¶
schemarouter.SchemaPlanner ¶
SchemaPlanner(registry: ToolRegistry, analyzer: QueryAnalyzer | None = None, *, decision_backend: DecisionBackend | None = None, decision_policy: DecisionPolicy | None = None, candidate_index: bool = True, availability_predicate: Callable[[ToolSpec, EndpointSpec], bool] | None = None)
Schema-aware planner with sync and async query-analysis paths.
plan_with_additional_availability ¶
plan_with_additional_availability(request: PlanRequest | str, predicate: Callable[[ToolSpec, EndpointSpec], bool]) -> ExecutionPlan
Plan with one extra local availability predicate.
The configured planner availability predicate still applies. This is used by execution-facing runtimes to add local readiness constraints (for example, current invoker binding state) without changing schema-only planning semantics.
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 ¶
Provider-neutral model-assisted analyzer.
The supplied model callable receives only structured data. Its output is treated as untrusted and projected onto the current registry before it reaches the planner.
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 and are evaluated before the legacy category switches. Existing allow_* flags remain the default behavior when no rule matches.
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.