schemarouter 0.2.0a1__py3-none-any.whl

schemarouter/validation.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from typing import Any
+
+from jsonschema import exceptions, validators
+
+from .errors import SchemaValidationError
+from .models import EndpointSpec
+
+
+def _synthesized_input_schema(endpoint: EndpointSpec) -> dict[str, Any]:
+    properties = {
+        parameter.name: parameter.json_schema or {}
+        for parameter in endpoint.parameters
+    }
+    required = [
+        parameter.name
+        for parameter in endpoint.parameters
+        if parameter.required
+    ]
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+        "additionalProperties": False,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def _synthesized_output_schema(endpoint: EndpointSpec) -> dict[str, Any]:
+    properties = {
+        field.name: field.json_schema or {}
+        for field in endpoint.output_fields
+    }
+    required = [
+        name
+        for name in endpoint.metadata.get("output_required", [])
+        if name in properties
+    ]
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def effective_input_schema(endpoint: EndpointSpec) -> dict[str, Any]:
+    return endpoint.input_schema or _synthesized_input_schema(endpoint)
+
+
+def effective_output_schema(endpoint: EndpointSpec) -> dict[str, Any]:
+    if endpoint.output_schema:
+        return endpoint.output_schema
+    if endpoint.output_fields:
+        return _synthesized_output_schema(endpoint)
+    return {}
+
+
+def validate_json_schema_value(
+    value: Any,
+    schema: dict[str, Any],
+    *,
+    context: str,
+) -> None:
+    if not schema:
+        return
+
+    try:
+        validator_cls = validators.validator_for(schema)
+        validator_cls.check_schema(schema)
+        validator = validator_cls(schema)
+        errors = sorted(
+            validator.iter_errors(value),
+            key=lambda error: [str(part) for part in error.absolute_path],
+        )
+    except exceptions.SchemaError as exc:
+        raise SchemaValidationError(
+            f"{context}: declared JSON Schema is invalid: {exc.message}"
+        ) from exc
+    except Exception as exc:  # unresolved refs and validator/runtime failures fail closed
+        raise SchemaValidationError(
+            f"{context}: JSON Schema could not be evaluated safely"
+        ) from exc
+
+    if not errors:
+        return
+
+    first = errors[0]
+    path = ".".join(str(part) for part in first.absolute_path)
+    location = f" at {path}" if path else ""
+    raise SchemaValidationError(
+        f"{context}{location}: {first.message}"
+    )

