schemarouter 0.2.0a1__py3-none-any.whl

schemarouter/__init__.py

@@ -0,0 +1,88 @@
+from ._version import __version__
+from .adapters.base import AdapterContext, AdapterLoadResult, AdapterRegistry, SourceAdapter
+from .adapters.optimade import OPTIMADESourceAdapter
+from .adapters.python import schema_tool, tool_from_callable
+from .analyzers import ModelCallable, ModelQueryAnalyzer
+from .errors import (
+    BindingDriftError,
+    ExecutionError,
+    ModelAnalysisError,
+    PlanningError,
+    PlanValidationError,
+    PolicyViolationError,
+    ProposalApprovalError,
+    RegistrationError,
+    SchemaDriftError,
+    SchemaRouterError,
+    SchemaSourceError,
+    SchemaValidationError,
+    UnsupportedSchemaSourceError,
+)
+from .executor import RegistryExecutor
+from .models import (
+    EndpointSpec,
+    EvidenceRequirements,
+    ExecutionPlan,
+    FieldSpec,
+    ParameterSpec,
+    PlanRequest,
+    QueryIntent,
+    ToolCall,
+    ToolResult,
+    ToolSpec,
+)
+from .planner import KeywordAnalyzer, QueryAnalyzer, SchemaPlanner
+from .policy import ExecutionPolicy
+from .proposals import SchemaProposal
+from .registry import InMemoryRegistry, ToolRegistry
+from .runs import RetryPolicy, RunConfig, RunEvent
+from .runtime import ConfiguredSchemaRouter, SchemaRouter
+
+__all__ = [
+    "__version__",
+    "AdapterContext",
+    "AdapterLoadResult",
+    "AdapterRegistry",
+    "BindingDriftError",
+    "ConfiguredSchemaRouter",
+    "EndpointSpec",
+    "EvidenceRequirements",
+    "ExecutionError",
+    "ExecutionPlan",
+    "ExecutionPolicy",
+    "FieldSpec",
+    "InMemoryRegistry",
+    "KeywordAnalyzer",
+    "ModelAnalysisError",
+    "ModelCallable",
+    "ModelQueryAnalyzer",
+    "ParameterSpec",
+    "PlanRequest",
+    "PlanValidationError",
+    "PlanningError",
+    "PolicyViolationError",
+    "ProposalApprovalError",
+    "QueryAnalyzer",
+    "QueryIntent",
+    "RegistrationError",
+    "RegistryExecutor",
+    "RetryPolicy",
+    "RunConfig",
+    "RunEvent",
+    "SchemaDriftError",
+    "SchemaPlanner",
+    "SchemaProposal",
+    "SchemaRouter",
+    "SchemaRouterError",
+    "SchemaSourceError",
+    "SchemaValidationError",
+    "SourceAdapter",
+    "OPTIMADESourceAdapter",
+    "ToolCall",
+    "ToolRegistry",
+    "ToolResult",
+    "ToolSpec",
+    "UnsupportedSchemaSourceError",
+    "schema_tool",
+    "tool_from_callable",
+]

schemarouter/_version.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("schemarouter")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

schemarouter/adapters/__init__.py

@@ -0,0 +1,29 @@
+from .base import AdapterContext, AdapterLoadResult, AdapterRegistry, SourceAdapter
+from .mcp import MCPRemoteInvoker, inspect_mcp_url, tool_from_mcp
+from .openapi import OpenAPIRemoteInvoker, resolve_openapi_base_url, tool_from_openapi
+from .optimade import OPTIMADERemoteInvoker, OPTIMADESourceAdapter
+from .python import (
+    PythonCallableInvoker,
+    callable_options,
+    schema_tool,
+    tool_from_callable,
+)
+
+__all__ = [
+    "AdapterContext",
+    "AdapterLoadResult",
+    "AdapterRegistry",
+    "MCPRemoteInvoker",
+    "OPTIMADERemoteInvoker",
+    "OPTIMADESourceAdapter",
+    "OpenAPIRemoteInvoker",
+    "PythonCallableInvoker",
+    "SourceAdapter",
+    "callable_options",
+    "inspect_mcp_url",
+    "resolve_openapi_base_url",
+    "schema_tool",
+    "tool_from_callable",
+    "tool_from_mcp",
+    "tool_from_openapi",
+]

