signalwire-agents 0.1.10__py3-none-any.whl → 0.1.12__py3-none-any.whl

signalwire_agents/skills/wikipedia/skill.py

@@ -0,0 +1,180 @@
+"""
+Wikipedia Search Skill
+
+Provides Wikipedia search capabilities using the Wikipedia API.
+"""
+
+import requests
+from urllib.parse import quote
+from typing import Dict, Any, Optional
+from signalwire_agents.core.skill_base import SkillBase
+
+
+class WikipediaSearchSkill(SkillBase):
+    """
+    Skill for searching Wikipedia articles and retrieving content.
+    
+    This skill uses the Wikipedia API to search for articles and retrieve
+    their introductory content, similar to getting a summary of a topic.
+    """
+    
+    # Skill metadata
+    SKILL_NAME = "wikipedia_search"
+    SKILL_DESCRIPTION = "Search Wikipedia for information about a topic and get article summaries"
+    SKILL_VERSION = "1.0.0"
+    REQUIRED_PACKAGES = ["requests"]
+    REQUIRED_ENV_VARS = []  # No environment variables required
+    
+    # Does not support multiple instances
+    SUPPORTS_MULTIPLE_INSTANCES = False
+    
+    def setup(self) -> bool:
+        """
+        Setup the Wikipedia search skill.
+        
+        Returns:
+            True if setup successful, False otherwise
+        """
+        # Extract configuration from params
+        self.num_results = max(1, self.params.get('num_results', 1))  # Ensure at least 1 result
+        self.no_results_message = self.params.get('no_results_message') or (
+            "I couldn't find any Wikipedia articles for '{query}'. "
+            "Try rephrasing your search or using different keywords."
+        )
+        
+        # Validate that requests package is available
+        if not self.validate_packages():
+            return False
+            
+        self.logger.info(f"Wikipedia search skill initialized with {self.num_results} max results")
+        return True
+    
+    def register_tools(self) -> None:
+        """
+        Register the SWAIG tool for Wikipedia search.
+        """
+        self.agent.define_tool(
+            name="search_wiki",
+            description="Search Wikipedia for information about a topic and get article summaries",
+            parameters={
+                "query": {
+                    "type": "string",
+                    "description": "The search term or topic to look up on Wikipedia"
+                }
+            },
+            handler=self._search_wiki_handler,
+            **self.swaig_fields
+        )
+    
+    def _search_wiki_handler(self, args, raw_data):
+        """Handler for search_wiki tool"""
+        from signalwire_agents.core.function_result import SwaigFunctionResult
+        
+        query = args.get("query", "").strip()
+        if not query:
+            return SwaigFunctionResult("Please provide a search query for Wikipedia.")
+        
+        result = self.search_wiki(query)
+        return SwaigFunctionResult(result)
+    
+    def search_wiki(self, query: str) -> str:
+        """
+        Search Wikipedia for articles matching the query.
+        
+        Args:
+            query: The search term to look up
+            
+        Returns:
+            String containing the Wikipedia article content or error message
+        """
+        try:
+            # Step 1: Search for articles matching the query
+            search_url = (
+                "https://en.wikipedia.org/w/api.php"
+                "?action=query&list=search&format=json"
+                f"&srsearch={quote(query)}"
+                f"&srlimit={self.num_results}"
+            )
+            
+            response = requests.get(search_url, timeout=10)
+            response.raise_for_status()
+            search_data = response.json()
+            
+            # Check if we got any search results
+            search_results = search_data.get('query', {}).get('search', [])
+            if not search_results:
+                return self.no_results_message.format(query=query)
+            
+            # Step 2: Get article extracts for each result
+            articles = []
+            for i, result in enumerate(search_results[:self.num_results]):
+                title = result['title']
+                
+                # Get the page extract
+                extract_url = (
+                    "https://en.wikipedia.org/w/api.php"
+                    "?action=query&prop=extracts&exintro&explaintext&format=json"
+                    f"&titles={quote(title)}"
+                )
+                
+                extract_response = requests.get(extract_url, timeout=10)
+                extract_response.raise_for_status()
+                extract_data = extract_response.json()
+                
+                # Get the first (and only) page from the response
+                pages = extract_data.get('query', {}).get('pages', {})
+                if pages:
+                    page = next(iter(pages.values()))
+                    extract = page.get('extract', '').strip()
+                    
+                    if extract:
+                        # Format the article with title and content
+                        articles.append(f"**{title}**\n\n{extract}")
+                    else:
+                        # Handle case where extract is empty
+                        articles.append(f"**{title}**\n\nNo summary available for this article.")
+            
+            if not articles:
+                return self.no_results_message.format(query=query)
+            
+            # Join multiple articles with separators
+            if len(articles) == 1:
+                return articles[0]
+            else:
+                return "\n\n" + "="*50 + "\n\n".join(articles)
+                
+        except requests.exceptions.RequestException as e:
+            return f"Error accessing Wikipedia: {str(e)}"
+        except Exception as e:
+            return f"Error searching Wikipedia: {str(e)}"
+    
+    def get_prompt_sections(self) -> list:
+        """
+        Return additional context for the agent prompt.
+        
+        Returns:
+            List of prompt sections to add to the agent
+        """
+        return [{
+            "title": "Wikipedia Search",
+            "body": f"You can search Wikipedia for factual information using search_wiki. This will return up to {self.num_results} Wikipedia article summaries.",
+            "bullets": [
+                "Use search_wiki for factual, encyclopedic information",
+                "Great for answering questions about people, places, concepts, and history",
+                "Returns reliable, well-sourced information from Wikipedia articles"
+            ]
+        }]
+    
+    def get_hints(self) -> list:
+        """
+        Return speech recognition hints for better accuracy.
+        
+        Returns:
+            List of words/phrases to help with speech recognition
+        """
+        # Currently no hints provided, but you could add them like:
+        # return [
+        #     "Wikipedia", "wiki", "search Wikipedia", "look up", "tell me about",
+        #     "what is", "who is", "information about", "facts about"
+        # ]
+        return [] 

