Skip to content

SchemaRouter 0.11.0

SchemaRouter 0.11.0 is the product-first typed capability retrieval release.

The package is usable independently of the ongoing routing research: an application can register OpenAPI, MCP, OPTIMADE, Python, or plugin-defined capabilities, retrieve a compact typed candidate set for an external agent, and keep validation/policy/execution authority inside SchemaRouter.

First-class Top-K capability retrieval

The primary addition is a public retrieval surface that does not execute tools:

candidates = router.retrieve(
    "current Young's modulus for MAT-7",
    k=5,
)

for candidate in candidates.candidates:
    print(candidate.route_id)
    print(candidate.parameters)
    print(candidate.output_fields)

Async callers use aretrieve.

When an application also needs current local execution binding readiness, use:

candidates = router.retrieve_executable(query, k=5)

or aretrieve_executable.

What a candidate contains

A CapabilityCandidate is tied to one registered endpoint and can carry:

  • route/tool/endpoint identity;
  • typed parameter contracts and the full effective input JSON Schema;
  • output fields plus the full effective output JSON Schema and datatype/shape;
  • semantic IDs;
  • optional source units, canonical normalization metadata and qualifiers;
  • provider/access/source/license metadata;
  • read-only/destructive classification;
  • tool and endpoint fingerprints;
  • deterministic ranking evidence.

The result is a detached snapshot. Mutating a returned candidate does not mutate the registry.

Retrieval is not execution authority

retrieve() is intentionally side-effect free.

query
  -> SchemaRouter Top-K registered capabilities
  -> downstream LLM/agent selects among them
  -> SchemaRouter validation + policy
  -> trusted execution
  -> typed result

SchemaRouter does not expose a hidden pseudo-tool, invent a route, or allow retrieval confidence to bypass local execution policy.

Plain retrieve() means the capability contract is registered. It does not imply a local invoker is currently bound. retrieve_executable() adds that readiness requirement.

Stable product boundary

0.11.0 keeps the existing product capabilities from 0.10.0:

  • typed Tool / Endpoint / Parameter / Field registry;
  • OpenAPI, MCP, OPTIMADE and Python ingestion;
  • field-first planning and multi-provider field coverage;
  • input/raw-output JSON Schema validation;
  • binding/schema drift protection;
  • read/write/destructive policy and approval gates;
  • bounded retry, health and fallback;
  • explicit field projection and trusted unit normalization;
  • sync/async, batch, streaming, typed events and traces;
  • SQLite persistence/inspection surfaces;
  • optional LangChain, LangGraph, LlamaIndex, System One/Jev, Laya, Ollama and OpenTelemetry integration surfaces.

Research is now downstream of the stable library

The active 0.14 research asks whether compact typed retrieval preserves or improves downstream agent utility relative to exposing the full tool catalog.

That research remains important, but it is no longer a prerequisite for publishing the usable library. B1/B2 replication, answer-quality, adaptive shortlist depth, state-aware corrective re-retrieval, larger held-out generalization and typed-representation ablations continue as separate evidence tracks.

A research result blocks a stable package only when it exposes a reproducible product correctness, security, policy, execution-authority, API-integrity, or packaging defect.

Compatibility

The new retrieval APIs are additive. Existing planning and execution APIs are not intentionally changed by this release.

SchemaRouter is Beta / pre-1.0. A later 1.0 should represent an explicit long-term public API compatibility commitment, not merely the completion of one research cycle.

Release validation

The protected release pipeline validates Python 3.10–3.14, Windows, minimum dependencies, type checking, branch coverage, wheel/sdist installation, optional integrations, docs, CodeQL/security, SBOM/provenance and exact post-publication PyPI artifact digests.