signalwire-agents 0.1.37__py3-none-any.whl → 0.1.38__py3-none-any.whl

signalwire_agents/skills/native_vector_search/README.md

@@ -0,0 +1,210 @@
+# Native Vector Search Skill
+
+The Native Vector Search skill provides document search capabilities using vector similarity and keyword search. It supports multiple storage backends including SQLite (local files) and PostgreSQL with pgvector extension.
+
+## Features
+
+- **Hybrid Search**: Combines vector similarity and keyword search for better results
+- **Multiple Backends**: SQLite for local deployment, pgvector for scalable production use
+- **Remote Search**: Connect to remote search servers
+- **Auto-indexing**: Automatically build indexes from source directories
+- **NLP Enhancement**: Query expansion and synonym matching
+- **Tag Filtering**: Filter results by document tags
+
+## Backends
+
+### SQLite Backend (Default)
+- Stores indexes in `.swsearch` files
+- Good for single-agent deployments
+- Portable and self-contained
+- No external dependencies
+
+### pgvector Backend
+- Uses PostgreSQL with pgvector extension
+- Scalable for multi-agent deployments
+- Real-time updates capability
+- Efficient similarity search with specialized indexes
+
+### Remote Search Server
+- Connect to centralized search API
+- Lower memory usage per agent
+- Shared knowledge base
+
+## Configuration Parameters
+
+### Basic Parameters
+- `tool_name`: Name of the search tool (default: "search_knowledge")
+- `description`: Tool description for the AI
+- `count`: Number of results to return (default: 5)
+- `distance_threshold`: Minimum similarity score (default: 0.0)
+- `tags`: Filter results by these tags
+
+### Backend Selection
+- `backend`: Storage backend - "sqlite" or "pgvector" (default: "sqlite")
+
+### SQLite Backend
+- `index_file`: Path to .swsearch index file
+- `build_index`: Auto-build index from source (default: false)
+- `source_dir`: Directory to index if build_index=true
+
+### pgvector Backend
+- `connection_string`: PostgreSQL connection string (required)
+- `collection_name`: Name of the collection to search (required)
+
+### Remote Backend
+- `remote_url`: URL of remote search server
+- `index_name`: Name of index on remote server
+
+### Response Formatting
+- `response_prefix`: Text to prepend to results
+- `response_postfix`: Text to append to results
+- `no_results_message`: Message when no results found
+
+### NLP Configuration
+- `query_nlp_backend`: NLP backend for queries ("nltk" or "spacy")
+- `index_nlp_backend`: NLP backend for indexing ("nltk" or "spacy")
+
+## Usage Examples
+
+### SQLite Backend (Local File)
+```python
+agent.add_skill("native_vector_search", {
+    "tool_name": "search_docs",
+    "description": "Search technical documentation",
+    "index_file": "docs.swsearch",
+    "count": 5
+})
+```
+
+### pgvector Backend (PostgreSQL)
+```python
+agent.add_skill("native_vector_search", {
+    "tool_name": "search_knowledge",
+    "description": "Search the knowledge base",
+    "backend": "pgvector",
+    "connection_string": "postgresql://user:pass@localhost:5432/knowledge",
+    "collection_name": "docs_collection",
+    "count": 5
+})
+```
+
+### Remote Search Server
+```python
+agent.add_skill("native_vector_search", {
+    "tool_name": "search_api",
+    "description": "Search API documentation",
+    "remote_url": "http://search-server:8001",
+    "index_name": "api_docs"
+})
+```
+
+### Auto-build Index
+```python
+agent.add_skill("native_vector_search", {
+    "tool_name": "search_local",
+    "build_index": True,
+    "source_dir": "./documentation",
+    "file_types": ["md", "txt"],
+    "index_file": "auto_docs.swsearch"
+})
+```
+
+### Multiple Search Instances
+```python
+# Documentation search
+agent.add_skill("native_vector_search", {
+    "tool_name": "search_docs",
+    "index_file": "docs.swsearch",
+    "description": "Search documentation"
+})
+
+# Code examples search
+agent.add_skill("native_vector_search", {
+    "tool_name": "search_examples",
+    "backend": "pgvector",
+    "connection_string": "postgresql://localhost/knowledge",
+    "collection_name": "examples",
+    "description": "Search code examples"
+})
+```
+
+## Installation
+
+### For SQLite Backend
+```bash
+pip install signalwire-agents[search]
+```
+
+### For pgvector Backend
+```bash
+pip install signalwire-agents[search,pgvector]
+```
+
+### For All Features
+```bash
+pip install signalwire-agents[search-all]
+```
+
+## Building Indexes
+
+### Using sw-search CLI
+
+#### SQLite Backend
+```bash
+sw-search ./docs --output docs.swsearch
+```
+
+#### pgvector Backend
+```bash
+sw-search ./docs \
+  --backend pgvector \
+  --connection-string "postgresql://localhost/knowledge" \
+  --output docs_collection
+```
+
+## Performance Considerations
+
+### SQLite
+- Fast for small to medium datasets (<100k documents)
+- Linear search for vector similarity
+- Single-file deployment
+
+### pgvector
+- Efficient for large datasets
+- Uses IVFFlat or HNSW indexes
+- Handles concurrent access well
+- Requires PostgreSQL server
+
+### NLP Backends
+- `nltk`: Fast, good for most use cases (~50-100ms)
+- `spacy`: Better quality, slower (~150-300ms)
+
+## Environment Variables
+
+None required - all configuration comes through skill parameters.
+
+## Troubleshooting
+
+### "Search dependencies not available"
+Install the search extras:
+```bash
+pip install signalwire-agents[search]
+```
+
+### "pgvector dependencies not available"
+Install pgvector support:
+```bash
+pip install signalwire-agents[pgvector]
+```
+
+### "Failed to connect to pgvector"
+1. Ensure PostgreSQL is running
+2. Check connection string
+3. Verify pgvector extension is installed
+4. Check collection exists
+
+### Poor Search Results
+1. Try different NLP backends
+2. Adjust distance_threshold
+3. Check document preprocessing
+4. Verify index quality

