signalwire-sdk 3.2.0.dev96__tar.gz → 3.2.0.dev99__tar.gz

{signalwire_sdk-3.2.0.dev96/signalwire/signalwire_sdk.egg-info → signalwire_sdk-3.2.0.dev99}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.2.0.dev96
+Version: 3.2.0.dev99
 Summary: SignalWire SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: fastapi>=0.115.12
 Requires-Dist: pydantic>=2.11.4
 Requires-Dist: PyYAML>=6.0.2
@@ -142,6 +143,7 @@ Each agent is a self-contained microservice that generates [SWML](docs/swml_serv
 from signalwire import AgentBase
 from signalwire.core.function_result import FunctionResult
 
+
 class MyAgent(AgentBase):
     def __init__(self):
         super().__init__(name="my-agent", route="/agent")
@@ -153,8 +155,10 @@ class MyAgent(AgentBase):
     def get_time(self):
         """Get the current time"""
         from datetime import datetime
+
         return FunctionResult(f"The time is {datetime.now().strftime('%H:%M:%S')}")
 
+
 if __name__ == "__main__":
     agent = MyAgent()
     agent.run()
@@ -213,7 +217,10 @@ Real-time call control and messaging over WebSocket. The RELAY client connects t
 ```python
 from signalwire.relay import RelayClient
 
-client = RelayClient(project="...", token="...", host="example.signalwire.com", contexts=["default"])
+client = RelayClient(
+    project="...", token="...", host="example.signalwire.com", contexts=["default"]
+)
+
 
 @client.on_call
 async def handle(call):
@@ -222,6 +229,7 @@ async def handle(call):
     await action.wait()
     await call.hangup()
 
+
 client.run()
 ```
 

{signalwire_sdk-3.2.0.dev96 → signalwire_sdk-3.2.0.dev99}/README.md

@@ -45,6 +45,7 @@ Each agent is a self-contained microservice that generates [SWML](docs/swml_serv
 from signalwire import AgentBase
 from signalwire.core.function_result import FunctionResult
 
+
 class MyAgent(AgentBase):
     def __init__(self):
         super().__init__(name="my-agent", route="/agent")
@@ -56,8 +57,10 @@ class MyAgent(AgentBase):
     def get_time(self):
         """Get the current time"""
         from datetime import datetime
+
         return FunctionResult(f"The time is {datetime.now().strftime('%H:%M:%S')}")
 
+
 if __name__ == "__main__":
     agent = MyAgent()
     agent.run()
@@ -116,7 +119,10 @@ Real-time call control and messaging over WebSocket. The RELAY client connects t
 ```python
 from signalwire.relay import RelayClient
 
-client = RelayClient(project="...", token="...", host="example.signalwire.com", contexts=["default"])
+client = RelayClient(
+    project="...", token="...", host="example.signalwire.com", contexts=["default"]
+)
+
 
 @client.on_call
 async def handle(call):
@@ -125,6 +131,7 @@ async def handle(call):
     await action.wait()
     await call.hangup()
 
+
 client.run()
 ```
 

{signalwire_sdk-3.2.0.dev96 → signalwire_sdk-3.2.0.dev99}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.2.0.dev96"
+version = "3.2.0.dev99"
 description = "SignalWire SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}
@@ -24,6 +24,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
+    "aiohttp>=3.9.0",
     "fastapi>=0.115.12",
     "pydantic>=2.11.4",
     "PyYAML>=6.0.2",
@@ -201,6 +202,19 @@ select = ["E4", "E7", "E9", "F", "B", "S", "C4", "PERF", "SIM", "PTH", "RET", "R
 # subscript is a runtime NameError under TYPE_CHECKING). Exempt F401 here; mypy +
 # the SIGNATURES/DRIFT gate prove these imports are real and correct.
 "signalwire/signalwire/rest/namespaces/*.py" = ["F401"]
+# Runnable docs — examples/, rest/examples/, relay/examples/. These are teaching
+# programs, not shipped SDK surface, so a few production-lint rules are demo-idiomatic
+# noise here (and are the ONLY findings that survive after autofix):
+#   E402 — a leading module docstring / "set your creds here" preamble before imports
+#          is the natural example shape (imports-not-at-top).
+#   S104 — binding 0.0.0.0 is how a demo server example says "listen on all interfaces".
+#   S106 — literal "password"/"token" kwargs are obvious placeholder creds in a snippet.
+#   S311 — non-crypto random (sample data / demo ids), never used for security here.
+# Everything else (F401 unused imports, F541 empty f-strings, C4/B/RET/SIM/…) is a real
+# smell and stays enforced so `examples/**` is gate-cleanable to zero.
+"examples/**" = ["E402", "S104", "S106", "S311"]
+"rest/examples/**" = ["E402", "S104", "S106", "S311"]
+"relay/examples/**" = ["E402", "S104", "S106", "S311"]
 
 [tool.ruff.lint.flake8-bugbear]
 # FastAPI's dependency-injection idiom puts Depends()/Query()/etc. in argument

{signalwire_sdk-3.2.0.dev96 → signalwire_sdk-3.2.0.dev99}/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.dev96"
+__version__ = "3.2.0.dev99"
 
 # §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
@@ -81,6 +81,10 @@ _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "BedrockAgent": ("signalwire.agents.bedrock", "BedrockAgent"),
     "SchemaValidationError": ("signalwire.utils.schema_utils", "SchemaValidationError"),
     "WebService": ("signalwire.web", "WebService"),
+    # AI Chat client — lazy so its aiohttp dep loads only on first access (mirrors how
+    # every other public client here is exposed; RestClient's factory form is the odd
+    # one out). Makes `from signalwire import AIChatClient` work like every sibling.
+    "AIChatClient": ("signalwire.ai_chat", "AIChatClient"),
 }
 
 
@@ -195,6 +199,7 @@ def RestClient(*args: Any, **kwargs: Any) -> "_RestClient":
 
 
 __all__ = [
+    "AIChatClient",
     "AgentBase",
     "AgentServer",
     "BedrockAgent",

{signalwire_sdk-3.2.0.dev96 → signalwire_sdk-3.2.0.dev99}/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.dev96",
+            version="3.2.0.dev99",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,

signalwire_sdk-3.2.0.dev99/signalwire/signalwire/agents/__init__.py

@@ -0,0 +1,16 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+
+Specialized agent implementations backed by specific inference providers.
+"""
+
+from signalwire.agents.bedrock import BedrockAgent
+
+__all__ = [
+    "BedrockAgent",
+]

signalwire_sdk-3.2.0.dev99/signalwire/signalwire/ai_chat/__init__.py

@@ -0,0 +1,37 @@
+"""
+Copyright (c) 2026 SignalWire
+
+This file is part of the SignalWire SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+
+Async client for the SignalWire AI Chat service — see
+:mod:`signalwire.ai_chat.client` for the full protocol notes.
+"""
+
+from .client import (
+    AIChatClient,
+    AIChatError,
+    AuthenticationError,
+    ChatInProgressError,
+    ChatLog,
+    ChatResponse,
+    ConversationInfo,
+    ConversationNotFoundError,
+    RateLimitError,
+    SummaryError,
+)
+
+__all__ = [
+    "AIChatClient",
+    "AIChatError",
+    "AuthenticationError",
+    "ChatInProgressError",
+    "ChatLog",
+    "ChatResponse",
+    "ConversationInfo",
+    "ConversationNotFoundError",
+    "RateLimitError",
+    "SummaryError",
+]

signalwire_sdk-3.2.0.dev99/signalwire/signalwire/ai_chat/client.py

@@ -0,0 +1,344 @@
+"""
+Copyright (c) 2026 SignalWire
+
+This file is part of the SignalWire SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+
+Async client for the SignalWire AI Chat service.
+
+The client speaks the standard SignalWire front-door protocol: HTTP Basic
+``project:api_token`` with the space in the hostname —
+``POST https://{space}.signalwire.com/api/ai/chat`` — carrying a JSON-RPC 2.0
+body whose params are pure payload (identity never appears in the body).
+
+Async-first by design: a ``chat()`` call waits on a full LLM round trip
+(seconds, not milliseconds), and the typical consumers — bots, MCP servers —
+run on asyncio event loops where a blocking HTTP call would stall every other
+conversation. Use it as an async context manager::
+
+    from signalwire.ai_chat import AIChatClient
+
+    async with AIChatClient(space="myspace") as client:  # env supplies creds
+        await client.create_conversation("conv-1", config_url=CONFIG_URL)
+        reply = await client.chat("conv-1", "hello")
+        print(reply.text)
+
+URL resolution, in order:
+
+1. ``url=`` constructor argument — used verbatim.
+2. ``RAILS_DEV_MODE`` environment variable — a full URL used verbatim
+   (point it at a dev chat service, e.g. ``http://localhost:8080/``).
+3. ``https://{space}.signalwire.com/api/ai/chat`` built from ``space``
+   (argument or ``SIGNALWIRE_SPACE``).
+
+Credentials come from the constructor or the standard environment variables
+``SIGNALWIRE_PROJECT_ID`` / ``SIGNALWIRE_API_TOKEN``.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+import aiohttp
+
+from signalwire.rest._base import _user_agent
+
+DEFAULT_PATH = "/api/ai/chat"
+
+# The service streams keepalive whitespace ahead of slow responses (every
+# ~10s), so liveness is byte-driven, not wall-clock: no total cap (turn
+# length is the server's business), ``sock_read`` as the dead-connection
+# detector (60s of true byte silence means the request is dead — the proxy
+# itself severs after 30s of upstream silence), and a bounded connect.
+# The leading whitespace is valid JSON, so ``resp.json()`` is unaffected.
+# Pass your own ``session=`` to override.
+DEFAULT_TIMEOUT = aiohttp.ClientTimeout(total=None, connect=10, sock_read=60)
+
+
+# ── Errors ───────────────────────────────────────────────────────────
+
+
+class AIChatError(Exception):
+    """Base error for AI Chat service failures."""
+
+    def __init__(self, code: int | None, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code}] {message}")
+
+
+class AuthenticationError(AIChatError):
+    """Missing/rejected identity (HTTP 401 / JSON-RPC -32009)."""
+
+
+class ConversationNotFoundError(AIChatError):
+    """The conversation does not exist in this project (-32001)."""
+
+
+class RateLimitError(AIChatError):
+    """Project or conversation rate limit hit (-32005 / -32006)."""
+
+
+class ChatInProgressError(AIChatError):
+    """Another message is being processed for this conversation (-32007)."""
+
+
+class SummaryError(AIChatError):
+    """Summary generation failed. ``summarize`` returns EXACTLY ONE of
+    ``{summary}`` (success) or ``{error}`` (generation failed), and the failure
+    rides the JSON-RPC *success* envelope — not an ``error`` object — so it never
+    reaches the ``_ERROR_BY_CODE`` mapping. Surfaced here so a failed summary
+    can't masquerade as an empty string. ``code`` is None (no JSON-RPC code)."""
+
+
+_ERROR_BY_CODE = {
+    -32001: ConversationNotFoundError,
+    -32005: RateLimitError,
+    -32006: RateLimitError,
+    -32007: ChatInProgressError,
+    -32009: AuthenticationError,
+}
+
+
+# ── Response models ──────────────────────────────────────────────────
+
+
+@dataclass
+class ConversationInfo:
+    id: str
+    status: str
+    initial_message: str | None = None
+
+
+@dataclass
+class ChatResponse:
+    text: str
+    conversation_id: str
+    user_event: dict[str, Any] | None = None
+
+
+@dataclass
+class ChatLog:
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    call_timeline: list[dict[str, Any]] = field(default_factory=list)
+
+
+# ── Client ───────────────────────────────────────────────────────────
+
+
+class AIChatClient:
+    """Async client for the SignalWire AI Chat service."""
+
+    def __init__(
+        self,
+        project: str | None = None,
+        token: str | None = None,
+        space: str | None = None,
+        url: str | None = None,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        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", "")
+
+        if not self._project:
+            raise ValueError(
+                "project is required. Provide it as an argument or set the "
+                "SIGNALWIRE_PROJECT_ID environment variable."
+            )
+
+        self.url = self._resolve_url(url, space)
+        self._auth = aiohttp.BasicAuth(self._project, self._token)
+        self._headers = {"User-Agent": _user_agent()}
+        self._session = session
+        self._owns_session = session is None
+        self._request_counter = 0
+
+    @staticmethod
+    def _resolve_url(url: str | None, space: str) -> str:
+        if url:
+            return url
+        dev_url = os.environ.get("RAILS_DEV_MODE", "").strip()
+        if dev_url and dev_url.lower() not in (
+            "false",
+            "0",
+            "no",
+            "off",
+            "true",
+            "1",
+            "yes",
+            "on",
+        ):
+            # RAILS_DEV_MODE doubles as the service's persona switch, so
+            # plain booleans mean "on" without carrying a URL — only a real
+            # URL-looking value overrides the target here.
+            return dev_url
+        if space:
+            return f"https://{space}.signalwire.com{DEFAULT_PATH}"
+        raise ValueError(
+            "No service URL: provide url=, set RAILS_DEV_MODE to a full URL, "
+            "or provide space= / SIGNALWIRE_SPACE."
+        )
+
+    # ── Session lifecycle ────────────────────────────────────────────
+
+    async def __aenter__(self) -> "AIChatClient":
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None:
+            self._session = aiohttp.ClientSession(
+                auth=self._auth, headers=self._headers, timeout=DEFAULT_TIMEOUT
+            )
+        return self._session
+
+    async def close(self) -> None:
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    # ── Wire ─────────────────────────────────────────────────────────
+
+    async def _request(self, method: str, params: dict[str, Any]) -> dict[str, Any]:
+        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:
+            try:
+                body = await resp.json()
+            except (aiohttp.ContentTypeError, ValueError) as err:
+                raise AIChatError(
+                    resp.status, f"non-JSON response (HTTP {resp.status})"
+                ) from err
+        # Success/failure is decided by the JSON-RPC body, NOT the HTTP status:
+        # the service's keepalive heartbeat commits ``200`` before the turn's
+        # outcome is known (heartbeat.py), so a slow error arrives as
+        # ``200 + {"error": …}``. Never gate on ``resp.status`` here.
+        if "error" in body:
+            error = body["error"] or {}
+            code = error.get("code")
+            exc_type = (
+                _ERROR_BY_CODE.get(code, AIChatError)
+                if code is not None
+                else AIChatError
+            )
+            raise exc_type(code, error.get("message", ""))
+        result = body.get("result")
+        return result if isinstance(result, dict) else {}
+
+    # ── API methods ──────────────────────────────────────────────────
+
+    async def create_conversation(
+        self,
+        conversation_id: str,
+        config_url: str,
+        user_message: str | None = None,
+        timeout: int | None = None,
+        user_metadata: dict[str, Any] | None = None,
+        reinit: bool = False,
+    ) -> ConversationInfo:
+        """Create a conversation (or reinitialize an existing one)."""
+        params: dict[str, Any] = {"id": conversation_id, "config_url": config_url}
+        if user_message:
+            params["user_message"] = user_message
+        if timeout:
+            params["conversation_timeout"] = timeout
+        if user_metadata:
+            params["user_meta_data"] = user_metadata
+        if reinit:
+            params["reinit"] = True
+        result = await self._request("create_conversation", params)
+        return ConversationInfo(
+            id=conversation_id,
+            status=result.get("status", "created"),
+            initial_message=result.get("initial_message"),
+        )
+
+    async def chat(
+        self,
+        conversation_id: str,
+        message: str,
+        role: str = "user",
+        config_url: str | None = None,
+        user_metadata: dict[str, Any] | None = None,
+        timeout: int | None = None,
+        reinit: bool = False,
+    ) -> ChatResponse:
+        """Send a message and return the AI reply.
+
+        This awaits a full LLM round trip server-side — expect seconds.
+        Passing ``config_url`` auto-creates the conversation if it doesn't
+        exist yet; ``timeout`` and ``reinit`` apply to that auto-create,
+        with the same meaning as on :meth:`create_conversation`.
+        """
+        params: dict[str, Any] = {
+            "id": conversation_id,
+            "message": message,
+            "role": role,
+        }
+        if config_url:
+            params["config_url"] = config_url
+        if user_metadata:
+            params["user_meta_data"] = user_metadata
+        if timeout:
+            params["conversation_timeout"] = timeout
+        if reinit:
+            params["reinit"] = True
+        result = await self._request("chat", params)
+        return ChatResponse(
+            text=result.get("response", ""),
+            conversation_id=conversation_id,
+            user_event=result.get("user_event"),
+        )
+
+    async def end(self, conversation_id: str) -> bool:
+        """End a conversation (triggers server-side post-processing)."""
+        result = await self._request("end_conversation", {"id": conversation_id})
+        return result.get("status") == "ended"
+
+    async def delete(self, conversation_id: str) -> bool:
+        """Permanently delete a conversation and its data."""
+        result = await self._request("delete", {"id": conversation_id})
+        return result.get("status") == "deleted"
+
+    async def log(self, conversation_id: str) -> ChatLog:
+        """Full message history plus the call timeline."""
+        result = await self._request("chat_log", {"id": conversation_id})
+        return ChatLog(
+            messages=result.get("chat_log", []),
+            call_timeline=result.get("call_timeline", []),
+        )
+
+    async def summarize(
+        self,
+        conversation_id: str,
+        summary_prompt: str | None = None,
+        **sampling: Any,
+    ) -> str:
+        """AI summary of the conversation (rate limited server-side).
+
+        Raises :class:`SummaryError` when the server reports that summary
+        generation failed — the service returns EXACTLY ONE of ``{summary}`` or
+        ``{error}`` (both on the success envelope), so a failure must surface as
+        an error, never as an empty string.
+        """
+        params: dict[str, Any] = {"id": conversation_id}
+        if summary_prompt:
+            params["summary_prompt"] = summary_prompt
+        params.update({k: v for k, v in sampling.items() if v is not None})
+        result = await self._request("summarize", params)
+        if "error" in result and "summary" not in result:
+            raise SummaryError(None, str(result["error"]))
+        summary = result.get("summary", "")
+        return summary if isinstance(summary, str) else str(summary)

{signalwire_sdk-3.2.0.dev96 → signalwire_sdk-3.2.0.dev99}/signalwire/signalwire/core/contexts.py

@@ -1493,6 +1493,38 @@ class ContextBuilder:
                         f"avoid the collision."
                     )
 
+            # Validate step set_functions([...]) whitelists against the known
+            # tool universe. A step that whitelists a function which is neither
+            # a registered SWAIG tool nor a reserved native tool is a DANGLING
+            # reference: it renders a step whose active-function set silently
+            # points at nothing (r5 F3 — get_datetime vs get_current_time).
+            # Only enforce when a real registry is present; a contexts builder
+            # with no agent (or a mock registry) cannot know the tool universe,
+            # so we must not red a valid document there.
+            if isinstance(registered, dict):
+                known_functions = set(registered.keys()) | RESERVED_NATIVE_TOOL_NAMES
+                for context_name, context in self._contexts.items():
+                    for step_name, step in context._steps.items():
+                        funcs = step._functions
+                        # "none" and [] are explicit disable-all — not lists of
+                        # references to resolve.
+                        if not isinstance(funcs, list):
+                            continue
+                        for fn in funcs:
+                            if fn not in known_functions:
+                                available = sorted(known_functions)
+                                raise ValueError(
+                                    f"Step '{step_name}' in context "
+                                    f"'{context_name}' whitelists function "
+                                    f"'{fn}' via set_functions(), but no such "
+                                    f"SWAIG tool is registered on the agent and "
+                                    f"it is not a reserved native tool. This "
+                                    f"would emit a dangling function reference. "
+                                    f"Register the tool (define_tool / a skill) "
+                                    f"or remove it from the step. Available: "
+                                    f"{available}"
+                                )
+
     def to_dict(self) -> dict[str, Any]:
         """Convert all contexts to dictionary for SWML generation"""
         self.validate()

{signalwire_sdk-3.2.0.dev96 → signalwire_sdk-3.2.0.dev99}/signalwire/signalwire/core/swml_renderer.py

@@ -168,9 +168,13 @@ class SwmlRenderer:
         # Use the service to build the document
         service.reset_document()
 
-        # Add a play block for the response if provided
+        # Add a play block for the response if provided. Text is played via the
+        # `say:` URL scheme — the SWML `play` verb has no `text` key (its config is
+        # PlayWithURL/PlayWithURLS, url matching `^...|say: ?.*|...$`). Emitting
+        # `{"text": ...}` produced a document the SWML schema rejects; the canonical
+        # form (mirrors SWMLBuilder.play) is `url: "say:<text>"`.
         if response_text:
-            service.add_verb("play", {"text": response_text})
+            service.add_verb("play", {"url": f"say:{response_text}"})
 
         # Add any actions that were provided
         if actions:

{signalwire_sdk-3.2.0.dev96 → signalwire_sdk-3.2.0.dev99}/signalwire/signalwire/core/swml_service.py

@@ -534,6 +534,22 @@ class SWMLService(ToolMixin):
             handler = self.verb_registry.get_handler(verb_name)
             assert handler is not None  # noqa: S101  # type-narrowing invariant (not input validation): guaranteed by has_handler() above
             is_valid, errors = handler.validate_config(config)
+            # A handler's validate_config carries verb-specific diagnostics
+            # (e.g. the ai verb's prompt/SWAIG shape checks) but does NOT reject
+            # unknown/misspelled TOP-LEVEL keys — so a typo'd key would slip
+            # through silently (r5 silent-drop family: ai temperatur/zzz). Add a
+            # shallow unknown-top-level-key check against the schema so a handler
+            # verb rejects stray keys like every other verb. We deliberately do
+            # NOT run the full deep schema here: the ai verb's DEEP shapes
+            # (an empty prompt.pom for a promptless agent, the SWAIG function
+            # shape) are the handler's remit and are legitimately emitted by the
+            # SDK in forms the JSON-schema's oneOf/pom rules don't all accept —
+            # full validation would false-reject valid documents. The shallow
+            # check is a no-op when validation is disabled.
+            if is_valid:
+                is_valid, errors = self.schema_utils._validate_verb_top_level_keys(
+                    verb_name, config
+                )
         else:
             # Use schema-based validation for standard verbs
             is_valid, errors = self.schema_utils.validate_verb(verb_name, config)
@@ -603,6 +619,14 @@ class SWMLService(ToolMixin):
             handler = self.verb_registry.get_handler(verb_name)
             assert handler is not None  # noqa: S101  # type-narrowing invariant (not input validation): guaranteed by has_handler() above
             is_valid, errors = handler.validate_config(config)
+            # See add_verb: also run the shallow unknown-top-level-key check so a
+            # handler verb rejects misspelled/unknown top-level keys (NOT the full
+            # deep schema, which would false-reject the ai verb's legitimate
+            # empty-pom / SWAIG emissions). No-op when validation is disabled.
+            if is_valid:
+                is_valid, errors = self.schema_utils._validate_verb_top_level_keys(
+                    verb_name, config
+                )
         else:
             # Use schema-based validation for standard verbs
             is_valid, errors = self.schema_utils.validate_verb(verb_name, config)