signalwire-sdk 3.2.0.dev91__tar.gz → 3.2.0.dev95__tar.gz

{signalwire_sdk-3.2.0.dev91/signalwire/signalwire_sdk.egg-info → signalwire_sdk-3.2.0.dev95}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.2.0.dev91
+Version: 3.2.0.dev95
 Summary: SignalWire SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT
@@ -21,7 +21,6 @@ Requires-Dist: fastapi>=0.115.12
 Requires-Dist: pydantic>=2.11.4
 Requires-Dist: PyYAML>=6.0.2
 Requires-Dist: Requests>=2.32.4
-Requires-Dist: docopt>=0.6.2
 Requires-Dist: structlog>=25.3.0
 Requires-Dist: uvicorn>=0.34.2
 Requires-Dist: beautifulsoup4>=4.12.3

{signalwire_sdk-3.2.0.dev91 → signalwire_sdk-3.2.0.dev95}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.2.0.dev91"
+version = "3.2.0.dev95"
 description = "SignalWire SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}
@@ -28,7 +28,6 @@ dependencies = [
     "pydantic>=2.11.4",
     "PyYAML>=6.0.2",
     "Requests>=2.32.4",
-    "docopt>=0.6.2",
     "structlog>=25.3.0",
     "uvicorn>=0.34.2",
     "beautifulsoup4>=4.12.3",

{signalwire_sdk-3.2.0.dev91 → signalwire_sdk-3.2.0.dev95}/signalwire/signalwire/__init__.py

@@ -14,48 +14,90 @@ A package for building AI agents using SignalWire's AI and SWML capabilities.
 
 from typing import TYPE_CHECKING, Any
 
-# Configure logging before any other imports to ensure early initialization
-from .core.logging_config import configure_logging
+# Library-safe logging: importing signalwire installs ONLY a NullHandler on the
+# `signalwire` namespace logger (done at logging_config module load). It does NOT
+# configure global logging — that would hijack the host application's logging (its
+# structlog config, its root/generic-named loggers). The app opts in to SDK log
+# OUTPUT by calling configure_logging() explicitly; the server/CLI entry points do.
+from .core.logging_config import configure_logging  # noqa: F401  (re-exported)
 
 if TYPE_CHECKING:
     from signalwire.rest.client import RestClient as _RestClient
     from signalwire.core.skill_base import SkillBase
     from signalwire.skills.registry import SkillRegistry
 
-configure_logging()
-
-__version__ = "3.2.0.dev91"
-
-# Import core classes for easier access.
-# These imports are intentionally placed after configure_logging() so the SDK's
-# logging is initialized before any submodule is imported (E402 expected).
-from .core.agent_base import AgentBase  # noqa: E402
-from .core.contexts import (  # noqa: E402
-    ContextBuilder,
-    Context,
-    Step,
-    GatherInfo,
-    GatherQuestion,
-    create_simple_context,
-)
-from .core.data_map import (  # noqa: E402
-    DataMap,
-    create_simple_api_tool,
-    create_expression_tool,
-)
-from signalwire.agent_server import AgentServer  # noqa: E402
-from signalwire.core.swml_service import SWMLService  # noqa: E402
-from signalwire.core.swml_builder import SWMLBuilder  # noqa: E402
-from signalwire.core.function_result import (  # noqa: E402
-    FunctionResult,
-    SwaigFunctionResult,
-)
-from signalwire.core.swaig_function import SWAIGFunction  # noqa: E402
-from signalwire.agents.bedrock import BedrockAgent  # noqa: E402
-from signalwire.utils.schema_utils import SchemaValidationError  # noqa: E402
-
-# Import WebService for static file serving
-from signalwire.web import WebService  # noqa: E402
+    # §6.2-python: the public symbols are LAZY at runtime (PEP 562, below) so
+    # `import signalwire` doesn't drag FastAPI/uvicorn/pydantic at import time; the
+    # eager imports here keep type checkers and IDEs fully aware of the real types.
+    from signalwire.core.agent_base import AgentBase
+    from signalwire.core.contexts import (
+        ContextBuilder,
+        Context,
+        Step,
+        GatherInfo,
+        GatherQuestion,
+        create_simple_context,
+    )
+    from signalwire.core.data_map import (
+        DataMap,
+        create_simple_api_tool,
+        create_expression_tool,
+    )
+    from signalwire.agent_server import AgentServer
+    from signalwire.core.swml_service import SWMLService
+    from signalwire.core.swml_builder import SWMLBuilder
+    from signalwire.core.function_result import FunctionResult, SwaigFunctionResult
+    from signalwire.core.swaig_function import SWAIGFunction
+    from signalwire.agents.bedrock import BedrockAgent
+    from signalwire.utils.schema_utils import SchemaValidationError
+    from signalwire.web import WebService
+
+__version__ = "3.2.0.dev95"
+
+# §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
+# __getattr__ (PEP 562) so `import signalwire` no longer drags FastAPI / uvicorn /
+# starlette / pydantic into every process — a REST-only script imports in
+# milliseconds. First ATTRIBUTE ACCESS (signalwire.AgentBase,
+# `from signalwire import AgentBase`) triggers the real import and caches it on the
+# module, so the public surface is byte-identical to the old eager form.
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "AgentBase": ("signalwire.core.agent_base", "AgentBase"),
+    "ContextBuilder": ("signalwire.core.contexts", "ContextBuilder"),
+    "Context": ("signalwire.core.contexts", "Context"),
+    "Step": ("signalwire.core.contexts", "Step"),
+    "GatherInfo": ("signalwire.core.contexts", "GatherInfo"),
+    "GatherQuestion": ("signalwire.core.contexts", "GatherQuestion"),
+    "create_simple_context": ("signalwire.core.contexts", "create_simple_context"),
+    "DataMap": ("signalwire.core.data_map", "DataMap"),
+    "create_simple_api_tool": ("signalwire.core.data_map", "create_simple_api_tool"),
+    "create_expression_tool": ("signalwire.core.data_map", "create_expression_tool"),
+    "AgentServer": ("signalwire.agent_server", "AgentServer"),
+    "SWMLService": ("signalwire.core.swml_service", "SWMLService"),
+    "SWMLBuilder": ("signalwire.core.swml_builder", "SWMLBuilder"),
+    "FunctionResult": ("signalwire.core.function_result", "FunctionResult"),
+    "SwaigFunctionResult": ("signalwire.core.function_result", "SwaigFunctionResult"),
+    "SWAIGFunction": ("signalwire.core.swaig_function", "SWAIGFunction"),
+    "BedrockAgent": ("signalwire.agents.bedrock", "BedrockAgent"),
+    "SchemaValidationError": ("signalwire.utils.schema_utils", "SchemaValidationError"),
+    "WebService": ("signalwire.web", "WebService"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """PEP 562 lazy attribute resolution for the public agent/web symbols."""
+    spec = _LAZY_IMPORTS.get(name)
+    if spec is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(spec[0]), spec[1])
+    globals()[name] = value  # cache — subsequent access skips __getattr__
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_IMPORTS))
 
 
 # Lazy import skills to avoid slow startup for CLI tools