schemarouter/adapters/base.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+import httpx
+
+from ..models import ToolSpec
+
+
+@dataclass(frozen=True)
+class AdapterContext:
+    url: str
+    name: str | None = None
+    namespace: str | None = None
+    base_url: str | None = None
+    schema_headers: dict[str, str] | None = None
+    trusted_headers: dict[str, str] | None = None
+    timeout: float = 20.0
+    http_client: httpx.AsyncClient | None = None
+
+
+@dataclass(frozen=True)
+class AdapterLoadResult:
+    tool: ToolSpec
+    invoker: Any | None = None
+
+
+class SourceAdapter(Protocol):
+    kind: str
+    priority: int
+
+    async def load(self, context: AdapterContext) -> AdapterLoadResult | None: ...
+
+
+class AdapterRegistry:
+    """Ordered registry for structured capability-source adapters."""
+
+    def __init__(self, adapters: list[SourceAdapter] | None = None) -> None:
+        self._adapters: dict[str, SourceAdapter] = {}
+        for adapter in adapters or []:
+            self.register(adapter)
+
+    def register(self, adapter: SourceAdapter, *, replace: bool = False) -> None:
+        kind = str(adapter.kind).strip().lower()
+        if not kind or kind == "auto":
+            raise ValueError("adapter kind must be a non-empty name other than 'auto'")
+        if kind in self._adapters and not replace:
+            raise ValueError(f"adapter kind already registered: {kind!r}")
+        self._adapters[kind] = adapter
+
+    def unregister(self, kind: str) -> None:
+        self._adapters.pop(kind.strip().lower(), None)
+
+    def get(self, kind: str) -> SourceAdapter:
+        normalized = kind.strip().lower()
+        try:
+            return self._adapters[normalized]
+        except KeyError as exc:
+            raise KeyError(f"unknown adapter kind: {normalized!r}") from exc
+
+    def kinds(self) -> tuple[str, ...]:
+        return tuple(sorted(self._adapters))
+
+    def ordered(self) -> tuple[SourceAdapter, ...]:
+        return tuple(
+            sorted(
+                self._adapters.values(),
+                key=lambda adapter: (-int(adapter.priority), str(adapter.kind)),
+            )
+        )

