schemarouter 0.2.0a1__py3-none-any.whl

schemarouter/registry.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Protocol
+
+from .errors import RegistrationError
+from .models import EndpointSpec, ToolSpec
+
+
+class ToolRegistry(Protocol):
+    """Structural contract for pluggable tool registries.
+
+    Read methods must return detached snapshots (or immutable equivalents) so callers cannot
+    mutate registry state without going through a versioned write operation.
+    """
+
+    @property
+    def version(self) -> int: ...
+
+    def register(self, tool: ToolSpec, *, replace: bool = False) -> str: ...
+
+    def get(self, key: str) -> ToolSpec: ...
+
+    def tools(self) -> tuple[ToolSpec, ...]: ...
+
+    def keys(self) -> tuple[str, ...]: ...
+
+    def endpoint(self, tool_key: str, endpoint_name: str) -> EndpointSpec: ...
+
+
+class InMemoryRegistry:
+    """Versioned, collision-safe in-memory tool catalog with snapshot reads."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolSpec] = {}
+        self._version = 0
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    @staticmethod
+    def _snapshot(tool: ToolSpec) -> ToolSpec:
+        return tool.model_copy(deep=True)
+
+    def register(self, tool: ToolSpec, *, replace: bool = False) -> str:
+        key = tool.key
+        if key in self._tools and not replace:
+            raise RegistrationError(f"tool {key!r} is already registered")
+        self._tools[key] = self._snapshot(tool)
+        self._version += 1
+        return key
+
+    def unregister(self, key: str) -> None:
+        if key not in self._tools:
+            raise KeyError(key)
+        del self._tools[key]
+        self._version += 1
+
+    def get(self, key: str) -> ToolSpec:
+        return self._snapshot(self._tools[key])
+
+    def tools(self) -> tuple[ToolSpec, ...]:
+        return tuple(self._snapshot(tool) for tool in self._tools.values())
+
+    def keys(self) -> tuple[str, ...]:
+        return tuple(self._tools)
+
+    def endpoint(self, tool_key: str, endpoint_name: str) -> EndpointSpec:
+        return self.get(tool_key).endpoint(endpoint_name)
+
+    def update_many(self, tools: Iterable[ToolSpec], *, replace: bool = False) -> None:
+        staged = list(tools)
+        staged_keys = [tool.key for tool in staged]
+        if len(staged_keys) != len(set(staged_keys)):
+            raise RegistrationError("duplicate tool keys in batch")
+        if not replace:
+            collisions = sorted(set(staged_keys) & set(self._tools))
+            if collisions:
+                raise RegistrationError(f"tools already registered: {', '.join(collisions)}")
+        for tool in staged:
+            self._tools[tool.key] = self._snapshot(tool)
+        if staged:
+            self._version += 1

schemarouter/runs.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+from pydantic import Field
+
+from .models import StrictModel
+
+
+class RetryPolicy(StrictModel):
+    """Deterministic retry policy applied at the trusted executor boundary."""
+
+    max_attempts: int = Field(default=1, ge=1, le=10)
+    initial_backoff_seconds: float = Field(default=0.0, ge=0.0, le=60.0)
+    backoff_multiplier: float = Field(default=2.0, ge=1.0, le=10.0)
+    max_backoff_seconds: float = Field(default=30.0, ge=0.0, le=300.0)
+    retry_non_read_only: bool = False
+
+
+class RunConfig(StrictModel):
+    """Per-run metadata and execution controls."""
+
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    max_concurrency: int = Field(default=8, ge=1, le=128)
+    include_payloads: bool = False
+    retry: RetryPolicy = Field(default_factory=RetryPolicy)
+
+
+RunEventName = Literal[
+    "run.start",
+    "plan.end",
+    "tool.start",
+    "tool.end",
+    "tool.error",
+    "run.end",
+    "run.error",
+]
+
+
+class RunEvent(StrictModel):
+    """Typed event envelope emitted by SchemaRouter streaming APIs."""
+
+    event: RunEventName
+    run_id: str
+    sequence: int = Field(ge=0)
+    timestamp: datetime
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    tool: str | None = None
+    endpoint: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        event: RunEventName,
+        run_id: str,
+        sequence: int,
+        config: RunConfig,
+        tool: str | None = None,
+        endpoint: str | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> RunEvent:
+        return cls(
+            event=event,
+            run_id=run_id,
+            sequence=sequence,
+            timestamp=datetime.now(timezone.utc),
+            tags=list(config.tags),
+            metadata=dict(config.metadata),
+            tool=tool,
+            endpoint=endpoint,
+            data=dict(data or {}),
+        )