SchemaRouter 0.17.0

SchemaRouter 0.17.0

SchemaRouter 0.17.0 is a hardening and architecture release focused on correctness under
concurrency, explicit security boundaries, failure-atomic runtime behavior, and maintainability of
the provider/runtime/planner core.

The public SchemaRouter facade remains intact. The largest changes are internal decompositions and
fail-closed correctness fixes rather than a new orchestration layer.

Runtime architecture

The runtime facade has been split into focused internal components for:

• provider registration and multi-method onboarding;
• trusted rebinding;
• native backend registration;
• native schema-refresh/watch lifecycle;
• shared runtime defaults and compatibility dispatch.

Native vector, graph and record-store providers now register through dedicated registries instead of
hard-coded central runtime dispatch. Existing convenience APIs remain compatibility delegates.

Planner architecture

Planning now uses explicit typed stages around an immutable planning context:

• candidate retrieval/ranking;
• primary executable-call selection;
• fallback selection;
• final plan assembly.

Analysis and planning share one registry snapshot end-to-end, reducing hidden live-registry reads and
making routing policy easier to test in isolation without changing the documented planner facade.

Failure atomicity and concurrency

0.17.0 hardens several boundaries that can otherwise produce partially published or ambiguous state:

• multi-capability/provider registration can be failure-atomic;
• registry and trusted-binding publication preserve predecessor state on failure;
• shared execution-budget reservation is atomic;
• schema-refresh health transitions are coordinated atomically;
• repeated concurrent tool spans remain distinguishable;
• capability publication and trace replay use explicit ordering/concurrency invariants.

Synchronous remote I/O, trace persistence and health probes are kept off the async event loop where
needed, and sync wrappers no longer depend on unsafe event-loop affinity.

Authorization and security

Principal-aware execution is preserved through native, LangChain and LlamaIndex exports and through
parallel preflight paths.

Security hardening includes:

• authorization revalidation at retry and final approval boundaries;
• additive approval requirements for side-effect authority;
• fail-closed handling when trusted vector/graph/data-scope filters cannot be enforced;
• centralized trusted HTTP-header validation;
• host-controlled network egress policy;
• sensitive trace-payload redaction before sinks;
• bounded schema structural complexity and JSON-Schema evaluation work;
• bounded persisted/adaptive checkpoint and administrative-document parsing;
• atomic SQLite backup-destination reservation.

These changes can reject malformed, ambiguous or unenforceable states earlier than 0.16.0. That is a
deliberate correctness/security tightening rather than a new execution capability.

Lifecycle and observability

Router-owned native schema watchers now have explicit lifecycle ownership and are stopped during
router shutdown. Direct replacement/unregister paths invalidate refresh state consistently.

SQLite run traces can use bounded retention/pruning, and trace persistence or post-invocation hook
failures are classified without silently converting an uncertain operation into a successful one.

CI and release qualification

The qualification pipeline was reworked to reduce queue pressure without weakening release gates:

• package fan-out is based on one immutable artifact;
• deterministic compatibility regressions are blocking;
• native adapter coverage has per-family ratchets;
• protected-main commits have exact post-merge qualification evidence;
• documented public API contracts are checked against the installed package;
• Python dependency downloads are cached across qualification jobs.

External validation infrastructure

The repository now contains frozen/shared external-validation contracts and development harnesses for
cross-project router evaluation, including a pinned SmartMCP semantic-discovery smoke.

These development/external-validation assets are evidence infrastructure only. They do not turn
ongoing Research 0.14 results into 0.17.0 product claims.

Compatibility

No intentional breaking change is introduced to the documented retrieval/planning/execution facade.
Internal services, stage components and lazy exports remain behind compatibility boundaries.

SchemaRouter remains Beta / pre-1.0. Research 0.14 uses separately frozen scientific sources and
continues independently from this product release.

Release integrity

Publication requires the exact 0.17.0 release commit to pass protected CI, compatibility/security
checks, package build and clean-install acceptance. The release workflow then creates v0.17.0,
publishes GitHub/PyPI artifacts through the existing trusted pipeline, emits provenance/SBOM/digest
metadata, and verifies the published artifacts.

SchemaRouter 0.16.0

SchemaRouter 0.16.0

SchemaRouter 0.16.0 is an enterprise data onboarding and authorization release built on the
typed capability and execution boundary established in earlier releases.

The release expands the kinds of caller-owned data systems that can be registered safely without
turning SchemaRouter into an IAM server, database proxy, or autonomous orchestrator.

Identity-aware authorization