signalwire_agents/skills/native_vector_search/skill.py

@@ -28,6 +28,174 @@ class NativeVectorSearchSkill(SkillBase):
     # Enable multiple instances support
     SUPPORTS_MULTIPLE_INSTANCES = True
     
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for Native Vector Search skill
+        
+        This skill supports three modes of operation:
+        1. Network Mode: Set 'remote_url' to connect to a remote search server
+        2. Local pgvector: Set backend='pgvector' with connection_string and collection_name
+        3. Local SQLite: Set 'index_file' to use a local .swsearch file (default)
+        """
+        schema = super().get_parameter_schema()
+        schema.update({
+            "index_file": {
+                "type": "string",
+                "description": "Path to .swsearch index file (SQLite backend only). Use this for local file-based search",
+                "required": False
+            },
+            "build_index": {
+                "type": "boolean",
+                "description": "Whether to build index from source files",
+                "default": False,
+                "required": False
+            },
+            "source_dir": {
+                "type": "string",
+                "description": "Directory containing documents to index (required if build_index=True)",
+                "required": False
+            },
+            "remote_url": {
+                "type": "string",
+                "description": "URL of remote search server for network mode (e.g., http://localhost:8001). Use this instead of index_file or pgvector for centralized search",
+                "required": False
+            },
+            "index_name": {
+                "type": "string",
+                "description": "Name of index on remote server (network mode only, used with remote_url)",
+                "default": "default",
+                "required": False
+            },
+            "count": {
+                "type": "integer",
+                "description": "Number of search results to return",
+                "default": 5,
+                "required": False,
+                "minimum": 1,
+                "maximum": 20
+            },
+            "distance_threshold": {
+                "type": "number",
+                "description": "Maximum distance threshold for results (0.0 = no limit)",
+                "default": 0.0,
+                "required": False,
+                "minimum": 0.0,
+                "maximum": 1.0
+            },
+            "tags": {
+                "type": "array",
+                "description": "Tags to filter search results",
+                "default": [],
+                "required": False,
+                "items": {
+                    "type": "string"
+                }
+            },
+            "global_tags": {
+                "type": "array",
+                "description": "Tags to apply to all indexed documents",
+                "default": [],
+                "required": False,
+                "items": {
+                    "type": "string"
+                }
+            },
+            "file_types": {
+                "type": "array",
+                "description": "File extensions to include when building index",
+                "default": ["md", "txt", "pdf", "docx", "html"],
+                "required": False,
+                "items": {
+                    "type": "string"
+                }
+            },
+            "exclude_patterns": {
+                "type": "array",
+                "description": "Patterns to exclude when building index",
+                "default": ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/build/**"],
+                "required": False,
+                "items": {
+                    "type": "string"
+                }
+            },
+            "no_results_message": {
+                "type": "string",
+                "description": "Message when no results are found",
+                "default": "No information found for '{query}'",
+                "required": False
+            },
+            "response_prefix": {
+                "type": "string",
+                "description": "Prefix to add to search results",
+                "default": "",
+                "required": False
+            },
+            "response_postfix": {
+                "type": "string",
+                "description": "Postfix to add to search results",
+                "default": "",
+                "required": False
+            },
+            "description": {
+                "type": "string",
+                "description": "Tool description",
+                "default": "Search the knowledge base for information",
+                "required": False
+            },
+            "hints": {
+                "type": "array",
+                "description": "Speech recognition hints",
+                "default": [],
+                "required": False,
+                "items": {
+                    "type": "string"
+                }
+            },
+            "nlp_backend": {
+                "type": "string",
+                "description": "NLP backend for query processing",
+                "default": "basic",
+                "required": False,
+                "enum": ["basic", "spacy", "nltk"]
+            },
+            "query_nlp_backend": {
+                "type": "string",
+                "description": "NLP backend for query expansion",
+                "required": False,
+                "enum": ["basic", "spacy", "nltk"]
+            },
+            "index_nlp_backend": {
+                "type": "string",
+                "description": "NLP backend for indexing",
+                "required": False,
+                "enum": ["basic", "spacy", "nltk"]
+            },
+            "backend": {
+                "type": "string",
+                "description": "Storage backend for local database mode: 'sqlite' for file-based or 'pgvector' for PostgreSQL. Ignored if remote_url is set",
+                "default": "sqlite",
+                "required": False,
+                "enum": ["sqlite", "pgvector"]
+            },
+            "connection_string": {
+                "type": "string",
+                "description": "PostgreSQL connection string (pgvector backend only, e.g., 'postgresql://user:pass@localhost:5432/dbname'). Required when backend='pgvector'",
+                "required": False
+            },
+            "collection_name": {
+                "type": "string",
+                "description": "Collection/table name in PostgreSQL (pgvector backend only). Required when backend='pgvector'",
+                "required": False
+            },
+            "verbose": {
+                "type": "boolean",
+                "description": "Enable verbose logging",
+                "default": False,
+                "required": False
+            }
+        })
+        return schema
+    
     def get_instance_key(self) -> str:
         """
         Get the key used to track this skill instance
