Skip to content

SchemaRouter 0.7.0

SchemaRouter 0.7.0 hardens the field-first execution boundary introduced in earlier releases. The release focuses on provider/access resilience, typed scientific result contracts, operation-scoped policy, bounded observability, and release/supply-chain verification without expanding SchemaRouter into a general agent runtime.

Highlights

Field-first provider and access routing

0.7 makes the logical data need more explicit before transport choice:

  • add explicit provider/access identities and precompiled read-only fallback routes;
  • prefer same-provider alternatives before optional cross-provider fallback;
  • compile each fallback independently against its own parameter and field contract;
  • add trusted server-side field projection contracts for APIs such as OpenAPI and OPTIMADE;
  • preserve final local projection after raw-response validation;
  • add finite access-path cooldowns plus trusted background health probes that can reopen recovered read-only routes without permanent blacklisting;
  • make execution-facing planning binding-aware through the execution-ready planning surface.

Fallback remains bounded and fail-closed. Schema, policy, approval, mutation, deterministic 4xx, and stale-contract failures are not treated as generic availability failures.

Typed scientific fields, units, and exact qualifiers

Scientific fields can now carry enough contract metadata to distinguish values that share a name but are not interchangeable:

  • explicit JSON value-shape contracts for selected result fields;
  • optional exact source-unit metadata;
  • affine UnitNormalizationSpec conversion into a declared canonical unit;
  • numeric-array normalization support;
  • compact ToolResult.field_contracts metadata for downstream consumers;
  • exact trusted FieldSpec.qualifiers for fixed context such as temperature, phase, orientation, pressure, or measurement method.

Qualifiers participate in schema fingerprints, inspection, schema-diff analysis, cross-provider fallback compatibility, and bounded field selection. When a qualifier is visibly present in the query, deterministic routing may use it to distinguish otherwise equivalent fields.

SchemaRouter deliberately does not infer scientific equivalence, convert qualifier values, normalize ontology terms, or synthesize unstated measurement context.

Trusted parameter aliases

ParameterSpec.aliases allows the same logical argument to bind to provider-specific local parameter names without model-authored remapping.

The binding rules are conservative:

  • exact parameter names take precedence;
  • aliases are trusted local schema declarations;
  • ambiguous aliases fail closed;
  • candidate indexing recognizes aliases;
  • fallback calls are compiled independently against each access contract.

Policy, schema drift, and explainability

0.7 adds several operational contracts around planning and execution:

  • ordered operation-scoped PolicyRule controls with allow, deny, and require_approval;
  • conservative endpoint/tool schema-diff reports with additive, breaking, and security-review classifications;
  • exact schema/tool fingerprints remain the execution authority even when a diff is informational;
  • structured PlanExplanation output for deterministic score components, field-selection reasons, ignored undeclared arguments, and bounded decision-selection source;
  • explicit parallel_read_only fan-out with preflight validation, shared budgets, bounded concurrency, and completion-order streaming.

Explanations expose locally observable routing signals only. They do not expose model chain-of-thought.

Benchmarking, compatibility, and packaging

The decision benchmark and release pipeline received a substantial reproducibility pass:

  • self-contained benchmark HTML and multi-run history reports;
  • corpus/source revision metadata and reproducibility manifests;
  • Wilson score intervals for routing and category-level accuracy;
  • confidence capture and offline threshold calibration;
  • public OpenAPI/OPTIMADE compatibility artifacts;
  • Hypothesis-based OpenAPI serialization properties;
  • consumer-acceptance scenarios from clean wheel and sdist environments;
  • isolated lightweight-extra and combined-integration package smokes;
  • exact-version post-publish verification against public PyPI artifacts.

Security and supply chain

Security-sensitive changes continue to prefer rejection over hidden coercion:

  • stricter datatype/unit compatibility for automatic fallback;
  • stale-plan protection across remote/local classification and execution metadata;
  • inspection provenance derived from fingerprinted contracts;
  • sanitized schema/document provenance before model or dashboard exposure;
  • dependency auditing, CodeQL, OpenSSF Scorecard, and immutable GitHub Action pins;
  • build provenance and SPDX SBOM attestations for release artifacts;
  • post-publish SHA-256 verification of public PyPI wheel and sdist against trusted build artifacts.

Platform and CI

The 0.7 release gates include:

  • Python 3.10 through 3.14;
  • Windows smoke;
  • minimum declared dependencies;
  • Pyright and branch coverage;
  • wheel/sdist build and clean-install consumer acceptance;
  • LangChain, LangGraph, LlamaIndex, Jev, Laya, MCP, and OpenTelemetry integration checks;
  • strict documentation build;
  • CodeQL, dependency audit, and OpenSSF Scorecard;
  • recent public OpenAPI and OPTIMADE compatibility smokes.

Compatibility

0.7.0 intentionally removes no public API from 0.6.0.

Some automatic fallback behavior is stricter by design: if SchemaRouter cannot prove datatype, unit, canonical-unit, or exact-qualifier compatibility, the alternative route is rejected rather than guessed. This is a correctness/security tightening of the fail-closed contract.

SchemaRouter remains pre-1.0, so later 0.x minor releases may still introduce deliberate documented compatibility changes.

External follow-up tracks

The following work is intentionally separate from the 0.7.0 code release:

  • dated live decision-routing measurements using real hosted/local model providers and concrete hardware;
  • LangChain/LlamaIndex ecosystem listing or packaging guidance from upstream maintainers;
  • repository About/protected-main administrator settings;
  • narrowing the PyPI Trusted Publisher to the dedicated pypi GitHub environment.

These items do not change the shipped runtime contract and are tracked independently.