scxp 0.1.0__py3-none-any.whl

scxp/__init__.py

@@ -0,0 +1,92 @@
+"""SCXP SDK for Python — Symmetric Context Exchange Protocol.
+
+Public surface for both sides of the protocol:
+
+    from scxp import Consumer, ConsumerConfig, Provider, ProviderCatalog, tool, Info
+
+The transport is yours: implement ``Channel`` (WebSocket, TCP, stdio, ...) and
+pass it to ``Consumer.create`` / ``Provider.create``.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .channel import Channel
+from .connection import Connection
+from .consumer import Consumer, ConsumerConfig
+from .contract_builder import build_tool_contract
+from .errors import (
+    ConnectionClosedError,
+    HandshakeError,
+    ProtocolErrors,
+    ScxpError,
+    ScxpProtocolError,
+)
+from .handshake import HandshakeMode, HandshakeResult
+from .protocol_version import CURRENT, SUPPORTED
+from .provider import Provider
+from .provider_catalog import ProviderCatalog
+from .tool import ToolMetadata, tool
+from .tool_schema import ToolSchemaGenerationError, generate_input_schema
+from .wire import (
+    Call,
+    CallToolParams,
+    CallToolResult,
+    Capabilities,
+    ContentBlock,
+    Domain,
+    Execution,
+    Info,
+    ListToolsResult,
+    ResourceLinkContent,
+    Role,
+    TextContent,
+    Tool,
+    ToolResult,
+    ToolsCapability,
+)
+
+__all__ = [
+    "__version__",
+    # surface
+    "Consumer",
+    "ConsumerConfig",
+    "Provider",
+    "ProviderCatalog",
+    "Channel",
+    "Connection",
+    "HandshakeMode",
+    "HandshakeResult",
+    # tools
+    "tool",
+    "ToolMetadata",
+    "build_tool_contract",
+    "generate_input_schema",
+    "ToolSchemaGenerationError",
+    # errors
+    "ScxpError",
+    "ScxpProtocolError",
+    "HandshakeError",
+    "ConnectionClosedError",
+    "ProtocolErrors",
+    # protocol version
+    "CURRENT",
+    "SUPPORTED",
+    # wire types
+    "Info",
+    "Capabilities",
+    "ToolsCapability",
+    "Role",
+    "Call",
+    "CallToolParams",
+    "CallToolResult",
+    "ToolResult",
+    "ListToolsResult",
+    "Domain",
+    "Tool",
+    "Execution",
+    "TextContent",
+    "ResourceLinkContent",
+    "ContentBlock",
+]

scxp/channel.py

@@ -0,0 +1,41 @@
+"""The transport seam between the user's transport and the protocol (doc 04 §2).
+
+The SDK does NOT open connections: it receives an already-open ``Channel``. A
+channel exposes exactly three capabilities: write bytes, subscribe to incoming
+bytes, and learn when the channel dies.
+
+The SDK depends on nothing but ``Channel``: it does not reference WebSocket, HTTP
+or stdio (transport-agnostic). Wrapping a WebSocket, stdin/stdout, a raw TCP
+socket, or a mock in an implementation of this Protocol runs the same SDK over
+any transport.
+
+Messages are the bytes of a serialized Envelope (JSON UTF-8). The SDK encodes and
+decodes internally; the interface only carries opaque bytes.
+"""
+
+from __future__ import annotations
+
+from typing import Awaitable, Callable, Optional, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Channel(Protocol):
+    """Transport seam: send bytes, receive bytes, observe close."""
+
+    async def send(self, message: bytes) -> None:
+        """Write one message (the bytes of an Envelope). Called by the SDK."""
+        ...
+
+    def on_message(self, handler: Callable[[bytes], Awaitable[None]]) -> None:
+        """Register the handler the SDK uses to receive incoming messages.
+
+        Each complete message (one Envelope) invokes the handler once.
+        """
+        ...
+
+    def on_close(self, handler: Callable[[Optional[Exception]], None]) -> None:
+        """Register the handler the SDK uses to learn the channel closed.
+
+        The argument is the cause (or None if the close was clean).
+        """
+        ...

scxp/codec.py

@@ -0,0 +1,54 @@
+"""Envelope (de)serialization — the single gate between bytes and typed models.
+
+The Connection sends/receives opaque bytes (one Envelope each); this module
+encodes a typed Envelope to JSON UTF-8 bytes and decodes incoming bytes back to
+the correct typed shape (discriminated by ``kind``).
+
+None policy on encode:
+  - Request / Notification: ``params`` is omitted when None (optional).
+  - Error: ``data`` is omitted when None (optional).
+  - Response: ``result`` is a required key that MAY be null, so it is ALWAYS
+    emitted (never dropped).
+
+Malformed input (bad JSON, unknown/missing ``kind``, schema-invalid) raises
+ValueError / json.JSONDecodeError / pydantic.ValidationError; the protocol layer
+maps those to INVALID_PARAMS.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Type
+
+from .wire import Envelope, Error, Notification, Request, Response
+
+_DECODERS: dict[str, Type] = {
+    "request": Request,
+    "response": Response,
+    "error": Error,
+    "notification": Notification,
+}
+
+
+def encode(envelope: Envelope) -> bytes:
+    """Serialize a typed Envelope to JSON UTF-8 bytes."""
+    if isinstance(envelope, Response):
+        # ``result`` is required and may be null → never drop it.
+        data = envelope.model_dump(mode="json", by_alias=True)
+    else:
+        data = envelope.model_dump(mode="json", by_alias=True, exclude_none=True)
+    return json.dumps(data, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def decode(data: bytes) -> Envelope:
+    """Deserialize JSON UTF-8 bytes to the correct Envelope shape (by ``kind``)."""
+    obj = json.loads(data)
+    if not isinstance(obj, dict):
+        raise ValueError("Envelope must be a JSON object.")
+
+    kind = obj.get("kind")
+    model = _DECODERS.get(kind)
+    if model is None:
+        raise ValueError(f"Unknown or missing envelope kind: {kind!r}")
+
+    return model.model_validate(obj)

scxp/connection.py

@@ -0,0 +1,176 @@
+"""Connection — request/response correlation, dispatch, robustness (doc 04 §3).
+
+Sits on top of a Channel. Outbound: ``send_request`` correlates a Response/Error
+to its Request by ``id`` (via a Future), with optional timeout and clean pending
+removal on cancellation/timeout. ``send_notification`` is fire-and-forget.
+
+Inbound robustness:
+  - a handler raising ScxpProtocolError → an Error with that error,
+  - a handler raising anything else → INTERNAL_ERROR (-32603); the loop survives,
+  - a notification handler raising → swallowed,
+  - a malformed inbound message (can't correlate an id) → dropped,
+  - a Request with an id already in flight → DUPLICATE_ID (-32004).
+
+Shutdown: ``aclose`` / ``async with`` faults pending requests (idempotent). The
+channel itself is owned by the user and is not closed here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from typing import Any, Awaitable, Callable, Optional
+
+from .channel import Channel
+from .codec import decode, encode
+from .errors import ConnectionClosedError, ProtocolErrors, ScxpProtocolError
+from .wire import Error, Notification, Request, Response
+
+RequestHandler = Callable[[str, Any], Awaitable[Any]]
+NotificationHandler = Callable[[str, Any], Awaitable[None]]
+
+
+class Connection:
+    """Correlates requests to replies and dispatches inbound messages."""
+
+    def __init__(self, channel: Channel) -> None:
+        self._channel = channel
+        self._pending: dict[str, asyncio.Future[Any]] = {}
+        self._in_flight: set[str] = set()
+        self._closed = False
+        self.request_handler: Optional[RequestHandler] = None
+        self.notification_handler: Optional[NotificationHandler] = None
+
+        channel.on_message(self._handle_incoming)
+        channel.on_close(self._handle_close)
+
+    # --- Outbound ------------------------------------------------------------
+
+    async def send_request(
+        self, method: str, params: Any = None, timeout: Optional[float] = None
+    ) -> Any:
+        """Send a request and await the correlated result (raises on Error).
+
+        If ``timeout`` elapses the wait is cancelled with ``asyncio.TimeoutError``;
+        cancellation or timeout removes the pending entry so it never leaks.
+        """
+        if self._closed:
+            raise ConnectionClosedError("Connection is closed.")
+
+        request_id = str(uuid.uuid4())
+        future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
+        self._pending[request_id] = future
+
+        try:
+            await self._channel.send(encode(Request(id=request_id, method=method, params=params)))
+        except BaseException:
+            self._pending.pop(request_id, None)
+            raise
+
+        try:
+            if timeout is not None:
+                return await asyncio.wait_for(future, timeout)
+            return await future
+        except BaseException:
+            # Cancellation / timeout / any error: don't leak the pending entry.
+            self._pending.pop(request_id, None)
+            raise
+
+    async def send_notification(self, method: str, params: Any = None) -> None:
+        """Send a one-way notification (no reply)."""
+        if self._closed:
+            raise ConnectionClosedError("Connection is closed.")
+        await self._channel.send(encode(Notification(method=method, params=params)))
+
+    # --- Inbound -------------------------------------------------------------
+
+    async def _handle_incoming(self, data: bytes) -> None:
+        try:
+            envelope = decode(data)
+        except Exception:  # noqa: BLE001
+            # Malformed inbound message: can't correlate an id → drop (keep the loop alive).
+            return
+
+        if isinstance(envelope, Response):
+            future = self._pending.pop(envelope.id, None)
+            if future is not None and not future.done():
+                future.set_result(envelope.result)
+
+        elif isinstance(envelope, Error):
+            future = self._pending.pop(envelope.id, None)
+            if future is not None and not future.done():
+                future.set_exception(ScxpProtocolError(envelope.error))
+
+        elif isinstance(envelope, Request):
+            await self._dispatch_request(envelope)
+
+        elif isinstance(envelope, Notification):
+            handler = self.notification_handler
+            if handler is not None:
+                try:
+                    await handler(envelope.method, envelope.params)
+                except Exception:  # noqa: BLE001
+                    # A notification handler failure must not break the receive loop.
+                    pass
+
+    async def _dispatch_request(self, request: Request) -> None:
+        # Inbound DUPLICATE_ID (-32004): a request whose id is already being processed.
+        if request.id in self._in_flight:
+            await self._send(Error(id=request.id, error=ProtocolErrors.duplicate_id()))
+            return
+
+        self._in_flight.add(request.id)
+        try:
+            handler = self.request_handler
+            if handler is None:
+                await self._send(Error(id=request.id, error=ProtocolErrors.unknown_method()))
+                return
+
+            try:
+                result = await handler(request.method, request.params)
+            except ScxpProtocolError as exc:
+                await self._send(Error(id=request.id, error=exc.error))
+                return
+            except Exception as exc:  # noqa: BLE001
+                # The handler threw an unexpected error → INTERNAL_ERROR; the loop survives.
+                await self._send(Error(id=request.id, error=ProtocolErrors.internal_error(str(exc))))
+                return
+
+            await self._send(Response(id=request.id, result=result))
+        finally:
+            self._in_flight.discard(request.id)
+
+    # --- Close / shutdown ----------------------------------------------------
+
+    def _handle_close(self, cause: Optional[Exception]) -> None:
+        self._closed = True
+        pending = list(self._pending.values())
+        self._pending.clear()
+
+        closed = ConnectionClosedError("The channel was closed.")
+        if cause is not None:
+            closed.__cause__ = cause
+
+        for future in pending:
+            if not future.done():
+                future.set_exception(closed)
+
+    async def aclose(self) -> None:
+        """Shut down: mark closed and fault pending requests (idempotent).
+
+        Does not close the channel — the transport is owned by the user.
+        """
+        if self._closed:
+            return
+        self._handle_close(None)
+
+    async def __aenter__(self) -> "Connection":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
+    # --- Helpers -------------------------------------------------------------
+
+    async def _send(self, envelope: Any) -> None:
+        await self._channel.send(encode(envelope))

scxp/consumer.py

@@ -0,0 +1,138 @@
+"""Consumer surface — ``create_consumer`` (doc 04 §3/§4).
+
+The user doesn't build envelopes or run ``initialize`` by hand: ``Consumer.create``
+runs the handshake and, once the session is negotiated, exposes the two consumer
+operations — ``list_tools`` (tools/list) and ``call_tools`` (tools/call).
+
+Role is implied by the method (creating a consumer ⇒ Role.consumer). The user
+never writes ``role`` or ``protocolVersions`` — the SDK injects them. By default
+the consumer INITIATEs the handshake, but it can AWAIT (a provider opened the
+channel and greets — the multi-pod case).
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+from typing import Any, Callable, Optional, Type, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from .channel import Channel
+from .connection import Connection
+from .errors import ProtocolErrors, ScxpProtocolError
+from .handshake import HandshakeMode, HandshakeResponder, HandshakeResult, initiate
+from .wire import (
+    Call,
+    CallToolParams,
+    CallToolResult,
+    Capabilities,
+    Info,
+    ListToolsResult,
+    Role,
+    ToolResult,
+)
+
+TOOLS_LIST_METHOD = "tools/list"
+TOOLS_CALL_METHOD = "tools/call"
+TOOLS_LIST_CHANGED_METHOD = "notifications/tools/list_changed"
+
+_T = TypeVar("_T", bound=BaseModel)
+
+
+@dataclass
+class ConsumerConfig:
+    """Minimal consumer config (doc 04 §3.1): only genuine user decisions.
+
+    ``role`` / ``protocolVersions`` are not here on purpose — they are SDK facts,
+    injected, so they cannot be written wrong (input defense by construction).
+    """
+
+    info: Info
+    capabilities: Optional[Capabilities] = None
+
+
+class Consumer:
+    """The consumer side: discovers and invokes tools after the handshake."""
+
+    def __init__(self, connection: Connection, session: HandshakeResult) -> None:
+        self._connection = connection
+        self.session = session
+        # No events in Python: a settable callable, invoked on tools/list_changed.
+        self.on_tools_list_changed: Optional[Callable[[], None]] = None
+        self._connection.notification_handler = self._handle_notification
+
+    @classmethod
+    async def create(
+        cls,
+        channel: Channel,
+        config: ConsumerConfig,
+        mode: HandshakeMode = HandshakeMode.INITIATE,
+    ) -> "Consumer":
+        """Create a consumer over an already-open channel and run the handshake."""
+        connection = Connection(channel)
+        caps = config.capabilities or Capabilities()
+
+        if mode is HandshakeMode.INITIATE:
+            session = await initiate(connection, Role.consumer, caps, config.info)
+        else:
+            responder = HandshakeResponder(Role.consumer, caps, config.info)
+            connection.request_handler = responder.handle_request
+            session = await responder.completed
+
+        return cls(connection, session)
+
+    async def list_tools(self) -> ListToolsResult:
+        """tools/list — fetch the provider's manifest, typed."""
+        raw = await self._connection.send_request(TOOLS_LIST_METHOD)
+        return self._parse(ListToolsResult, raw, TOOLS_LIST_METHOD)
+
+    async def call_tools(self, calls: list[Call]) -> CallToolResult:
+        """tools/call — invoke a batch of tools; sub-results correlate by tool_call_id.
+
+        A ScxpProtocolError here is a layer-1 failure (the whole batch). A single
+        tool failing does NOT raise: it travels in its ToolResult with isError.
+        """
+        params = CallToolParams(calls=calls).model_dump(
+            mode="json", by_alias=True, exclude_none=True
+        )
+        raw = await self._connection.send_request(TOOLS_CALL_METHOD, params)
+        return self._parse(CallToolResult, raw, TOOLS_CALL_METHOD)
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+        tool_call_id: Optional[str] = None,
+        context: Optional[dict[str, Any]] = None,
+    ) -> ToolResult:
+        """Convenience: invoke a single tool (a batch of one, doc 05 §8.1)."""
+        call = Call(
+            tool_call_id=tool_call_id or uuid.uuid4().hex,
+            name=name,
+            arguments=arguments,
+            context=context,
+        )
+        result = await self.call_tools([call])
+        if not result.results:
+            raise ScxpProtocolError(
+                ProtocolErrors.internal_error(
+                    "The provider returned no sub-result for the sent call (empty result)."
+                )
+            )
+        return result.results[0]
+
+    async def _handle_notification(self, method: str, params: Any) -> None:
+        if method == TOOLS_LIST_CHANGED_METHOD and self.on_tools_list_changed is not None:
+            self.on_tools_list_changed()
+
+    @staticmethod
+    def _parse(model: Type[_T], raw: Any, method: str) -> _T:
+        try:
+            return model.model_validate(raw)
+        except ValidationError as exc:
+            raise ScxpProtocolError(
+                ProtocolErrors.internal_error(
+                    f"The result of '{method}' is not a valid {model.__name__}."
+                )
+            ) from exc