@@ -43,6 +211,9 @@ class NativeVectorSearchSkill(SkillBase):
         
         # Get configuration first
         self.tool_name = self.params.get('tool_name', 'search_knowledge')
+        self.backend = self.params.get('backend', 'sqlite')
+        self.connection_string = self.params.get('connection_string')
+        self.collection_name = self.params.get('collection_name')
         self.index_file = self.params.get('index_file')
         self.build_index = self.params.get('build_index', False)
         self.source_dir = self.params.get('source_dir')
@@ -153,13 +324,32 @@ class NativeVectorSearchSkill(SkillBase):
         
         # Initialize local search engine
         self.search_engine = None
-        if self.search_available and self.index_file and os.path.exists(self.index_file):
-            try:
-                from signalwire_agents.search import SearchEngine
-                self.search_engine = SearchEngine(self.index_file)
-            except Exception as e:
-                self.logger.error(f"Failed to load search index {self.index_file}: {e}")
-                self.search_available = False
+        if self.search_available:
+            if self.backend == 'pgvector':
+                # Initialize pgvector backend
+                if self.connection_string and self.collection_name:
+                    try:
+                        from signalwire_agents.search import SearchEngine
+                        self.search_engine = SearchEngine(
+                            backend='pgvector',
+                            connection_string=self.connection_string,
+                            collection_name=self.collection_name
+                        )
+                        self.logger.info(f"Connected to pgvector collection: {self.collection_name}")
+                    except Exception as e:
+                        self.logger.error(f"Failed to connect to pgvector: {e}")
+                        self.search_available = False
+                else:
+                    self.logger.error("pgvector backend requires connection_string and collection_name")
+                    self.search_available = False
+            elif self.index_file and os.path.exists(self.index_file):
+                # Initialize SQLite backend
+                try:
+                    from signalwire_agents.search import SearchEngine
+                    self.search_engine = SearchEngine(backend='sqlite', index_path=self.index_file)
+                except Exception as e:
+                    self.logger.error(f"Failed to load search index {self.index_file}: {e}")
+                    self.search_available = False
         
         return True
         

