Skip to content

SchemaRouter 0.10.0

SchemaRouter 0.10.0 is a consolidation release.

It does not claim that the open-set routing research is finished. The purpose of this release is to make the product boundary, the stable implementation, the scientific data contracts and the current benchmark evidence line up clearly after several research cycles.

Product model

The release defines SchemaRouter as a typed capability retrieval and execution layer that sits between an agent/RAG application and registered APIs or tools.

RAG means Retrieval-Augmented Generation: a generator is augmented with information retrieved from external sources. SchemaRouter is not that complete generation architecture. It can provide a structured retrieval/execution boundary for RAG or agent systems when the external source is an API or tool.

RAG / Agent
    -> declare external data need
SchemaRouter
    -> retrieve registered capability
    -> select endpoint + fields
    -> validate and execute
    -> return typed external data
RAG / Agent
    -> generate or reason with that data

LangChain, LangGraph, LlamaIndex or an application sit above SchemaRouter. OpenAPI, MCP, OPTIMADE, Python tools and approved plugins sit below it. SchemaRouter does not become an autonomous agent loop.

Stable architecture in this release

The default product path remains the evidence-backed, fail-closed architecture:

request
  -> semantic field need
  -> registered candidate recall
  -> bounded route selection
  -> policy / health / evidence checks
  -> parameter + field plan
  -> raw schema validation
  -> optional declared unit normalization
  -> local field projection
  -> typed ToolResult

Optional decision backends may assist bounded selection over already registered candidates. They do not receive execution authority and are not promoted as unconditional defaults merely because a development benchmark improves.

Typed data contracts

0.10.0 documents the data contract as a first-class part of the capability catalog.

Registered fields may carry:

  • JSON datatype/shape;
  • semantic IDs and trusted aliases;
  • source units;
  • explicit UnitNormalizationSpec dimension, canonical unit, scale and offset;
  • exact qualifiers such as temperature, pressure, phase, orientation or measurement method;
  • provenance/license/source-type evidence where declared.

Units are optional. Text, identifiers, booleans, structured metadata and dimensionless numbers can be unitless.

Cross-provider fallback is conservative. SchemaRouter does not infer scientific equivalence or unit conversions that were not declared by trusted code.

Generic capability registration

The intended user experience is generic registration rather than benchmark-specific route configuration. Native ToolSpec, OpenAPI, MCP, OPTIMADE and Python capabilities are normalized into the same typed registry model.

A first registry-compiled capability-verifier prototype was also evaluated against both canonical DEV and a separate previously unseen native/OpenAPI/MCP registration holdout. The provider-neutral typed compiler worked, but the synthetic learned veto over-rejected supported requests: exact routing fell to 5.03% on canonical DEV and 2.08% on the registration holdout while false-route stayed at 0%. That candidate is terminally rejected and is not included as a 0.10.0 default.

Routing benchmark: current evidence

The 0.11 architecture-search cycle closed without a promoted production-target candidate.

The standing target is supported exact >=85%, near-domain unsupported rejection >=97%, OOD rejection 100%, false-route <=1%, zero authority/execution errors and executable p95 <=250 ms.

The strongest executable DEV candidate reached 85.07 / 99.31 / 100 / 0.62 with 176.94 ms p95. The unchanged zero-overlap fresh confirmation then reached 84.81 / 90.45 / 100 / 8.49 with 278.37 ms p95. The fresh result failed promotion, so calibration/blind-final were not consumed.

The conservative #259 profile remains a useful reference at 83.77% supported exact, 98.96% near-domain rejection, 0.93% false-route and approximately 134.95 ms p95, but it is not relabelled as a target pass.

See Routing research status for the current interpretation and the full terminal report for provenance.

Bounded decision ecosystem

0.10.0 also consolidates the replaceable decision-provider surface:

  • explicit third-party schemarouter.decision_backends entry points;
  • provider-neutral CallableDecisionBackend;
  • System-One/Jev-compatible provider configuration without planner-specific model classes;
  • benchmark/report metadata that records provider/model configuration without exposing secrets;
  • runtime-parity and freeze-manifest infrastructure for evidence-preserving optimization.

Provider compatibility is not treated as evidence that a model is safe or accurate enough to become a default.

Compatibility

SchemaRouter remains pre-1.0. This release does not move orchestration, memory, conversation state or autonomous tool loops into the package.

Existing applications using deterministic routing or optional bounded decision backends do not need to adopt any experimental capability-verifier path.

Release validation

The normal protected release pipeline covers Python 3.10-3.14, Windows smoke, minimum dependencies, Pyright, branch coverage, package wheel/sdist checks, optional integrations, documentation, security analysis, SBOM/provenance generation and exact post-publish PyPI artifact verification.