signalwire_agents/utils/__init__.py

@@ -7,3 +7,17 @@ Licensed under the MIT License.
 See LICENSE file in the project root for full license information.
 """
 
+from .schema_utils import SchemaUtils
+from signalwire_agents.core.logging_config import get_execution_mode
+
+def is_serverless_mode() -> bool:
+    """
+    Check if running in any serverless environment.
+    
+    Returns:
+        bool: True if in serverless mode, False if in server mode
+    """
+    return get_execution_mode() != 'server'
+
+__all__ = ["SchemaUtils", "get_execution_mode", "is_serverless_mode"]
+

signalwire_agents/utils/schema_utils.py

@@ -1,3 +1,4 @@
+#!/usr/bin/env python3
 """
 Copyright (c) 2025 SignalWire
 
@@ -7,62 +8,129 @@ Licensed under the MIT License.
 See LICENSE file in the project root for full license information.
 """
 
+# -*- coding: utf-8 -*-
 """
-Utilities for working with the SWML JSON schema.
-
-This module provides functions for loading, parsing, and validating SWML schemas.
-It also provides utilities for working with SWML documents based on the schema.
+Schema utilities for SWML validation and verb extraction
 """
 
-import json
 import os
-import re
-from typing import Dict, List, Any, Optional, Set, Tuple, Callable
+import json
+import logging
+from typing import Dict, Any, List, Optional, Tuple
 
+try:
+    import structlog
+    # Ensure structlog is configured
+    if not structlog.is_configured():
+        structlog.configure(
+            processors=[
+                structlog.stdlib.filter_by_level,
+                structlog.stdlib.add_logger_name,
+                structlog.stdlib.add_log_level,
+                structlog.stdlib.PositionalArgumentsFormatter(),
+                structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S"),
+                structlog.processors.StackInfoRenderer(),
+                structlog.processors.format_exc_info,
+                structlog.processors.UnicodeDecoder(),
+                structlog.dev.ConsoleRenderer()
+            ],
+            context_class=dict,
+            logger_factory=structlog.stdlib.LoggerFactory(),
+            wrapper_class=structlog.stdlib.BoundLogger,
+            cache_logger_on_first_use=True,
+        )
+except ImportError:
+    raise ImportError(
+        "structlog is required. Install it with: pip install structlog"
+    )
+
+# Create a logger
+logger = structlog.get_logger("schema_utils")
 
 class SchemaUtils:
     """
