schemarouter 0.12.0

Typed capability routing and execution for RAG and LLM agent systems.

English · 한국어 · Docs · Latest release

Stable release: 0.11.0 · pip install schemarouter · Beta / pre-1.0

SchemaRouter sits between a RAG/agent application and its structured external capabilities. It normalizes OpenAPI, MCP, OPTIMADE, Python, and plugin-defined tools into a typed capability catalog, selects a bounded executable route for the requested data, and validates the contract again before and after execution.

It is not a general agent framework, an LLM provider layer, or a RAG generator.

Where SchemaRouter fits in RAG

Retrieval-Augmented Generation (RAG) augments generation with information retrieved from external, non-parametric sources.

SchemaRouter does not perform the final generation step. Its role is narrower: it can provide the structured retrieval and execution layer that lets a RAG or agent system obtain live external data from APIs and tools under explicit schemas and policy.

User query
    |
    v
RAG / Agent / Application
    |
    |  "I need elastic modulus + provenance"
    v
SchemaRouter
    |
    +--> retrieve a registered capability
    +--> select endpoint + required fields
    +--> validate parameters / policy / health
    +--> execute trusted transport
    +--> validate raw output
    +--> normalize declared units / project fields
    |
    v
Typed external data
    |
    v
RAG generation / agent reasoning

For document-centric RAG, a retriever commonly searches chunks or records. SchemaRouter addresses a different retrieval surface: executable capabilities and the structured data they can return.

Read the RAG positioning and capability model

Field-first, route-second

SchemaRouter first resolves what data is required, then chooses a registered route that can provide it.

For example:

Query: "What is the elastic modulus of this material at 300 K?"

Required field
  semantic_id: mechanical.elastic_modulus
  datatype: number
  unit: optional but declared when applicable
  qualifiers:
    temperature: 300 K

Possible routes
  provider A / REST endpoint
  provider A / OPTIMADE access
  provider B / MCP tool

Availability can change the route. It must not silently change the requested data contract.

A field contract can carry:

• JSON datatype / shape;
• semantic ID and aliases;
• optional source unit;
• explicit canonical unit normalization;
• exact qualifiers such as temperature, pressure, phase, orientation, or method;
• provenance, license, or source-type evidence;
• provider/access identity and availability metadata.

Units are optional because many legitimate fields are text, identifiers, booleans, structured objects, or dimensionless values. SchemaRouter does not infer scientific equivalence or conversion factors from a unit string alone.

Execution boundary

LangChain / LangGraph / LlamaIndex / your application
                         |
                    SchemaRouter
                         |
          OpenAPI / MCP / OPTIMADE / Python

The surrounding framework owns conversation, decomposition, generation, memory, graphs, and agent loops. SchemaRouter owns the typed capability and execution boundary.

Optional Laya, Ollama, Jev/System-One, hosted-model, embedding, or pairwise decision backends may assist selection over locally registered candidates. They do not become execution authority and cannot invent tools, fields, credentials, permissions, or side effects.

Retrieve a compact tool set for an agent

SchemaRouter can return registered capability candidates without planning or executing them:

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

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

Use retrieve_executable(..., k=5) when candidates must also have a currently ready local execution binding. Async counterparts are aretrieve and aretrieve_executable.

The returned candidates retain the full effective input/output JSON Schemas plus registered parameters/output fields, semantic IDs, optional units and qualifiers, provider/access identity, read/write/destructive metadata, and schema fingerprints. Retrieval has no side effect and does not grant execution authority; the surrounding agent still chooses among candidates and execution remains subject to SchemaRouter validation and policy.

Quickstart

from pydantic import BaseModel
from schemarouter import PlanRequest, SchemaRouter, schema_tool


class Weather(BaseModel):
    city: str
    temperature: float


@schema_tool(read_only=True)
def current_weather(city: str) -> Weather:
    return Weather(city=city, temperature=20.5)


router = SchemaRouter()
router.add_callable(current_weather)