signalwire_agents/skills/play_background_file/skill.py

@@ -48,6 +48,42 @@ class PlayBackgroundFileSkill(SkillBase):
     SKILL_DESCRIPTION = "Control background file playback"
     SUPPORTS_MULTIPLE_INSTANCES = True
     
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for Play Background File skill"""
+        schema = super().get_parameter_schema()
+        schema.update({
+            "files": {
+                "type": "array",
+                "description": "Array of file configurations to make available for playback",
+                "required": True,
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "key": {
+                            "type": "string",
+                            "description": "Unique identifier for the file"
+                        },
+                        "description": {
+                            "type": "string",
+                            "description": "Human-readable description of the file"
+                        },
+                        "url": {
+                            "type": "string",
+                            "description": "URL of the audio/video file to play"
+                        },
+                        "wait": {
+                            "type": "boolean",
+                            "description": "Whether to wait for file to finish playing",
+                            "default": False
+                        }
+                    },
+                    "required": ["key", "description", "url"]
+                }
+            }
+        })
+        return schema
+    
     def __init__(self, agent, params: Dict[str, Any] = None):
         """
         Initialize the skill with configuration parameters.

signalwire_agents/skills/registry.py

@@ -128,6 +128,42 @@ class SkillRegistry:
         if not hasattr(skill_class, 'SKILL_NAME') or skill_class.SKILL_NAME is None:
             raise ValueError(f"{skill_class} must define SKILL_NAME")
             
+        # Validate that the skill has a proper parameter schema
+        if not hasattr(skill_class, 'get_parameter_schema') or not callable(getattr(skill_class, 'get_parameter_schema')):
+            raise ValueError(f"{skill_class.__name__} must have get_parameter_schema() classmethod")
+        
+        # Try to call get_parameter_schema to ensure it's properly implemented
+        try:
+            schema = skill_class.get_parameter_schema()
+            if not isinstance(schema, dict):
+                raise ValueError(f"{skill_class.__name__}.get_parameter_schema() must return a dictionary, got {type(schema)}")
+            
+            # Ensure it's not an empty schema (skills should at least have the base parameters)
+            if not schema:
+                raise ValueError(f"{skill_class.__name__}.get_parameter_schema() returned an empty dictionary. Skills should at least call super().get_parameter_schema()")
+            
+            # Check if the skill has overridden the method (not just inherited base)
+            skill_method = getattr(skill_class, 'get_parameter_schema', None)
+            base_method = getattr(SkillBase, 'get_parameter_schema', None)
+            
+            if skill_method and base_method:
+                # For class methods, check the underlying function
+                skill_func = skill_method.__func__ if hasattr(skill_method, '__func__') else skill_method
+                base_func = base_method.__func__ if hasattr(base_method, '__func__') else base_method
+                
+                if skill_func is base_func:
+                    # Get base schema to check if skill added any parameters
+                    base_schema = SkillBase.get_parameter_schema()
+                    if set(schema.keys()) == set(base_schema.keys()):
+                        raise ValueError(f"{skill_class.__name__} must override get_parameter_schema() to define its specific parameters")
+                
+        except AttributeError as e:
+            raise ValueError(f"{skill_class.__name__} must properly implement get_parameter_schema() classmethod")
+        except ValueError:
+            raise  # Re-raise our validation errors
+        except Exception as e:
+            raise ValueError(f"{skill_class.__name__}.get_parameter_schema() failed: {e}")
+            
         if skill_class.SKILL_NAME in self._skills:
             self.logger.warning(f"Skill '{skill_class.SKILL_NAME}' already registered")
             return