schemarouter-0.2.0a1.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.5
+Name: schemarouter
+Version: 0.2.0a1
+Summary: Schema-aware planning and execution layer for LLM tool ecosystems
+Project-URL: Homepage, https://github.com/JDeun/SchemaRouter
+Project-URL: Repository, https://github.com/JDeun/SchemaRouter
+Project-URL: Documentation, https://jdeun.github.io/SchemaRouter/
+Project-URL: Issues, https://github.com/JDeun/SchemaRouter/issues
+Project-URL: Research, https://github.com/JDeun/paper_SchemaRouter
+Project-URL: Brand, https://jdeun.github.io/SchemaRouter/project/brand/
+Author: Yong-eun Cho
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,llm,mcp,openapi,optimade,schema,tool-routing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.7; extra == 'docs'
+Requires-Dist: mkdocstrings-python<3,>=2; extra == 'docs'
+Requires-Dist: mkdocstrings<2,>=1; extra == 'docs'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=1.6; extra == 'langchain'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JDeun/SchemaRouter/main/docs/assets/brand/schemarouter-lockup-dark.svg">
+    <img alt="SchemaRouter" src="https://raw.githubusercontent.com/JDeun/SchemaRouter/main/docs/assets/brand/schemarouter-lockup-light.svg" width="760">
+  </picture>
+</p>
+
+# SchemaRouter
+
+**Schema-aware planning and execution for LLM tool ecosystems.**
+
+[![CI](https://github.com/JDeun/SchemaRouter/actions/workflows/ci.yml/badge.svg)](https://github.com/JDeun/SchemaRouter/actions/workflows/ci.yml)
+[![Docs](https://github.com/JDeun/SchemaRouter/actions/workflows/docs.yml/badge.svg)](https://github.com/JDeun/SchemaRouter/actions/workflows/docs.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/JDeun/SchemaRouter/blob/main/LICENSE)
+
+SchemaRouter compiles a natural-language request plus a registered capability catalog into a small,
+typed, auditable execution plan.
+
+It goes beyond `Query -> Tool` routing:
+
+```text
+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
+
+```python
+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:
+
+```python
+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
+
+```python
+router = await SchemaRouter.from_url(
+    "https://api.example.com/openapi.json",
+    kind="openapi",
+)
+```
+
+### OPTIMADE
+
+```python
+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
+
+```bash
+pip install -e ".[mcp]"
+```
+
+```python
+router = await SchemaRouter.from_url(
+    "http://localhost:8000/mcp",
+    kind="mcp",
+)
+```
+
+### Python
+
+```python
+router.add_callable(my_typed_function)
+```
+
+### Human-readable API docs
+
+```python
+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:
+
+```bash
+pip install -e ".[langchain]"
+```
+
+Then expose registered endpoints as LangChain `StructuredTool` objects:
+
+```python
+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](https://jdeun.github.io/SchemaRouter/getting-started/installation/)
+- [Core concepts](https://jdeun.github.io/SchemaRouter/concepts/schema-router/)
+- [OpenAPI guide](https://jdeun.github.io/SchemaRouter/guides/openapi/)
+- [OPTIMADE guide](https://jdeun.github.io/SchemaRouter/guides/optimade/)
+- [MCP guide](https://jdeun.github.io/SchemaRouter/guides/mcp/)
+- [LangChain integration](https://jdeun.github.io/SchemaRouter/integrations/langchain/)
+- [API reference](https://jdeun.github.io/SchemaRouter/reference/api/)
+- [Architecture](https://jdeun.github.io/SchemaRouter/architecture/)
+- [Security](https://github.com/JDeun/SchemaRouter/blob/main/SECURITY.md)
+- [Brand assets](https://jdeun.github.io/SchemaRouter/project/brand/)
+
+Build the docs locally with:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Development
+
+```bash
+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:
+
+```bash
+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](https://github.com/JDeun/paper_SchemaRouter).
+The framework keeps the research idea while removing harness assumptions such as one endpoint per
+tool and fixture-only execution.
+
+## License
+
+[MIT](LICENSE) © 2026 Yong-eun Cho

schemarouter-0.2.0a1.dist-info/RECORD

@@ -0,0 +1,28 @@
+schemarouter/__init__.py,sha256=35KxcP_aDxLvh3qoSCxxemhQK8pu8fE7Yh8h6Wo5cKU,2242
+schemarouter/_version.py,sha256=TSc1i5RpPmxz8SJO0026XvlaNzvXzcmAVrWlPIiCqiU,204
+schemarouter/errors.py,sha256=_xXTd0VnEwvCal1KQlQyjHKwtJ09PWmCzT5AEJ9VJTU,1446
+schemarouter/executor.py,sha256=q65t37boNR6QH6MMBHzZ3HZfqk6KhrqfNI_neD4KZ8k,7571
+schemarouter/ingestion.py,sha256=ulpu6bDadgctFMVLDkiTRVHgCg9gIqy0OEEMeq52qZs,11907
+schemarouter/models.py,sha256=H2nbHTS71JYqwW8EPMjB0b3cmS5avhYrnvgBG5UeB6Q,5217
+schemarouter/planner.py,sha256=chsE524EYCjM__bB_qTJfjPk4wolRZyOCmu2eyGGkMM,8754
+schemarouter/policy.py,sha256=uH_cYlid7X_GAwcA07Q4vFIVH9d5ZbEUnc4HWNVoEYY,1649
+schemarouter/proposals.py,sha256=TtqifnSZhTCtCZiGR7ecG9iySgBn9MrQwNbq57BtlZ4,13774
+schemarouter/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+schemarouter/registry.py,sha256=7drBnDUXOhVshvVA29k1fjko_Ug3TFLbIR4Q8nEI584,2734
+schemarouter/runs.py,sha256=a34lM_59nfBiZbQuAGn28rbyDrDAfXJch6hId0Gw9OU,2124
+schemarouter/runtime.py,sha256=gnc50L6uL9nJg1KxmyoV9u7XlKj9GDxRBY3K58Knn4Q,22329
+schemarouter/validation.py,sha256=Fp7y6uOX7d14xVIA0D29wTOWe1UfzW61kQnzE1H6mTQ,2673
+schemarouter/adapters/__init__.py,sha256=BaMVOLTSpUaQL9IYynwXUmICMBMrrrzD4GSDYIKF04M,833
+schemarouter/adapters/base.py,sha256=UDe2rt1TwRyNpNBVQJrJWWX5WaKRrDw2n0WJ9X9o1nI,2137
+schemarouter/adapters/mcp.py,sha256=Kyon1cG85cu9JrZDH-kP1clIjXCdvNrebLZLlC_sNdE,6299
+schemarouter/adapters/openapi.py,sha256=Hd2l49V-Wi093b9swrB8ruhMR4y5z-b9L0tmB3iUg8M,16161
+schemarouter/adapters/optimade.py,sha256=SVuKlwFve7o4o4h-Nu276MfqiMChOc-LQqOlM83OChQ,23289
+schemarouter/adapters/python.py,sha256=_T6x4TKIF4_rWTsMlgq4qCSnYLIs8a6wLytHIrebu2s,6292
+schemarouter/analyzers/__init__.py,sha256=FD0SPxM73z1Lhp6Esdz6itv5DJd6sioSTG1GoMtqmqc,132
+schemarouter/analyzers/model.py,sha256=g6otRPvPlFKAjviajyHI3nDk7HfQjzC-fSGuiDDMKyY,7031
+schemarouter/integrations/__init__.py,sha256=kAhuW7AcwtddfxaveLfeghD9NyAa2nvn_o3FplzyLvw,116
+schemarouter/integrations/langchain.py,sha256=t9HaljVsNMT4dljqat1o_l8MpBjrVoBMjtkyxhTlFsY,2871
+schemarouter-0.2.0a1.dist-info/METADATA,sha256=aQCoePBaMis_lKolA0LLl-LFxaPa4ButfbbbY0qjcsA,9190
+schemarouter-0.2.0a1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+schemarouter-0.2.0a1.dist-info/licenses/LICENSE,sha256=yvJzTnx0kTgez87WW1o-9QRwYw0vY7ascd0JCfgloEk,1069
+schemarouter-0.2.0a1.dist-info/RECORD,,

schemarouter-0.2.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

schemarouter-0.2.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yong-eun Cho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.