Applications can pass a verified PrincipalContext and enforce deny-by-default RBAC/ABAC across
roles, departments, teams, and trusted attributes.

Authorization is applied before model-visible retrieval and revalidated at execution. Data-scope
rules can additionally narrow visible fields, trusted row/tenant filters, graph relationship sets,
and traversal depth.

Authentication, SSO/token verification, identity directories, and database-native roles remain
host-owned.

Relational database onboarding

SchemaRouter can introspect local SQLite connections and caller-owned SQLAlchemy Engines into typed
read-only capabilities.

The model does not receive arbitrary SQL authority. The generated surface uses introspected schema,
bounded projection, exact-match parameters where supported, and parameterized execution.

The SQLAlchemy path is designed to work with dialect-supported relational/warehouse systems while
keeping credentials, pools, and live connections outside model-visible contracts.

Vector databases

The provider-neutral vector contract is complemented by native caller-owned adapters for:

• Qdrant;
• Milvus;
• Pinecone;
• Weaviate;
• Chroma;
• PostgreSQL/pgvector.

Adapters discover or require explicit collection/index schema information, validate vector
dimensions, keep embedding/vector creation inside trusted host code, and apply principal-derived
metadata filters through vendor-safe query structures.

Graph and RDF data

The graph contract now includes native caller-owned adapters for:

• Neo4j;
• Amazon Neptune Database / Neptune Analytics;
• ArangoDB;
• FalkorDB;
• SPARQL 1.1 endpoints.

FalkorDB support includes graph, label, relationship and property discovery plus bounded read-only
traversal through ro_query(). Release-gated compatibility starts a real FalkorDB container and
executes discovery and traversal with the official Python client.

Raw Cypher, AQL, Gremlin, or SPARQL does not become model-visible execution authority.

Document, search, key-value and time-series data

The bounded record-store contract adds native caller-owned adapters for:

• MongoDB;
• Elasticsearch / OpenSearch;
• Amazon DynamoDB;
• Azure Cosmos DB for NoSQL;
• Couchbase;
• ClickHouse;
• InfluxDB 2.x / Flux.

Vendor query languages remain inside trusted adapter code rather than model output.

Redis boundary

Generic Redis record/vector/search support is intentionally not part of the first-class core
database surface in 0.16. FalkorDB is supported specifically as a graph database through the graph
contract.

This keeps the core focused on data models with clear schema discovery and bounded execution
semantics. Redis-specific use cases can still be implemented through plugins or adopter-owned
adapters when needed.

Provider discovery boundary

Unknown-provider discovery remains proposal-first: discovery may produce inspectable candidates,
but registration requires explicit approval and never grants execution authority by itself.

Existing provider-first onboarding for known services remains available.

Compatibility

The stable retrieval and execution facade remains intact. The 0.16 additions are new onboarding,
authorization, and adapter surfaces around the same capability contracts.

SchemaRouter remains Beta / pre-1.0. Database/vendor support means the bounded adapter and
contract exist in core; it does not imply every hosted account, vendor version, or deployment
topology has completed live external acceptance.

Documentation

0.16 reorganizes the repository landing pages so README stays focused on product identity,
quickstart, architecture, supported source families, authorization boundaries, and links to the
full documentation.

Detailed database behavior now lives under:

• Enterprise data onboarding
• Relational database onboarding
• Vector store onboarding
• Graph and RDF onboarding
• NoSQL record-store onboarding
• Principal-aware authorization

Release integrity

Publication requires the exact 0.16.0 release commit to pass the protected CI/security matrix,
package checks, compatibility smoke suite, Python preview, and live FalkorDB acceptance. The normal
release workflow then creates v0.16.0, builds and clean-installs wheel/sdist artifacts, emits
SBOM/provenance metadata, publishes through PyPI Trusted Publishing, and verifies the published
artifacts.

SchemaRouter 0.15.0

SchemaRouter 0.15.0

SchemaRouter 0.15.0 is a provider-first onboarding and capability-runtime release built on the stable execution boundary established in 0.12 and the operability work shipped in 0.14.

The release keeps SchemaRouter focused on typed capability retrieval and schema-aware execution. It does not add autonomous orchestration, and it does not promote incomplete research experiments into stable product claims.

Provider-first onboarding

Users can now start from a provider identity instead of having to know every protocol or SDK that provider exposes.

from schemarouter import SchemaRouter

router = SchemaRouter()
resolution = router.resolve_provider("materials-project")
registration = await router.add_provider("materials-project")

