scxp 0.1.0__tar.gz

scxp-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

scxp-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: scxp
+Version: 0.1.0
+Summary: Symmetric Context Exchange Protocol (SCXP) SDK for Python: consumer + provider surface, handshake, id correlation/dispatch, and Gen A tool-schema generation. Transport-agnostic.
+Author: SCXP contributors
+License-Expression: MIT
+Keywords: agents,handshake,llm,protocol,scxp,tools
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scxp
+
+Python SDK for the **Symmetric Context Exchange Protocol (SCXP)** — a protocol for
+exchanging tool catalogs and tool calls between a *consumer* (which discovers and
+invokes tools) and a *provider* (which registers and serves them).
+
+The SDK is **transport-agnostic**: you bring the transport (WebSocket, TCP, stdio,
+...) by implementing a small `Channel`, and the SDK handles the protocol —
+handshake, id correlation, batching, and tool-schema generation.
+
+## Install
+
+```bash
+pip install scxp
+```
+
+Requires Python 3.11+.
+
+## Provider — expose tools
+
+```python
+from scxp import Provider, ProviderCatalog, tool, Info
+
+class Tools:
+    @tool(name="add", domain="com.example.math", description="Add two integers.")
+    def add(self, a: int, b: int) -> int:
+        return a + b
+
+catalog = ProviderCatalog.from_object(Tools(), Info(name="my-provider", version="1.0.0"))
+
+# `channel` is your Channel implementation, already connected.
+provider = await Provider.create(channel, catalog)
+# The provider now serves tools/list and tools/call.
+```
+
+## Consumer — discover and invoke tools
+
+```python
+from scxp import Consumer, ConsumerConfig, Info
+
+# `channel` is your Channel implementation, already connected.
+consumer = await Consumer.create(
+    channel, ConsumerConfig(info=Info(name="my-app", version="1.0.0"))
+)
+
+manifest = await consumer.list_tools()          # discover
+result = await consumer.call_tool("add", {"a": 2, "b": 3})   # invoke
+print(result.content[0].text)  # "5"
+```
+
+## Bring your own transport
+
+Implement `Channel` (send bytes, receive bytes, observe close). A runnable
+WebSocket example lives under `examples/`.
+
+```python
+from scxp import Channel  # a typing.Protocol with: send / on_message / on_close
+```
+
+## Docs
+
+- Consumer and provider integration guides: `docs/`
+- Protocol spec and JSON Schemas: the SCXP repository
+
+## License
+
+MIT.

scxp-0.1.0/README.md

@@ -0,0 +1,67 @@
+# scxp
+
+Python SDK for the **Symmetric Context Exchange Protocol (SCXP)** — a protocol for
+exchanging tool catalogs and tool calls between a *consumer* (which discovers and
+invokes tools) and a *provider* (which registers and serves them).
+
+The SDK is **transport-agnostic**: you bring the transport (WebSocket, TCP, stdio,
+...) by implementing a small `Channel`, and the SDK handles the protocol —
+handshake, id correlation, batching, and tool-schema generation.
+
+## Install
+
+```bash
+pip install scxp
+```
+
+Requires Python 3.11+.
+
+## Provider — expose tools
+
+```python
+from scxp import Provider, ProviderCatalog, tool, Info
+
+class Tools:
+    @tool(name="add", domain="com.example.math", description="Add two integers.")
+    def add(self, a: int, b: int) -> int:
+        return a + b
+
+catalog = ProviderCatalog.from_object(Tools(), Info(name="my-provider", version="1.0.0"))
+
+# `channel` is your Channel implementation, already connected.
+provider = await Provider.create(channel, catalog)
+# The provider now serves tools/list and tools/call.
+```
+
+## Consumer — discover and invoke tools
+
+```python
+from scxp import Consumer, ConsumerConfig, Info
+
+# `channel` is your Channel implementation, already connected.
+consumer = await Consumer.create(
+    channel, ConsumerConfig(info=Info(name="my-app", version="1.0.0"))
+)
+
+manifest = await consumer.list_tools()          # discover
+result = await consumer.call_tool("add", {"a": 2, "b": 3})   # invoke
+print(result.content[0].text)  # "5"
+```
+
+## Bring your own transport
+
+Implement `Channel` (send bytes, receive bytes, observe close). A runnable
+WebSocket example lives under `examples/`.
+
+```python
+from scxp import Channel  # a typing.Protocol with: send / on_message / on_close
+```
+
+## Docs
+
+- Consumer and provider integration guides: `docs/`
+- Protocol spec and JSON Schemas: the SCXP repository
+
+## License
+
+MIT.

