Skip to content

SchemaRouter 0.5.0

SchemaRouter 0.5.0 is a runtime-hardening release focused on making existing execution contracts more authoritative under failure, time budgets, and real-world OpenAPI documents.

The release does not broaden SchemaRouter into a general agent framework. Instead, it tightens the tool-schema boundary introduced in earlier releases: retry behavior is more explicit, elapsed-time budgets cover more of the trusted execution path, and OpenAPI import/runtime behavior follows source semantics more faithfully.

Highlights

  • public NonRetryableInvocationError for deterministic invocation failures that should fail fast;
  • conservative transient HTTP retry classification for built-in OpenAPI and OPTIMADE transports;
  • retry backoff that cannot sleep past the remaining execution wall-clock budget;
  • max_backoff_seconds enforced from the first retry delay onward;
  • elapsed-time budgets covering approval callbacks and before/after execution hooks;
  • correct Operation-over-Path-Item OpenAPI parameter precedence;
  • collision-safe generated OpenAPI endpoint names without rewriting explicit operationId values;
  • required JSON object request-body presence preserved even when all flattened properties are optional;
  • schema-less JSON request bodies reported rather than fabricated as empty objects;
  • OpenAPI Accept, Content-Type, and Authorization header parameters excluded from planner arguments as required by the Parameter Object contract;
  • multiple 2xx JSON/no-content response variants preserved for runtime validation;
  • no-content successful HTTP responses represented as None;
  • compatibility scanning across every successful OpenAPI response instead of only the first.

Installation

pip install schemarouter

Optional integrations remain independently selectable:

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

Retry semantics

Built-in OpenAPI and OPTIMADE HTTP transports now distinguish a conservative set of transient status codes from deterministic failures. HTTP 408, 425, 429, 500, 502, 503, and 504 remain retryable when the endpoint and RetryPolicy allow retries. Other HTTP error statuses fail fast.

Trusted custom invokers retain their existing behavior for ordinary exceptions and can raise NonRetryableInvocationError when repeating the same invocation cannot safely recover.

Retry backoff is part of the run's elapsed-time budget. A configured delay cannot extend execution past ExecutionBudget.max_elapsed_seconds, and max_backoff_seconds applies from the first retry delay.

Execution budgets

The elapsed-time budget now covers awaited approval callbacks and trusted before/after execution hooks as well as the actual invoker attempt. This closes gaps where trusted middleware could previously outlive the run-level wall-clock limit.

Mutation/destructive policy, approval requirements, schema validation, retry policy, and budget accounting remain separate local authority layers.

OpenAPI fidelity

0.5.0 includes a concentrated OpenAPI correctness pass.

Parameter and endpoint identity

Operation-level parameters correctly override Path Item parameters with the same (name, in) identity. Generated endpoint names remain stable when unambiguous and receive deterministic suffixes only when distinct valid paths would otherwise collide. Explicit operationId values remain unchanged.

Request bodies and headers

For supported application/json object bodies, requestBody.required: true now preserves body presence even when every property is optional, so an empty required body is sent as {}.

A JSON request body without an explicit schema is not assumed to be an object. It remains unrepresented and is surfaced as a machine-readable compatibility limitation.

OpenAPI header parameters named Accept, Content-Type, or Authorization are ignored during import. Runtime authentication and other trusted headers remain local configuration, not model-owned arguments.

Success responses

Operations may declare different payloads for different 2xx response codes. SchemaRouter now collects supported JSON and no-content success variants rather than binding validation to the first 2xx response.

When multiple supported schemas exist, runtime validation uses a combined JSON Schema while planner output fields are retained across JSON variants. True no-content successes return None. If a successful variant uses an unsupported media type, strict output validation is disabled instead of incorrectly rejecting a valid success response, and the compatibility report exposes the limitation.

Compatibility

0.5.0 introduces no intentional public API removals relative to 0.4.0.

The principal behavior changes are correctness fixes for cases that were previously retried when they could not recover, allowed timing to exceed an explicit budget, or interpreted OpenAPI semantics incorrectly. Applications that relied on those prior edge-case behaviors should review the CHANGELOG.md.

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

Validation

The protected release gate covers:

  • Python 3.10 through 3.14 core tests;
  • Windows + Python 3.14 smoke execution;
  • Pyright static typing;
  • branch coverage with the blocking project threshold;
  • 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 provider/model benchmark evidence remains an external research track because credentials, hardware, provider versions, and pricing are non-deterministic CI inputs.

Security posture

0.5.0 preserves the existing fail-closed trust model and tightens several operational boundaries:

  • remote schemas and model output still cannot grant execution authority;
  • deterministic built-in transport failures can fail without consuming unnecessary retries;
  • retry delays cannot bypass the run wall-clock budget;
  • approval callbacks and execution hooks remain inside the elapsed-time boundary;
  • model-selected arguments cannot control protocol/auth headers excluded by the OpenAPI contract;
  • unsupported schema-less request bodies are reported instead of fabricated;
  • runtime payload tracing remains redacted by default;
  • stale schema fingerprints and stale invoker bindings remain rejected.

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