Built-in acceptance profiles cover Materials Project, Crossref, Tavily, APIs.guru, and the OData.org V4 reference service. Provider profiles remain a thin onboarding layer over the existing adapters.

URL-backed methods flow into the normal OpenAPI, OPTIMADE, GraphQL, OData, OpenRPC, or MCP ingestion paths. Declarative HTTP/JSON tools use an explicitly trusted ToolSpec. Python SDKs and caller-owned transports still require an explicit trusted binding; package presence alone never grants execution authority.

Release-gated compatibility evidence also exercises provider-profile-routed local GraphQL, OpenRPC, and MCP reference implementations. Public-provider checks remain point-in-time compatibility evidence rather than uptime guarantees.

State-aware corrective retrieval

0.15.0 adds explicit state-conditioned corrective retrieval through reretrieve_state_aware() and areretrieve_state_aware().

These APIs can remove ineligible candidates and backfill from the remaining eligible capability surface without changing the stable retrieve(..., k=5) / aretrieve(..., k=5) facade. The behavior is additive and opt-in.

Capability dependency graph and drift handling

Capability graph construction is now indexed and incrementally maintainable. The runtime adds indexed dependency construction, deterministic SCC analysis and bounded cycle witnesses, incremental rebuild, atomic compare-and-swap snapshot publication, validated full-rebuild fallback, and source/predecessor preservation on publication failure.

Sparse graph benchmarks cover 1k, 10k, and 50k capability scales.

Portable artifacts, snapshots, and decision traces

Capability graph artifacts and snapshots now have explicit format versions and deterministic migration behavior. Legacy 1.0 graph artifacts migrate to 1.1 while preserving legacy edges as external evidence. Raw pre-envelope snapshots remain readable after validation and can be migrated into the versioned envelope.

The release also adds privacy-safe capability decision traces with compact/detailed rendering, router.inspect(...), CLI inspection, and HTML dashboard integration.

Compatibility fix found through live acceptance

The expanded Materials Project provider-first smoke exposed an OPTIMADE streamed compressed-response reconstruction defect. 0.15.0 fixes that path and adds regression coverage.

Compatibility and stable-core boundary

There is no intentional breaking change to the stable retrieval/execution facade. retrieve(request, *, k=5) and aretrieve(request, *, k=5) keep their existing signatures; state-aware re-retrieval is additive; provider-first registration reuses existing adapter/execution contracts; and credentials, live clients, SDK objects, and transport handles remain outside persisted/model-visible schemas.

SchemaRouter remains Beta / pre-1.0.

Research boundary

The active routing research program continues independently from this package release. The large held-out semantic benchmark, final-answer quality evaluation, and remaining projection/decision-backend confirmation are not required for 0.15.0 publication unless they reveal a product correctness, security, packaging, or API defect.

Partial research rows are therefore not presented as product guarantees in this release.

Release integrity

Publication requires the exact 0.15.0 release commit to pass the protected CI/security matrix and release-gated pinned protocol compatibility references. The automated workflow then creates v0.15.0, builds and clean-installs wheel/sdist, emits an SPDX SBOM and provenance attestations, creates SHA256SUMS.txt and release-manifest.json, publishes through PyPI Trusted Publishing, verifies public artifact digests, and re-installs the published artifacts and integration extras outside the checkout.

SchemaRouter 0.14.0

SchemaRouter 0.14.0

SchemaRouter 0.14.0 is an operability and ecosystem-validation release built on the stable-core
retrieval/execution boundary established in 0.12.0.

The release does not turn SchemaRouter into an autonomous agent framework and does not promote an
unfinished research result into a product guarantee. Its focus is practical operation: inspecting
sources before registration, preserving execution authority across restarts and schema changes,
making registered capabilities easier to inspect, and validating composition with surrounding agent
ecosystems.

Safer source inspection and authentication

Structured-source discovery is now easier to diagnose without granting execution authority.

• probe_url(...) can inspect a source without registering or executing it.
• Ordinary HTML and unsupported URLs fail with explicit diagnostics instead of silently producing an
  empty tool surface.
• Automatic URL discovery is passive by default.
• OpenAPI authentication requirements are part of the canonical endpoint/tool contract, while
  credential values remain in trusted runtime configuration.
• Schema watches and HTTP validators stay pinned to the exact accepted source/contract identity.

The result is a clearer separation between recognizing a capability source and authorizing a
runtime binding.

Runtime lifecycle and persisted state

0.14.0 fills operational gaps that matter once a registry survives beyond one process.

• persisted registries can restore trusted process-local bindings through explicit startup
  rebinding;
