dexto 1.0.1 → 1.1.0

package/agents/music-agent/README.md

@@ -0,0 +1,294 @@
+# Music Creator Agent
+
+A comprehensive AI agent for music creation, editing, and audio processing using the [Music Creator MCP Server](https://github.com/truffle-ai/mcp-servers/tree/main/src/music).
+
+> **⚠️ Experimental Status**: This agent is currently in experimental development. The tools have not been extensively tested in production environments and may have limitations or bugs. We're actively seeking feedback and improvements from users.
+## 🧪 Experimental Features
+
+- **Limited Testing**: Tools have been tested in controlled environments but may behave differently with various audio formats, file sizes, or system configurations
+- **Active Development**: Features are being refined based on user feedback and real-world usage
+- **Feedback Welcome**: We encourage users to report issues, suggest improvements, and share use cases
+- **Breaking Changes**: API and tool behavior may change as we improve the implementation
+
+## Overview
+
+This agent provides access to professional-grade music production tools through a clean conversational interface. Built with industry-standard libraries like librosa, pydub, and music21, it offers comprehensive audio processing capabilities using the published `truffle-ai-music-creator-mcp` package.
+
+## Features
+
+### 🎵 Audio Analysis
+- **Tempo Detection**: Automatically detect BPM and beat positions
+- **Key Detection**: Identify musical key and mode
+- **Spectral Analysis**: Analyze frequency spectrum, MFCC features, and audio characteristics
+- **Comprehensive Analysis**: Get detailed audio information including duration, sample rate, and format
+
+### 🎼 Music Generation
+- **Melody Creation**: Generate melodies in any key and scale
+- **Chord Progressions**: Create chord progressions using Roman numeral notation
+- **Drum Patterns**: Generate drum patterns for rock, jazz, and funk styles
+- **MIDI Export**: All generated music exports to MIDI format for further editing
+
+### 🔊 Audio Processing
+- **Format Conversion**: Convert between MP3, WAV, FLAC, OGG, M4A, AIFF, WMA
+- **Volume Control**: Adjust audio levels with precise dB control
+- **Audio Normalization**: Normalize audio to target levels
+- **Audio Trimming**: Cut audio to specific time ranges
+- **Audio Effects**: Apply reverb, echo, distortion, and filters
+
+### 🎚️ Mixing & Arrangement
+- **Audio Merging**: Combine multiple audio files with crossfade support
+- **Multi-track Mixing**: Mix multiple audio tracks with individual volume control
+- **Batch Processing**: Process multiple files with the same operation
+
+## Quick Start
+
+### Prerequisites
+- **Node.js 18+**: For the Dexto framework
+- **Python 3.10+**: Automatically managed by the MCP server
+- **FFmpeg**: For audio processing (optional, but recommended)
+
+### Installation
+
+1. **Install FFmpeg** (recommended):
+   ```bash
+   # macOS
+   brew install ffmpeg
+   
+   # Ubuntu/Debian
+   sudo apt update && sudo apt install ffmpeg
+   ```
+
+2. **Run the Agent**:
+   ```bash
+   # From the project root
+   dexto --agent agents/music-agent/music-agent.yml
+   ```
+
+That's it! The MCP server will be automatically downloaded and installed via `uvx` on first run.
+
+## Usage Examples
+
+### Audio Analysis
+```
+"Analyze the tempo and key of my song.mp3"
+"What's the BPM of this track?"
+"What key is this song in?"
+```
+
+### Music Generation
+```
+"Create a melody in G major at 140 BPM for 15 seconds"
+"Create a I-IV-V-I chord progression in D major"
+"Create a basic rock drum pattern"
+```
+
+### Audio Processing
+```
+"Convert my song.wav to MP3 format"
+"Convert my MIDI melody to WAV format"
+"Increase the volume of my vocals by 3dB"
+"Normalize my guitar track to -18dB"
+"Trim my song from 30 seconds to 2 minutes"
+```
+
+### Audio Effects
+```
+"Add reverb to my guitar with 200ms reverb time"
+"Add echo to my vocals with 500ms delay and 0.7 decay"
+"Add some distortion to my bass track"
+```
+
+### Mixing & Playback
+```
+"Mix my vocals, guitar, and drums together with the vocals at +3dB"
+"Mix a MIDI melody with an MP3 drum loop"
+"Create a melody in G major and play it for 5 seconds"
+"Play my song.mp3 starting from 30 seconds for 10 seconds"
+```
+
+## Available Tools
+
+### Music Generation
+- `create_melody` - Generate melodies in any key and scale
+- `create_chord_progression` - Create chord progressions using Roman numerals
+- `create_drum_pattern` - Generate drum patterns for different styles
+
+### Audio Analysis
+- `analyze_audio` - Comprehensive audio analysis
+- `detect_tempo` - Detect BPM and beat positions
+- `detect_key` - Identify musical key and mode
+- `get_audio_info` - Get detailed audio file information
+- `get_midi_info` - Get detailed MIDI file information
+
+### Audio Processing
+- `convert_audio_format` - Convert between audio formats
+- `convert_midi_to_audio` - Convert MIDI files to high-quality audio format (WAV, 44.1kHz, 16-bit)
+- `adjust_volume` - Adjust audio levels in dB
+- `normalize_audio` - Normalize audio to target levels
+- `trim_audio` - Cut audio to specific time ranges
+- `apply_audio_effect` - Apply reverb, echo, distortion, filters
+
+### Mixing & Arrangement
+- `merge_audio_files` - Combine multiple audio files
+- `mix_audio_files` - Mix tracks with individual volume control (supports both audio and MIDI files)
+
+### Playback
+- `play_audio` - Play audio files with optional start time and duration
+- `play_midi` - Play MIDI files with optional start time and duration
+
+### Utility
+- `list_available_effects` - List all audio effects
+- `list_drum_patterns` - List available drum patterns
+
+## Supported Formats
+
+### Audio Formats
+- **MP3**: Most common compressed format
+- **WAV**: Uncompressed high-quality audio
+- **FLAC**: Lossless compressed audio
+- **OGG**: Open-source compressed format
+- **M4A**: Apple's compressed format
+- **AIFF**: Apple's uncompressed format
+- **WMA**: Windows Media Audio
+
+### MIDI Formats
+- **MID**: Standard MIDI files
+- **MIDI**: Alternative MIDI extension
+
+## Configuration
+
+### Agent Configuration
+The agent is configured to use the published MCP server:
+
+```yaml
+systemPrompt: |
+  You are an AI assistant specialized in music creation, editing, and production...
+
+mcpServers:
+  music_creator:
+    type: stdio
+    command: uvx
+    args:
+      - truffle-ai-music-creator-mcp
+    connectionMode: strict
+
+llm:
+  provider: openai
+  model: gpt-4o-mini
+  apiKey: $OPENAI_API_KEY
+```
+
+### Environment Variables
+Set your OpenAI API key:
+
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+```
+
+Or create a `.env` file in the project root:
+
+```bash
+OPENAI_API_KEY=your-api-key-here
+```
+
+## Use Cases
+
+### Music Production
+- Create backing tracks and accompaniments
+- Generate drum patterns for different genres
+- Compose melodies and chord progressions
+- Mix and master audio tracks
+
+### Audio Editing
+- Clean up audio recordings
+- Normalize volume levels
+- Apply professional effects
+- Convert between formats
+
+### Music Analysis
+- Analyze existing music for tempo and key
+- Extract musical features for machine learning
+- Study musical patterns and structures
+- Compare different audio files
+
+### Educational
+- Learn about musical theory through generation
+- Study different musical styles and patterns
+- Experiment with composition techniques
+- Understand audio processing concepts
+
+## MCP Server
+
+This agent uses the **Music Creator MCP Server**, which is maintained separately at:
+
+**🔗 [https://github.com/truffle-ai/mcp-servers/tree/main/src/music](https://github.com/truffle-ai/mcp-servers/tree/main/src/music)**
+
+The MCP server repository provides:
+- Complete technical documentation
+- Development and contribution guidelines  
+- Server implementation details
+- Advanced configuration options
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Server Installation
+The MCP server will be automatically installed via `uvx` on first run. No manual setup required.
+
+#### 2. "FFmpeg not found" warnings
+These warnings can be safely ignored. The agent includes fallback methods using librosa and soundfile for audio processing when FFmpeg is not available.
+
+```bash
+# Optional: Install FFmpeg for optimal performance
+brew install ffmpeg  # macOS
+sudo apt install ffmpeg  # Ubuntu/Debian
+```
+
+#### 3. Large Audio Files
+Consider trimming or converting to smaller formats for faster processing.
+
+#### 4. Memory Usage
+Monitor system memory during heavy audio operations.
+
+### Performance Tips
+
+1. **Large Audio Files**: Consider trimming or converting to smaller formats for faster processing
+2. **Memory Usage**: Monitor system memory during heavy audio operations
+3. **Batch Processing**: Use batch operations for multiple files to improve efficiency
+4. **FFmpeg**: Install FFmpeg for optimal audio processing performance (optional - fallback methods available)
+
+## Technical Details
+
+### Dependencies
+The MCP server uses industry-standard libraries:
+- **librosa**: Audio analysis and music information retrieval
+- **pydub**: Audio file manipulation and processing
+- **music21**: Music notation and analysis
+- **pretty_midi**: MIDI file handling
+- **numpy**: Numerical computing
+- **scipy**: Scientific computing
+- **matplotlib**: Plotting and visualization
+
+### Architecture
+The agent uses a Python-based MCP server that provides:
+- Fast audio processing with optimized libraries
+- Memory-efficient handling of large audio files
+- Thread-safe operations for concurrent processing
+- Comprehensive error handling and validation
+
+### Performance
+- Supports audio files up to several hours in length
+- Efficient processing of multiple file formats
+- Optimized algorithms for real-time analysis
+- Minimal memory footprint for batch operations
+
+## 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 agent configuration is part of the Dexto AI Agent framework. The MCP server is distributed under the MIT license.

package/agents/music-agent/music-agent.yml

@@ -0,0 +1,43 @@
+# Dexto Agent Configuration for Music Creation and Editing MCP Server
+
+systemPrompt: |
+  You are an AI assistant specialized in music creation, editing, and production. You have access to a comprehensive set of tools for working with audio and music including:
+  
+  - **Audio Analysis**: Analyze audio files for tempo, key, BPM, frequency spectrum, and audio characteristics
+  - **Audio Processing**: Convert formats, adjust volume, normalize, apply effects (reverb, echo, distortion, etc.)
+  - **Music Generation**: Create melodies, chord progressions, drum patterns, and complete compositions
+  - **Audio Manipulation**: Trim, cut, splice, loop, and arrange audio segments
+  - **Effects & Filters**: Apply various audio effects and filters for creative sound design
+  - **Mixing & Mastering**: Balance levels, apply compression, EQ, and mastering effects
+  - **File Management**: Organize, convert, and manage audio files in various formats
+  
+  When working with music and audio:
+  1. Always validate that input audio files exist and are in supported formats
+  2. Provide clear feedback about what operations you're performing
+  3. Save processed audio with descriptive names and appropriate formats
+  4. Include audio information (duration, sample rate, bit depth, format) in your responses
+  5. Suggest additional enhancements and creative possibilities when appropriate
+  6. Consider musical theory and composition principles in your suggestions
+  
+  Supported audio formats: MP3, WAV, FLAC, OGG, M4A, AIFF, WMA
+  Supported MIDI formats: MID, MIDI
+
+mcpServers:
+  music_creator:
+    type: stdio
+    command: uvx
+    args:
+      - truffle-ai-music-creator-mcp
+    connectionMode: strict
+
+llm:
+  provider: openai
+  model: gpt-4o-mini
+  apiKey: $OPENAI_API_KEY
+
+storage:
+  cache:
+    type: in-memory
+  database:
+    type: sqlite
+    path: .dexto/database/music-agent.db 

package/agents/product-name-researcher/README.md

@@ -0,0 +1,98 @@
+# Product Name Research Agent
+
+An AI agent specialized in comprehensive product name research and brand validation. Combines domain availability checking, search engine analysis, developer platform collision detection, and competitive intelligence to provide thorough name validation.
+
+## 📖 Tutorial
+
+For a complete walkthrough of building and using this agent, see the [Product Name Scout Agent Tutorial](../../docs/docs/tutorials/product-name-scout-agent.md).
+
+## Features
+
+- **Domain Availability**: Check multiple TLD extensions (.com, .io, .app, .dev, etc.)
+- **SERP Competition Analysis**: Analyze search engine results for brand competition
+- **Autocomplete Intelligence**: Assess name recognition and spelling patterns
+- **Developer Platform Collision Detection**: Check GitHub, npm, and PyPI for conflicts
+- **Competitive Research**: DuckDuckGo-powered market intelligence
+- **Comprehensive Scoring**: Weighted algorithms for brand viability assessment
+- **Batch Comparison**: Compare multiple names with detailed scoring breakdown
+
+## Prerequisites
+
+Ensure you have the domain checker MCP server available:
+
+```bash
+# Install the domain checker MCP server
+uvx truffle-ai-domain-checker-mcp
+```
+
+## Usage
+
+### Start the Agent
+
+```bash
+# From the dexto root directory
+dexto -a agents/product-name-researcher/product-name-researcher.yml
+```
+
+### Example Interactions
+
+**Single Product Name Research:**
+```
+User: I want to research the name "CloudSync" for my new file sync product
+Agent: [Performs comprehensive research including domain availability, trademark search, social media handles, and competitive analysis]
+```
+
+**Compare Multiple Names:**
+```
+User: Help me choose between "DataFlow", "InfoStream", and "SyncHub" for my data management tool
+Agent: [Compares all three names across multiple criteria and provides recommendations]
+```
+
+**Domain-Focused Research:**
+```
+User: Check domain availability for "myawesomeapp" across all major TLDs
+Agent: [Uses domain checker to verify availability across .com, .net, .org, .io, .app, etc.]
+```
+
+## Configuration
+
+The agent uses:
+- **Domain Checker MCP Server**: For domain availability checking
+- **DuckDuckGo MCP Server**: For web search and competitive research
+- **Product Name Scout MCP Server**: For SERP analysis, autocomplete, and developer collision detection
+
+## Research Report
+
+The agent generates comprehensive reports including:
+
+1. **Domain Availability Summary**
+   - Available domains with recommendations
+   - Pricing information where available
+   - Alternative TLD suggestions
+
+2. **Trademark Analysis**
+   - Similar trademarks found
+   - Risk assessment
+   - Recommendations for trademark clearance
+
+3. **Developer Platform Analysis**
+   - GitHub repository conflicts
+   - NPM package collisions
+   - PyPI package conflicts
+
+4. **Competitive Landscape**
+   - Existing products with similar names
+   - Market positioning analysis
+   - Differentiation opportunities
+
+5. **Overall Recommendation**
+   - Scoring across all criteria
+   - Risk assessment
+   - Next steps recommendations
+
+## Tips for Best Results
+
+- **Be specific about your product**: Include the product category and target market
+- **Provide alternatives**: Give multiple name options for comparison
+- **Consider your priorities**: Mention if domain availability, trademark clearance, or developer platform conflicts are most important
+- **Think internationally**: Consider how the name works in different languages and markets

package/agents/product-name-researcher/product-name-researcher.yml

@@ -0,0 +1,161 @@
+# Product Name Research Agent Configuration
+# Specializes in comprehensive product name validation including domain availability,
+# trademark searching, social media handle checking, and competitive analysis
+
+mcpServers:
+  # Domain availability checking
+  domain-checker:
+    type: stdio
+    command: uvx
+    args:
+      - truffle-ai-domain-checker-mcp
+  
+  # Web search for competitive research and trademark checking
+  duckduckgo:
+    type: stdio
+    command: uvx
+    args:
+      - duckduckgo-mcp-server
+  
+  # Advanced product name research tools (SERP analysis, autocomplete, dev collisions, scoring)
+  product-name-scout:
+    type: stdio
+    command: npx
+    args:
+      - "@truffle-ai/product-name-scout-mcp"
+
+systemPrompt:
+  contributors:
+    - id: primary
+      type: static
+      priority: 0
+      content: |
+        You are a specialized Product Name Research Agent focused on helping entrepreneurs, product managers, and marketing teams validate potential product names through comprehensive research. Your expertise combines domain availability checking with competitive landscape analysis and market research.
+
+        ## Your Core Capabilities
+
+        ### 1. Domain Availability Research
+        - Use the domain-checker tools to verify domain availability across multiple TLDs
+        - Prioritize .com, .ai, .dev, .org, .io, .app and .tech extensions, in that order.
+        - Provide recommendations on domain alternatives and pricing considerations
+        - Check domain variations (with/without hyphens, plurals, abbreviations)
+        - Compare multiple domain options for product names
+
+        ### 2. Competitive Research & Market Analysis
+        - Use DuckDuckGo search to research existing products/companies with similar names
+        - Search for trademark conflicts and existing brand usage
+        - Analyze competitive landscape and market positioning
+        - Research industry-specific naming conventions and trends
+        - Identify potential brand confusion or conflicts
+
+        ### 3. Comprehensive Brand Validation
+        - Combine domain availability with competitive research
+        - Assess market saturation for similar product names
+        - Evaluate naming conflicts across different industries
+        - Research social media presence and brand mentions
+        - Provide risk assessments for trademark and competitive conflicts
+
+        ## Research Methodology
+
+        ### For Single Name Research:
+        1. **Domain Availability Check**: Use domain-checker to verify availability across key TLDs
+        2. **Competitive Analysis**: Search DuckDuckGo for existing companies/products with similar names
+        3. **Trademark Research**: Search for trademark conflicts and existing brand usage
+        4. **Market Context**: Research industry usage and naming patterns
+        5. **Risk Assessment**: Evaluate potential conflicts and brand confusion risks
+        6. **Strategic Recommendations**: Provide actionable recommendations based on all findings
+
+        ### For Multiple Name Comparison:
+        1. **Batch Domain Analysis**: Check all names across key TLD extensions
+        2. **Competitive Research**: Search each name for existing market presence
+        3. **Comparison Matrix**: Create comprehensive comparison including domains and competitive landscape
+        4. **Scoring & Ranking**: Rank names based on availability, competitive conflicts, and strategic value
+        5. **Final Recommendation**: Provide clear recommendation with detailed reasoning
+
+        ## Key Guidelines
+
+        ### Domain Research Best Practices:
+        - Always start with .com availability as the highest priority
+        - Check .ai, .dev, .io, .app, .tech for tech/startup products
+        - Consider .org for non-profits or community-focused products
+        - Test common misspellings and character variations
+        - Look for patterns in domain availability that might indicate trademark issues
+
+        ### Competitive Research Best Practices:
+        - Search for exact name matches and close variations
+        - Research across different industries and markets
+        - Look for existing trademarks and brand registrations
+        - Check for social media presence and brand mentions
+        - Identify potential customer confusion risks
+        - Consider international markets and global brand presence
+
+        ### Search Strategy Guidelines:
+        - Use specific search queries: "[name] company", "[name] trademark", "[name] brand"
+        - Search for industry-specific usage: "[name] [industry]", "[name] product"
+        - Look for legal conflicts: "[name] lawsuit", "[name] trademark dispute"
+        - Check domain parking and cybersquatting patterns
+        - Research naming trends in the target industry
+
+        ### Interaction Guidelines:
+        - **Ask targeted questions**: Product category, target market, budget considerations
+        - **Provide context**: Explain why domain choices matter for business success
+        - **Be practical**: Focus on actionable domain strategies within user's budget
+        - **Offer alternatives**: When preferred domains are taken, suggest creative variations
+        - **Think holistically**: Consider how domain choice impacts overall brand strategy
+
+        ## Available Tools
+
+        ### Domain Checking Tools:
+        1. **check_domain(domain)**: Check a single domain's availability
+        2. **check_multiple_domains(domains)**: Check multiple domains at once
+        3. **check_domain_variations(base_name, extensions)**: Check a name across multiple TLD extensions
+
+        ### Advanced Name Analysis Tools:
+        1. **check_brand_serp(name, engine, limit)**: Analyze search engine results for brand competition and searchability
+        2. **get_autocomplete(name)**: Get search engine autocomplete suggestions to assess name recognition
+        3. **check_dev_collisions(name, platforms)**: Check for existing projects on GitHub, npm, PyPI
+        4. **score_name(name, weights, rawSignals)**: Get comprehensive scoring across multiple factors
+
+        ### Research Tools:
+        1. **search(query, max_results)**: Search DuckDuckGo for competitive research and market analysis
+        2. **get_content(url)**: Extract and analyze content from specific web pages
+
+        ## Tool Usage Strategy:
+
+        **For Comprehensive Research:**
+        1. Start with domain availability using domain-checker tools
+        2. Analyze search competition: `check_brand_serp(name)` to assess existing brand presence
+        3. Check autocomplete patterns: `get_autocomplete(name)` to understand search behavior
+        4. Identify developer conflicts: `check_dev_collisions(name)` for tech product names
+        5. Search for existing companies/products: `search("[name] company")`
+        6. Check for trademarks: `search("[name] trademark")`
+        7. Research industry usage: `search("[name] [industry] product")`
+        8. Look for legal issues: `search("[name] lawsuit trademark dispute")`
+        9. Get comprehensive scoring: `score_name(name)` for overall assessment
+        10. Get detailed content from relevant pages using `get_content(url)`
+
+        Use these tools strategically to provide comprehensive product name validation that combines technical availability with market intelligence.
+
+    - id: dateTime
+      type: dynamic
+      priority: 10
+      source: dateTime
+      enabled: true
+
+# LLM configuration
+llm:
+  provider: anthropic
+  model: claude-4-sonnet-20250514
+  apiKey: $ANTHROPIC_API_KEY
+
+# Storage configuration
+storage:
+  cache:
+    type: in-memory
+  database:
+    type: sqlite
+
+# Tool confirmation - auto-approve for seamless domain checking
+toolConfirmation:
+  mode: auto-approve
+  allowedToolsStorage: memory