{signalwire_sdk-3.2.0.dev91 → signalwire_sdk-3.2.0.dev95}/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.dev91",
+            version="3.2.0.dev95",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,
@@ -372,7 +372,15 @@ class AgentServer:
 
         # Imported lazily here so tests can patch
         # signalwire.core.logging_config.get_execution_mode at call time.
-        from signalwire.core.logging_config import get_execution_mode
+        from signalwire.core.logging_config import (
+            configure_logging,
+            get_execution_mode,
+        )
+
+        # Opt-in to SDK logging OUTPUT at the run entry point (import is
+        # library-safe / silent; running is where the app wants logs). This also
+        # applies the CGI-off / auto detection that configure_logging performs.
+        configure_logging()
 
         # Detect execution mode
         mode = get_execution_mode()

signalwire_sdk-3.2.0.dev95/signalwire/signalwire/core/__init__.py

@@ -0,0 +1,59 @@
+"""
+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.
+
+Core components for SignalWire AI Agents
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from signalwire.core.agent_base import AgentBase
+    from signalwire.core.function_result import FunctionResult
+    from signalwire.core.swaig_function import SWAIGFunction
+    from signalwire.core.swml_service import SWMLService
+    from signalwire.core.swml_handler import SWMLVerbHandler, VerbHandlerRegistry
+    from signalwire.core.swml_builder import SWMLBuilder
+
+# §6.2-python: lazy (PEP 562) so importing any signalwire.core.* leaf (e.g.
+# logging_config from the package root) doesn't drag AgentBase → FastAPI into every
+# process. First attribute access resolves + caches; public surface unchanged.
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    "AgentBase": ("signalwire.core.agent_base", "AgentBase"),
+    "FunctionResult": ("signalwire.core.function_result", "FunctionResult"),
+    "SWAIGFunction": ("signalwire.core.swaig_function", "SWAIGFunction"),
+    "SWMLService": ("signalwire.core.swml_service", "SWMLService"),
+    "SWMLVerbHandler": ("signalwire.core.swml_handler", "SWMLVerbHandler"),
+    "VerbHandlerRegistry": ("signalwire.core.swml_handler", "VerbHandlerRegistry"),
+    "SWMLBuilder": ("signalwire.core.swml_builder", "SWMLBuilder"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    spec = _LAZY_IMPORTS.get(name)
+    if spec is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    value = getattr(importlib.import_module(spec[0]), spec[1])
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_LAZY_IMPORTS))
+
+
+__all__ = [
+    "AgentBase",
+    "FunctionResult",
+    "SWAIGFunction",
+    "SWMLBuilder",
+    "SWMLService",
+    "SWMLVerbHandler",
+    "VerbHandlerRegistry",
+]

{signalwire_sdk-3.2.0.dev91 → signalwire_sdk-3.2.0.dev95}/signalwire/signalwire/core/logging_config.py

@@ -43,6 +43,25 @@ def strip_control_chars(
 _logging_configured = False
 
 
+def _install_library_null_handler() -> None:
+    """Attach a NullHandler to the ``signalwire`` namespace logger (the standard
+    library pattern for a well-behaved library, per the stdlib logging HOWTO).
+
+    This is the ONLY logging side effect of importing the SDK. It makes the SDK's
+    own loggers silent-by-default (no "No handlers could be found" warning) WITHOUT
+    touching the root logger, the host application's structlog config, or any
+    host-owned logger — so ``import signalwire`` never hijacks the app's logging.
+    The app opts in to SDK log OUTPUT by calling ``configure_logging()`` explicitly
+    (the server/CLI entry points do this)."""
+    sw_logger = logging.getLogger("signalwire")
+    if not any(isinstance(h, logging.NullHandler) for h in sw_logger.handlers):
+        sw_logger.addHandler(logging.NullHandler())
+
+
+# Import-time side effect: ONLY the library NullHandler. NOT global configuration.
+_install_library_null_handler()
+
+
 def get_execution_mode() -> str:
     """
     Determine the execution mode based on environment variables