• SQLite registry/trace formats are versioned and support validated migration from the legacy
  unversioned format;
• breaking or security-relevant schema drift has explicit accept/reject handling;
• capability removal is available through one high-level lifecycle operation;
• health probes remain coherent across accepted contract transitions;
• runtime shutdown closes watchers, monitors, bindings, and owned resources through one public
  lifecycle;
• adapter plugins can participate in the same conservative schema-refresh boundary.

Persisted schema data still does not contain credentials, live clients, sockets, subprocess handles,
or other execution authority.

Capability Explorer and first-use path

The documentation and inspection surface now matches the product model more closely.

The protocol-neutral Capability Explorer provides a Swagger-style, read-only view of registered
tools, endpoints, parameters, output fields, units/qualifiers, fingerprints, binding state,
authentication requirements, health state, and schema-watch status. It does not expose execution
buttons or credentials.

The public quickstart now uses a real, no-auth OpenAPI provider while mandatory CI keeps a
deterministic offline equivalent. Runnable examples cover local callables, SDK bindings, multiple
providers, schema drift, MCP stdio, framework integrations, context reduction, and inspection.

Adapter and agent-ecosystem composition

The installed package is exercised against external-style integration boundaries rather than only
repository-local fixtures.

0.14.0 includes runnable adapter and decision-backend plugin examples and built-wheel validation for:

• PydanticAI ToolSearch composition;
• OpenAI Agents SDK dynamic MCP filtering;
• mcp-agent large-tool catalogs;
• downstream SourceAdapter entry-point plugins.

These checks establish compatibility evidence for the tested pinned surfaces. They are not claims
that SchemaRouter replaces those frameworks or that every version of a third-party project is
supported.

English and Korean documentation

The GitHub Pages site now provides English and Korean from one site with an in-header language
selector.

English remains the canonical documentation source. Korean first-class pages cover the main
onboarding, concept, protocol, inspection, and trust surfaces. For pages not yet translated, the
same Korean URL exists and clearly links to the current English original instead of returning a
404. A source-blob manifest makes the documentation build fail when a translated page falls behind
its canonical source.

Release and research records

Mechanical public facts are now derived from canonical repository sources.

• the stable version/date comes from CHANGELOG.md;
• the development/release version comes from pyproject.toml;
• the public experiment count comes from
  benchmarks/research-experiment-ledger.json;
• protected CI rejects stale public fact lines;
• a scheduled workflow can open a reviewable synchronization PR when those facts drift;
• the research evidence exporter also runs on relevant main changes and on a schedule.

The release pipeline additionally emits SHA256SUMS.txt and release-manifest.json with the
exact release source SHA, artifact names, sizes, and SHA-256 digests. These files are attached to the
GitHub Release alongside wheel, sdist, and the SPDX SBOM.

Stable-core and research boundary

The active 0.14 research program continues independently from this package release. Corrective
re-retrieval, runtime qualification, held-out generalization, final-answer quality, and field-level
projection evidence are not treated as product defaults until their preregistered gates and
evidence rules permit that conclusion.

The package release therefore does not claim that those open experiments have completed or that
their partial rows establish production superiority.

Compatibility

There is no intentional breaking public API change relative to 0.13.0.

The stable product boundary remains:

registered typed capabilities
  -> bounded retrieval / planning
  -> local schema + policy + binding validation
  -> trusted execution
  -> validated/projected ToolResult

SchemaRouter remains Beta / pre-1.0.

Release integrity

Publication requires the exact release commit to pass the protected CI/security matrix. The release
workflow then:

1. creates the annotated v0.14.0 tag at that exact green main SHA;
2. builds and clean-installs wheel and sdist;
3. generates an SPDX JSON SBOM;
4. emits GitHub provenance attestations;
5. generates SHA256SUMS.txt and release-manifest.json;
6. publishes to PyPI through Trusted Publishing;
7. downloads the exact public wheel and sdist and verifies their digests against the trusted build;
8. installs the published wheel, sdist, lightweight extras, and combined integration extras outside
   the checkout.

SchemaRouter 0.13.0

SchemaRouter 0.13.0

SchemaRouter 0.13.0 is an operational-completeness release on top of the stable-core boundary
established in 0.12.0.

The architecture is not being reopened. This release closes concrete product gaps that appear when
the same typed capability contract is connected to real protocol, SDK, transport, nested-result and
schema-lifecycle surfaces.

Universal capability ingestion

The first-class ingestion surface now covers:

• direct ToolSpec registration and typed Python callables;
• explicit ToolSpec + trusted arbitrary SDK/client invokers through add_bound_tool();
• OpenAPI/Swagger;
• MCP Streamable HTTP, trusted stdio subprocesses and transport-neutral bound client factories;
• OPTIMADE;
• GraphQL introspection with native selection semantics;
• OData CSDL with $select;
• OpenRPC / JSON-RPC;
• declarative HTTP/JSON capabilities;
• inbound LangChain and LlamaIndex tools;
• explicit SourceAdapter plugins and the existing grounded-document proposal/approval path.

Different access paths for one logical provider remain distinct. The registry records provider and
access identity rather than pretending that a Python SDK, MCP server, OpenAPI endpoint and
OPTIMADE service are the same transport.

Field contracts survive real nested responses

Structured adapters now align around the same field contract model. Nested OpenAPI, MCP and
OPTIMADE responses, Python/plugin schemas, and arrays of records retain their declared hierarchy.

A response such as an array of records is projected record by record. SchemaRouter does not
flatten all matching child values into an unrelated list. Datatype, semantic ID, optional units,
normalization, qualifiers and result paths remain attached to the registered field contract.

Trusted local code can also amend an imported capability when a provider omits a result contract.
That amendment path is intentionally narrow: it may declare or annotate approved data contracts,
but it cannot silently rewrite imported execution identity or grant remote mutation authority.

Schema lifecycle is now operational

Schema drift can be handled without turning remote metadata into authority:

accepted ToolSpec
  -> reinspect provider
  -> exact fingerprint + conservative compatibility report
  -> identical: no write
  -> compatible: optional CAS apply + exact rebind
  -> breaking/security: pending review

The periodic watcher runs the same boundary with bounded concurrency.

Safe single-document HTTP schema surfaces can use ETag / Last-Modified validators as a
network optimization. Correctness still falls back to full inspection and fingerprint comparison
when validators are unavailable or insufficient.

MCP stdio and custom transports are refreshable without inventing an HTTP URL. SchemaRouter reuses
only the current fingerprint-matched process-local trusted factory. Credentials, subprocess
configuration, sockets and live transport state are never serialized into ToolSpec or watcher
snapshots. Missing or stale trusted bindings fail closed.

Stable-core boundary remains intact

0.13.0 does not turn SchemaRouter into an autonomous agent framework and does not give retrieval or
remote schemas execution authority.

The surrounding application/agent still chooses among bounded registered candidates. SchemaRouter
continues to own typed registry identity, argument/output validation, field projection, local
policy, approvals, binding readiness and execution.

The public bounded retrieval facade introduced in 0.11.0 and frozen as stable core in 0.12.0 remains
the product boundary:

• retrieve / aretrieve;
• retrieve_executable / aretrieve_executable;
• validated planning/invocation APIs and their existing policy boundary.

Research remains separate

The 0.14 agent-utility research cycle continues independently. B1/B2 evidence, the negative
structural K3-vs-K5 gate, corrective re-retrieval, large held-out confirmation, final-answer quality
and output-field projection experiments do not control whether this package release is usable.

No frozen 0.14 experimental corpus, ranking condition, promotion gate or evidence interpretation was
changed to prepare 0.13.0.

Compatibility

There is no intentional breaking public API change relative to 0.12.0. New ingestion, bound
transport, field-contract and schema-watch paths are additive.

SchemaRouter remains Beta / pre-1.0. The 0.12 stable-core architecture is preserved, while 0.x
minor releases may still add deliberately documented capabilities around that boundary.

Release integrity

The release commit must pass the protected CI matrix before publication. The automated release
workflow then creates v0.13.0 at that exact green main SHA, builds and clean-installs wheel and
sdist artifacts, emits provenance attestations and an SPDX SBOM, publishes through PyPI Trusted
Publishing, and verifies the exact public artifacts and integration extras after publication.

SchemaRouter 0.12.0

SchemaRouter 0.12.0

SchemaRouter 0.12.0 is the stable-core product closure release for the current pre-1.0 architecture.

Version 0.11.0 established first-class bounded typed capability retrieval. Version 0.12.0 closes
that product cycle by freezing the architecture/API boundary, strengthening installed-package and
adapter policy regression coverage, and making the released artifact itself the canonical stable
baseline while research continues independently.

Stable-core boundary

The product architecture is now explicitly frozen around this contract:

Python / OpenAPI / MCP / OPTIMADE / adapter plugins
                         |
                 typed registry
                         |
          bounded capability retrieval
                         |
            agent / application
                         |
              planning/calls
                         |
       validation + local execution policy
                         |
                bound execution