result = router.invoke(
    PlanRequest(query="city temperature", arguments={"city": "Seoul"})
)

print(result[0].data)

Connect capabilities

Framework bridges are available for LangChain, LangGraph, and LlamaIndex. OpenTelemetry is optional. Third-party bounded decision backends can be published through the schemarouter.decision_backends entry-point group.

What works in 0.11.0

The released package provides a working beta implementation of the core architecture:

• typed Tool / Endpoint / Parameter / Field registry contracts;
• first-class bounded Top-K capability retrieval through retrieve / aretrieve and executable-ready variants;
• Python, OpenAPI, MCP, and OPTIMADE ingestion paths;
• field-first planning and bounded multi-provider field coverage;
• input and raw-output JSON Schema validation;
• schema fingerprints and binding-drift rejection;
• read/write/destructive local policy gates and per-call approval hooks;
• explicit server-side field projection plus final local projection;
• optional datatype/unit normalization and exact scientific qualifiers;
• provider/access fallback with finite cooldown and trusted health recovery;
• sync/async invocation, batch, streaming, typed events, traces, and inspection/dashboard surfaces;
• LangChain, LangGraph, LlamaIndex, Jev/System-One, Laya, Ollama, and OpenTelemetry integration surfaces.

So the architecture works today for declared capabilities and supported routing cases.

Current research direction: compact capability retrieval for agents

The stable 0.11.0 execution boundary is unchanged. The active research question has shifted from making SchemaRouter itself the final open-set classifier to evaluating it as a typed capability retrieval substrate for a downstream LLM agent.

The intended separation is:

registered capability catalog
  -> SchemaRouter Top-K typed candidates
  -> downstream agent chooses among candidates
  -> local schema / argument / permission / destructive policy
  -> execution

Why this matters: on the corrected frozen 0.14 Phase-A benchmark, Top-1 required-route recall is 68.97%, while Top-5 preserves 100% of required capabilities. At 250 registered endpoints, Top-5 exposes only 2.38% of the FULL serialized schema context on average.

Those are retrieval results, not a completed production claim. The active #420 B1 experiment is measuring whether the same real tool-calling agent maintains or improves deterministic task success while consuming less tool context under FULL vs SR-3/SR-5/SR-10/progressive conditions. A separate strong-agent replication (#423) and final-answer quality benchmark (#424) are required before generalizing the result.

The earlier 0.11–0.13 open-set classifier/veto experiments remain valuable negative evidence. No experimental learned router is promoted as an unconditional production default in 0.11.0.

See:

• Routing research status
• Prior-art roadmap
• Complete experiment index
• 0.11.0 release notes
• Changelog

Inspect the registry and runs

schemarouter inspect registry --db ./registry.sqlite3
schemarouter inspect tool materials --db ./registry.sqlite3
schemarouter inspect diff materials \
  --old-db ./registry-before.sqlite3 \
  --new-db ./registry-current.sqlite3
schemarouter inspect traces --db ./traces.sqlite3
schemarouter inspect trace <RUN_ID> --db ./traces.sqlite3
schemarouter dashboard \
  --registry ./registry.sqlite3 \
  --traces ./traces.sqlite3 \
  --output ./artifacts/schemarouter-dashboard.html

Documentation

• Installation
• Quickstart
• What SchemaRouter is
• RAG positioning and capability model
• Field-first execution
• OpenAPI
• MCP
• Architecture and maturity
• Security model
• Prior-art roadmap
• Routing research status
• Complete experiment index

Scope

SchemaRouter intentionally does not implement another chat abstraction, prompt framework, model-provider layer, conversation memory, checkpoint store, or graph runtime.

Natural-language request → typed capability plan → validated external data → surrounding RAG/agent

Research and license

SchemaRouter originated from SchemaRouter: Field-Aware Tool Routing for Efficient Heterogeneous Agentic RAG.

MIT © 2026 Yong-eun Cho