signalwire-agents 0.1.9__py3-none-any.whl → 0.1.11__py3-none-any.whl

signalwire_agents/core/skill_manager.py

@@ -31,10 +31,6 @@ class SkillManager:
         Returns:
             tuple: (success, error_message) - error_message is empty string if successful
         """
-        if skill_name in self.loaded_skills:
-            self.logger.warning(f"Skill '{skill_name}' is already loaded")
-            return True, ""
-            
         # Get skill class from registry if not provided
         if skill_class is None:
             try:
@@ -50,8 +46,21 @@ class SkillManager:
                 return False, error_msg
         
         try:
-            # Create skill instance with parameters
+            # Create skill instance with parameters to get the instance key
             skill_instance = skill_class(self.agent, params)
+            instance_key = skill_instance.get_instance_key()
+            
+            # Check if this instance is already loaded
+            if instance_key in self.loaded_skills:
+                # For single-instance skills, this is an error
+                if not skill_instance.SUPPORTS_MULTIPLE_INSTANCES:
+                    error_msg = f"Skill '{skill_name}' is already loaded and does not support multiple instances"
+                    self.logger.error(error_msg)
+                    return False, error_msg
+                else:
+                    # For multi-instance skills, just warn and return success
+                    self.logger.warning(f"Skill instance '{instance_key}' is already loaded")
+                    return True, ""
             
             # Validate environment variables with specific error details
             import os
@@ -97,9 +106,9 @@ class SkillManager:
             for section in prompt_sections:
                 self.agent.prompt_add_section(**section)
             
-            # Store loaded skill
-            self.loaded_skills[skill_name] = skill_instance
-            self.logger.info(f"Successfully loaded skill '{skill_name}'")
+            # Store loaded skill using instance key
+            self.loaded_skills[instance_key] = skill_instance
+            self.logger.info(f"Successfully loaded skill instance '{instance_key}' (skill: '{skill_name}')")
             return True, ""
             
         except Exception as e:
@@ -107,30 +116,87 @@ class SkillManager:
             self.logger.error(error_msg)
             return False, error_msg
     
-    def unload_skill(self, skill_name: str) -> bool:
-        """Unload a skill and cleanup"""
-        if skill_name not in self.loaded_skills:
-            self.logger.warning(f"Skill '{skill_name}' is not loaded")
+    def unload_skill(self, skill_identifier: str) -> bool:
+        """
+        Unload a skill and cleanup
+        
+        Args:
+            skill_identifier: Either a skill name or an instance key
+            
+        Returns:
+            bool: True if successfully unloaded, False otherwise
+        """
+        # Try to find the skill by identifier (could be skill name or instance key)
+        skill_instance = None
+        instance_key = None
+        
+        # First try as direct instance key
+        if skill_identifier in self.loaded_skills:
+            instance_key = skill_identifier
+            skill_instance = self.loaded_skills[skill_identifier]
+        else:
+            # Try to find by skill name (for backwards compatibility)
+            for key, instance in self.loaded_skills.items():
+                if instance.SKILL_NAME == skill_identifier:
+                    instance_key = key
+                    skill_instance = instance
+                    break
+        
+        if skill_instance is None:
+            self.logger.warning(f"Skill '{skill_identifier}' is not loaded")
             return False
             
         try:
-            skill_instance = self.loaded_skills[skill_name]
             skill_instance.cleanup()
-            del self.loaded_skills[skill_name]
-            self.logger.info(f"Successfully unloaded skill '{skill_name}'")
+            del self.loaded_skills[instance_key]
+            self.logger.info(f"Successfully unloaded skill instance '{instance_key}'")
             return True
         except Exception as e:
-            self.logger.error(f"Error unloading skill '{skill_name}': {e}")
+            self.logger.error(f"Error unloading skill '{skill_identifier}': {e}")
             return False
     
     def list_loaded_skills(self) -> List[str]:
-        """List names of currently loaded skills"""
+        """List instance keys of currently loaded skills"""
         return list(self.loaded_skills.keys())
     
-    def has_skill(self, skill_name: str) -> bool:
-        """Check if skill is currently loaded"""
-        return skill_name in self.loaded_skills
+    def has_skill(self, skill_identifier: str) -> bool:
+        """
+        Check if skill is currently loaded
+        
+        Args:
+            skill_identifier: Either a skill name or an instance key
+            
+        Returns:
+            bool: True if loaded, False otherwise
+        """
+        # First try as direct instance key
+        if skill_identifier in self.loaded_skills:
+            return True
+        
+        # Try to find by skill name (for backwards compatibility)
+        for instance in self.loaded_skills.values():
+            if instance.SKILL_NAME == skill_identifier:
+                return True
+        
+        return False
     
-    def get_skill(self, skill_name: str) -> Optional[SkillBase]:
-        """Get a loaded skill instance by name"""
-        return self.loaded_skills.get(skill_name) 
+    def get_skill(self, skill_identifier: str) -> Optional[SkillBase]:
+        """
+        Get a loaded skill instance by identifier
+        
+        Args:
+            skill_identifier: Either a skill name or an instance key
+            
+        Returns:
+            SkillBase: The skill instance if found, None otherwise
+        """
+        # First try as direct instance key
+        if skill_identifier in self.loaded_skills:
+            return self.loaded_skills[skill_identifier]
+        
+        # Try to find by skill name (for backwards compatibility)
+        for instance in self.loaded_skills.values():
+            if instance.SKILL_NAME == skill_identifier:
+                return instance
+        
+        return None 

signalwire_agents/core/swaig_function.py

@@ -27,7 +27,9 @@ class SWAIGFunction:
         description: str,
         parameters: Dict[str, Dict] = None,
         secure: bool = False,
-        fillers: Optional[Dict[str, List[str]]] = None
+        fillers: Optional[Dict[str, List[str]]] = None,
+        webhook_url: Optional[str] = None,
+        **extra_swaig_fields
     ):
         """
         Initialize a new SWAIG function
