signalwire-agents 0.1.6__py3-none-any.whl → 1.0.7__py3-none-any.whl

signalwire_agents/skills/wikipedia_search/README.md

@@ -0,0 +1,228 @@
+# Wikipedia Search Skill
+
+The Wikipedia Search skill provides agents with the ability to search Wikipedia articles and retrieve factual information. This skill uses the Wikipedia API to search for articles and return their introductory content, making it perfect for answering factual questions about people, places, concepts, and more.
+
+## Features
+
+- **Free Wikipedia API**: No API keys or credentials required
+- **Article Summaries**: Returns introductory content from Wikipedia articles
+- **Multiple Results**: Can return multiple article summaries for broader topics
+- **Customizable Messages**: Custom no-results messages with query placeholders
+- **Error Handling**: Graceful handling of network errors and API issues
+- **Speech Recognition**: Includes hints for better voice recognition accuracy
+
+## Requirements
+
+- **Python Packages**: `requests` (automatically installed with SignalWire Agents)
+- **API Keys**: None required - uses free Wikipedia API
+- **Environment Variables**: None required
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `num_results` | int | 1 | Number of Wikipedia articles to return (minimum: 1) |
+| `no_results_message` | str | Auto-generated | Custom message when no results found. Use `{query}` as placeholder |
+| `swaig_fields` | dict | {} | Additional SWAIG function configuration (fillers, etc.) |
+
+## Tools Created
+
+This skill creates one SWAIG tool:
+
+### `search_wiki`
+- **Description**: Search Wikipedia for information about a topic and get article summaries
+- **Parameters**:
+  - `query` (string, required): The search term or topic to look up on Wikipedia
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+from signalwire_agents import AgentBase
+
+agent = AgentBase("Wikipedia Assistant")
+
+# Add Wikipedia search with default settings
+agent.add_skill("wikipedia_search")
+```
+
+### Custom Configuration
+
+```python
+# Custom number of results and no-results message
+agent.add_skill("wikipedia_search", {
+    "num_results": 2,  # Return up to 2 articles
+    "no_results_message": "Sorry, I couldn't find any Wikipedia articles about '{query}'. Try different keywords or check the spelling."
+})
+```
+
+### With SWAIG Fields (Fillers)
+
+```python
+# Add custom fillers for better user experience
+agent.add_skill("wikipedia_search", {
+    "num_results": 1,
+    "swaig_fields": {
+        "fillers": {
+            "en-US": [
+                "Let me check Wikipedia for that...",
+                "Searching Wikipedia...",
+                "Looking that up on Wikipedia...",
+                "Checking the encyclopedia..."
+            ]
+        }
+    }
+})
+```
+
+### Advanced Configuration
+
+```python
+# Full configuration example
+agent.add_skill("wikipedia_search", {
+    "num_results": 3,
+    "no_results_message": "I searched Wikipedia but couldn't find information about '{query}'. You might want to try rephrasing your question or searching for related topics.",
+    "swaig_fields": {
+        "fillers": {
+            "en-US": [
+                "Searching Wikipedia for factual information...",
+                "Let me look that up in the encyclopedia...",
+                "Checking Wikipedia's knowledge base..."
+            ]
+        },
+        "meta": {
+            "description": "Search Wikipedia for reliable, factual information"
+        }
+    }
+})
+```
+
+## Multiple Instance Support
+
+**This skill does NOT support multiple instances.** You can only load one instance of the Wikipedia search skill per agent. This is because:
+
+- Wikipedia search is a general-purpose tool that doesn't need specialization
+- The tool name `search_wiki` is fixed and meaningful
+- Multiple instances would create confusion without added benefit
+
+If you need different Wikipedia search behaviors, use the `num_results` parameter to control the scope of results.
+
+## API Details
+
+The skill uses the Wikipedia API with two steps:
+
+1. **Search**: Uses the `action=query&list=search` endpoint to find matching articles
+2. **Extract**: Uses the `action=query&prop=extracts` endpoint to get article summaries
+
+### Search Process
+
+```
+1. Search for articles matching the query
+   → GET https://en.wikipedia.org/w/api.php?action=query&list=search&format=json&srsearch={query}&srlimit={num_results}
+
+2. For each result, get the article extract
+   → GET https://en.wikipedia.org/w/api.php?action=query&prop=extracts&exintro&explaintext&format=json&titles={title}
+
+3. Format and return the results
+```
+
+## Response Format
+
+### Single Result
+```
+**Article Title**
+
+Article content summary...
+```
+
+### Multiple Results
+```
+**First Article Title**
+
+First article content summary...
+
+==================================================
+
+**Second Article Title**
+
+Second article content summary...
+```
+
+## Error Handling
+
+The skill handles various error conditions gracefully:
+
+- **No Results**: Returns the custom `no_results_message` with the query
+- **Network Errors**: Returns "Error accessing Wikipedia: {error details}"
+- **API Errors**: Returns "Error searching Wikipedia: {error details}"
+- **Empty Extracts**: Returns "No summary available for this article"
+
+## Speech Recognition Hints
+
+The skill provides these hints to improve voice recognition:
+
+- "Wikipedia"
+- "wiki" 
+- "search Wikipedia"
+- "look up"
+- "tell me about"
+- "what is"
+- "who is"
+- "information about"
+- "facts about"
+
+## Best Practices
+
+### Query Optimization
+- Use specific terms for better results
+- Try both full names and common names (e.g., "Einstein" vs "Albert Einstein")
+- For disambiguation, be more specific (e.g., "Python programming language" vs "Python")
+
+### Result Management
+- Use `num_results: 1` for specific factual queries
+- Use `num_results: 2-3` for broader topics that might have multiple relevant articles
+- Avoid very high numbers as it can overwhelm users
+
+### Error Messages
+- Customize `no_results_message` to match your agent's personality
+- Include suggestions for alternative searches
+- Use the `{query}` placeholder to reference what the user searched for
+
+### Integration Tips
+- Combine with web search for comprehensive information gathering
+- Use for factual verification of claims
+- Great for educational and reference applications
+
+## Example Conversations
+
+**User**: "Tell me about quantum physics"
+**Agent**: *Searching Wikipedia...* "Here's what I found about quantum physics: **Quantum mechanics** - Quantum mechanics is a fundamental theory that describes the behavior of nature at and below the scale of atoms..."
+
+**User**: "Who was Marie Curie?"
+**Agent**: *Let me check Wikipedia for that...* "**Marie Curie** - Marie Salomea Skłodowska-Curie was a Polish and naturalized-French physicist and chemist who conducted pioneering research on radioactivity..."
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Skill not loading**: Ensure `requests` package is installed
+2. **No results for valid topics**: Try different search terms or check spelling
+3. **Network timeouts**: The skill has a 10-second timeout for API calls
+
+### Debug Information
+
+The skill logs initialization and search activities:
+```
+Wikipedia search skill initialized with {num_results} max results
+```
+
+Enable debug logging to see detailed API interactions and error information.
+
+## Related Skills
+
+- **web_search**: For current information and broader web content
+- **datasphere**: For searching custom knowledge bases
+- **datetime**: For current date/time context in historical queries
+
+The Wikipedia skill is perfect for factual, encyclopedic information, while web search is better for current events and specific products/services. 

signalwire_agents/{core/state → skills/wikipedia_search}/__init__.py

@@ -8,10 +8,11 @@ See LICENSE file in the project root for full license information.
 """
 
 """
-State management for SignalWire AI Agents
+Wikipedia Search Skill
+
+This skill provides Wikipedia search capabilities using the Wikipedia API.
 """
 
-from .state_manager import StateManager
-from .file_state_manager import FileStateManager
+from .skill import WikipediaSearchSkill
 
-__all__ = ['StateManager', 'FileStateManager'] 
+__all__ = ['WikipediaSearchSkill'] 

signalwire_agents/skills/wikipedia_search/skill.py

@@ -0,0 +1,210 @@
+"""
+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.
+"""
+
+"""
+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
+    
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for Wikipedia search skill"""
+        schema = super().get_parameter_schema()
+        schema.update({
+            "num_results": {
+                "type": "integer",
+                "description": "Maximum number of Wikipedia articles to return",
+                "default": 1,
+                "required": False,
+                "minimum": 1,
+                "maximum": 5
+            },
+            "no_results_message": {
+                "type": "string",
+                "description": "Custom message when no Wikipedia articles are found",
+                "default": "I couldn't find any Wikipedia articles for '{query}'. Try rephrasing your search or using different keywords.",
+                "required": False
+            }
+        })
+        return schema
+    
+    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.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
+        )
+    
+    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"]
+