signalwire_agents/skills/spider/skill.py

@@ -33,6 +33,119 @@ class SpiderSkill(SkillBase):
     # Compiled regex for performance
     WHITESPACE_REGEX = re.compile(r'\s+')
     
+    @classmethod
+    def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
+        """Get parameter schema for Spider skill"""
+        schema = super().get_parameter_schema()
+        schema.update({
+            "delay": {
+                "type": "number",
+                "description": "Delay between requests in seconds",
+                "default": 0.1,
+                "required": False,
+                "minimum": 0.0
+            },
+            "concurrent_requests": {
+                "type": "integer",
+                "description": "Number of concurrent requests allowed",
+                "default": 5,
+                "required": False,
+                "minimum": 1,
+                "maximum": 20
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "Request timeout in seconds",
+                "default": 5,
+                "required": False,
+                "minimum": 1,
+                "maximum": 60
+            },
+            "max_pages": {
+                "type": "integer",
+                "description": "Maximum number of pages to scrape",
+                "default": 1,
+                "required": False,
+                "minimum": 1,
+                "maximum": 100
+            },
+            "max_depth": {
+                "type": "integer",
+                "description": "Maximum crawl depth (0 = single page only)",
+                "default": 0,
+                "required": False,
+                "minimum": 0,
+                "maximum": 5
+            },
+            "extract_type": {
+                "type": "string",
+                "description": "Content extraction method",
+                "default": "fast_text",
+                "required": False,
+                "enum": ["fast_text", "clean_text", "full_text", "html", "custom"]
+            },
+            "max_text_length": {
+                "type": "integer",
+                "description": "Maximum text length to return",
+                "default": 10000,
+                "required": False,
+                "minimum": 100,
+                "maximum": 100000
+            },
+            "clean_text": {
+                "type": "boolean",
+                "description": "Whether to clean extracted text",
+                "default": True,
+                "required": False
+            },
+            "selectors": {
+                "type": "object",
+                "description": "Custom CSS/XPath selectors for extraction",
+                "default": {},
+                "required": False,
+                "additionalProperties": {
+                    "type": "string"
+                }
+            },
+            "follow_patterns": {
+                "type": "array",
+                "description": "URL patterns to follow when crawling",
+                "default": [],
+                "required": False,
+                "items": {
+                    "type": "string"
+                }
+            },
+            "user_agent": {
+                "type": "string",
+                "description": "User agent string for requests",
+                "default": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+                "required": False
+            },
+            "headers": {
+                "type": "object",
+                "description": "Additional HTTP headers",
+                "default": {},
+                "required": False,
+                "additionalProperties": {
+                    "type": "string"
+                }
+            },
+            "follow_robots_txt": {
+                "type": "boolean",
+                "description": "Whether to respect robots.txt",
+                "default": True,
+                "required": False
+            },
+            "cache_enabled": {
+                "type": "boolean",
+                "description": "Whether to cache scraped pages",
+                "default": True,
+                "required": False
+            }
+        })
+        return schema
+    
     def __init__(self, agent, params: Dict[str, Any]):
         """Initialize the spider skill with configuration parameters."""
         super().__init__(agent, params)