-    Utilities for working with SWML JSON schema.
-    
-    This class provides methods for:
-    - Loading and parsing schema files
-    - Extracting verb definitions
-    - Validating SWML objects against the schema
-    - Generating helpers for schema operations
+    Utility class for loading and working with SWML schemas
     """
     
     def __init__(self, schema_path: Optional[str] = None):
         """
-        Initialize the SchemaUtils with the provided schema
+        Initialize the schema utilities
         
         Args:
-            schema_path: Path to the schema file (optional)
+            schema_path: Path to the schema file
         """
+        self.log = logger.bind(component="schema_utils")
+        
         self.schema_path = schema_path
         if not self.schema_path:
             self.schema_path = self._get_default_schema_path()
-            print(f"No schema_path provided, using default: {self.schema_path}")
+            self.log.debug("using_default_schema_path", path=self.schema_path)
         
         self.schema = self.load_schema()
         self.verbs = self._extract_verb_definitions()
-        print(f"Extracted {len(self.verbs)} verbs from schema")
+        self.log.debug("schema_initialized", verb_count=len(self.verbs))
         if self.verbs:
-            print(f"First few verbs: {list(self.verbs.keys())[:5]}")
+            self.log.debug("first_verbs_extracted", verbs=list(self.verbs.keys())[:5])
         
-    def _get_default_schema_path(self) -> str:
+    def _get_default_schema_path(self) -> Optional[str]:
         """
-        Get the default path to the schema file
+        Get the default path to the schema file using the same robust logic as SWMLService
         
         Returns:
-            Path to the schema file
+            Path to the schema file or None if not found
         """
-        # Default path is the schema.json in the root directory
-        package_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-        default_path = os.path.join(package_dir, "schema.json")
-        print(f"Default schema path: {default_path}")
-        print(f"Path exists: {os.path.exists(default_path)}")
-        
-        return default_path
+        # Try package resources first (most reliable after pip install)
+        try:
+            import importlib.resources
+            try:
+                # Python 3.9+
+                try:
+                    # Python 3.13+
+                    path = importlib.resources.files("signalwire_agents").joinpath("schema.json")
+                    return str(path)
+                except Exception:
+                    # Python 3.9-3.12
+                    with importlib.resources.files("signalwire_agents").joinpath("schema.json") as path:
+                        return str(path)
+            except AttributeError:
+                # Python 3.7-3.8
+                with importlib.resources.path("signalwire_agents", "schema.json") as path:
+                    return str(path)
+        except (ImportError, ModuleNotFoundError):
+            pass
+            
+        # Fall back to pkg_resources for older Python or alternative lookup
+        try:
+            import pkg_resources
+            return pkg_resources.resource_filename("signalwire_agents", "schema.json")
+        except (ImportError, ModuleNotFoundError, pkg_resources.DistributionNotFound):
+            pass
+
+        # Fall back to manual search in various locations
+        import sys
+        
+        # Get package directory relative to this file
+        package_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        
+        # Potential locations for schema.json
+        potential_paths = [
+            os.path.join(os.getcwd(), "schema.json"),  # Current working directory
+            os.path.join(package_dir, "schema.json"),  # Package directory
+            os.path.join(os.path.dirname(package_dir), "schema.json"),  # Parent of package directory
+            os.path.join(sys.prefix, "schema.json"),  # Python installation directory
+            os.path.join(package_dir, "data", "schema.json"),  # Data subdirectory
+            os.path.join(os.path.dirname(package_dir), "data", "schema.json"),  # Parent's data subdirectory
+        ]
+        
+        # Try to find the schema file
+        for path in potential_paths:
+            self.log.debug("checking_schema_path", path=path, exists=os.path.exists(path))
+            if os.path.exists(path):
+                self.log.debug("schema_found_at", path=path)
+                return path
+        
+        self.log.warning("schema_not_found_in_any_location")
+        return None
         
     def load_schema(self) -> Dict[str, Any]:
         """