scxp-0.1.0/docs/consumer-guide.md

@@ -0,0 +1,174 @@
+# Consumer Guide (Python)
+
+> Audience: a developer who wants to **consume tools** exposed by an SCXP provider.
+
+---
+
+## What is a Consumer?
+
+A Consumer discovers and invokes tools. It connects to a Provider over any
+transport wrapped in a `Channel`, runs the handshake automatically, and then
+exposes two operations: `list_tools()` (`tools/list`) and `call_tools()` /
+`call_tool()` (`tools/call`).
+
+You don't build envelopes, correlate ids, or negotiate versions — the SDK does.
+
+---
+
+## Step 1: Implement a `Channel`
+
+`Channel` is a `typing.Protocol` with three members (structural — no inheritance
+required):
+
+```python
+class Channel(Protocol):
+    async def send(self, message: bytes) -> None: ...
+    def on_message(self, handler: Callable[[bytes], Awaitable[None]]) -> None: ...
+    def on_close(self, handler: Callable[[Exception | None], None]) -> None: ...
+```
+
+Each message is one complete Envelope (JSON bytes). If your transport is
+message-framed (WebSocket), one frame = one Envelope. A ready-to-use WebSocket
+implementation lives in `examples/websocket_channel.py`.
+
+The SDK never opens connections — you bring the `Channel` already connected.
+
+---
+
+## Step 2: Create the Consumer
+
+```python
+from scxp import Consumer, ConsumerConfig, Info
+
+# `channel` is your Channel implementation, already connected.
+consumer = await Consumer.create(
+    channel,
+    ConsumerConfig(info=Info(name="my-app", version="1.0.0")),
+)
+
+print(consumer.session.protocol_version)      # agreed version
+print(consumer.session.remote_info.name)      # the provider's name
+```
+
+### `ConsumerConfig`
+
+| Field | Required | Description |
+|---|---|---|
+| `info` | Yes | Your software identity (`name` must be non-empty). |
+| `capabilities` | No | Capabilities you support. Defaults to `Capabilities()`. |
+
+You never set `role` or `protocol_versions` — they are SDK facts, injected
+automatically (`role` is implied by creating a *consumer*).
+
+---
+
+## Step 3: Discover tools
+
+```python
+manifest = await consumer.list_tools()   # ListToolsResult
+
+for domain in manifest.domains:
+    for tool in domain.tools:
+        print(domain.role, tool.name, tool.description)
+        # tool.input_schema is the JSON Schema (a dict) of the arguments.
+```
+
+---
+
+## Step 4: Invoke tools
+
+### Single call
+
+```python
+result = await consumer.call_tool("search_items", {"query": "example", "limit": 5})
+
+if result.is_error:
+    print("tool failed:", result.content[0].text)
+else:
+    print(result.content[0].text)          # inline text
+    if result.structured_content is not None:
+        print(result.structured_content)   # typed data, when present
+```
+
+### Batch (multiple calls)
+
+```python
+from scxp import Call
+
+calls = [
+    Call(tool_call_id="c1", name="get_item", arguments={"id": "42"}),
+    Call(tool_call_id="c2", name="get_item", arguments={"id": "99"}),
+]
+batch = await consumer.call_tools(calls)
+
+for r in batch.results:
+    print(r.tool_call_id, r.is_error, r.content[0].text)
+```
+
+Key rules:
+- `tool_call_id` correlates each result to its call (order is NOT guaranteed).
+- `tool_call_id` must be unique within the batch (your responsibility).
+- One tool failing (`is_error = True`) does NOT break the others.
+
+---
+
+## Step 5: React to hot-swap
+
+The provider can change its catalog at runtime. Subscribe with a callable:
+
+```python
+def refresh():
+    print("catalog changed; re-fetching")
+    # schedule a task to call consumer.list_tools() again
+
+consumer.on_tools_list_changed = refresh
+```
+
+This fires only if the provider declared the `tools.listChanged` capability
+(check `consumer.session.remote_capabilities.tools.list_changed`).
+
+---
+
+## Errors
+
+| Exception | When | Notes |
+|---|---|---|
+| `HandshakeError` | During `create` | Peer rejected the handshake. `.code` ∈ {-32001 version, -32002 role}. |
+| `ScxpProtocolError` | During `list_tools` / `call_tools` | Layer-1 failure (whole request). `.code` ∈ {-32601 unknown method, -32602 invalid params, -32603 internal}. |
+| `ConnectionClosedError` | Channel closed with requests in flight | In-flight requests fault. |
+| `asyncio.TimeoutError` | `send_request(..., timeout=...)` elapsed | Only when you pass a timeout (Connection level). |
+
+Tool-level failures are NOT exceptions: they arrive as `is_error=True` in the
+individual `ToolResult`, and the rest of the batch is fine.
+
+---
+
+## HandshakeMode: who greets?
+
+By default the consumer greets (`HandshakeMode.INITIATE`). If the provider opened
+the channel and greets first (multi-pod case), the consumer waits:
+
+```python
+from scxp import HandshakeMode
+
+consumer = await Consumer.create(channel, config, mode=HandshakeMode.AWAIT)
+```
+
+Both modes produce the same Consumer with the same API.
+
+---
+
+## End-to-end minimal example
+
+```python
+from scxp import Consumer, ConsumerConfig, Info
+
+consumer = await Consumer.create(
+    channel, ConsumerConfig(info=Info(name="my-app", version="1.0.0"))
+)
+await consumer.list_tools()
+result = await consumer.call_tool("add", {"a": 2, "b": 3})
+print(result.content[0].text)  # "5"
+```
+
+For a runnable example with real WebSocket transport, see `examples/`.

