signalwire-agents 0.1.13__py3-none-any.whl → 1.0.17.dev4__py3-none-any.whl

{signalwire_agents-0.1.13.dist-info → signalwire_agents-1.0.17.dev4.dist-info}/METADATA

@@ -1,10 +1,12 @@
 Metadata-Version: 2.4
 Name: signalwire_agents
-Version: 0.1.13
+Version: 1.0.17.dev4
 Summary: SignalWire AI Agents SDK
 Author-email: SignalWire Team <info@signalwire.com>
-Project-URL: Homepage, https://github.com/signalwire/signalwire-ai-agents
-Classifier: Development Status :: 3 - Alpha
+License: MIT
+Project-URL: Homepage, https://github.com/signalwire/signalwire-agents
+Keywords: signalwire,ai,agents,voice,telephony,swaig,swml
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -16,16 +18,22 @@ Classifier: Programming Language :: Python :: 3.11
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastapi==0.115.12
-Requires-Dist: pydantic==2.11.4
-Requires-Dist: PyYAML==6.0.2
-Requires-Dist: Requests==2.32.3
-Requires-Dist: setuptools==66.1.1
-Requires-Dist: signalwire_pom==2.7.1
-Requires-Dist: structlog==25.3.0
-Requires-Dist: uvicorn==0.34.2
-Requires-Dist: beautifulsoup4==4.12.3
-Requires-Dist: pytz==2023.3
+Requires-Dist: fastapi>=0.115.12
+Requires-Dist: pydantic>=2.11.4
+Requires-Dist: PyYAML>=6.0.2
+Requires-Dist: Requests>=2.32.3
+Requires-Dist: setuptools<81,>=66.1.1
+Requires-Dist: signalwire_pom>=2.7.1
+Requires-Dist: structlog>=25.3.0
+Requires-Dist: uvicorn>=0.34.2
+Requires-Dist: beautifulsoup4>=4.12.3
+Requires-Dist: pytz>=2023.3
+Requires-Dist: lxml>=4.9.0
+Provides-Extra: search-queryonly
+Requires-Dist: numpy>=1.24.0; extra == "search-queryonly"
+Requires-Dist: scikit-learn>=1.3.0; extra == "search-queryonly"
+Requires-Dist: sentence-transformers>=2.2.0; extra == "search-queryonly"
+Requires-Dist: nltk>=3.8; extra == "search-queryonly"
 Provides-Extra: search
 Requires-Dist: sentence-transformers>=2.2.0; extra == "search"
 Requires-Dist: scikit-learn>=1.3.0; extra == "search"
@@ -62,28 +70,165 @@ Requires-Dist: striprtf>=0.0.26; extra == "search-all"
 Requires-Dist: openpyxl>=3.1.0; extra == "search-all"
 Requires-Dist: python-pptx>=0.6.21; extra == "search-all"
 Requires-Dist: python-magic>=0.4.27; extra == "search-all"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "search-all"
+Requires-Dist: pgvector>=0.2.0; extra == "search-all"
+Provides-Extra: pgvector
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "pgvector"
+Requires-Dist: pgvector>=0.2.0; extra == "pgvector"
+Provides-Extra: mcp-gateway
+Requires-Dist: flask>=2.0.0; extra == "mcp-gateway"
+Requires-Dist: flask-limiter>=3.5.0; extra == "mcp-gateway"
+Provides-Extra: all
+Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
+Requires-Dist: scikit-learn>=1.3.0; extra == "all"
+Requires-Dist: nltk>=3.8; extra == "all"
+Requires-Dist: numpy>=1.24.0; extra == "all"
+Requires-Dist: spacy>=3.6.0; extra == "all"
+Requires-Dist: pdfplumber>=0.9.0; extra == "all"
+Requires-Dist: python-docx>=0.8.11; extra == "all"
+Requires-Dist: markdown>=3.4.0; extra == "all"
+Requires-Dist: striprtf>=0.0.26; extra == "all"
+Requires-Dist: openpyxl>=3.1.0; extra == "all"
+Requires-Dist: python-pptx>=0.6.21; extra == "all"
+Requires-Dist: python-magic>=0.4.27; extra == "all"
 Dynamic: license-file
 
-# SignalWire AI Agent SDK
+<!-- Header -->
+<div align="center">
+    <a href="https://signalwire.com" target="_blank">
+        <img src="https://github.com/user-attachments/assets/0c8ed3b9-8c50-4dc6-9cc4-cc6cd137fd50" width="500" />
+    </a>
 
