signalwire-sdk 3.2.0.dev99__tar.gz → 3.3.0.dev103__tar.gz

{signalwire_sdk-3.2.0.dev99 → signalwire_sdk-3.3.0.dev103}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.2.0.dev99
+Version: 3.3.0.dev103
 Summary: SignalWire SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT
@@ -298,6 +298,7 @@ Guides are also available in the [`docs/`](docs/) directory:
 - [DataMap Guide](docs/datamap_guide.md) -- serverless API tools without webhooks
 - [LLM Parameters](docs/llm_parameters.md) -- temperature, top_p, barge confidence tuning
 - [SWML Service Guide](docs/swml_service_guide.md) -- low-level construction of SWML documents
+- [AI Chat Gateway](docs/ai_chat_gateway.md) -- browser chat widgets without a token in the page
 
 ### Skills and Extensions
 

{signalwire_sdk-3.2.0.dev99 → signalwire_sdk-3.3.0.dev103}/README.md

@@ -200,6 +200,7 @@ Guides are also available in the [`docs/`](docs/) directory:
 - [DataMap Guide](docs/datamap_guide.md) -- serverless API tools without webhooks
 - [LLM Parameters](docs/llm_parameters.md) -- temperature, top_p, barge confidence tuning
 - [SWML Service Guide](docs/swml_service_guide.md) -- low-level construction of SWML documents
+- [AI Chat Gateway](docs/ai_chat_gateway.md) -- browser chat widgets without a token in the page
 
 ### Skills and Extensions
 

{signalwire_sdk-3.2.0.dev99 → signalwire_sdk-3.3.0.dev103}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.2.0.dev99"
+version = "3.3.0.dev103"
 description = "SignalWire SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}

{signalwire_sdk-3.2.0.dev99 → signalwire_sdk-3.3.0.dev103}/signalwire/signalwire/__init__.py

@@ -52,7 +52,7 @@ if TYPE_CHECKING:
     from signalwire.utils.schema_utils import SchemaValidationError
     from signalwire.web import WebService
 
-__version__ = "3.2.0.dev99"
+__version__ = "3.3.0.dev103"
 
 # §6.2-python (owner decision: NO packaging split — one package, all deps required;
 # IMPORT-TIME behavior only): the agent/web symbols are lazy-imported via module

{signalwire_sdk-3.2.0.dev99 → signalwire_sdk-3.3.0.dev103}/signalwire/signalwire/agent_server.py

@@ -68,7 +68,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="3.2.0.dev99",
+            version="3.3.0.dev103",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,

{signalwire_sdk-3.2.0.dev99 → signalwire_sdk-3.3.0.dev103}/signalwire/signalwire/ai_chat/__init__.py

@@ -10,6 +10,7 @@ Async client for the SignalWire AI Chat service — see
 :mod:`signalwire.ai_chat.client` for the full protocol notes.
 """
 
+from .gateway import ChatGateway, GatewayRejection
 from .client import (
     AIChatClient,
     AIChatError,
@@ -27,11 +28,13 @@ __all__ = [
     "AIChatClient",
     "AIChatError",
     "AuthenticationError",
+    "ChatGateway",
     "ChatInProgressError",
     "ChatLog",
     "ChatResponse",
     "ConversationInfo",
     "ConversationNotFoundError",
+    "GatewayRejection",
     "RateLimitError",
     "SummaryError",
 ]

{signalwire_sdk-3.2.0.dev99 → signalwire_sdk-3.3.0.dev103}/signalwire/signalwire/ai_chat/client.py

@@ -38,6 +38,8 @@ Credentials come from the constructor or the standard environment variables
 """
 
 import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
 from typing import Any
 
@@ -64,6 +66,14 @@ class AIChatError(Exception):
     """Base error for AI Chat service failures."""
 
     def __init__(self, code: int | None, message: str) -> None:
+        """Carry the service's own failure code alongside its message.
+
+        Args:
+            code: JSON-RPC error code from the service (e.g. -32001 unknown
+                conversation, -32009 rejected identity), or None when the
+                failure happened below the JSON-RPC layer (transport, bad HTTP).
+            message: Human-readable description from the service.
+        """
         self.code = code
         self.message = message
         super().__init__(f"[{code}] {message}")