@@ -39,6 +41,8 @@ class SWAIGFunction:
             parameters: Dictionary of parameters, keys are parameter names, values are param definitions
             secure: Whether this function requires token validation
             fillers: Optional dictionary of filler phrases by language code
+            webhook_url: Optional external webhook URL to use instead of local handling
+            **extra_swaig_fields: Additional SWAIG fields to include in function definition
         """
         self.name = name
         self.handler = handler
@@ -46,6 +50,11 @@ class SWAIGFunction:
         self.parameters = parameters or {}
         self.secure = secure
         self.fillers = fillers
+        self.webhook_url = webhook_url
+        self.extra_swaig_fields = extra_swaig_fields
+        
+        # Mark as external if webhook_url is provided
+        self.is_external = webhook_url is not None
         
     def _ensure_parameter_structure(self) -> Dict:
         """
@@ -165,6 +174,9 @@ class SWAIGFunction:
         # Add fillers if provided
         if self.fillers and len(self.fillers) > 0:
             function_def["fillers"] = self.fillers
+        
+        # Add any extra SWAIG fields
+        function_def.update(self.extra_swaig_fields)
             
         return function_def
 

signalwire_agents/core/swml_handler.py

@@ -93,17 +93,33 @@ class AIVerbHandler(SWMLVerbHandler):
         """
         errors = []
         
-        # Check required fields
+        # Check that prompt is present
         if "prompt" not in config:
             errors.append("Missing required field 'prompt'")
+            return False, errors
         
-        # Validate prompt structure if present
-        if "prompt" in config:
-            prompt = config["prompt"]
-            if not isinstance(prompt, dict):
-                errors.append("'prompt' must be an object")
-            elif "text" not in prompt and "pom" not in prompt:
-                errors.append("'prompt' must contain either 'text' or 'pom'")
+        prompt = config["prompt"]
+        if not isinstance(prompt, dict):
+            errors.append("'prompt' must be an object")
+            return False, errors
+        
+        # Check that prompt contains one of: text, pom, or contexts
+        has_text = "text" in prompt
+        has_pom = "pom" in prompt
+        has_contexts = "contexts" in prompt
+        
+        options_count = sum([has_text, has_pom, has_contexts])
+        
+        if options_count == 0:
+            errors.append("'prompt' must contain one of: 'text', 'pom', or 'contexts'")
+        elif options_count > 1:
+            errors.append("'prompt' can only contain one of: 'text', 'pom', or 'contexts'")
+        
+        # Validate contexts structure if present
+        if has_contexts:
+            contexts = prompt["contexts"]
+            if not isinstance(contexts, dict):
+                errors.append("'prompt.contexts' must be an object")
         
         # Validate SWAIG structure if present
         if "SWAIG" in config:
@@ -116,6 +132,7 @@ class AIVerbHandler(SWMLVerbHandler):
     def build_config(self, 
                     prompt_text: Optional[str] = None,
                     prompt_pom: Optional[List[Dict[str, Any]]] = None,
+                    contexts: Optional[Dict[str, Any]] = None,
                     post_prompt: Optional[str] = None,
                     post_prompt_url: Optional[str] = None,
                     swaig: Optional[Dict[str, Any]] = None,
@@ -124,8 +141,9 @@ class AIVerbHandler(SWMLVerbHandler):
         Build a configuration for the AI verb
         
         Args:
-            prompt_text: Text prompt for the AI (mutually exclusive with prompt_pom)
-            prompt_pom: POM structure for the AI prompt (mutually exclusive with prompt_text)
+            prompt_text: Text prompt for the AI (mutually exclusive with prompt_pom and contexts)
+            prompt_pom: POM structure for the AI prompt (mutually exclusive with prompt_text and contexts)
+            contexts: Contexts and steps configuration (mutually exclusive with prompt_text and prompt_pom)
             post_prompt: Optional post-prompt text
             post_prompt_url: Optional URL for post-prompt processing
             swaig: Optional SWAIG configuration
@@ -136,13 +154,19 @@ class AIVerbHandler(SWMLVerbHandler):
         """
         config = {}
         
