signalwire-sdk 3.0.2.dev70__tar.gz → 3.0.2.dev73__tar.gz

{signalwire_sdk-3.0.2.dev70/signalwire/signalwire_sdk.egg-info → signalwire_sdk-3.0.2.dev73}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.0.2.dev70
+Version: 3.0.2.dev73
 Summary: SignalWire SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT
@@ -138,6 +138,7 @@ pip install signalwire-sdk
 
 Each agent is a self-contained microservice that generates [SWML](docs/swml_service_guide.md) (SignalWire Markup Language) and handles [SWAIG](docs/swaig_reference.md) (SignalWire AI Gateway) tool calls. The SignalWire platform runs the entire AI pipeline (STT, LLM, TTS) -- your agent just defines the behavior.
 
+<!-- include: examples/quickstart_agent.py#agent -->
 ```python
 from signalwire import AgentBase
 from signalwire.core.function_result import FunctionResult
@@ -209,6 +210,7 @@ See [examples/README.md](examples/README.md) for the full list organized by cate
 
 Real-time call control and messaging over WebSocket. The RELAY client connects to SignalWire via the Blade protocol and gives you imperative, async control over live phone calls and SMS/MMS.
 
+<!-- include: examples/quickstart_relay.py#relay -->
 ```python
 from signalwire.relay import RelayClient
 
@@ -237,6 +239,7 @@ See the **[RELAY documentation](relay/README.md)** for the full guide, API refer
 
 Synchronous REST client for managing SignalWire resources and controlling calls over HTTP. No WebSocket required.
 
+<!-- include: examples/quickstart_rest.py#rest -->
 ```python
 from signalwire.rest import RestClient
 
@@ -248,7 +251,7 @@ client.phone_numbers.search(area_code="512")
 client.datasphere.documents.search(query_string="billing policy")
 ```
 
-- 21 namespaced API surfaces: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Compat (Twilio-compatible), Phone Numbers, SIP, Queues, Recordings, and more
+- 20 namespaced API surfaces: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Phone Numbers, SIP, Queues, Recordings, and more
 - Shared `requests.Session` for connection pooling
 - Dict returns -- raw JSON, no wrapper objects
 

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/README.md

@@ -40,6 +40,7 @@ pip install signalwire-sdk
 
 Each agent is a self-contained microservice that generates [SWML](docs/swml_service_guide.md) (SignalWire Markup Language) and handles [SWAIG](docs/swaig_reference.md) (SignalWire AI Gateway) tool calls. The SignalWire platform runs the entire AI pipeline (STT, LLM, TTS) -- your agent just defines the behavior.
 
+<!-- include: examples/quickstart_agent.py#agent -->
 ```python
 from signalwire import AgentBase
 from signalwire.core.function_result import FunctionResult
@@ -111,6 +112,7 @@ See [examples/README.md](examples/README.md) for the full list organized by cate
 
 Real-time call control and messaging over WebSocket. The RELAY client connects to SignalWire via the Blade protocol and gives you imperative, async control over live phone calls and SMS/MMS.
 
+<!-- include: examples/quickstart_relay.py#relay -->
 ```python
 from signalwire.relay import RelayClient
 
@@ -139,6 +141,7 @@ See the **[RELAY documentation](relay/README.md)** for the full guide, API refer
 
 Synchronous REST client for managing SignalWire resources and controlling calls over HTTP. No WebSocket required.
 
+<!-- include: examples/quickstart_rest.py#rest -->
 ```python
 from signalwire.rest import RestClient
 
@@ -150,7 +153,7 @@ client.phone_numbers.search(area_code="512")
 client.datasphere.documents.search(query_string="billing policy")
 ```
 
-- 21 namespaced API surfaces: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Compat (Twilio-compatible), Phone Numbers, SIP, Queues, Recordings, and more
+- 20 namespaced API surfaces: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Phone Numbers, SIP, Queues, Recordings, and more
 - Shared `requests.Session` for connection pooling
 - Dict returns -- raw JSON, no wrapper objects
 

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.0.2.dev70"
+version = "3.0.2.dev73"
 description = "SignalWire SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}