-A Python SDK for creating, hosting, and securing SignalWire AI agents as microservices with minimal boilerplate.
+# Agents SDK
+
+#### _A Python SDK for creating, hosting, and securing SignalWire AI agents as microservices with minimal boilerplate._
+
+<br/>
+
+<p align="center">
+  <a href="https://developer.signalwire.com/sdks/agents-sdk" target="_blank">📖 Documentation</a> &nbsp; &nbsp; <code>#</code> &nbsp; &nbsp;
+  <a href="https://github.com/signalwire/signalwire-docs/issues/new/choose" target="_blank">🐛 Report an issue</a> &nbsp; &nbsp; <code>#</code> &nbsp; &nbsp;
+  <a href="https://pypi.org/project/signalwire-agents/" target="_blank">🐍 PyPI</a>
+</p>
+
+<br/>
+
+<!-- Badges -->
+<div align="center">
+    <a href="https://discord.com/invite/F2WNYTNjuF" target="_blank"><img src="https://img.shields.io/badge/Discord%20Community-5865F2" alt="Discord" /></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/MIT-License-blue" alt="MIT License" /></a>
+    <a href="https://github.com/signalwire" target="_blank"><img src="https://img.shields.io/badge/GitHub-%23121011.svg?logo=github&logoColor=white&" alt="GitHub" /></a>
+    <a href="https://github.com/signalwire/docs" target="_blank"><img src="https://img.shields.io/github/stars/signalwire/signalwire-agents" alt="GitHub Stars" /></a>
+</div>
+
+<br/>
+
+<a href="https://signalwire.com/signup" target="_blank">
+    <img src="https://github.com/user-attachments/assets/c2510c86-ae03-42a9-be06-ab9bcea948e1" alt="Sign Up" height="65"/>
+</a>
+
+</div>
 
 ## Features
 
-- **Self-Contained Agents**: Each agent is both a web app and an AI persona
-- **Prompt Object Model**: Structured prompt composition using POM
-- **SWAIG Integration**: Easily define and handle AI tools/functions
-- **Dynamic Configuration**: Configure agents per-request for multi-tenant apps and personalization
-- **Custom Routing**: Dynamic request handling for different paths and content
-- **SIP Integration**: Route SIP calls to agents based on SIP usernames
-- **Security Built-In**: Session management, function-specific security tokens, and basic auth
-- **State Management**: Persistent conversation state with automatic tracking
-- **Prefab Archetypes**: Ready-to-use agent types for common scenarios
-- **Multi-Agent Support**: Host multiple agents on a single server
-- **Modular Skills System**: Add capabilities to agents with simple one-liner calls
-- **Local Search System**: Offline document search with vector similarity and keyword search
-
-## Skills System
+|                   |                                                                  |
+|-------------------------------|:-----------------------------------------------------------------------------:|
+| 🤖     **Self-Contained Agents** | Each agent is both a web app and an AI persona                            |
+| 📝     **Prompt Object Model**   | Structured prompt composition using POM                                   |
+| ⚙️     **SWAIG Integration**     | Easily define and handle AI tools/functions                               |
+| 🔧     **Dynamic Configuration** | Configure agents per-request for multi-tenant apps and personalization    |
+| 🗺️     **Custom Routing**        | Dynamic request handling for different paths and content                  |
+| 📞     **SIP Integration**       | Route SIP calls to agents based on SIP usernames                          |
+| 🔒     **Security Built-In**     | Session management, function-specific security tokens, and basic auth     |
+| 💾     **State Management**      | Persistent conversation state with automatic tracking                     |
+| 🏗️     **Prefab Archetypes**     | Ready-to-use agent types for common scenarios                            |
+| 🏢     **Multi-Agent Support**   | Host multiple agents on a single server                                  |
+| �      **Modular Skills System** | Add capabilities to agents with simple one-liner calls                   |
+| 🔍     **Local Search System**   | Offline document search with vector similarity and keyword search        |
+
+## Installation
+
+### Basic Installation
+
+```bash
+pip install signalwire-agents
+```
+
+### Optional Search Functionality
+
+The SDK includes optional local search capabilities that can be installed separately to avoid adding large dependencies to the base installation:
+
+#### Search Installation Options
+
+```bash
+# Query existing .swsearch files only (smallest footprint)
+pip install signalwire-agents[search-queryonly]
+
+# Basic search (vector search + keyword search + building indexes)
+pip install signalwire-agents[search]
+
+# Full search with document processing (PDF, DOCX, etc.)
+pip install signalwire-agents[search-full]
+
+# Advanced NLP features (includes spaCy)
+pip install signalwire-agents[search-nlp]
+
+# All search features
+pip install signalwire-agents[search-all]
+```
+
+#### What Each Option Includes
+
+| Option | Size | Features |
+|--------|------|----------|
+| `search-queryonly` | ~400MB | Query existing .swsearch files only (no building/processing) |
+| `search` | ~500MB | Vector embeddings, keyword search, basic text processing |
+| `search-full` | ~600MB | + PDF, DOCX, Excel, PowerPoint, HTML, Markdown processing |
+| `search-nlp` | ~600MB | + Advanced spaCy NLP features |
+| `search-all` | ~700MB | All search features combined |
+
+**When to use `search-queryonly`:**
+- Production containers with pre-built `.swsearch` files
+- Lambda/serverless deployments
+- Agents that only need to query knowledge bases (not build them)
+- Smaller deployment footprint requirements
+
+#### Search Features
+
+- **Local/Offline Search**: No external API dependencies
+- **Hybrid Search**: Vector similarity + keyword search
+- **Smart Document Processing**: Markdown, Python, PDF, DOCX, etc.
+- **Multiple Languages**: English, Spanish, with extensible framework
+- **CLI Tools**: Build search indexes from document directories
+- **HTTP API**: Standalone or embedded search service
+
+#### Usage Example
+
+```python
+# Only available with search extras installed
+from signalwire_agents.search import IndexBuilder, SearchEngine
+
+# Build search index
+builder = IndexBuilder()
+builder.build_index(
+    source_dir="./docs",
+    output_file="knowledge.swsearch",
+    file_types=['md', 'txt', 'pdf']
+)
+
+# Search documents
+engine = SearchEngine("knowledge.swsearch")
+results = engine.search(
+    query_vector=embeddings,
+    enhanced_text="search query",
+    count=5
+)
+```
+
+<details>
+<summary><h2>Documentation</h2></summary>
+
+### Skills System
 
 The SignalWire Agents SDK includes a powerful modular skills system that allows you to add complex capabilities to your agents with simple one-liner calls:
 