-        # Add prompt (either text or POM)
+        # Add prompt (either text, POM, or contexts - mutually exclusive)
+        prompt_options_count = sum(x is not None for x in [prompt_text, prompt_pom, contexts])
+        if prompt_options_count == 0:
+            raise ValueError("One of prompt_text, prompt_pom, or contexts must be provided")
+        elif prompt_options_count > 1:
+            raise ValueError("prompt_text, prompt_pom, and contexts are mutually exclusive")
+        
         if prompt_text is not None:
             config["prompt"] = {"text": prompt_text}
         elif prompt_pom is not None:
             config["prompt"] = {"pom": prompt_pom}
-        else:
-            raise ValueError("Either prompt_text or prompt_pom must be provided")
+        elif contexts is not None:
+            config["prompt"] = {"contexts": contexts}
         
         # Add post-prompt if provided
         if post_prompt is not None:

signalwire_agents/core/swml_service.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """
 Copyright (c) 2025 SignalWire
 
@@ -7,11 +8,9 @@ Licensed under the MIT License.
 See LICENSE file in the project root for full license information.
 """
 
+# -*- coding: utf-8 -*-
 """
-SWMLService - Base class for SWML document creation and serving
-
-This class provides the foundation for creating and serving SWML documents.
-It handles schema validation, document creation, and web service functionality.
+Base SWML Service for SignalWire Agents
 """
 
 import os
@@ -37,11 +36,11 @@ try:
                 structlog.stdlib.add_logger_name,
                 structlog.stdlib.add_log_level,
                 structlog.stdlib.PositionalArgumentsFormatter(),
-                structlog.processors.TimeStamper(fmt="iso"),
+                structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S"),
                 structlog.processors.StackInfoRenderer(),
                 structlog.processors.format_exc_info,
                 structlog.processors.UnicodeDecoder(),