@@ -149,6 +149,7 @@ include-package-data = true
 
 [tool.setuptools.package-data]
 signalwire = [
+    "py.typed",
     "schema.json",
     "**/*.json",
     "skills/*/README.md",
@@ -182,6 +183,16 @@ select = ["E4", "E7", "E9", "F", "B", "S", "C4", "PERF", "SIM", "PTH", "RET", "R
 # call) and S607 (partial executable path: git/ssh resolved via PATH, the normal
 # idiom) are expected and safe across this file.
 "signalwire/signalwire/cli/dokku.py" = ["S603", "S607"]
+# REST namespace files import spec-generated types under TYPE_CHECKING and use
+# them ONLY inside quoted forward-refs — method return annotations
+# (`-> "RoomResponse"`) and the generic CRUD-base subscript bindings
+# (`class VideoRooms(CrudResource["ListRoomsResponse", "RoomResponse", ...])`).
+# Ruff's F401 cannot see usages inside a class-base subscript's string literals,
+# so it false-positives "unused import" and `--fix` would strip imports that ARE
+# used (breaking mypy). The bindings must stay quoted (a bare name in the base
+# 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"]
 
 [tool.ruff.lint.flake8-bugbear]
 # FastAPI's dependency-injection idiom puts Depends()/Query()/etc. in argument
@@ -202,16 +213,22 @@ extend-immutable-calls = [
 
 [tool.mypy]
 python_version = "3.10"
-files = ["signalwire/signalwire"]
+# Both the source tree AND the test suite are in scope — the generated REST tests are
+# strict-clean by construction, and the hand-written tests were fully annotated, so the
+# strict bar now covers tests too (a new untyped test fails the gate).
+files = ["signalwire/signalwire", "tests"]
 # Third-party packages without type stubs (nltk, sentence_transformers, the
 # search/relay stacks) are out of scope — we type our own code, not theirs.
 ignore_missing_imports = true
-# The bar: our own code is clean. Bodies of untyped defs are checked so real
-# type errors inside them surface (this is what found the mixin cluster).
-check_untyped_defs = true
-warn_unused_ignores = true
-# `# type: ignore` is reserved for genuinely-unfixable third-party-stub gaps and
-# must carry an error code + reason. warn_unused_ignores keeps them honest.
+# The bar: the whole source tree is mypy --strict clean (full annotations + all
+# the strict sub-flags). Achieved by typing handlers with REAL types (FastAPI
+# Response/dict, generated payload types where they exist) — never papered with
+# bare `Any`. `strict` subsumes check_untyped_defs / warn_unused_ignores / etc.
+strict = true
+# `# type: ignore` is reserved for genuinely-unfixable third-party-stub gaps (e.g.
+# flask/flask-limiter optional extras with no stubs) and the documented
+# _HostTyped/AgentBase TYPE_CHECKING-vs-runtime split; each must carry an error
+# code + reason. warn_unused_ignores (via strict) keeps them honest.
 show_error_codes = true
 
 # numpy (a search/relay-extra runtime dep we do NOT type — same class as nltk /

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/signalwire/signalwire/__init__.py

@@ -12,12 +12,19 @@ SignalWire SDK
 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
 
+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.0.2.dev70"
+__version__ = "3.0.2.dev73"
 
 # Import core classes for easier access.
 # These imports are intentionally placed after configure_logging() so the SDK's
@@ -53,14 +60,14 @@ from signalwire.web import WebService  # noqa: E402
 
 # Lazy import skills to avoid slow startup for CLI tools
 # Skills are now loaded on-demand when requested
-def _get_skill_registry():
+def _get_skill_registry() -> "SkillRegistry":
     """Lazy import and return skill registry"""
     import signalwire.skills
 
     return signalwire.skills.skill_registry
 
 
-def list_skills():
+def list_skills() -> list[dict[str, Any]]:
     """List all available skills with metadata.
 
     Returns one dict per skill (name, description, version, required packages /
@@ -71,7 +78,7 @@ def list_skills():
     return skill_registry.list_skills()
 
 
-def list_skills_with_params():
+def list_skills_with_params() -> dict[str, dict[str, Any]]:
     """
     Get complete schema for all available skills including parameter metadata
 
@@ -98,7 +105,7 @@ def list_skills_with_params():
     return skill_registry.get_all_skills_schema()
 
 
-def register_skill(skill_class):
+def register_skill(skill_class: "type[SkillBase]") -> None:
     """
     Register a custom skill class
 
@@ -119,7 +126,7 @@ def register_skill(skill_class):
     return skill_registry.register_skill(skill_class)
 
 
-def add_skill_directory(path):
+def add_skill_directory(path: str) -> None:
     """
     Add a directory to search for skills
 
@@ -138,7 +145,7 @@ def add_skill_directory(path):
     return skill_registry.add_skill_directory(path)
 
 
-def RestClient(*args, **kwargs):
+def RestClient(*args: Any, **kwargs: Any) -> "_RestClient":
     """Create a SignalWire REST API client (lazy import)"""
     from signalwire.rest import RestClient as _RestClient
 

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/signalwire/signalwire/agent_server.py

@@ -13,7 +13,7 @@ import os
 import re
 from pathlib import Path
 from typing import Any
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 
 try:
     from fastapi import FastAPI, Request, Response
@@ -26,6 +26,7 @@ except ImportError:
 from signalwire.core.agent_base import AgentBase
 from signalwire.core.swml_service import SWMLService
 from signalwire.core.logging_config import get_logger
+from signalwire.core.mixins.web_mixin import _as_response
 import contextlib
 
 
@@ -67,7 +68,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="3.0.2.dev70",
+            version="3.0.2.dev73",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,
@@ -76,7 +77,9 @@ class AgentServer:
 
         # Add security headers middleware
         @self.app.middleware("http")
-        async def add_security_headers(request, call_next):
+        async def add_security_headers(
+            request: Request, call_next: Callable[[Request], Awaitable[Response]]
+        ) -> Response:
             response = await call_next(request)
             response.headers["X-Content-Type-Options"] = "nosniff"
             response.headers["X-Frame-Options"] = "DENY"
@@ -104,7 +107,7 @@ class AgentServer:
         # all other routes are registered. This ensures custom routes like /get_token
         # don't get overshadowed by the catch-all /{full_path:path} route.
         @self.app.on_event("startup")
-        async def _setup_catch_all():
+        async def _setup_catch_all() -> None:
             self._register_catch_all_handler()
 
     def register(self, agent: AgentBase, route: str | None = None) -> None:
@@ -187,9 +190,10 @@ class AgentServer:
             for agent_route, agent in self.agents.items():
                 self._auto_map_agent_sip_usernames(agent, agent_route)
 
-        # Create a unified routing callback that checks all registered usernames
+        # Create a unified routing callback that checks all registered usernames.
+        # Framework-free (body, headers) shape; this callback only reads the body.
         def server_sip_routing_callback(
-            request: Request, body: dict[str, Any]
+            body: dict[str, Any], headers: dict[str, Any]
         ) -> str | None:
             """Unified SIP routing callback that checks all registered usernames"""
             # Extract the SIP username
@@ -343,8 +347,8 @@ class AgentServer:
 
     def run(
         self,
-        event=None,
-        context=None,
+        event: Any = None,
+        context: Any = None,
         host: str | None = None,
         port: int | None = None,
     ) -> Any:
@@ -511,7 +515,7 @@ class AgentServer:
         error_response = {"error": "Not Found"}
         return self._format_cgi_response(error_response, status="404 Not Found")
 
-    def _handle_lambda_request(self, event, context) -> dict:
+    def _handle_lambda_request(self, event: Any, context: Any) -> dict[str, Any]:
         """Handle Lambda request using same routing logic as server"""
         import json
 
@@ -600,7 +604,7 @@ class AgentServer:
         }
 
     def _format_cgi_response(
-        self, data, content_type: str = "application/json", status: str = "200 OK"
+        self, data: Any, content_type: str = "application/json", status: str = "200 OK"
     ) -> str:
         """Format response for CGI output"""
         import json
@@ -634,7 +638,7 @@ class AgentServer:
         """
 
         @self.app.get("/health")
-        def health_check():
+        def health_check() -> dict[str, Any]:
             return {
                 "status": "ok",
                 "agents": len(self.agents),
@@ -642,7 +646,7 @@ class AgentServer:
             }
 
         @self.app.get("/ready")
-        def readiness_check():
+        def readiness_check() -> dict[str, Any]:
             return {"status": "ready", "agents": len(self.agents)}
 
     def _run_server(self, host: str | None = None, port: int | None = None) -> None:
@@ -709,15 +713,18 @@ class AgentServer:
             uvicorn.run(self.app, host=host, port=port, log_level=self.log_level)
 
     def register_global_routing_callback(
-        self, callback_fn: Callable[[Request, dict[str, Any]], str | None], path: str
+        self,
+        callback_fn: Callable[[dict[str, Any], dict[str, Any]], str | None],
+        path: str,
     ) -> None:
         """
         Register a routing callback across all agents
 
         This allows you to add unified routing logic to all agents at the same path.
+        The callback receives ``(body, headers)`` — the framework-free shape.
 
         Args:
-            callback_fn: The callback function to register
+            callback_fn: The callback function to register, ``(body, headers)``.
             path: The path to register the callback at
         """
         # Normalize the path
@@ -845,7 +852,7 @@ class AgentServer:
 
         @self.app.get("/{full_path:path}")
         @self.app.post("/{full_path:path}")
-        async def handle_all_routes(request: Request, full_path: str):
+        async def handle_all_routes(request: Request, full_path: str) -> Response:
             """Handle requests that don't match registered routes (e.g. /matti instead of /matti/)"""
             # Check if this path maps to one of our registered agents
             for route, agent in self.agents.items():
@@ -868,11 +875,20 @@ class AgentServer:
                     if clean_path == "swaig":
                         from fastapi import Response
 
-                        return await agent._handle_swaig_request(request, Response())
+                        # _handle_swaig_request returns Response | dict (the dict is a
+                        # SWAIG-result passthrough); funnel through _as_response so this
+                        # route handler stays -> Response (FastAPI-safe).
+                        return _as_response(
+                            await agent._handle_swaig_request(request, Response())
+                        )
                     if clean_path == "post_prompt":
-                        return await agent._handle_post_prompt_request(request)
+                        return _as_response(
+                            await agent._handle_post_prompt_request(request)
+                        )
                     if clean_path == "check_for_input":
-                        return await agent._handle_check_for_input_request(request)
+                        return _as_response(
+                            await agent._handle_check_for_input_request(request)
+                        )
 
                     # Check for custom routing callbacks
                     if hasattr(agent, "_routing_callbacks"):

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/signalwire/signalwire/cli/core/service_loader.py

@@ -196,8 +196,10 @@ async def simulate_request_to_service(
         import json
 
         # json.loads() is typed -> Any; a FastAPI Response body is the rendered
-        # SWML JSON object, matching the declared dict return.
-        return cast(dict[str, Any], json.loads(result.body.decode()))
+        # SWML JSON object, matching the declared dict return. result.body is
+        # bytes | memoryview — bytes() handles both before decode (memoryview has
+        # no .decode()), a real latent bug strict typing surfaced.
+        return cast(dict[str, Any], json.loads(bytes(result.body).decode()))
     if isinstance(result, dict):
         return result
     # Try to get content from response

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/signalwire/signalwire/cli/test_swaig.py

@@ -226,8 +226,25 @@ swaig-test agent.py --simulate-serverless cgi --cgi-host example.com --dump-swml
 
 def main() -> int:
     """Main entry point for the CLI tool"""
-    # Set up suppression early if we're dumping SWML
-    if "--dump-swml" in sys.argv:
+    # Detect --parse-only / --dry-run FIRST and strip it from argv.
+    # It is detected before everything else because:
+    #   1. --dump-swml installs a global stdout suppressor below; parse-only must
+    #      still be able to print its one "parse OK" line, so we skip that setup.
+    #   2. The --exec split further down consumes every token after the function
+    #      name as a function argument, so a --parse-only trailing an --exec
+    #      invocation (the position the DOC-CLI gate appends it) would otherwise be
+    #      swallowed and never reach argparse. Stripping it here makes the flag
+    #      position-independent — it works whether it precedes or follows --exec.
+    # It is still declared as a normal argparse argument below so it appears in
+    # --help and validates like any flag.
+    parse_only_early = False
+    if "--parse-only" in sys.argv or "--dry-run" in sys.argv:
+        parse_only_early = True
+        sys.argv = [a for a in sys.argv if a not in ("--parse-only", "--dry-run")]
+
+    # Set up suppression early if we're dumping SWML (but never under --parse-only,
+    # which must be free to print its result line).
+    if "--dump-swml" in sys.argv and not parse_only_early:
         setup_output_suppression()
 
     # Check for help sections early
@@ -410,6 +427,18 @@ def main() -> int:
         "--help-examples", action="store_true", help="Show comprehensive usage examples"
     )
 
+    # Parse-only / dry-run: validate the invocation's arguments and exit WITHOUT
+    # loading the agent or hitting the network. Used by the DOC-CLI gate to prove a
+    # documented invocation's arguments are well-formed. Canonical contract mirrored
+    # by every port -- see the "--parse-only / --dry-run" section of docs/cli_guide.md.
+    parser.add_argument(
+        "--parse-only",
+        "--dry-run",
+        action="store_true",
+        dest="parse_only",
+        help="Validate arguments and exit without running the agent (prints 'parse OK')",
+    )
+
     args = parser.parse_args()
 
     # Restore original sys.argv
@@ -434,6 +463,16 @@ def main() -> int:
         # If no tool_name and no special flags, default to listing tools
         args.list_tools = True
 
+    # ===== PARSE-ONLY / DRY-RUN =====
+    # All argparse parsing + cross-flag validation has succeeded by this point.
+    # Report success and exit WITHOUT loading the agent, touching the filesystem,
+    # or hitting the network. (parser.parse_args()/parser.error() already exited
+    # non-zero on any bad flag or invalid combination above.) The flag is detected
+    # both early (stripped from argv, position-independent) and via argparse.
+    if parse_only_early or args.parse_only:
+        print("parse OK")
+        return 0
+
     # ===== SERVERLESS SIMULATION SETUP =====
     serverless_simulator = None
 

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/signalwire/signalwire/core/_agent_host.py

@@ -22,3 +22,6 @@ if TYPE_CHECKING:
     from signalwire.core.agent_base import AgentBase as AgentHost  # type: ignore[attr-defined]  # intentional TYPE_CHECKING-only re-export; agent_base imports this module's consumers (the mixins), so the name resolves for them but not in self-check
 else:
     AgentHost = object
+
+# Explicit re-export so --strict (no_implicit_reexport) lets _mixin_host import AgentHost.
+__all__ = ["AgentHost"]

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/signalwire/signalwire/core/agent/prompt/manager.py

@@ -20,7 +20,7 @@ logger = get_logger(__name__)
 class PromptManager:
     """Manages prompt building and configuration."""
 
-    def __init__(self, agent):
+    def __init__(self, agent: Any) -> None:
         """
         Initialize PromptManager with reference to parent agent.
 
@@ -29,10 +29,10 @@ class PromptManager:
         """
         self.agent = agent
         self._prompt_text: str | None = None
-        self._post_prompt_text = None
-        self._contexts = None
+        self._post_prompt_text: str | None = None
+        self._contexts: dict[str, Any] | None = None
 
-    def _validate_prompt_mode_exclusivity(self):
+    def _validate_prompt_mode_exclusivity(self) -> None:
         """
         Check that only one prompt mode is in use.
 

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/signalwire/signalwire/core/agent/tools/decorator.py

@@ -9,16 +9,23 @@ See LICENSE file in the project root for full license information.
 Tool decorator functionality.
 """
 
+from typing import Any, TypeVar
+from collections.abc import Callable
+
 from signalwire.core.logging_config import get_logger
 
 logger = get_logger(__name__)
 
+_F = TypeVar("_F", bound=Callable[..., Any])
+
 
 class ToolDecorator:
     """Handles tool decoration logic."""
 
     @staticmethod
-    def create_instance_decorator(registry):
+    def create_instance_decorator(
+        registry: Any,
+    ) -> Callable[..., Callable[[_F], _F]]:
         """
         Create instance tool decorator.
 
@@ -29,7 +36,7 @@ class ToolDecorator:
             Decorator function
         """
 
-        def decorator(name=None, **kwargs):
+        def decorator(name: str | None = None, **kwargs: Any) -> Callable[[_F], _F]:
             """
             Decorator for defining SWAIG tools in a class.
 
@@ -78,7 +85,7 @@ class ToolDecorator:
             guidance.
             """
 
-            def inner_decorator(func):
+            def inner_decorator(func: _F) -> _F:
                 nonlocal name
                 if name is None:
                     name = func.__name__
@@ -90,7 +97,7 @@ class ToolDecorator:
                 webhook_url = kwargs.pop("webhook_url", None)
                 required = kwargs.pop("required", None)
 
-                handler = func
+                handler: Callable[..., Any] = func
                 is_typed = False
 
                 # If parameters not explicitly provided, try type inference
@@ -138,7 +145,7 @@ class ToolDecorator:
         return decorator
 
     @classmethod
-    def create_class_decorator(cls):
+    def create_class_decorator(cls) -> Callable[..., Callable[[_F], _F]]:
         """
         Create class tool decorator.
 
@@ -146,7 +153,7 @@ class ToolDecorator:
             Decorator function
         """
 
-        def tool(name=None, **kwargs):
+        def tool(name: str | None = None, **kwargs: Any) -> Callable[[_F], _F]:
             """
             Class method decorator for defining SWAIG tools.
 
@@ -180,11 +187,11 @@ class ToolDecorator:
                     ...
             """
 
-            def decorator(func):
+            def decorator(func: _F) -> _F:
                 # Mark the function as a tool
-                func._is_tool = True
-                func._tool_name = name if name else func.__name__
-                func._tool_params = kwargs
+                func._is_tool = True  # type: ignore[attr-defined]  # dynamic marker attrs read back by ToolRegistry.register_class_decorated_tools
+                func._tool_name = name if name else func.__name__  # type: ignore[attr-defined]
+                func._tool_params = kwargs  # type: ignore[attr-defined]
 
                 # Return the original function
                 return func

{signalwire_sdk-3.0.2.dev70 → signalwire_sdk-3.0.2.dev73}/signalwire/signalwire/core/agent/tools/registry.py

@@ -22,7 +22,7 @@ logger = get_logger(__name__)
 class ToolRegistry:
     """Manages SWAIG function registration."""
 
-    def __init__(self, agent):
+    def __init__(self, agent: Any) -> None:
         """
         Initialize ToolRegistry with reference to parent agent.
 
@@ -30,15 +30,15 @@ class ToolRegistry:
             agent: Parent AgentBase instance
         """
         self.agent = agent
-        self._swaig_functions = {}
-        self._class_decorated_tools = []
+        self._swaig_functions: dict[str, SWAIGFunction | dict[str, Any]] = {}
+        self._class_decorated_tools: list[Any] = []
 
     def define_tool(
         self,
         name: str,
         description: str,
         parameters: dict[str, Any],
-        handler: Callable,
+        handler: Callable[..., Any],
         secure: bool = True,
         fillers: dict[str, list[str]] | None = None,
         wait_file: str | None = None,
@@ -46,7 +46,7 @@ class ToolRegistry:
         webhook_url: str | None = None,
         required: list[str] | None = None,
         is_typed_handler: bool = False,
-        **swaig_fields,
+        **swaig_fields: Any,
     ) -> None:
         """
         Define a SWAIG function that the AI can call.