@@ -107,6 +117,16 @@ _ERROR_BY_CODE = {
 
 @dataclass
 class ConversationInfo:
+    """A conversation as the service reports it after create/end.
+
+    Attributes:
+        id: Service-assigned conversation id. This, not anything the caller
+            supplies, is what later turns must reference.
+        status: Lifecycle state reported by the service (e.g. "created",
+            "ended").
+        initial_message: Opening line when the agent speaks first, else None.
+    """
+
     id: str
     status: str
     initial_message: str | None = None
@@ -114,6 +134,17 @@ class ConversationInfo:
 
 @dataclass
 class ChatResponse:
+    """One assistant turn.
+
+    Attributes:
+        text: What the assistant said — the only field a simple client needs.
+        conversation_id: Conversation this turn belongs to, for the next turn.
+        user_event: Structured payload the agent emitted alongside the text
+            (a SWML user_event), or None. This is how an agent asks the client
+            to do something — render a form, show a keypad — rather than only
+            speak.
+    """
+
     text: str
     conversation_id: str
     user_event: dict[str, Any] | None = None
@@ -121,6 +152,16 @@ class ChatResponse:
 
 @dataclass
 class ChatLog:
+    """A conversation transcript as the service stores it.
+
+    Attributes:
+        messages: Every turn, INCLUDING the substituted system prompt and tool
+            traffic. Do not relay this to a browser verbatim — see
+            `ChatGateway.visible_messages`, which reduces it to the dialogue.
+        call_timeline: Timed events for the conversation, when the service
+            reports them.
+    """
+
     messages: list[dict[str, Any]] = field(default_factory=list)
     call_timeline: list[dict[str, Any]] = field(default_factory=list)
 
@@ -139,6 +180,23 @@ class AIChatClient:
         url: str | None = None,
         session: aiohttp.ClientSession | None = None,
     ) -> None:
+        """Build a client for the AI Chat service.
+
+        Each argument falls back to its environment variable, so a configured
+        environment needs no arguments at all.
+
+        Args:
+            project: Project id. Falls back to `SIGNALWIRE_PROJECT_ID`.
+            token: API token. Falls back to `SIGNALWIRE_API_TOKEN`.
+            space: Space name used to build the default URL. Falls back to
+                `SIGNALWIRE_SPACE`.
+            url: Full service URL, overriding the one derived from `space`.
+            session: An existing aiohttp session to reuse. Omit and the client
+                creates (and owns, and closes) its own.
+
+        Raises:
+            ValueError: If no project id is available from either source.
+        """
         self._project = project or os.environ.get("SIGNALWIRE_PROJECT_ID", "")
         self._token = token or os.environ.get("SIGNALWIRE_API_TOKEN", "")
         space = space or os.environ.get("SIGNALWIRE_SPACE", "")
@@ -199,6 +257,11 @@ class AIChatClient:
         return self._session
 
     async def close(self) -> None:
+        """Close the HTTP session, if this client owns it.
+
+        A session passed in via `session=` belongs to the caller and is left
+        open; only one the client created for itself is closed here.
+        """
         if self._owns_session and self._session is not None:
             await self._session.close()
             self._session = None
@@ -237,6 +300,34 @@ class AIChatClient:
         result = body.get("result")
         return result if isinstance(result, dict) else {}
 
+    @asynccontextmanager
+    async def raw_post(
+        self, method: str, params: dict[str, Any]
+    ) -> AsyncIterator[aiohttp.ClientResponse]:
+        """Yield the response for one JSON-RPC call with its body unread.
+
+        For proxies that must stream the body through rather than buffer it.
+        The service pads a slow response with keepalive whitespace so
+        intermediaries do not sever the connection mid-turn; a proxy that
+        awaits the whole body absorbs that padding and reintroduces the very
+        timeout it exists to prevent. Iterate ``resp.content`` and forward the
+        chunks as they arrive.
+
+        The caller owns interpreting the result — including that a JSON-RPC
+        error arrives under HTTP 200 (see ``_request``). Prefer the typed
+        methods unless you are genuinely relaying bytes.
+        """
+        session = await self._ensure_session()
+        self._request_counter += 1
+        payload = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params,
+            "id": f"req-{self._request_counter}",
+        }
+        async with session.post(self.url, json=payload) as resp:
+            yield resp
+
     # ── API methods ──────────────────────────────────────────────────
 
     async def create_conversation(