-                structlog.processors.JSONRenderer()
+                structlog.dev.ConsoleRenderer()
             ],
             context_class=dict,
             logger_factory=structlog.stdlib.LoggerFactory(),
@@ -188,17 +187,21 @@ class SWMLService:
         """
         Create auto-vivified methods for all verbs at initialization time
         """
-        print("Creating auto-vivified methods for all verbs")
+        self.log.debug("creating_verb_methods")
         
         # Get all verb names from the schema
+        if not self.schema_utils:
+            self.log.warning("no_schema_utils_available")
+            return
+            
         verb_names = self.schema_utils.get_all_verb_names()
-        print(f"Found {len(verb_names)} verbs in schema")
+        self.log.debug("found_verbs_in_schema", count=len(verb_names))
         
         # Create a method for each verb
         for verb_name in verb_names:
             # Skip verbs that already have specific methods
             if hasattr(self, verb_name):
-                print(f"Skipping {verb_name} - already has a method")
+                self.log.debug("skipping_verb_has_method", verb=verb_name)
                 continue
             
             # Handle sleep verb specially since it takes an integer directly
@@ -210,7 +213,7 @@ class SWMLService:
                     Args:
                         duration: The amount of time to sleep in milliseconds
                     """
-                    print(f"Executing auto-vivified method for 'sleep'")
+                    self.log.debug("executing_sleep_verb", duration=duration)
                     # Sleep verb takes a direct integer parameter in SWML
                     if duration is not None:
                         return self_instance.add_verb("sleep", duration)
@@ -226,7 +229,7 @@ class SWMLService:
                 # Also cache it for later
                 self._verb_methods_cache[verb_name] = sleep_method
                 
-                print(f"Created special method for {verb_name}")
+                self.log.debug("created_special_method", verb=verb_name)
                 continue
                 
             # Generate the method implementation for normal verbs
@@ -235,7 +238,7 @@ class SWMLService:
                     """
                     Dynamically generated method for SWML verb
                     """
-                    print(f"Executing auto-vivified method for '{name}'")
+                    self.log.debug("executing_verb_method", verb=name, kwargs_count=len(kwargs))
                     config = {}
                     for key, value in kwargs.items():
                         if value is not None:
@@ -260,7 +263,7 @@ class SWMLService:
             # Also cache it for later
             self._verb_methods_cache[verb_name] = method
             
-            print(f"Created method for {verb_name}")
+            self.log.debug("created_verb_method", verb=verb_name)
     
     def __getattr__(self, name: str) -> Any:
         """
@@ -280,21 +283,26 @@ class SWMLService:
         Raises:
             AttributeError: If name is not a valid SWML verb
         """
-        print(f"DEBUG: __getattr__ called for '{name}'")
+        self.log.debug("getattr_called", attribute=name)
         
         # Simple version to match our test script
         # First check if this is a valid SWML verb
+        if not self.schema_utils:
+            msg = f"'{self.__class__.__name__}' object has no attribute '{name}' (no schema available)"
+            self.log.debug("getattr_no_schema", attribute=name)
+            raise AttributeError(msg)
+            
         verb_names = self.schema_utils.get_all_verb_names()
         
         if name in verb_names:
-            print(f"DEBUG: '{name}' is a valid verb")
+            self.log.debug("getattr_valid_verb", verb=name)
             
             # Check if we already have this method in the cache
             if not hasattr(self, '_verb_methods_cache'):
                 self._verb_methods_cache = {}
                 
             if name in self._verb_methods_cache:
-                print(f"DEBUG: Using cached method for '{name}'")
+                self.log.debug("getattr_cached_method", verb=name)
                 return types.MethodType(self._verb_methods_cache[name], self)
             
             # Handle sleep verb specially since it takes an integer directly
@@ -306,7 +314,7 @@ class SWMLService:
                     Args:
                         duration: The amount of time to sleep in milliseconds
                     """