@@ -72,27 +140,26 @@ class SchemaUtils:
             The schema as a dictionary
         """
         if not self.schema_path:
-            print(f"Warning: No schema path provided. Using empty schema.")
+            self.log.warning("no_schema_path_provided")
             return {}
             
         try:
-            print(f"Attempting to load schema from: {self.schema_path}")
-            print(f"File exists: {os.path.exists(self.schema_path)}")
+            self.log.debug("loading_schema", path=self.schema_path, exists=os.path.exists(self.schema_path))
             
             if os.path.exists(self.schema_path):
                 with open(self.schema_path, "r") as f:
                     schema = json.load(f)
-                print(f"Successfully loaded schema from {self.schema_path}")
-                print(f"Schema has {len(schema.keys()) if schema else 0} top-level keys")
+                self.log.debug("schema_loaded_successfully", 
+                              path=self.schema_path,
+                              top_level_keys=len(schema.keys()) if schema else 0)
                 if "$defs" in schema:
-                    print(f"Schema has {len(schema['$defs'])} definitions")
+                    self.log.debug("schema_definitions_found", count=len(schema['$defs']))
                 return schema
             else:
-                print(f"Schema file not found at {self.schema_path}")
+                self.log.error("schema_file_not_found", path=self.schema_path)
                 return {}
         except (FileNotFoundError, json.JSONDecodeError) as e:
-            print(f"Error loading schema: {e}")
-            print(f"Using empty schema as fallback")
+            self.log.error("schema_loading_error", error=str(e), path=self.schema_path)
             return {}
     
     def _extract_verb_definitions(self) -> Dict[str, Dict[str, Any]]:
@@ -107,17 +174,17 @@ class SchemaUtils:
         # Extract from SWMLMethod anyOf
         if "$defs" in self.schema and "SWMLMethod" in self.schema["$defs"]:
             swml_method = self.schema["$defs"]["SWMLMethod"]
-            print(f"Found SWMLMethod in schema with keys: {swml_method.keys()}")
+            self.log.debug("swml_method_found", keys=list(swml_method.keys()))
             
             if "anyOf" in swml_method:
-                print(f"Found anyOf in SWMLMethod with {len(swml_method['anyOf'])} items")
+                self.log.debug("anyof_found", count=len(swml_method['anyOf']))
                 
                 for ref in swml_method["anyOf"]:
                     if "$ref" in ref:
                         # Extract the verb name from the reference
                         verb_ref = ref["$ref"]
                         verb_name = verb_ref.split("/")[-1]
-                        print(f"Processing verb reference: {verb_ref} -> {verb_name}")
+                        self.log.debug("processing_verb_reference", ref=verb_ref, name=verb_name)
                         
                         # Look up the verb definition
                         if verb_name in self.schema["$defs"]:
@@ -133,11 +200,11 @@ class SchemaUtils:
                                         "schema_name": verb_name,
                                         "definition": verb_def
                                     }
-                                    print(f"Added verb: {actual_verb}")
+                                    self.log.debug("verb_added", verb=actual_verb)
         else:
-            print(f"Missing $defs or SWMLMethod in schema")
+            self.log.warning("missing_swml_method_or_defs")
             if "$defs" in self.schema:
-                print(f"Available definitions: {list(self.schema['$defs'].keys())}")
+                self.log.debug("available_definitions", defs=list(self.schema['$defs'].keys()))
         
         return verbs