dexto 1.0.1 → 1.1.0

package/agents/talk2pdf-agent/README.md

@@ -0,0 +1,166 @@
+# Talk2PDF Agent
+
+A comprehensive AI agent for parsing and analyzing PDF documents using the [Talk2PDF MCP Server](https://github.com/truffle-ai/mcp-servers/tree/main/src/talk2pdf).
+
+This agent provides intelligent PDF document processing through a TypeScript-based MCP server that can extract text, metadata, and search for specific content within PDF files.
+
+## Features
+
+### 📄 **PDF Parsing & Text Extraction**
+- **Full Document Parsing**: Extract complete text content from PDF files
+- **Metadata Extraction**: Get document information (title, author, page count, creation date)
+- **Format Support**: Handle various PDF versions and structures
+- **Error Handling**: Graceful handling of corrupted or protected PDFs
+
+### 🔍 **Content Search & Analysis**
+- **Section Extraction**: Search for and extract specific content sections
+- **Intelligent Filtering**: Find content containing specific terms or patterns
+- **Context Preservation**: Maintain document structure and formatting
+- **Multi-page Support**: Process documents of any length
+
+### 🧠 **AI-Powered Analysis**
+- **Document Summarization**: Generate intelligent summaries of PDF content
+- **Key Information Extraction**: Identify and extract important details
+- **Question Answering**: Answer questions about document content
+- **Content Classification**: Analyze document type and structure
+
+## Quick Start
+
+### Prerequisites
+- **Node.js 20+**: For the Dexto framework
+- **TypeScript**: Automatically managed by the MCP server
+
+### Installation
+
+1. **Run the Agent**:
+   ```bash
+   # From the dexto project root
+   dexto --agent agents/talk2pdf-agent/talk2pdf-agent.yml
+   ```
+
+That's it! The MCP server will be automatically downloaded and installed via `npx` on first run.
+
+## Configuration
+
+The agent is configured to use the published MCP server:
+
+```yaml
+mcpServers:
+  talk2pdf:
+    type: stdio
+    command: npx
+    args:
+      - "@truffle-ai/talk2pdf-mcp"
+    timeout: 30000
+    connectionMode: strict
+```
+
+## MCP Server
+
+This agent uses the **Talk2PDF MCP Server**, which is maintained separately at:
+
+**🔗 [https://github.com/truffle-ai/mcp-servers/tree/main/src/talk2pdf](https://github.com/truffle-ai/mcp-servers/tree/main/src/talk2pdf)**
+
+The MCP server repository provides:
+- Complete technical documentation
+- Development and contribution guidelines  
+- Server implementation details
+- Advanced configuration options
+
+## Available Tools
+
+### PDF Processing Tools
+
+#### `parse_pdf`
+Extract complete text content and metadata from a PDF file.
+
+**Parameters:**
+- `filePath` (string): Path to the PDF file to parse
+
+**Returns:**
+- Full text content of the document
+- Document metadata (title, author, page count, creation date, etc.)
+- File information (size, format)
+
+#### `extract_section`
+Search for and extract specific content sections from a PDF.
+
+**Parameters:**
+- `filePath` (string): Path to the PDF file
+- `searchTerms` (string): Terms or patterns to search for
+- `maxResults` (number, optional): Maximum number of results to return
+
+**Returns:**
+- Matching content sections with context
+- Page numbers and locations
+- Relevance scoring
+
+## Supported PDF Features
+
+- **Standard PDF formats**: PDF 1.4 through 2.0
+- **Text-based PDFs**: Documents with extractable text content
+- **Multi-page documents**: No page limit restrictions
+- **Metadata support**: Title, author, creation date, modification date
+- **Various encodings**: UTF-8, Latin-1, and other standard encodings
+
+## Example Usage
+
+### Basic PDF Parsing
+```
+"Parse the PDF at /path/to/document.pdf and show me the full content"
+"Extract all text and metadata from my research paper"
+"What's in this PDF file?"
+```
+
+### Content Search
+```
+"Find all sections about 'machine learning' in the PDF"
+"Extract the introduction and conclusion from this document" 
+"Search for mentions of 'budget' in the financial report"
+```
+
+### Document Analysis
+```
+"Summarize the main points from this PDF"
+"What is this document about?"
+"Extract the key findings from the research paper"
+"List all the recommendations mentioned in the report"
+```
+
+### Intelligent Q&A
+```
+"What are the main conclusions of this study?"
+"Who are the authors of this document?"
+"When was this document created?"
+"How many pages does this PDF have?"
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Server Installation**: The MCP server will be automatically installed via `npx` on first run. No manual setup required.
+
+2. **PDF Access Issues**: Ensure the PDF file path is correct and the file is readable. Protected or encrypted PDFs may require special handling.
+
+3. **Memory Issues**: For very large PDFs (100+ pages), processing may take longer. Consider breaking large documents into sections.
+
+4. **Text Extraction**: If text appears garbled, the PDF may use non-standard encoding or be scanned image-based (OCR not supported).
+
+### Error Handling
+
+The agent provides clear error messages for common issues:
+- File not found or inaccessible
+- Invalid PDF format
+- Corrupted PDF files
+- Permission-protected documents
+
+## Getting Help
+
+- **MCP Server Issues**: Report at the [mcp-servers repository](https://github.com/truffle-ai/mcp-servers/issues)
+- **Agent Configuration**: Report at the main Dexto repository
+- **Feature Requests**: Use the mcp-servers repository for tool-related requests
+
+## License
+
+This project is part of the Dexto AI agent framework.

package/agents/talk2pdf-agent/talk2pdf-agent.yml

@@ -0,0 +1,42 @@
+# Talk2PDF Agent
+# This agent provides natural language access to PDF parsing tools via a custom MCP server
+
+mcpServers:
+  talk2pdf:
+    type: stdio
+    command: npx
+    args:
+      - "@truffle-ai/talk2pdf-mcp"
+    timeout: 30000
+    connectionMode: strict 
+
+systemPrompt:
+  contributors:
+    - id: primary
+      type: static
+      priority: 0
+      content: |
+        You are a Talk2PDF Agent. You can parse PDF files, extract their text, metadata, and provide summaries or extract specific sections for LLM consumption.
+        
+        ## Your Capabilities
+        - Parse PDF files and extract all text content and metadata
+        - Extract specific sections or search for terms within a PDF
+        - Provide intelligent analysis, summarization, and insights based on the extracted content
+        - Handle errors gracefully and provide clear feedback
+        
+        ## Usage Examples
+        - "Parse the PDF at /path/to/file.pdf and show me the text."
+        - "Analyze and summarize the document at /path/to/file.pdf."
+        - "Extract all content containing 'invoice' from /path/to/file.pdf and explain what you found."
+        
+        Always ask for the file path if not provided. If a file is not a PDF or does not exist, inform the user.
+    - id: dateTime
+      type: dynamic
+      priority: 10
+      source: dateTime
+      enabled: true
+
+llm:
+  provider: openai
+  model: gpt-4.1-mini
+  apiKey: $OPENAI_API_KEY 

package/agents/triage-demo/README.md

@@ -0,0 +1,337 @@
+# TeamFlow Customer Support Triage Agent System
+
+This demonstration showcases an intelligent **Customer Support Triage System** built with Dexto agents for **TeamFlow**, a cloud-based project management and team collaboration platform. The system automatically analyzes customer inquiries, routes them to specialized support agents, and provides complete customer support responses.
+
+## 🏢 About TeamFlow (Demo Business Context)
+
+TeamFlow is a fictional cloud-based project management platform used for this demonstration. It offers three service tiers:
+
+- **Basic Plan ($9/user/month)**: Up to 10 team members, 5GB storage, basic features
+- **Pro Plan ($19/user/month)**: Up to 100 team members, 100GB storage, advanced integrations (Slack, GitHub, Salesforce)  
+- **Enterprise Plan ($39/user/month)**: Unlimited users, 1TB storage, SSO, dedicated support
+
+Key features include project management, team collaboration, time tracking, mobile apps, and a comprehensive API. The platform integrates with popular tools like Slack, GitHub, Salesforce, and Google Workspace.
+
+This realistic business context allows the agents to provide specific, accurate responses about pricing, features, technical specifications, and policies using the FileContributor system to access comprehensive documentation.
+
+## 🏗️ Architecture Overview
+
+```
+Customer Request
+       ↓
+   Triage Agent (Main Coordinator)
+       ↓
+   [Analyzes, Routes & Executes via MCP]
+       ↓
+┌─────────────────────────────────────────┐
+│  Technical Support  │  Billing Agent   │
+│      Agent          │                  │
+├─────────────────────┼──────────────────┤
+│  Product Info       │  Escalation      │
+│     Agent           │    Agent         │
+└─────────────────────────────────────────┘
+       ↓
+   Complete Customer Response
+```
+
+The triage agent doesn't just route requests - it **executes the specialized agents as MCP servers** and provides complete, integrated customer support responses that combine routing intelligence with expert answers.
+
+## 🤖 Agent Roles
+
+### 1. **Triage Agent** (`triage-agent.yml`)
+- **Primary Role**: Intelligent routing coordinator AND customer response provider
+- **Capabilities**: 
+  - Analyzes requests and categorizes issues
+  - Routes to specialists via `chat_with_agent` tool calls
+  - **Executes specialist agents directly through MCP connections**
+  - **Provides complete customer responses** combining routing + specialist answers
+- **Tools**: Filesystem, web research, **chat_with_agent** (connects to all specialists)
+- **Tool Confirmation**: Auto-approve mode for seamless delegation
+
+### 2. **Technical Support Agent** (`technical-support-agent.yml`) 
+- **Specialization**: Bug fixes, troubleshooting, system issues
+- **Tools**: Filesystem, terminal, browser automation
+- **Model**: GPT-4o (higher capability for complex technical issues)
+- **Connection**: Available as MCP server via stdio
+
+### 3. **Billing Agent** (`billing-agent.yml`)
+- **Specialization**: Payments, subscriptions, financial inquiries  
+- **Tools**: Browser automation, filesystem for policy docs
+- **Model**: GPT-4o-mini (efficient for structured billing processes)
+- **Connection**: Available as MCP server via stdio
+
+### 4. **Product Info Agent** (`product-info-agent.yml`)
+- **Specialization**: Features, comparisons, documentation
+- **Tools**: Web research (Tavily), filesystem, browser automation
+- **Model**: GPT-4o-mini (efficient for information retrieval)
+- **Connection**: Available as MCP server via stdio
+
+### 5. **Escalation Agent** (`escalation-agent.yml`)
+- **Specialization**: Complex issues, Enterprise customers, management approval
+- **Tools**: Filesystem, web research for compliance/legal info
+- **Model**: GPT-4o (higher capability for sensitive issues)
+- **Connection**: Available as MCP server via stdio
+
+## 📚 Business Context Documentation
+
+Each agent has access to relevant TeamFlow documentation via the FileContributor system:
+
+### Documentation Files (`docs/` folder)
+- **`company-overview.md`**: General company information, plans, SLAs, contact info
+- **`technical-documentation.md`**: API docs, system requirements, troubleshooting guides
+- **`billing-policies.md`**: Pricing, refund policies, billing procedures, payment methods
+- **`product-features.md`**: Feature descriptions, plan comparisons, integrations
+- **`escalation-policies.md`**: Escalation procedures, contact information, incident templates
+
+### Agent-Specific Context
+- **Technical Support**: Company overview + technical documentation
+- **Billing Agent**: Company overview + billing policies
+- **Product Info**: Company overview + product features
+- **Escalation**: Company overview + escalation policies
+- **Triage Agent**: Company overview for routing context
+
+## 🚀 Getting Started
+
+### Quick Start - Integrated Triage System
+
+The **recommended way** to run the triage system is using the main triage agent, which automatically connects to all specialists:
+
+```bash
+# Run the complete triage system (connects to all specialist agents automatically)
+npx dexto --agent agents/triage-demo/triage-agent.yml
+
+# Test with a customer inquiry
+npx dexto --agent agents/triage-demo/triage-agent.yml "I want to upgrade from Basic to Pro but confused about pricing"
+```
+
+This will:
+1. **Auto-connect** to all 4 specialist agents as MCP servers
+2. **Analyze** your request and route to the appropriate specialist  
+3. **Execute** the specialist agent to get the expert answer
+4. **Respond** with a complete customer support response
+
+### Running Individual Agents (Advanced)
+
+For testing individual specialist agents:
+
+```bash
+# Run specialized agents individually  
+npx dexto --agent agents/triage-demo/technical-support-agent.yml
+npx dexto --agent agents/triage-demo/billing-agent.yml
+npx dexto --agent agents/triage-demo/product-info-agent.yml
+npx dexto --agent agents/triage-demo/escalation-agent.yml
+```
+
+### Environment Setup
+
+Ensure you have the required API keys in your `.env` file:
+
+```env
+OPENAI_API_KEY=your_openai_api_key
+TAVILY_API_KEY=your_tavily_api_key  # For web research
+```
+
+## 📋 Example Scenarios
+
+### Scenario 1: Technical Issue
+**Customer Input**: *"My app keeps crashing when I try to upload files. Getting error code 500."*
+
+**Triage Agent Response**:
+- **Analysis**: Technical Issue → Route to Technical Support Agent
+- **Execution**: Calls `chat_with_agent` → Technical Support provides debugging steps
+- **Customer Response**: *"I've routed your issue to our Technical Support team. Here's how to resolve the 500 error when uploading files: [detailed technical troubleshooting steps from specialist]"*
+
+### Scenario 2: Billing Question  
+**Customer Input**: *"I want to upgrade from Basic to Pro but confused about pricing. Will I be charged the full amount?"*
+
+**Triage Agent Response**:
+- **Analysis**: Billing Question → Route to Billing Agent  
+- **Execution**: Calls `chat_with_agent` → Billing Agent explains prorated pricing
+- **Customer Response**: *"I've routed your inquiry to our Billing team. When upgrading from Basic to Pro, you'll only be charged a prorated amount for the remaining billing period - just the difference between plans for the time left in your cycle. The upgrade takes effect immediately."*
+
+### Scenario 3: Product Information
+**Customer Input**: *"What's the difference between your Pro and Enterprise plans? I need API access."*
+
+**Triage Agent Response**:
+- **Analysis**: Product Inquiry → Route to Product Info Agent
+- **Execution**: Calls `chat_with_agent` → Product Info Agent provides detailed comparison
+- **Customer Response**: *"I've connected you with our Product team. Both Pro and Enterprise plans include full API access. The main differences are: Pro supports up to 100 users with 100GB storage, while Enterprise offers unlimited users, 1TB storage, SSO, and dedicated support. [detailed feature comparison]"*
+
+### Scenario 4: Escalation Required
+**Customer Input**: *"This is my third time contacting support about data privacy concerns. I'm considering legal action."*
+
+**Triage Agent Response**:
+- **Analysis**: Legal/Compliance Issue → Route to Escalation Agent
+- **Execution**: Calls `chat_with_agent` → Escalation Agent provides management contact
+- **Customer Response**: *"I've escalated your data privacy concerns to our senior support team. Given the legal implications, I'm connecting you directly with our compliance manager Sarah Johnson (sarah.johnson@teamflow.com). She'll address your concerns within 2 hours."*
+
+## 🔧 Advanced Configuration
+
+### Current MCP Server Configuration (Automatic)
+
+The triage agent automatically connects to specialists via stdio MCP servers:
+
+```yaml
+# Current configuration in triage-agent.yml
+mcpServers:
+  technical_support:
+    type: stdio
+    command: npx
+    args: [dexto, --mode, mcp, --agent, agents/triage-demo/technical-support-agent.yml]
+  
+  billing_support:
+    type: stdio  
+    command: npx
+    args: [dexto, --mode, mcp, --agent, agents/triage-demo/billing-agent.yml]
+  
+  # Similar configuration for product_info and escalation agents...
+```
+
+### Production Configuration (Distributed Servers)
+
+For production deployment, you would run each specialist as a separate server:
+
+```yaml
+# triage-agent.yml - Production Configuration
+mcpServers:
+  technical_support:
+    type: sse
+    url: "http://localhost:3001/mcp"
+    headers:
+      Authorization: "Bearer your-auth-token"
+  
+  billing_support:
+    type: sse  
+    url: "http://localhost:3002/mcp"
+    headers:
+      Authorization: "Bearer your-auth-token"
+  
+  product_info:
+    type: sse
+    url: "http://localhost:3003/mcp"
+    headers:
+      Authorization: "Bearer your-auth-token"
+    
+  escalation:
+    type: sse
+    url: "http://localhost:3004/mcp"
+    headers:
+      Authorization: "Bearer your-auth-token"
+```
+
+### Running Distributed Servers
+
+```bash
+# Terminal 1: Technical Support Server
+npx dexto --agent agents/triage-demo/technical-support-agent.yml --mode server --port 3001
+
+# Terminal 2: Billing Support Server  
+npx dexto --agent agents/triage-demo/billing-agent.yml --mode server --port 3002
+
+# Terminal 3: Product Info Server
+npx dexto --agent agents/triage-demo/product-info-agent.yml --mode server --port 3003
+
+# Terminal 4: Escalation Server
+npx dexto --agent agents/triage-demo/escalation-agent.yml --mode server --port 3004
+
+# Terminal 5: Main Triage Coordinator
+npx dexto --agent agents/triage-demo/triage-agent.yml --mode server --port 3000
+```
+
+## 🎯 Key Features Demonstrated
+
+### 1. **Intelligent Routing with Execution**
+- Natural language analysis to determine issue category
+- **Automatic execution** of specialist agents via MCP
+- **Complete customer responses** combining routing + expert answers
+- Seamless tool confirmation with auto-approve mode
+
+### 2. **Specialized Expertise Integration**
+- Each agent has domain-specific knowledge and tools
+- **Real-time coordination** between triage and specialists
+- **Unified customer experience** despite multi-agent backend
+
+### 3. **Scalable MCP Architecture**
+- **Stdio connections** for local development and testing
+- **SSE connections** for distributed production deployment
+- **Tool-based delegation** using `chat_with_agent`
+
+### 4. **Comprehensive Tool Access**
+- Filesystem access for documentation and logging
+- Web research capabilities for up-to-date information
+- Browser automation for testing and demonstrations
+- **Agent-to-agent communication** via MCP tools
+
+## 🔍 Testing the System
+
+### Interactive Testing
+
+1. **Start the complete triage system**:
+   ```bash
+   npx dexto --agent agents/triage-demo/triage-agent.yml
+   ```
+
+2. **Test with various customer scenarios** and observe:
+   - **Routing analysis** (which specialist is chosen)
+   - **Tool execution** (`chat_with_agent` calls)
+   - **Complete responses** (routing confirmation + specialist answer)
+
+### Sample Test Cases
+
+```
+Test 1: "API returns 401 unauthorized error"
+Expected: Technical Support Agent → Complete troubleshooting response
+
+Test 2: "Cancel my subscription immediately"  
+Expected: Billing Agent → Complete cancellation process and policy info
+
+Test 3: "Do you have a mobile app?"
+Expected: Product Info Agent → Complete feature details and download links
+
+Test 4: "Your service caused my business to lose $10,000"
+Expected: Escalation Agent → Complete escalation with management contact
+```
+
+### One-Shot Testing
+
+```bash
+# Test billing scenario
+npx dexto --agent agents/triage-demo/triage-agent.yml "I was charged twice this month"
+
+# Test technical scenario  
+npx dexto --agent agents/triage-demo/triage-agent.yml "Getting 500 errors on file upload"
+
+# Test product scenario
+npx dexto --agent agents/triage-demo/triage-agent.yml "What integrations do you support?"
+```
+
+## 🚦 Production Considerations
+
+### Security
+- Implement proper authentication between agents
+- Secure API key management  
+- Customer data privacy controls
+- **Tool confirmation policies** for sensitive operations
+
+### Monitoring  
+- Log all routing decisions and tool executions
+- Track resolution times by agent type
+- Monitor escalation patterns
+- **Tool usage analytics** for optimization
+
+### Scaling
+- Load balance multiple instances of specialist agents
+- Implement request queuing for high volume
+- **Distributed MCP server deployment**
+- Add more specialized agents as needed (e.g., Sales, Onboarding)
+
+## 🤝 Contributing
+
+To extend this triage system:
+
+1. **Add new specialist agents** by creating new YAML configs
+2. **Update triage routing logic** in the main agent's system prompt  
+3. **Configure new agents as MCP servers** in the triage agent's mcpServers section
+4. **Test end-to-end flow** including tool execution and complete responses
+
+This demonstration showcases the power of **multi-agent coordination with tool execution** using Dexto's MCP integration capabilities! 

package/agents/triage-demo/billing-agent.yml

@@ -0,0 +1,76 @@
+# Billing Agent Configuration
+# Specializes in billing, payments, subscriptions, and financial inquiries
+
+systemPrompt:
+  contributors:
+    - id: base-prompt
+      type: static
+      priority: 0
+      content: |
+        You are a specialized Billing Agent for TeamFlow, responsible for handling payment issues, subscription management, and financial inquiries.
+
+        Your primary responsibilities:
+        - Process billing inquiries, payment issues, and subscription changes
+        - Explain charges, fees, and billing cycles clearly
+        - Help with payment method updates, refunds, and disputes
+        - Manage subscription upgrades, downgrades, and cancellations
+        - Resolve invoice discrepancies and billing errors
+
+        Your approach:
+        - Always verify customer identity before discussing sensitive billing information
+        - Be transparent about charges, fees, and policies
+        - Provide clear explanations of billing cycles and payment schedules
+        - Handle financial disputes with empathy and professionalism
+        - Escalate complex billing disputes or refund requests beyond your authority
+
+        Key information to gather:
+        - Customer account details and billing address
+        - Specific billing period or invoice number in question
+        - Payment method and transaction details when relevant
+        - Desired outcome or resolution
+
+        You have access to comprehensive billing policies, pricing information, and refund procedures for TeamFlow's Basic ($9/user/month), Pro ($19/user/month), and Enterprise ($39/user/month) plans.
+
+        Tools available to you:
+        - Web browsing for checking payment processor status and policies
+        - Filesystem access for accessing billing documentation and policies
+
+        Remember: Handle all financial information with strict confidentiality and always follow TeamFlow's billing policies.
+    
+    - id: company-overview
+      type: file
+      priority: 10
+      files:
+        - "${{dexto.agent_dir}}/docs/company-overview.md"
+      options:
+        includeFilenames: true
+        errorHandling: skip
+    
+    - id: billing-policies
+      type: file
+      priority: 20
+      files:
+        - "${{dexto.agent_dir}}/docs/billing-policies.md"
+      options:
+        includeFilenames: true
+        errorHandling: skip
+
+mcpServers:
+  puppeteer:
+    type: stdio
+    command: npx
+    args:
+      - -y
+      - "@truffle-ai/puppeteer-server"
+  filesystem:
+    type: stdio
+    command: npx
+    args:
+      - -y
+      - "@modelcontextprotocol/server-filesystem"
+      - .
+
+llm:
+  provider: openai
+  model: gpt-4o-mini
+  apiKey: $OPENAI_API_KEY