scxp-0.1.0/docs/provider-guide.md

@@ -0,0 +1,224 @@
+# Provider Guide (Python)
+
+> Audience: a developer who wants to **expose tools** to an SCXP consumer.
+
+---
+
+## What is a Provider?
+
+A Provider registers and serves tools. It connects to a Consumer over a `Channel`,
+runs the handshake automatically, and then answers `tools/list` (catalog) and
+`tools/call` (invocation) from the registered catalog.
+
+You define tools as decorated methods; the SDK generates the JSON Schema, batches,
+isolates failures, and handles the protocol.
+
+---
+
+## Step 1: Define your tools
+
+Decorate methods with `@tool`. Every tool belongs to a `domain`:
+
+```python
+from scxp import tool
+
+class InventoryTools:
+    @tool(
+        name="search_items",
+        domain="com.example.inventory",
+        description="Search items by name.",
+        when_to_use="When the caller needs to find items by keyword.",
+    )
+    def search_items(self, query: str, limit: int = 10) -> list[str]:
+        return ["item-1", "item-2"]
+
+    @tool(
+        name="create_order",
+        domain="com.example.orders",
+        description="Create an order.",
+        requires_approval=True,
+        destructive=True,
+        timeout_ms=10000,
+    )
+    def create_order(self, item_id: str, quantity: int) -> bool:
+        return True
+```
+
+### `@tool` parameters (closed list)
+
+`name`, `domain`, `description`, `when_to_use`, `when_not_to_use`,
+`requires_approval`, `idempotent`, `destructive`, `timeout_ms`, `meta`.
+
+The decorator is keyword-only: an unknown keyword (e.g. a `requires_aproval`
+typo) raises `TypeError` at decoration time.
+
+### Argument schema (Gen A)
+
+The `input_schema` is generated from the method signature:
+
+| Python annotation | JSON Schema |
+|---|---|
+| `str` / `int` / `float` / `bool` | scalar type |
+| `list[str]` (leaf items) | `array` |
+| `dict` | free `object` |
+| `X | None` / `Optional[X]` | nullable scalar |
+| `Literal["a", "b"]` | string `enum` |
+| `Annotated[T, Field(description=...)]` | adds a per-parameter `description` |
+
+Parameters with a default are optional; the rest are required. Nested objects,
+arrays of objects/arrays, and non-string enums raise `ToolSchemaGenerationError`.
+
+### Return values
+
+| Return | Consumer sees |
+|---|---|
+| `str` | `content: [text]` |
+| `dict` or a pydantic model | `structured_content` + `content: [text]` |
+| scalar / list | `content: [text]` |
+| a `ToolResult` | passthrough (full control; no size guardrail) |
+| `None` | `content: [text ""]` |
+| a coroutine (`async def`) | awaited, then mapped as above |
+
+---
+
+## Step 2: Register the catalog
+
+```python
+from scxp import ProviderCatalog, Info
+
+catalog = ProviderCatalog.from_object(
+    InventoryTools(), Info(name="my-provider", version="1.0.0")
+)
+```
+
+Validations run at REGISTRATION (they raise, not at runtime):
+
+| Rule | Raises |
+|---|---|
+| Two tools with the same name in the same domain | `ValueError` |
+| A tool without a domain | `ValueError` |
+| `_meta` key without a DNS-reverse prefix / reserved second label | `ToolSchemaGenerationError` |
+
+`info.name` non-empty is enforced by the `Info` model itself.
+
+Use `from_type(cls, info)` if you only need the manifest (static tools);
+`from_object(instance, info)` when tools must be invoked.
+
+---
+
+## Step 3: Create the Provider
+
+```python
+from scxp import Provider, Capabilities, ToolsCapability
+
+capabilities = Capabilities(tools=ToolsCapability(list_changed=True))
+
+# `channel` is your Channel implementation, already connected.
+provider = await Provider.create(channel, catalog, capabilities=capabilities)
+```
+
+`info` flows from `catalog.info` — you don't pass it again. After `create`
+resolves, the provider is serving `tools/list` and `tools/call`.
+
+---
+
+## Step 4: Hot-swap (optional)
+
+```python
+# Requires the tools.listChanged capability declared above.
+await provider.notify_tools_list_changed()
+```
+
+If you did NOT declare the capability, this raises `RuntimeError`.
+
+---
+
+## Large payloads: the inline-size policy
+
+The SDK checks an auto-serialized result's size in three tiers (doc 05 §3):
+
+- **≤ 325 KB** — travels inline, no flag.
+- **325 KB – 1 MB** — travels inline, but the SDK emits a `warnings.warn` and attaches a
+  `_meta` advisory (`dev.scxp/inline-size-warning`) to the result.
+- **> 1 MB** — the SDK returns an `is_error` result guiding you to use a `resource_link`.
+
+For large data, return a `resource_link` instead of inline text:
+
+```python
+from scxp import ToolResult, ResourceLinkContent, tool
+
+class ReportTools:
+    @tool(name="export", domain="com.example.reports")
+    def export(self, report_id: str) -> ToolResult:
+        url = upload_to_storage(report_id)   # your code
+        return ToolResult(
+            tool_call_id="",  # forced by the SDK
+            content=[ResourceLinkContent(uri=url, mime="text/csv")],
+        )
+```
+
+Returning a `ToolResult` manually skips the guardrail — you own the payload.
+
+---
+
+## `_meta`: tool metadata
+
+```python
+@tool(
+    name="search_items",
+    domain="com.example.inventory",
+    meta={"com.example.analytics/category": "lookup"},
+)
+def search_items(self, query: str) -> list[str]: ...
+```
+
+Keys must use a DNS-reverse prefix (e.g. `com.example.x/key`); a bare key or a
+reserved second label (`mcp` / `modelcontextprotocol`) fails at registration.
+
+---
+
+## Errors the SDK handles for you
+
+| Situation | Response to consumer | Your tools called? |
+|---|---|---|
+| Malformed `tools/call` | `INVALID_PARAMS` (-32602) | No |
+| Unknown method | `UNKNOWN_METHOD` (-32601) | No |
+| Duplicate in-flight request id | `DUPLICATE_ID` (-32004) | No |
+| Handler raises an unexpected error | `INTERNAL_ERROR` (-32603) | — |
+| Unknown / ambiguous tool name | `is_error` sub-result | Others: yes |
+| Missing required argument | `is_error` sub-result | Others: yes |
+| Tool raises | `is_error` sub-result | Others: yes |
+
+One tool failing never breaks the batch (doc 05 §8.3).
+
+---
+
+## HandshakeMode: who greets?
+
+By default the provider awaits (`HandshakeMode.AWAIT`). To open toward the
+consumer and greet first:
+
+```python
+from scxp import HandshakeMode
+
+provider = await Provider.create(channel, catalog, mode=HandshakeMode.INITIATE)
+```
+
+---
+
+## End-to-end minimal example
+
+```python
+from scxp import Provider, ProviderCatalog, tool, Info
+
+class Tools:
+    @tool(name="add", domain="com.example.math", description="Add two integers.")
+    def add(self, a: int, b: int) -> int:
+        return a + b
+
+catalog = ProviderCatalog.from_object(Tools(), Info(name="my-provider", version="1.0.0"))
+provider = await Provider.create(channel, catalog)
+# Serving tools/list and tools/call. Keep the connection alive.
+```
+
+For a runnable example with real WebSocket transport, see `examples/`.