Research may improve ranking/index implementations, shortlist defaults, adaptive depth and
corrective re-retrieval behind this boundary. A benchmark improvement by itself is not sufficient
reason to redesign the public facade.

Public retrieval facade

The current research cycles are expected to preserve:

• SchemaRouter.retrieve(..., k=5)
• SchemaRouter.aretrieve(..., k=5)
• SchemaRouter.retrieve_executable(..., k=5)
• SchemaRouter.aretrieve_executable(..., k=5)
• the equivalent ConfiguredSchemaRouter surfaces.

CapabilityCandidate continues to preserve the registered executable contract, including full
effective input/output JSON Schema, declared parameters and output fields, semantic IDs, optional
units/dimensions/qualifiers, policy metadata and fingerprints.

Retrieval remains side-effect free and does not grant execution authority.

Stronger closure validation

0.12.0 extends the product validation surface so release artifacts themselves exercise the frozen
contract.

The installed wheel/sdist consumer acceptance now verifies:

• sync and async bounded retrieval;
• executable-ready retrieval;
• retrieval produces no tool side effect;
• full input/output schemas are retained;
• registered tool/endpoint fingerprints are retained;
• actual invocation remains a separate operation.

Framework integration regression tests also verify that LangChain and LlamaIndex wrappers cannot
bypass SchemaRouter's local mutation/execution policy.

Research remains separate

Active research continues after the product closure release:

• stronger-agent B2 replication;
• large independently held-out agent-utility generalization;
• final-answer fact/value/unit/provenance quality;
• adaptive shortlist depth;
• execution-state-aware corrective re-retrieval;
• representation/index studies.

Those results may improve compatible internals and future defaults. They do not reopen the product
architecture unless they identify a reproducible correctness, security, policy, execution-authority,
API-integrity or packaging defect.

Compatibility

0.12.0 intentionally introduces no breaking public API change relative to 0.11.0.

Existing planning, invocation, validation, policy, async, batch, streaming, tracing, persistence,
inspection and optional integration surfaces remain available.

SchemaRouter remains Beta / pre-1.0. The stable-core freeze means the architecture is no longer
an active research variable; it is not yet the long-term semantic-versioning commitment implied by
a future 1.0 release.

Release integrity

The automated release pipeline requires the exact release-prep commit to pass protected CI and then:

• creates an annotated v0.12.0 tag at the exact green main SHA;
• builds wheel and sdist from that resolved release SHA;
• clean-installs and smoke-tests both artifacts;
• generates provenance attestations and an SPDX JSON SBOM;
• publishes to PyPI through OIDC;
• publishes GitHub Release assets;
• downloads the public PyPI wheel and sdist and verifies their digests against the trusted build;
• re-installs the exact public release as wheel, sdist, lightweight extras and combined integration
  extras outside the checkout.

The product track is considered fully closed only after those post-publish checks are green.

SchemaRouter 0.11.0

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 remains 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 explicitly 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 remains 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.

SchemaRouter 0.10.0

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.

A useful analogy is RAG infrastructure:

documents -> parser -> chunks/metadata -> index -> retriever -> RAG
APIs/tools -> adapter -> endpoint/field contracts -> registry/index -> router -> RAG/agent

The retrieved unit is different: SchemaRouter works with executable endpoint/field contracts rather
than text chunks.

LangChain, LangGraph, LlamaIndex or an application remain above SchemaRouter. OpenAPI, MCP,
OPTIMADE, Python tools and approved plugins remain 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 remain optional. Text, identifiers, booleans, structured metadata and dimensionless numbers
can be unitless.

Cross-provider fallback remains 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.

The active research successor explores a registry-compiled capability verifier that can work with
previously unseen registered tools. That verifier remains research-only in this release until it
passes both canonical and arbitrary-registration evaluation followed by a new independent fresh
confirmation.

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 intentionally 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 the successor capability-verifier research 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.

SchemaRouter 0.9.0

SchemaRouter 0.9.0

SchemaRouter 0.9.0 adds a bounded pairwise decision primitive for applications that want
cross-encoder or reranker-style relevance scoring while preserving SchemaRouter's local execution
authority model.

Highlights

Provider-neutral pairwise decisions

PairwiseDecisionBackend accepts an application-owned scorer over already-authorized
(query, option_text) pairs and maps its scores back to the original opaque option IDs locally.

The contract is deliberately narrow:

