Skip to content

SchemaRouter 0.4.0

SchemaRouter 0.4.0 extends the first non-prerelease baseline into a more operational runtime while keeping the same narrow responsibility: compile natural-language requests into schema-constrained tool calls and execute them through explicit local trust boundaries.

This release adds durable registry and trace storage, richer bounded decision surfaces, stronger OpenAPI ingestion, native LangGraph integration, and trusted execution hooks. Features that can change persistence, model-assisted selection, network reach, or interception behavior remain explicitly opt-in or locally controlled.

Highlights

  • transactional SQLiteRegistry persistence behind the public ToolRegistry protocol;
  • append-only SQLiteRunTraceStore persistence with validated non-executing replay;
  • exact-recall candidate indexing cached by registry version;
  • bounded output-field selection with identifier preservation and deterministic fallback;
  • explicit nested-object projection through FieldSpec.path;
  • conservative evidence-sufficiency decisions with local metadata prechecks and provider veto-only semantics;
  • provider-neutral EmbeddingDecisionBackend for application-owned embedding callables;
  • local OllamaDecisionBackend using structured finite-choice output with local revalidation;
  • native LangGraph StateGraph integration through schemarouter[langgraph];
  • opt-in bounded same-origin OpenAPI cross-document $ref resolution;
  • improved OpenAPI handling for chained local references, Path Item references, and object composition through allOf;
  • trusted ordered sync/async before/after execution hooks with detached snapshots and fail-closed error semantics.

Installation

Core package:

pip install schemarouter

Optional integrations:

pip install "schemarouter[mcp]"
pip install "schemarouter[langchain]"
pip install "schemarouter[langgraph]"
pip install "schemarouter[llamaindex]"
pip install "schemarouter[jev]"
pip install "schemarouter[otel]"

Ollama support does not require an additional Python SDK. Applications opt into a locally installed model by constructing OllamaDecisionBackend explicitly.

Persistence and replay

SQLiteRegistry persists catalog metadata transactionally without serializing trusted invokers or credentials. Reopened registries preserve deterministic ordering and monotonic registry versions.

SQLiteRunTraceStore persists validated runtime event streams and can replay them without re-running planners, network calls, or tools. Payload redaction behavior remains governed by the runtime event contract.

Bounded decisions

The optional decision layer now covers three independently controlled surfaces:

  • candidate / endpoint selection;
  • output-field selection;
  • conservative evidence sufficiency.

Embedding, Jev, Ollama, and provider-neutral callable backends may only choose from locally authorized finite options. Unknown IDs fail closed, abstention/error handling follows the configured fallback policy, and model output cannot create schema members or grant execution authority.

OpenAPI

Cross-document OpenAPI references can now be enabled explicitly for trusted sources. Resolution is restricted to the entry document's origin and bounded by redirect, depth, document-count, and aggregate-byte limits. The default remains off.

The planner also handles more same-document reference and allOf object-composition cases while retaining full runtime JSON Schema validation and machine-readable compatibility reporting.

Execution hooks

Trusted before/after hooks can observe detached schema, call, and result snapshots. Hooks cannot transform calls or results: returning a value is invalid, failures are non-retryable, and schema / binding state is refreshed around awaited hook execution.

Compatibility and validation

0.4.0 introduces no intentional public API removals relative to 0.3.0. The project remains pre-1.0, so later 0.x minor releases may still contain deliberate documented compatibility changes.

The required release gate covers:

  • Python 3.10 through 3.14 core tests;
  • Windows + Python 3.14 smoke execution;
  • Pyright static typing;
  • branch coverage with an 82% blocking floor;
  • declared minimum runtime dependency versions;
  • wheel and sdist build plus clean-install smoke tests;
  • strict MkDocs build;
  • LangChain, LangGraph, LlamaIndex, Jev, MCP, and OpenTelemetry integration suites.

Python 3.15 remains a separate non-blocking forward-compatibility preview. Live public-service and provider benchmarks remain external evidence rather than deterministic merge blockers.

Security posture

0.4.0 preserves the fail-closed trust model:

  • remote schemas and model output do not become execution authority;
  • persistent registries do not serialize trusted invokers or credentials;
  • external OpenAPI references remain explicit, same-origin, and bounded;
  • bounded-decision providers cannot invent options or upgrade missing evidence;
  • execution hooks cannot mutate the call/result contract;
  • runtime payload tracing remains redacted by default;
  • stale schema fingerprints and stale invoker bindings remain rejected;
  • retries remain read-only by default unless trusted local code opts otherwise.

See CHANGELOG.md, SECURITY.md, docs/versioning.md, and docs/framework-maturity.md for the detailed contracts and follow-up roadmap.