scxp-0.1.0/examples/websocket_channel.py

@@ -0,0 +1,52 @@
+"""A Channel implementation over a real WebSocket (the ``websockets`` library).
+
+Shows the SDK is transport-agnostic (doc 04 §2, doc 06 §3): all the protocol
+lives in the SDK; the transport only moves bytes. ``websockets`` is a dependency
+of THIS example only — the SDK itself references nothing but ``Channel``.
+
+Each WebSocket message = one Envelope (JSON bytes). Delivery is via a receive
+loop (real async), unlike the reentrant in-memory channel used in tests.
+
+Run the demo (needs ``pip install websockets``):
+
+    python examples/websocket_example.py
+"""
+
+from __future__ import annotations
+
+from typing import Awaitable, Callable, Optional
+
+
+class WebSocketChannel:
+    """Wraps a ``websockets`` connection (client or server side) as an SCXP Channel."""
+
+    def __init__(self, ws) -> None:
+        self._ws = ws
+        self._on_message: Optional[Callable[[bytes], Awaitable[None]]] = None
+        self._on_close: Optional[Callable[[Optional[Exception]], None]] = None
+
+    async def send(self, message: bytes) -> None:
+        await self._ws.send(message)
+
+    def on_message(self, handler: Callable[[bytes], Awaitable[None]]) -> None:
+        self._on_message = handler
+
+    def on_close(self, handler: Callable[[Optional[Exception]], None]) -> None:
+        self._on_close = handler
+
+    async def run_receive_loop(self) -> None:
+        """Pump each incoming WebSocket message (one Envelope) to the SDK handler.
+
+        Call once, concurrently, after registering handlers and before/while the
+        SDK uses the channel. Ends when the socket closes.
+        """
+        try:
+            async for message in self._ws:
+                data = message if isinstance(message, bytes) else message.encode("utf-8")
+                if self._on_message is not None:
+                    await self._on_message(data)
+            if self._on_close is not None:
+                self._on_close(None)
+        except Exception as exc:  # noqa: BLE001 — surface any transport error as a close cause.
+            if self._on_close is not None:
+                self._on_close(exc)