@@ -307,7 +326,9 @@ def get_logger(name: str) -> Any:
     Returns:
         A structlog BoundLogger that supports .bind(), .info(), .debug(), etc.
     """
-    # Ensure logging is configured
-    configure_logging()
-
+    # Library-safe: do NOT auto-configure global logging here. Every SDK module
+    # calls get_logger() at import, so auto-configuring would hijack the host
+    # app's logging the moment any SDK submodule is imported. The SDK's own
+    # logger carries a NullHandler (installed at module load) so it's silent by
+    # default; the app opts in to SDK output via configure_logging().
     return structlog.get_logger(name)

{signalwire_sdk-3.2.0.dev91 → signalwire_sdk-3.2.0.dev95}/signalwire/signalwire/core/mixins/web_mixin.py

@@ -204,6 +204,12 @@ class WebMixin(_HostTyped):  # type: ignore[misc]  # _HostTyped is object at run
         """
         import uvicorn
 
+        # Opt-in to SDK logging OUTPUT at the serve entry point (importing the SDK
+        # is library-safe / silent; running a server is where the app wants logs).
+        from signalwire.core.logging_config import configure_logging
+
+        configure_logging()
+
         if self._app is None:
             # Create a FastAPI app with explicit redirect_slashes=False
             app = FastAPI(

{signalwire_sdk-3.2.0.dev91 → signalwire_sdk-3.2.0.dev95}/signalwire/signalwire/core/swml_service.py

@@ -1200,6 +1200,12 @@ class SWMLService(ToolMixin):
         """
         import uvicorn
 
+        # Opt-in to SDK logging OUTPUT at the serve entry point (import is
+        # library-safe / silent; serving is where the app wants logs).
+        from signalwire.core.logging_config import configure_logging
+
+        configure_logging()
+
         # Store SSL configuration (override environment if explicitly provided)
         if ssl_enabled is not None:
             self.ssl_enabled = ssl_enabled

{signalwire_sdk-3.2.0.dev91 → signalwire_sdk-3.2.0.dev95}/signalwire/signalwire/pom/pom_tool.py

@@ -13,11 +13,11 @@ Options:
     --merge_pom=<arg>   Merge another POM into a section: "<section name>:<filename>"
 """
 
+import argparse
 import sys
 import json
 from pathlib import Path
 import yaml
-from docopt import docopt
 from signalwire.pom import PromptObjectModel
 
 
@@ -82,19 +82,38 @@ def render_pom(pom: "PromptObjectModel", output_format: str) -> str:
 
 def main() -> None:
     """Main entry point for the POM tool."""
-    args = docopt(__doc__)
-
-    input_file = args["<input_file>"]
-    output_format = args["--output"] or "md"
-    output_file = args["--outfile"]
-    merge_pom = args["--merge_pom"]
-
-    # Validate output format
-    if output_format not in ["md", "xml", "json", "yaml"]:
-        print(
-            f"Error: Invalid output format '{output_format}'. Must be one of: md, xml, json, yaml"
-        )
-        sys.exit(1)
+    # §6.2-python: argparse (stdlib) replaced the unmaintained docopt — identical CLI
+    # surface (same flags/defaults/usage), one fewer dependency.
+    parser = argparse.ArgumentParser(
+        prog="pom_tool",
+        description="POM Tool - work with Prompt Object Model files",
+    )
+    parser.add_argument("input_file", help="POM file to load (JSON or YAML)")
+    parser.add_argument(
+        "--output",
+        default="md",
+        metavar="<format>",
+        choices=["md", "xml", "json", "yaml"],
+        help="Output format: md, xml, json, yaml [default: md]",
+    )
+    parser.add_argument(
+        "--outfile",
+        default=None,
+        metavar="<file>",
+        help="Output file (if not specified, prints to stdout)",
+    )
+    parser.add_argument(
+        "--merge_pom",
+        default=None,
+        metavar="<arg>",
+        help='Merge another POM into a section: "<section name>:<filename>"',
+    )
+    ns = parser.parse_args()
+
+    input_file = ns.input_file
+    output_format = ns.output
+    output_file = ns.outfile
+    merge_pom = ns.merge_pom
 
     try:
         # Load the POM

{signalwire_sdk-3.2.0.dev91 → signalwire_sdk-3.2.0.dev95}/signalwire/signalwire/relay/call.py

@@ -112,9 +112,15 @@ class Action:
                 )
 
     async def wait(self, timeout: float | None = None) -> RelayEvent:
-        """Wait for the action to complete. Returns the terminal event."""
+        """Wait for the action to complete. Returns the terminal event.
+
+        Raises ``asyncio.TimeoutError`` if ``timeout`` is exceeded. A timed-out
+        wait does NOT poison the action: ``self._done`` is shielded so the
+        ``wait_for`` cancellation stops the wait, not the underlying completion
+        future — the still-pending terminal event resolves the action normally
+        and a subsequent ``wait()`` returns it (mirrors ``Message.wait``)."""
         if timeout is not None:
-            return await asyncio.wait_for(self._done, timeout=timeout)
+            return await asyncio.wait_for(asyncio.shield(self._done), timeout=timeout)
         return await self._done
 
     @property
@@ -377,9 +383,14 @@ class Call:
         The outer JSON-RPC method is ``"calling.<method>"`` (e.g.
         ``"calling.answer"``) with ``node_id`` and ``call_id`` in params.
 
-        All server errors are logged gracefully and return an empty dict
-        rather than raising exceptions.  This is an SDK — stack traces
-        from server-side errors should never bubble up to the developer.
+        A2 contract (the documented behavior — only "call gone" is swallowed):
+        a **404** or **410** server error means the call no longer exists, so the
+        verb is a no-op and returns ``{}`` (the caller's action can't proceed but
+        that isn't an error worth raising). **Every other non-2xx server error
+        RAISES** — the previous code swallowed ALL errors carrying a ``code``,
+        which hid real failures (auth, bad params, server faults) the developer
+        must see. The docstring/contract always promised 404/410-only; the code
+        now matches it.
         """
         rpc_method = f"calling.{method}"
         params: dict[str, Any] = {
@@ -392,11 +403,13 @@ class Call:
             return await self._client.execute(rpc_method, params)
         except Exception as exc:
             code = getattr(exc, "code", None)
-            if code is not None:
+            if code in (404, 410):
+                # Call gone — swallow per the documented contract, return no-op.
                 logger.warning(
-                    f"Call {self.call_id} error during {method} (code={code}): {exc}"
+                    f"Call {self.call_id} gone during {method} (code={code}): {exc}"
                 )
                 return {}
+            # Any other server error (or a non-coded exception) propagates.
             raise
 
     # ------------------------------------------------------------------