• scorers cannot invent tools, endpoints, credentials, arguments, or side effects;
• option metadata is not forwarded by the default formatter;
• one score in [0, 1] is required for every authorized option;
• wrong batch lengths, malformed values, NaN/Infinity, and out-of-range scores fail closed;
• score thresholds and selection-boundary margins can abstain conservatively;
• sync and async scorers are supported;
• SchemaRouter core gains no Torch, Transformers, or model-specific dependency.

Applications remain responsible for the scorer implementation and workload-specific calibration.

Pairwise operation-fit research

After the 0.8.0/v10 release, operation-fit optimization continued on development/calibration data
without reusing consumed holdouts.

Threshold-margin variants, two-tier rescue rules, multilingual MPNet, and multilingual E5 did not
improve the pre-registered robustness objective over the existing multilingual MiniLM bi-encoder.
A pairwise experiment with BAAI/bge-reranker-v2-m3 was the first candidate to improve that
development/calibration objective.

The complete candidate configuration was frozen before evaluating the reserved v11 holdout:

• semantic candidate recall: multilingual MiniLM, top-k 2;
• capability fit: multilingual MiniLM, min similarity 0.25;
• operation fit: BGE reranker v2-m3, sigmoid pair score, min score 0.01;
• endpoint disambiguation: multilingual MiniLM, min margin 0.03.

v11 one-shot evidence

The frozen BGE candidate was evaluated exactly once on the fresh 600-case multilingual v11
operation-generalization holdout.

Metric	BGE pairwise v11	MiniLM 0.40 post-consumption diagnostic
Overall accuracy	51.667%	54.833%
Supported-operation routed accuracy	25.781%	40.625%
Near-domain unsupported-operation rejection	97.396%	77.604%
Ordinary OOD rejection	100%	100%
Equal-weight supported/rejection score	61.589%	59.115%
Mean CPU latency	589.627 ms	253.947 ms

The MiniLM comparison was run only after v11 had already been consumed, so it is diagnostic evidence,
not a fresh holdout claim.

The result shows a real trade-off: BGE improved the pre-registered equal-weight rejection/recall
objective by 2.474 percentage points, but reduced supported-route recall by 14.844 points, reduced
overall accuracy by 3.167 points, and more than doubled CPU latency. 0.9.0 therefore exposes pairwise
scoring as an optional backend and does not make BGE the library default.

v11 is consumed and must not be used for later threshold, model, representation, or hybrid-rule
selection.

Reproducibility

Frozen BGE one-shot:

• source revision: 57af2fd18d254fa1a9cd5855a158ae74b94adfc7;
• corpus SHA-256: efa8cd371bc7613895e44a915d78c77f5b88239c64a8de52d9c407839660d816;
• Actions run: 36239340782;
• artifact ID: 10905503165;
• artifact SHA-256: f977511c7d65bc94e2dba9142b6cedf378ceaae1b8418c351e85b550f191dfd1.

Post-consumption MiniLM diagnostic:

• source revision: 099cf009003df35f48571ecdc988fddaa11db904;
• Actions run: 36240431389;
• artifact ID: 10905429518;
• artifact SHA-256: 1048405ab34b41371004247e15934f5086a53977a14d4957bd14c6d69e194dee.

Compatibility

0.9.0 adds a new public backend without removing the existing embedding, deterministic, hosted, or
integration decision paths. Existing applications do not need to opt into pairwise scoring.

The release remains pre-1.0 and follows the compatibility policy in
docs/versioning.md.

Release validation

The protected release surface covers Python 3.10–3.14, Windows smoke, minimum dependencies,
type checking, branch coverage, wheel/sdist consumer acceptance, optional integrations, strict docs,
dependency/security analysis, CodeQL, OpenSSF Scorecard, SBOM/provenance generation, and exact
post-publish PyPI artifact verification.

SchemaRouter 0.8.0

SchemaRouter 0.8.0

SchemaRouter 0.8.0 strengthens bounded semantic routing and multi-provider evidence handling while
keeping the same execution-boundary philosophy: models may assist selection among locally declared
capabilities, but they do not gain authority to invent tools, schemas, credentials, or side effects.

Highlights

Bounded semantic routing pipeline

0.8 separates several decisions that were previously easier to conflate:

• optional multilingual semantic candidate recall with an explicit top-k bound;
• a capability-fit gate that may abstain without choosing an execution route;
• same-tool endpoint disambiguation that can only reorder sibling endpoints;
• an operation-fit gate scoped to the currently leading tool domain;
• trusted EndpointSpec.operation_aliases that are declared locally and fingerprinted.