scxp-0.1.0/examples/websocket_example.py

@@ -0,0 +1,86 @@
+"""End-to-end SCXP over a real WebSocket (the ``websockets`` library).
+
+A single process: a server hosting a Provider and a client running a Consumer.
+Exercises the SDK over a real async transport (not the reentrant in-memory
+channel of the tests). Domain is 100% generic (com.example.*).
+
+Run (needs ``pip install websockets`` and an editable install of scxp):
+
+    python examples/websocket_example.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import websockets
+from websocket_channel import WebSocketChannel
+
+from scxp import Consumer, ConsumerConfig, Info, Provider, ProviderCatalog, tool
+
+HOST = "localhost"
+PORT = 8765
+URI = f"ws://{HOST}:{PORT}"
+
+
+# --- Provider tools (agnostic) ----------------------------------------------
+
+class Tools:
+    @tool(name="add", domain="com.example.math", description="Add two integers.")
+    def add(self, a: int, b: int) -> int:
+        return a + b
+
+    @tool(name="echo", domain="com.example.text", description="Return the message as-is.")
+    def echo(self, message: str) -> str:
+        return message
+
+
+# --- Server side (Provider) --------------------------------------------------
+
+async def serve_provider(ws) -> None:
+    channel = WebSocketChannel(ws)
+    receive = asyncio.create_task(channel.run_receive_loop())
+
+    catalog = ProviderCatalog.from_object(Tools(), Info(name="example-provider", version="1.0.0"))
+    provider = await Provider.create(channel, catalog)
+    print(f"[server] handshake ok, peer={provider.session.remote_info.name}")
+
+    await receive  # serve until the socket closes
+
+
+# --- Client side (Consumer) --------------------------------------------------
+
+async def run_client() -> None:
+    async with websockets.connect(URI) as ws:
+        channel = WebSocketChannel(ws)
+        receive = asyncio.create_task(channel.run_receive_loop())
+
+        consumer = await Consumer.create(
+            channel, ConsumerConfig(info=Info(name="example-consumer", version="1.0.0"))
+        )
+        print(f"[client] handshake ok, peer={consumer.session.remote_info.name}")
+
+        manifest = await consumer.list_tools()
+        print(f"[client] tools/list -> {len(manifest.domains)} domain(s):")
+        for domain in manifest.domains:
+            for t in domain.tools:
+                print(f"           - {domain.role}/{t.name}: {t.description}")
+
+        add = await consumer.call_tool("add", {"a": 3, "b": 5})
+        print(f"[client] add(3,5) -> {add.content[0].text}")
+
+        echo = await consumer.call_tool("echo", {"message": "hello SCXP"})
+        print(f"[client] echo -> {echo.content[0].text}")
+
+        receive.cancel()
+
+
+async def main() -> None:
+    async with websockets.serve(serve_provider, HOST, PORT):
+        print(f"[server] listening on {URI}")
+        await run_client()
+    print("[done] example finished")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())