-                    print(f"DEBUG: Executing auto-vivified method for 'sleep'")
+                    self.log.debug("executing_sleep_method", duration=duration)
                     # Sleep verb takes a direct integer parameter in SWML
                     if duration is not None:
                         return self_instance.add_verb("sleep", duration)
@@ -317,7 +325,7 @@ class SWMLService:
                         raise TypeError("sleep() missing required argument: 'duration'")
                 
                 # Cache the method for future use
-                print(f"DEBUG: Caching special method for '{name}'")
+                self.log.debug("caching_sleep_method", verb=name)
                 self._verb_methods_cache[name] = sleep_method
                 
                 # Return the bound method
@@ -328,7 +336,7 @@ class SWMLService:
                 """
                 Dynamically generated method for SWML verb
                 """
-                print(f"DEBUG: Executing auto-vivified method for '{name}'")
+                self.log.debug("executing_dynamic_verb", verb=name, kwargs_count=len(kwargs))
                 config = {}
                 for key, value in kwargs.items():
                     if value is not None:
@@ -343,7 +351,7 @@ class SWMLService:
                 verb_method.__doc__ = f"Add the {name} verb to the document."
             
             # Cache the method for future use
-            print(f"DEBUG: Caching method for '{name}'")
+            self.log.debug("caching_verb_method", verb=name)
             self._verb_methods_cache[name] = verb_method
             
             # Return the bound method
@@ -351,7 +359,7 @@ class SWMLService:
         
         # Not a valid verb
         msg = f"'{self.__class__.__name__}' object has no attribute '{name}'"
-        print(f"DEBUG: {msg}")
+        self.log.debug("getattr_invalid_attribute", attribute=name, error=msg)
         raise AttributeError(msg)
     
     def _find_schema_path(self) -> Optional[str]:
@@ -823,7 +831,7 @@ class SWMLService:
                 route_with_slash = route_path + "/"
                 
                 # Log the incoming path for debugging
-                print(f"Catch-all received: '{full_path}', route: '{route_path}'")
+                self.log.debug("catch_all_route_hit", path=full_path, route=route_path)
                 
                 # Check for exact match to our route (without trailing slash)
                 if full_path == route_path:
@@ -851,21 +859,21 @@ class SWMLService:
                                 return await self._handle_request(request, response)
                 
                 # Not our route or not matching our patterns
-                print(f"No match for path: '{full_path}'")
+                self.log.debug("no_route_match", path=full_path)
                 return {"error": "Path not found"}
             
-            # Print all routes for debugging
-            print(f"All routes for {self.name}:")
+            # Log all routes for debugging
+            self.log.debug("registered_routes", service=self.name)
             for route in app.routes:
                 if hasattr(route, "path"):
-                    print(f"  {route.path}")
+                    self.log.debug("route_registered", path=route.path)
             
             self._app = app
         
         host = host or self.host
         port = port or self.port
         
-        # Print the auth credentials
+        # Get the auth credentials
         username, password = self._basic_auth
         
         # Use correct protocol and host in displayed URL
@@ -878,12 +886,13 @@ class SWMLService:
                      username=username,
                      password_length=len(password))
         
+        # Print user-friendly startup message (keep for UX)
         print(f"Service '{self.name}' is available at:")
         print(f"URL: {protocol}://{display_host}{self.route}")
         print(f"URL with trailing slash: {protocol}://{display_host}{self.route}/")
         print(f"Basic Auth: {username}:{password}")
         
-        # Check if SIP routing is enabled and print additional info
+        # Check if SIP routing is enabled and log additional info
         if self._routing_callbacks:
             print(f"Callback endpoints:")
             for path in self._routing_callbacks:

signalwire_agents/skills/datasphere/__init__.py

@@ -0,0 +1,12 @@
+"""
+Copyright (c) 2025 SignalWire
+
+This file is part of the SignalWire AI Agents SDK.
+
+Licensed under the MIT License.
+See LICENSE file in the project root for full license information.
+"""
+
+from .skill import DataSphereSkill
+
+__all__ = ['DataSphereSkill']