scxp/contract_builder.py

@@ -0,0 +1,82 @@
+"""ContractBuilder — assembles the full Tool Contract from a decorated tool (doc 02).
+
+Routes each declared param to its wire channel:
+  - LLM channel: description (or docstring fallback), when_to_use, when_not_to_use.
+  - Schema: input_schema (Gen A).
+  - Orchestrator channel: execution (only the flags that were set).
+  - Domain metadata: _meta (validated key by key).
+
+``domain`` is NOT part of the Contract (it is structural — the catalog uses it).
+Invalid _meta keys raise ``ToolSchemaGenerationError`` (same error as Gen A).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable
+
+from .tool import ToolMetadata, get_tool_metadata
+from .tool_schema import ToolSchemaGenerationError, generate_input_schema
+
+# _meta key: DNS-reverse prefix ending in '/', then a non-space/quote/backslash tail.
+_META_KEY = re.compile("^([a-z0-9-]+\\.)+[a-z0-9-]+/[^\\s\"'\\\\]+$")
+
+# Second labels reserved for the protocol (cases.json reserved_meta_second_labels).
+_RESERVED_SECOND_LABELS = {"mcp", "modelcontextprotocol"}
+
+
+def _validate_meta_key(key: str) -> None:
+    if not _META_KEY.match(key):
+        raise ToolSchemaGenerationError(
+            f"Invalid _meta key {key!r}: must be a DNS-reverse prefix ending in '/…'."
+        )
+    prefix = key.split("/", 1)[0]
+    labels = prefix.split(".")
+    if len(labels) >= 2 and labels[1] in _RESERVED_SECOND_LABELS:
+        raise ToolSchemaGenerationError(
+            f"_meta key {key!r} uses a reserved second label ({labels[1]!r})."
+        )
+
+
+def _execution(metadata: ToolMetadata) -> dict[str, Any]:
+    execution: dict[str, Any] = {}
+    if metadata.requires_approval is not None:
+        execution["requires_approval"] = metadata.requires_approval
+    if metadata.idempotent is not None:
+        execution["idempotent"] = metadata.idempotent
+    if metadata.destructive is not None:
+        execution["destructive"] = metadata.destructive
+    if metadata.timeout_ms is not None:
+        execution["timeout_ms"] = metadata.timeout_ms
+    return execution
+
+
+def build_tool_contract(func: Callable[..., Any]) -> dict[str, Any]:
+    """Build the full Tool Contract dict for a decorated tool."""
+    metadata = get_tool_metadata(func) or ToolMetadata()
+
+    name = metadata.name or func.__name__
+    description = metadata.description
+    if description is None and func.__doc__:
+        description = func.__doc__.strip()
+
+    contract: dict[str, Any] = {"name": name}
+    if description:
+        contract["description"] = description
+    if metadata.when_to_use:
+        contract["when_to_use"] = metadata.when_to_use
+    if metadata.when_not_to_use:
+        contract["when_not_to_use"] = metadata.when_not_to_use
+
+    contract["input_schema"] = generate_input_schema(func)
+
+    execution = _execution(metadata)
+    if execution:
+        contract["execution"] = execution
+
+    if metadata.meta:
+        for key in metadata.meta:
+            _validate_meta_key(key)
+        contract["_meta"] = dict(metadata.meta)
+
+    return contract

scxp/errors.py

@@ -0,0 +1,105 @@
+"""Protocol error codes, error factories, and SDK exceptions (doc 03 §6).
+
+Codes mirror protocol.yaml. ``ProtocolErrors`` builds wire ``ProtocolError``
+payloads; the exception types are what the SDK raises to the caller.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .wire import ProtocolError
+
+# --- Error codes (doc 03 §6 / protocol.yaml) ---------------------------------
+
+VERSION_MISMATCH = -32001
+ROLE_CONFLICT = -32002
+PREMATURE_METHOD = -32003
+DUPLICATE_ID = -32004
+UNKNOWN_METHOD = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+
+# --- Exceptions --------------------------------------------------------------
+
+class ScxpError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class ScxpProtocolError(ScxpError):
+    """Carries a wire ``ProtocolError`` (an incoming Error envelope or a raised one)."""
+
+    def __init__(self, error: ProtocolError) -> None:
+        self.error = error
+        super().__init__(f"[{error.code}] {error.message}")
+
+    @property
+    def code(self) -> int:
+        return self.error.code
+
+    @property
+    def message(self) -> str:
+        return self.error.message
+
+    @property
+    def data(self) -> Optional[Any]:
+        return self.error.data
+
+
+class HandshakeError(ScxpProtocolError):
+    """Raised when the initialize handshake fails (version/role/layer-1 error)."""
+
+
+class ConnectionClosedError(ScxpError):
+    """Raised on in-flight requests when the underlying channel closes."""
+
+
+# --- Factories ---------------------------------------------------------------
+
+class ProtocolErrors:
+    """Builders for the standard wire ``ProtocolError`` payloads."""
+
+    @staticmethod
+    def version_mismatch(
+        message: str = "No common protocol version.", data: Optional[Any] = None
+    ) -> ProtocolError:
+        return ProtocolError(code=VERSION_MISMATCH, message=message, data=data)
+
+    @staticmethod
+    def role_conflict(
+        message: str = "Both sides declared the same role.", data: Optional[Any] = None
+    ) -> ProtocolError:
+        return ProtocolError(code=ROLE_CONFLICT, message=message, data=data)
+
+    @staticmethod
+    def premature_method(
+        message: str = "A method was sent before the handshake completed.",
+        data: Optional[Any] = None,
+    ) -> ProtocolError:
+        return ProtocolError(code=PREMATURE_METHOD, message=message, data=data)
+
+    @staticmethod
+    def duplicate_id(
+        message: str = "A request with this id is already in flight.",
+        data: Optional[Any] = None,
+    ) -> ProtocolError:
+        return ProtocolError(code=DUPLICATE_ID, message=message, data=data)
+
+    @staticmethod
+    def unknown_method(
+        message: str = "Unknown method.", data: Optional[Any] = None
+    ) -> ProtocolError:
+        return ProtocolError(code=UNKNOWN_METHOD, message=message, data=data)
+
+    @staticmethod
+    def invalid_params(
+        message: str = "Invalid params.", data: Optional[Any] = None
+    ) -> ProtocolError:
+        return ProtocolError(code=INVALID_PARAMS, message=message, data=data)
+
+    @staticmethod
+    def internal_error(
+        message: str = "Internal error.", data: Optional[Any] = None
+    ) -> ProtocolError:
+        return ProtocolError(code=INTERNAL_ERROR, message=message, data=data)