These stages remain subordinate to registered schemas, policy, fingerprints, and execution
validation. A decision backend can suppress or prioritize an already declared option; it cannot
create execution authority.

Field evidence and coverage

Planning now makes heterogeneous information requirements more explicit:

• PlanRequest.field_evidence can require provenance, license, source type, or unit evidence for
  one semantic field without imposing the same requirement on unrelated fields;
• ToolCall.required_evidence and route-available evidence are revalidated again at execution;
• ExecutionPlan.coverage reports required, covered, and uncovered semantic-field requirements;
• explicit multi-call planning prefers complementary field coverage and can stop before
  max_calls once the matched field set is complete.

Unknown active field-evidence identifiers and forged evidence overclaims fail closed.

Multi-provider corroboration and aggregation

PlanRequest.retrieval_mode="corroborate" can deliberately request independent providers when
the application wants corroborating evidence rather than minimum-call coverage.

Returned provider records can then be normalized with SourceRecord and aggregated through
aggregate_records():

• documents use trusted identifiers such as DOI/PMID/PMCID/arXiv for canonical grouping;
• material and chemical identity requires explicit structural/canonical identifiers rather than
  formula-only or name/title similarity;
• material and chemical fields preserve independent observations, units, qualifiers, provider, and
  provenance by default;
• disagreement is surfaced instead of silently selecting one scientific value as truth.

SchemaRouter intentionally leaves fuzzy entity resolution and domain truth adjudication to the
application layer.

Reproducible multilingual routing evaluation

0.8 adds a larger benchmark/evaluation discipline around the bounded routing stack:

• 1,200-case multilingual/adversarial v2 stress corpus;
• separate capability-fit, endpoint-disambiguation, operation calibration, and post-change holdouts;
• split- and language-level metrics, Wilson intervals, failure taxonomy, JSON/CSV/HTML reports, and
  source/corpus reproducibility metadata;
• explicit holdout-consumption rules so a measured test set is not reused as a tuning set.

The selected operation-fit representation and threshold were frozen using v5
development/calibration data only. The final frozen configuration was then run exactly once on a
fresh 600-case v10 operation-generalization holdout.

Metric	v9 consumed holdout	v10 fresh one-shot
Overall accuracy	51.167%	55.667%
Supported-operation routed accuracy	38.281%	42.188%
Near-domain unsupported-operation rejection	70.833%	77.083%
Ordinary OOD rejection	100%	100%

The v10 failure taxonomy was:

• 334 correct;
• 44 false routes;
• 199 missed routes;
• 23 wrong endpoints;
• 0 wrong tools;
• 0 execution errors;
• 0 invalid plans.

Of the 199 missed supported routes, 162 were attributed to operation-fit and 37 to capability-fit.

Current limitation

The result is an improvement over v9, but it is not presented as solved routing quality.
Supported-operation routed accuracy is still 42.188% on v10, and operation-fit is the dominant
remaining recall bottleneck.

v10 is therefore now consumed regression evidence. It must not be used for iterative threshold or
representation tuning. Any post-0.8 optimization cycle needs a newly reserved untouched holdout
before implementation choices are evaluated.

Compatibility and scope

0.8.0 intentionally removes no documented public API from 0.7.0. New routing stages are optional and
bounded; multi-provider corroboration is explicit; aggregation does not bypass execution policy or
schema validation.

SchemaRouter remains pre-1.0 and remains deliberately narrower than a general agent framework.
Conversation memory, autonomous tool loops, workflow/DAG ownership, and model-provider orchestration
remain outside core.

Release validation

The protected release surface covers:

• Python 3.10–3.14 plus Windows smoke and Python preview signals;
• minimum dependencies, Pyright, branch coverage, and warnings-as-errors;
• wheel/sdist build and clean consumer acceptance;
• LangChain, LangGraph, LlamaIndex, Jev, Laya, MCP, and OpenTelemetry integrations;
• strict documentation build;
• dependency audit, CodeQL, OpenSSF Scorecard, immutable Action pins;
• release provenance, SPDX SBOM, and exact post-publish public-PyPI artifact verification.

External follow-up tracks

These remain deliberately separate from the runtime release:

• LangChain/LlamaIndex ecosystem listing or packaging guidance; outreach is already sent and no
  maintainer reply had arrived as of 2026-09-26;
• broader live hosted-provider/Jev decision evidence with dated runtime/token/cost metadata;
• GitHub About metadata and protected-main freshness settings;
• constraining the PyPI Trusted Publisher to the dedicated pypi GitHub environment.

The last two are repository/package-administration settings rather than missing runtime code.