SchemaRouter

Schema-aware planning and execution for LLM tool ecosystems.

SchemaRouter compiles a natural-language request plus a registered capability catalog into a small, typed, auditable execution plan.

It goes beyond Query -> Tool routing:

Query
  -> Tool
  -> Endpoint
  -> Parameters
  -> Response fields
  -> Evidence / policy
  -> Schema validation
  -> Execute

SchemaRouter is intentionally narrower than LangChain or LangGraph. It is designed to sit at the tool-schema boundary between an agent and structured capability sources such as OpenAPI, MCP, OPTIMADE, Python callables, and third-party adapter protocols.

Status: 0.2.0a1 pre-release candidate. The adapter ecosystem, OPTIMADE support, package artifact, and public OpenAPI/OPTIMADE compatibility smokes are release-gated in CI.

Why

As an agent gains more tools, choosing the tool is only one part of the problem. The runtime also needs to know:

• which operation inside that tool is relevant;
• which parameters are declared and valid;
• which response fields should be retained;
• whether the operation is read-only, mutating, destructive, or unclassified;
• whether the schema changed after planning;
• whether the raw tool result actually satisfies the declared contract.

SchemaRouter makes those decisions explicit.

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)

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

print(results[0].data)

The same execution vocabulary works across capability sources:

router.invoke(request)
await router.ainvoke(request)

router.batch(requests)
await router.abatch(requests)

router.stream(request)
router.astream(request)
router.astream_events(request)

Bring your schema

OpenAPI

router = await SchemaRouter.from_url(
    "https://api.example.com/openapi.json",
    kind="openapi",
)

OPTIMADE

router = await SchemaRouter.from_url(
    "https://www.crystallography.net/cod/optimade",
    kind="optimade",
)

OPTIMADE entry schemas are discovered from /info/<entry_type>. Planned fields are translated into the protocol's response_fields query parameter before execution.

MCP

pip install -e ".[mcp]"

router = await SchemaRouter.from_url(
    "http://localhost:8000/mcp",
    kind="mcp",
)

Python

router.add_callable(my_typed_function)

Human-readable API docs

proposal = await router.inspect_url(
    "https://docs.example.com/api",
    model=documentation_model,
)

router.approve_proposal(
    proposal,
    base_url="https://api.example.com",
)

Human-readable documentation never becomes executable automatically. It first becomes an evidence-grounded proposal and then requires explicit approval.

Core guarantees

• Schema-constrained planning — unknown tools, endpoints, parameters, and fields cannot become executable calls.
• Runtime JSON Schema validation — validate arguments before invocation and raw output before projection.
• Schema and binding drift detection — stale plans and stale transports fail closed.
• Local execution authority — remote metadata and model output cannot grant mutation or destructive permissions.
• Credential separation — schema-fetch credentials and runtime credentials stay in different channels.
• Read-only retries by default — contract violations are never retried.
• Redacted runtime events by default — payload tracing is opt-in.
• Pluggable registry — custom registries can implement the public ToolRegistry protocol.
• Pluggable source adapters — AdapterRegistry lets structured protocols compile into the same ToolSpec / EndpointSpec execution model.

With LangChain

Install the optional integration:

pip install -e ".[langchain]"

Then expose registered endpoints as LangChain StructuredTool objects:

from schemarouter.integrations import to_langchain_tools

tools = to_langchain_tools(router)

Execution still flows through SchemaRouter's policy, fingerprint, input, and output validation.

Documentation

Full documentation is organized as a framework manual rather than embedded in this README:

• Getting started
• Core concepts
• OpenAPI guide
• OPTIMADE guide
• MCP guide
• LangChain integration
• API reference
• Architecture
• Security
• Brand assets

Build the docs locally with:

pip install -e ".[docs]"
mkdocs serve

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ruff check .
pytest -q -m "not mcp_integration"
python examples/quickstart.py

Optional integration suites are isolated from the core package:

pip install -e ".[dev,mcp]"
pytest -q tests/test_mcp_integration.py

pip install -e ".[dev,langchain]"
pytest -q tests/test_langchain_integration.py

Project scope

SchemaRouter does not implement another chat abstraction, graph runtime, model-provider layer, memory system, or checkpoint store. Those belong in surrounding agent frameworks.

Its scope is:

Natural-language request -> typed tool execution plan -> validated execution.

Research

SchemaRouter originated from SchemaRouter: Field-Aware Tool Routing for Efficient Heterogeneous Agentic RAG. The framework keeps the research idea while removing harness assumptions such as one endpoint per tool and fixture-only execution.

License

MIT © 2026 Yong-eun Cho