schemarouter/adapters/mcp.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import SchemaSourceError
+from ..models import EndpointSpec, FieldSpec, ParameterSpec, ToolSpec
+
+
+def _properties(schema: dict[str, Any] | None) -> dict[str, dict[str, Any]]:
+    if not isinstance(schema, dict):
+        return {}
+    props = schema.get("properties", {})
+    return props if isinstance(props, dict) else {}
+
+
+def _as_dict(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return value
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json", by_alias=True, exclude_none=True)
+    raise TypeError(f"cannot convert MCP value {type(value)!r} to dict")
+
+
+def tool_from_mcp(
+    server_name: str,
+    tools_list_result: dict[str, Any] | list[dict[str, Any]],
+    *,
+    namespace: str | None = None,
+) -> ToolSpec:
+    """Convert an MCP tools/list result into a single server-scoped ToolSpec.
+
+    Remote annotations are preserved as untrusted metadata only; they do not grant permissions.
+    """
+    raw_tools = (
+        tools_list_result.get("tools", [])
+        if isinstance(tools_list_result, dict)
+        else tools_list_result
+    )
+    endpoints: list[EndpointSpec] = []
+    for raw_item in raw_tools:
+        item = _as_dict(raw_item)
+        input_schema = item.get("inputSchema") or item.get("input_schema") or {}
+        required = (
+            set(input_schema.get("required", []))
+            if isinstance(input_schema, dict)
+            else set()
+        )
+        parameters = [
+            ParameterSpec(
+                name=name,
+                description=spec.get("description", "") if isinstance(spec, dict) else "",
+                required=name in required,
+                location="argument",
+                json_schema=spec if isinstance(spec, dict) else {},
+            )
+            for name, spec in _properties(input_schema).items()
+        ]
+
+        output_schema = item.get("outputSchema") or item.get("output_schema") or {}
+        output_required = (
+            set(output_schema.get("required", []))
+            if isinstance(output_schema, dict)
+            else set()
+        )
+        fields = [
+            FieldSpec(
+                name=name,
+                description=spec.get("description", "") if isinstance(spec, dict) else "",
+                json_schema=spec if isinstance(spec, dict) else {},
+                identifier=name in {"id", "uuid", "key"} or name.endswith("_id"),
+                aliases=[name.replace("_", " ")],
+            )
+            for name, spec in _properties(output_schema).items()
+        ]
+        metadata = {
+            "title": item.get("title"),
+            "annotations": item.get("annotations"),
+            "output_required": sorted(output_required),
+            "remote_name": item.get("name"),
+        }
+        endpoints.append(
+            EndpointSpec(
+                name=item["name"],
+                description=item.get("description", ""),
+                parameters=parameters,
+                output_fields=fields,
+                input_schema=input_schema if isinstance(input_schema, dict) else {},
+                output_schema=output_schema if isinstance(output_schema, dict) else {},
+                metadata=metadata,
+            )
+        )
+
+    return ToolSpec(
+        name=server_name,
+        namespace=namespace,
+        description=f"MCP server: {server_name}",
+        endpoints=endpoints,
+        metadata={"adapter": "mcp", "remote_metadata_untrusted": True},
+    )
+
+
+async def inspect_mcp_url(
+    url: str,
+    *,
+    server_name: str | None = None,
+    namespace: str | None = None,
+) -> ToolSpec:
+    """Connect to a Streamable HTTP MCP URL and import all advertised tools."""
+    try:
+        from mcp import Client
+    except ImportError as exc:
+        raise SchemaSourceError(
+            'MCP support requires the optional dependency: pip install "schemarouter[mcp]"'
+        ) from exc
+
+    raw_tools: list[dict[str, Any]] = []
+    try:
+        async with Client(url) as client:
+            cursor: str | None = None
+            while True:
+                page = await client.list_tools(cursor=cursor)
+                raw_tools.extend(_as_dict(tool) for tool in page.tools)
+                cursor = page.next_cursor
+                if cursor is None:
+                    break
+
+            info = getattr(client, "server_info", None)
+            discovered_name = getattr(info, "name", None)
+            protocol_version = getattr(client, "protocol_version", None)
+    except Exception as exc:  # noqa: BLE001
+        raise SchemaSourceError(f"failed to inspect MCP server at {url!r}") from exc
+
+    name = server_name or discovered_name or "mcp_server"
+    tool = tool_from_mcp(name, raw_tools, namespace=namespace)
+    tool.metadata.update(
+        {
+            "source_url": url,
+            "protocol_version": protocol_version,
+        }
+    )
+    return tool
+
+
+class MCPRemoteInvoker:
+    """Trusted runtime adapter for a remote MCP server.
+
+    A fresh client lifecycle is used per invocation in v0.1. Connection pooling belongs in a
+    later transport layer so the core executor remains stateless and easy to reason about.
+    """
+
+    def __init__(self, url: str) -> None:
+        self.url = url
+
+    async def __call__(self, endpoint: str, arguments: dict[str, Any]) -> Any:
+        try:
+            from mcp import Client
+        except ImportError as exc:
+            raise SchemaSourceError(
+                'MCP execution requires: pip install "schemarouter[mcp]"'
+            ) from exc
+
+        async with Client(self.url) as client:
+            result = await client.call_tool(endpoint, arguments)
+            if getattr(result, "is_error", False):
+                raise RuntimeError(f"MCP tool {endpoint!r} returned an error")
+
+            structured = getattr(result, "structured_content", None)
+            if structured is not None:
+                return structured
+
+            content = getattr(result, "content", None)
+            if content is None:
+                return None
+            return [
+                block.model_dump(mode="json", by_alias=True, exclude_none=True)
+                if hasattr(block, "model_dump")
+                else str(block)
+                for block in content
+            ]