@@ -155,7 +300,7 @@ agent.add_skill("datasphere", {
 agent.serve()
 ```
 
-### Available Built-in Skills
+#### Available Built-in Skills
 
 - **web_search**: Google Custom Search API integration with web scraping (supports multiple instances)
 - **datetime**: Current date and time with timezone support
@@ -163,7 +308,7 @@ agent.serve()
 - **datasphere**: SignalWire DataSphere knowledge search (supports multiple instances)
 - **native_vector_search**: Offline document search with vector similarity and keyword search
 
-### Benefits
+#### Benefits
 
 - **One-liner integration**: `agent.add_skill("skill_name")`
 - **Configurable parameters**: `agent.add_skill("skill_name", {"param": "value"})`
@@ -171,13 +316,13 @@ agent.serve()
 - **Dependency validation**: Clear error messages for missing requirements
 - **Modular architecture**: Skills are self-contained and reusable
 
-For detailed documentation, see [Skills System README](docs/SKILLS_SYSTEM_README.md).
+For detailed documentation, see [Skills System README](docs/skills_system.md).
 
-## DataMap Tools
+### DataMap Tools
 
 The SDK provides a DataMap system for creating SWAIG tools that integrate directly with REST APIs without requiring custom webhook endpoints. DataMap tools execute on the SignalWire server, making them simpler to deploy than traditional webhook-based tools.
 
-### Basic DataMap Usage
+#### Basic DataMap Usage
 
 ```python
 from signalwire_agents import AgentBase
@@ -203,7 +348,7 @@ agent = APIAgent()
 agent.serve()
 ```
 
-### Advanced DataMap Examples
+#### Advanced DataMap Examples
 
 ```python
 # POST API with authentication
@@ -234,7 +379,7 @@ docs_tool = (DataMap('get_latest_docs')
 )
 ```
 
-### Helper Functions
+#### Helper Functions
 
 For simpler use cases, use the convenience functions:
 
@@ -264,7 +409,7 @@ self.register_swaig_function(weather.to_swaig_function())
 self.register_swaig_function(file_control.to_swaig_function())
 ```
 
-### Variable Expansion
+#### Variable Expansion
 
 DataMap tools support powerful variable expansion using `${variable}` syntax:
 
@@ -274,7 +419,7 @@ DataMap tools support powerful variable expansion using `${variable}` syntax:
 - **Global data**: `${global_data.key}`
 - **Metadata**: `${meta_data.call_id}`
 
-### Benefits of DataMap Tools
+#### Benefits of DataMap Tools
 
 - **No webhook infrastructure**: Tools run on SignalWire servers
 - **Simplified deployment**: No need to expose endpoints
@@ -285,20 +430,20 @@ DataMap tools support powerful variable expansion using `${variable}` syntax:
 
 For detailed documentation, see [DataMap Guide](docs/datamap_guide.md).
 
-## Contexts and Steps
+### Contexts and Steps
 
-The SignalWire Agents SDK provides a powerful alternative to traditional Prompt Object Model (POM) prompts through the **Contexts and Steps** system. This feature allows you to create structured, workflow-driven AI interactions with explicit navigation control and step-by-step guidance.
+The SignalWire Agents SDK provides a powerful enhancement to traditional prompts through the **Contexts and Steps** system. This feature allows you to add structured, workflow-driven AI interactions on top of your base prompt, with explicit navigation control and step-by-step guidance.
 
-### Why Use Contexts and Steps?
+#### Why Use Contexts and Steps?
 
 - **Structured Workflows**: Define clear, step-by-step processes for complex interactions
 - **Navigation Control**: Explicitly control which steps or contexts users can access
 - **Completion Criteria**: Set specific criteria for step completion and progression  
 - **Function Restrictions**: Limit which AI tools are available in each step
 - **Workflow Isolation**: Create separate contexts for different conversation flows
-- **Backward Compatibility**: Works alongside traditional prompts and all existing AgentBase features
+- **Enhanced Base Prompts**: Adds structured workflows on top of your existing prompt foundation
 
-### Basic Usage
+#### Basic Usage
 
 ```python
 from signalwire_agents import AgentBase
@@ -307,30 +452,34 @@ class WorkflowAgent(AgentBase):
     def __init__(self):
         super().__init__(name="Workflow Assistant", route="/workflow")
         
-        # Define contexts and steps (alternative to traditional prompts)
+        # Set base prompt (required even when using contexts)
+        self.prompt_add_section("Role", "You are a helpful workflow assistant.")
+        self.prompt_add_section("Instructions", "Guide users through structured processes step by step.")
+        
+        # Define contexts and steps (adds structured workflow to base prompt)
         contexts = self.define_contexts()
         
         # Create a single context named "default" (required for single context)
-        context = contexts.create_context("default")
+        context = contexts.add_context("default")
         
         # Add step-by-step workflow
-        context.create_step("greeting") \
+        context.add_step("greeting") \
             .set_text("Welcome! I'm here to help you complete your application. Let's start with your personal information.") \
             .set_step_criteria("User has provided their name and confirmed they want to continue") \
             .set_valid_steps(["personal_info"])  # Can only go to personal_info step
         
-        context.create_step("personal_info") \
+        context.add_step("personal_info") \
             .add_section("Instructions", "Collect the user's personal information") \
             .add_bullets(["Ask for full name", "Ask for email address", "Ask for phone number"]) \
             .set_step_criteria("All personal information has been collected and confirmed") \
             .set_valid_steps(["review", "personal_info"])  # Can stay or move to review
         
-        context.create_step("review") \
+        context.add_step("review") \
             .set_text("Let me review the information you've provided. Please confirm if everything is correct.") \
             .set_step_criteria("User has confirmed or requested changes") \
             .set_valid_steps(["personal_info", "complete"])  # Can go back or complete
         
-        context.create_step("complete") \
+        context.add_step("complete") \
             .set_text("Thank you! Your application has been submitted successfully.") \
             .set_step_criteria("Application processing is complete")
             # No valid_steps = end of workflow
@@ -339,29 +488,34 @@ agent = WorkflowAgent()
 agent.serve()
 ```
 
-### Advanced Features
+#### Advanced Features
 
 ```python
 class MultiContextAgent(AgentBase):
     def __init__(self):
         super().__init__(name="Multi-Context Agent", route="/multi-context")
         
-        # Add skills first
+        # Set base prompt (required)
+        self.prompt_add_section("Role", "You are a versatile AI assistant.")
+        self.prompt_add_section("Capabilities", "You can help with calculations and provide time information.")
+        
+        # Add skills
         self.add_skill("datetime")
         self.add_skill("math")
         
+        # Define contexts for different service modes
         contexts = self.define_contexts()
         
         # Main conversation context
-        main_context = contexts.create_context("main")
-        main_context.create_step("welcome") \
+        main_context = contexts.add_context("main")
+        main_context.add_step("welcome") \
             .set_text("Welcome! I can help with calculations or provide date/time info. What would you like to do?") \
             .set_step_criteria("User has chosen a service type") \
             .set_valid_contexts(["calculator", "datetime_info"])  # Can switch contexts
         
         # Calculator context with function restrictions
-        calc_context = contexts.create_context("calculator")
-        calc_context.create_step("math_mode") \
+        calc_context = contexts.add_context("calculator")
+        calc_context.add_step("math_mode") \
             .add_section("Role", "You are a mathematical assistant") \
             .add_section("Instructions", "Help users with calculations") \
             .set_functions(["math"])  # Only math function available \
@@ -369,21 +523,21 @@ class MultiContextAgent(AgentBase):
             .set_valid_contexts(["main"])  # Can return to main
         
         # DateTime context
-        datetime_context = contexts.create_context("datetime_info")
-        datetime_context.create_step("time_mode") \
+        datetime_context = contexts.add_context("datetime_info")
+        datetime_context.add_step("time_mode") \
             .set_text("I can provide current date and time information. What would you like to know?") \
             .set_functions(["datetime"])  # Only datetime function available \
             .set_step_criteria("Date/time information has been provided") \
             .set_valid_contexts(["main"])  # Can return to main
 ```
 
-### Context and Step Methods
+#### Context and Step Methods
 
-#### Context Methods
-- `create_step(name)`: Create a new step in this context
+##### Context Methods
+- `add_step(name)`: Create a new step in this context
 - `set_valid_contexts(contexts)`: Control which contexts can be accessed from this context
 
-#### Step Methods
+##### Step Methods
 - `set_text(text)`: Set direct text prompt for the step
 - `add_section(title, body)`: Add POM-style section (alternative to set_text)
 - `add_bullets(bullets)`: Add bullet points to the current or last section
@@ -392,55 +546,59 @@ class MultiContextAgent(AgentBase):
 - `set_valid_steps(steps)`: Control navigation to other steps in same context
 - `set_valid_contexts(contexts)`: Control navigation to other contexts
 
-### Navigation Rules
+#### Navigation Rules
 
 - **Valid Steps**: If omitted, only "next" step is implied. If specified, only those steps are allowed.
 - **Valid Contexts**: If omitted, user is trapped in current context. If specified, can navigate to those contexts.
 - **Single Context**: Must be named "default" for single-context workflows.
 - **Function Restrictions**: Use `set_functions(["function_name"])` or `set_functions("none")` to control AI tool access.
 
-### Complete Example: Customer Support Workflow
+#### Complete Example: Customer Support Workflow
 
 ```python
 class SupportAgent(AgentBase):
     def __init__(self):
         super().__init__(name="Customer Support", route="/support")
         
+        # Set base prompt (required)
+        self.prompt_add_section("Role", "You are a professional customer support representative.")
+        self.prompt_add_section("Goal", "Provide excellent customer service using structured workflows.")
+        
         # Add skills for enhanced capabilities
         self.add_skill("datetime")
         self.add_skill("web_search", {"api_key": "your-key", "search_engine_id": "your-id"})
         
+        # Define support workflow contexts
         contexts = self.define_contexts()
         
         # Triage context
-        triage = contexts.create_context("triage")
-        triage.create_step("initial_greeting") \
-            .add_section("Role", "You are a helpful customer support agent") \
-            .add_section("Goal", "Understand the customer's issue and route them appropriately") \
-            .add_bullets(["Be empathetic and professional", "Ask clarifying questions", "Categorize the issue"]) \
+        triage = contexts.add_context("triage")
+        triage.add_step("initial_greeting") \
+            .add_section("Current Task", "Understand the customer's issue and route them appropriately") \
+            .add_bullets("Questions to Ask", ["What problem are you experiencing?", "How urgent is this issue?", "Have you tried any troubleshooting steps?"]) \
             .set_step_criteria("Issue type has been identified") \
             .set_valid_contexts(["technical_support", "billing_support", "general_inquiry"])
         
         # Technical support context
-        tech = contexts.create_context("technical_support")
-        tech.create_step("technical_diagnosis") \
-            .add_section("Role", "You are a technical support specialist") \
-            .add_section("Instructions", "Help diagnose and resolve technical issues") \
+        tech = contexts.add_context("technical_support")
+        tech.add_step("technical_diagnosis") \
+            .add_section("Current Task", "Help diagnose and resolve technical issues") \
+            .add_section("Available Tools", "Use web search to find solutions and datetime to check service windows") \
             .set_functions(["web_search", "datetime"])  # Can search for solutions and check times \
             .set_step_criteria("Technical issue is resolved or escalated") \
             .set_valid_contexts(["triage"])  # Can return to triage
         
         # Billing support context  
-        billing = contexts.create_context("billing_support")
-        billing.create_step("billing_assistance") \
+        billing = contexts.add_context("billing_support")
+        billing.add_step("billing_assistance") \
             .set_text("I'll help you with your billing inquiry. Please provide your account details.") \
             .set_functions("none")  # No external tools for sensitive billing info \
             .set_step_criteria("Billing issue is addressed") \
             .set_valid_contexts(["triage"])
         
         # General inquiry context
-        general = contexts.create_context("general_inquiry")
-        general.create_step("general_help") \
+        general = contexts.add_context("general_inquiry")
+        general.add_step("general_help") \
             .set_text("I'm here to help with general questions. What can I assist you with?") \
             .set_functions(["web_search", "datetime"])  # Full access to search and time \
             .set_step_criteria("Inquiry has been answered") \
@@ -450,7 +608,7 @@ agent = SupportAgent()
 agent.serve()
 ```
 
-### Benefits
+#### Benefits
 
 - **Clear Structure**: Explicit workflow definition makes agent behavior predictable
 - **Enhanced Control**: Fine-grained control over function access and navigation
@@ -460,76 +618,7 @@ agent.serve()
 
 For detailed documentation and advanced examples, see [Contexts and Steps Guide](docs/contexts_guide.md).
 
-## Installation
-
-### Basic Installation
-
-```bash
-pip install signalwire-agents
-```
-
-### Optional Search Functionality
-
-The SDK includes optional local search capabilities that can be installed separately to avoid adding large dependencies to the base installation:
-
-#### Search Installation Options
-
-```bash
-# Basic search (vector search + keyword search)
-pip install signalwire-agents[search]
-
-# Full search with document processing (PDF, DOCX, etc.)
-pip install signalwire-agents[search-full]
-
-# Advanced NLP features (includes spaCy)
-pip install signalwire-agents[search-nlp]
-
-# All search features
-pip install signalwire-agents[search-all]
-```
-
-#### What Each Option Includes
-
-| Option | Size | Features |
-|--------|------|----------|
-| `search` | ~500MB | Vector embeddings, keyword search, basic text processing |
-| `search-full` | ~600MB | + PDF, DOCX, Excel, PowerPoint, HTML, Markdown processing |
-| `search-nlp` | ~600MB | + Advanced spaCy NLP features |
-| `search-all` | ~700MB | All search features combined |
-
-#### Search Features
-
-- **Local/Offline Search**: No external API dependencies
-- **Hybrid Search**: Vector similarity + keyword search
-- **Smart Document Processing**: Markdown, Python, PDF, DOCX, etc.
-- **Multiple Languages**: English, Spanish, with extensible framework
-- **CLI Tools**: Build search indexes from document directories
-- **HTTP API**: Standalone or embedded search service
-
-#### Usage Example
-
-```python
-# Only available with search extras installed
-from signalwire_agents.search import IndexBuilder, SearchEngine
-
-# Build search index
-builder = IndexBuilder()
-builder.build_index(
-    source_dir="./docs",
-    output_file="knowledge.swsearch",
-    file_types=['md', 'txt', 'pdf']
-)
-
-# Search documents
-engine = SearchEngine("knowledge.swsearch")
-results = engine.search(
-    query_vector=embeddings,
-    enhanced_text="search query",
-    count=5
-)
-```
-
-## Quick Start
+### Quick Start
 
 ```python
 from signalwire_agents import AgentBase
@@ -544,10 +633,7 @@ class SimpleAgent(AgentBase):
         self.prompt_add_section("Goal", body="Help users with basic questions.")
         self.prompt_add_section("Instructions", bullets=["Be concise and clear."])
         
-        # Alternative using convenience methods:
-        # self.setPersonality("You are a helpful assistant.")
-        # self.setGoal("Help users with basic questions.")
-        # self.setInstructions(["Be concise and clear."])
+        # Note: Use prompt_add_section() for all prompt configuration
     
     @AgentBase.tool(
         name="get_time", 
@@ -565,65 +651,59 @@ if __name__ == "__main__":
     agent.serve(host="0.0.0.0", port=8000)
 ```
 
-## Using State Management
+### Customizing LLM Parameters
+
+The SDK allows you to customize LLM parameters for both the main prompt and post-prompt, giving you fine control over the AI's behavior:
 
 ```python
 from signalwire_agents import AgentBase
-from signalwire_agents.core.function_result import SwaigFunctionResult
-from signalwire_agents.core.state import FileStateManager
 
-class StatefulAgent(AgentBase):
+class PreciseAgent(AgentBase):
     def __init__(self):
-        # Configure state management
-        state_manager = FileStateManager(storage_dir="./state_data")
-        
-        super().__init__(
-            name="stateful", 
-            route="/stateful",
-            enable_state_tracking=True,  # Enable state tracking
-            state_manager=state_manager  # Use custom state manager
+        super().__init__(name="precise", route="/precise")
+        
+        # Configure the agent's personality
+        self.prompt_add_section("Role", "You are a precise technical assistant.")
+        self.prompt_add_section("Instructions", "Provide accurate, detailed information.")
+        
+        # Set custom LLM parameters for the main prompt
+        # These parameters are passed to the server which validates them based on the model
+        self.set_prompt_llm_params(
+            temperature=0.3,        # Low temperature for more consistent responses
+            top_p=0.9,             # Slightly reduced for focused responses
+            barge_confidence=0.7,  # Moderate interruption threshold
+            presence_penalty=0.1,  # Slight penalty for repetition
+            frequency_penalty=0.2  # Encourage varied vocabulary
         )
         
-        # When enable_state_tracking=True, startup_hook and hangup_hook
-        # are automatically registered to track session lifecycle
-    
-    # Custom tool for accessing and updating state
-    @AgentBase.tool(
-        name="save_preference",
-        description="Save a user preference",
-        parameters={
-            "preference_name": {
-                "type": "string",
-                "description": "Name of the preference to save"
-            },
-            "preference_value": {
-                "type": "string",
-                "description": "Value of the preference"
-            }
-        }
-    )
-    def save_preference(self, args, raw_data):
-        # Get the call ID from the raw data
-        call_id = raw_data.get("call_id")
+        # Set post-prompt for summaries
+        self.set_post_prompt("Provide a concise summary of the key points discussed.")
         
-        if call_id:
-            # Get current state or empty dict if none exists
-            state = self.get_state(call_id) or {}
-            
-            # Update the state
-            preferences = state.get("preferences", {})
-            preferences[args.get("preference_name")] = args.get("preference_value")
-            state["preferences"] = preferences
-            
-            # Save the updated state
-            self.update_state(call_id, state)
-            
-            return SwaigFunctionResult("Preference saved successfully")
-        else:
-            return SwaigFunctionResult("Could not save preference: No call ID")
+        # Different parameters for post-prompt (summaries should be even more focused)
+        self.set_post_prompt_llm_params(
+            temperature=0.2,       # Very low for consistent summaries
+            top_p=0.85            # More focused token selection
+        )
+
+agent = PreciseAgent()
+agent.serve()
 ```
 
-## Using Prefab Agents
+#### Common LLM Parameters
+
+The SDK accepts any parameters which are passed to the server for validation based on the model. Common parameters include:
+
+- **temperature**: Controls randomness. Lower = more focused, higher = more creative
+- **top_p**: Nucleus sampling. Lower = more focused on likely tokens
+- **barge_confidence**: ASR confidence to interrupt. Higher = harder to interrupt (main prompt only)
+- **presence_penalty**: Topic diversity. Positive = new topics
+- **frequency_penalty**: Repetition control. Positive = varied vocabulary
+
+Note: No defaults are sent unless explicitly set. The server handles validation and applies appropriate defaults based on the model.
+
+For more details on LLM parameter tuning, see [LLM Parameters Guide](docs/llm_parameters.md).
+
+### Using Prefab Agents
 
 ```python
 from signalwire_agents.prefabs import InfoGathererAgent
@@ -648,16 +728,16 @@ Available prefabs include:
 - `SurveyAgent`: Conducts structured surveys with questions and rating scales
 - `ReceptionistAgent`: Greets callers and transfers them to appropriate departments
 
-## Dynamic Agent Configuration
+### Dynamic Agent Configuration
 
 Configure agents dynamically based on request parameters for multi-tenant applications, A/B testing, and personalization.
 
-### Static vs Dynamic Configuration
+#### Static vs Dynamic Configuration
 
 - **Static**: Agent configured once at startup (traditional approach)
 - **Dynamic**: Agent configured fresh for each request based on parameters
 
-### Basic Example
+#### Basic Example
 
 ```python
 from signalwire_agents import AgentBase
@@ -702,7 +782,7 @@ class DynamicAgent(AgentBase):
 # curl "http://localhost:3000/dynamic?tier=standard&language=en"
 ```
 
-### Use Cases
+#### Use Cases
 
 - **Multi-tenant SaaS**: Different configurations per customer/organization
 - **A/B Testing**: Test different agent behaviors with different user groups
@@ -710,13 +790,55 @@ class DynamicAgent(AgentBase):
 - **Localization**: Language and cultural adaptation based on user location
 - **Dynamic Pricing**: Adjust features and capabilities based on subscription tiers
 
-The `EphemeralAgentConfig` object provides all the same familiar methods as `AgentBase` (like `add_language()`, `prompt_add_section()`, `set_global_data()`) but applies them per-request instead of at startup.
+#### Preserving Dynamic State in SWAIG Callbacks
+
+When using dynamic configuration to add skills or tools based on request parameters, there's a challenge: SWAIG webhook callbacks are separate HTTP requests that won't have the original query parameters. The SDK provides `add_swaig_query_params()` to solve this:
+
+```python
+class DynamicAgent(AgentBase):
+    def __init__(self):
+        super().__init__(name="dynamic-agent", route="/agent")
+        self.set_dynamic_config_callback(self.configure_per_request)
+    
+    def configure_per_request(self, query_params, body_params, headers, agent):
+        tier = query_params.get('tier', 'basic')
+        region = query_params.get('region', 'us-east')
+        
+        if tier == 'premium':
+            # Add premium skills dynamically
+            agent.add_skill('advanced_search', {
+                'api_key': 'your-api-key',
+                'num_results': 5
+            })
+            
+            # IMPORTANT: Preserve parameters for SWAIG callbacks
+            agent.add_swaig_query_params({
+                'tier': tier,
+                'region': region
+            })
+            
+            # Now when SignalWire calls the SWAIG webhook, these params
+            # will be included, triggering the same dynamic configuration
+
+# Initial request: GET /agent?tier=premium&region=eu-west
+# SWAIG callback: POST /swaig/?tier=premium&region=eu-west
+# Result: Premium skills are available in both requests!
+```
+
+**Key Points:**
+
+- **Problem**: Dynamically added skills/tools won't exist during SWAIG callbacks without the original request parameters
+- **Solution**: Use `add_swaig_query_params()` to include critical parameters in all SWAIG webhook URLs
+- **Clear State**: Use `clear_swaig_query_params()` if needed to reset parameters between requests
+- **Token Safety**: The SDK automatically renames security tokens from `token` to `__token` to avoid parameter collisions
+
+This ensures that any dynamic configuration based on request parameters is consistently applied across the initial SWML request and all subsequent SWAIG function callbacks.
 
 For detailed documentation and advanced examples, see the [Agent Guide](docs/agent_guide.md#dynamic-agent-configuration).
 
-## Configuration
+### Configuration
 
-### Environment Variables
+#### Environment Variables
 
 The SDK supports the following environment variables:
 
@@ -733,14 +855,14 @@ When the auth environment variables are set, they will be used for all agents in
 
 To enable HTTPS directly (without a reverse proxy), set `SWML_SSL_ENABLED` to "true", provide valid paths to your certificate and key files, and specify your domain name.
 
-## Testing
+### Testing
 
 The SDK includes powerful CLI tools for development and testing:
 
 - **`swaig-test`**: Comprehensive local testing and serverless environment simulation
 - **`sw-search`**: Build local search indexes from document directories and search within them
 
-### Local Testing with swaig-test
+#### Local Testing with swaig-test
 
 Test your agents locally without deployment:
 
@@ -757,12 +879,16 @@ swaig-test examples/my_agent.py --list-tools
 # Test SWAIG functions with CLI syntax
 swaig-test examples/my_agent.py --exec get_weather --location "New York"
 
+# Multi-agent support
+swaig-test examples/multi_agent.py --route /agent-path --list-tools
+swaig-test examples/multi_agent.py --agent-class AgentName --exec function_name
+
 # Generate and inspect SWML documents
 swaig-test examples/my_agent.py --dump-swml
-swaig-test examples/my_agent.py --dump-swml --format-json | jq '.'
+swaig-test examples/my_agent.py --dump-swml --raw | jq '.'
 ```
 
-### Serverless Environment Simulation
+#### Serverless Environment Simulation
 
 Test your agents in simulated serverless environments without deployment:
 
@@ -795,7 +921,7 @@ swaig-test examples/my_agent.py --simulate-serverless azure_function \
   --exec my_function
 ```
 
-### Environment Management
+#### Environment Management
 
 Use environment files for consistent testing across platforms:
 
@@ -817,7 +943,7 @@ swaig-test examples/my_agent.py --simulate-serverless lambda \
   --env-file production.env --env DEBUG=true --dump-swml
 ```
 
-### Cross-Platform Testing
+#### Cross-Platform Testing
 
 Test the same agent across multiple serverless platforms:
 
@@ -834,7 +960,7 @@ swaig-test examples/my_agent.py --simulate-serverless lambda --dump-swml | grep
 swaig-test examples/my_agent.py --simulate-serverless cgi --cgi-host example.com --dump-swml | grep web_hook_url
 ```
 
-### Key Benefits
+#### Key Benefits
 
 - **No Deployment Required**: Test serverless behavior locally
 - **Environment Simulation**: Complete platform-specific environment variable setup
@@ -845,7 +971,7 @@ swaig-test examples/my_agent.py --simulate-serverless cgi --cgi-host example.com
 
 For detailed testing documentation, see the [CLI Testing Guide](docs/cli_testing_guide.md).
 
-## Documentation
+### Documentation
 
 The package includes comprehensive documentation in the `docs/` directory:
 
@@ -858,6 +984,12 @@ The package includes comprehensive documentation in the `docs/` directory:
 
 These documents provide in-depth explanations of the features, APIs, and usage patterns.
 
+</details
+
+### ***[Read the official docs.](https://developer.signalwire.com/sdks/agents-sdk)***
+
+---
+
 ## License
 
 MIT