aia 0.9.11 → 0.9.12

data/docs/configuration.md

@@ -0,0 +1,347 @@
+# Configuration
+
+AIA provides a flexible configuration system with multiple layers of precedence, allowing you to customize behavior at different levels.
+
+## Configuration Precedence
+
+AIA follows a hierarchical configuration system (highest to lowest precedence):
+
+1. **Embedded Directives** - `//config` directives in prompt files
+2. **Command Line Arguments** - CLI flags and options
+3. **Environment Variables** - Shell environment variables
+4. **Configuration Files** - YAML configuration files
+5. **Defaults** - Built-in default values
+
+## Configuration Files
+
+### Primary Configuration File
+
+The main configuration file is located at `~/.aia/config.yml`:
+
+```yaml
+# ~/.aia/config.yml - Main AIA configuration
+
+# Core Settings
+adapter: ruby_llm              # AI adapter to use (currently only ruby_llm)
+model: gpt-3.5-turbo          # Default AI model
+prompts_dir: ~/.prompts        # Directory containing prompt files
+roles_prefix: roles            # Subdirectory name for role files
+
+# AI Parameters
+temperature: 0.7               # Creativity/randomness (0.0-2.0)
+max_tokens: 2000              # Maximum response length
+top_p: 1.0                    # Nucleus sampling
+frequency_penalty: 0.0        # Repetition penalty (-2.0 to 2.0)
+presence_penalty: 0.0         # Topic penalty (-2.0 to 2.0)
+
+# Output Settings
+out_file: null                # Output file (null = no file output)
+append: false                 # Append to output file instead of overwriting
+markdown: true                # Format output with Markdown
+verbose: false                # Show detailed output
+debug: false                  # Enable debug logging
+
+# Chat Settings
+chat: false                   # Start in chat mode
+terse: false                  # Request shorter AI responses
+system_prompt: null           # Default system prompt for chat
+
+# Audio/Speech Settings
+speak: false                  # Convert text to speech
+voice: alloy                  # Voice for speech synthesis
+speech_model: tts-1           # Model for text-to-speech
+transcription_model: whisper-1 # Model for speech-to-text
+
+# Image Generation Settings
+image_size: 1024x1024         # Default image size
+image_quality: standard       # Image quality (standard/hd)
+image_style: vivid           # Image style (vivid/natural)
+
+# Search Settings
+fuzzy: false                  # Enable fuzzy prompt searching
+parameter_regex: null         # Regex for parameter extraction
+
+# Tool Settings
+tool_paths: []                # Paths to tool files/directories
+allowed_tools: []             # Whitelist of allowed tools
+rejected_tools: []            # Blacklist of rejected tools
+require_libs: []              # Ruby libraries to require
+
+# Workflow Settings
+pipeline: []                  # Default prompt pipeline
+executable_prompt: false     # Run prompts as executables
+
+# Logging
+log_file: null               # Log file path
+refresh: 7                   # Model database refresh interval (days)
+```
+
+### Model-Specific Configuration
+
+You can create model-specific configuration files:
+
+```yaml
+# ~/.aia/models/gpt-4.yml
+temperature: 0.3
+max_tokens: 4000
+top_p: 0.95
+```
+
+```yaml
+# ~/.aia/models/claude-3.yml  
+temperature: 0.5
+max_tokens: 8000
+```
+
+## Environment Variables
+
+All configuration options can be set via environment variables with the `AIA_` prefix:
+
+```bash
+# Core settings
+export AIA_MODEL="gpt-4"
+export AIA_TEMPERATURE="0.8"
+export AIA_PROMPTS_DIR="/path/to/my/prompts"
+
+# API Keys (handled by RubyLLM)
+export OPENAI_API_KEY="your_key_here"
+export ANTHROPIC_API_KEY="your_key_here" 
+export GOOGLE_API_KEY="your_key_here"
+
+# Chat settings
+export AIA_CHAT="true"
+export AIA_VERBOSE="true"
+export AIA_DEBUG="false"
+
+# Output settings
+export AIA_OUT_FILE="/tmp/aia_output.md"
+export AIA_MARKDOWN="true"
+```
+
+## Command Line Arguments
+
+All options can be overridden via command line arguments. See [CLI Reference](cli-reference.md) for complete details.
+
+## Embedded Directives
+
+Prompts can contain configuration directives that override all other settings:
+
+```markdown
+//config model claude-3-sonnet
+//config temperature 0.9
+//config max_tokens 1500
+
+Write a creative story about...
+```
+
+## Advanced Configuration
+
+### Multi-Model Configuration
+
+Configure multiple models with different settings:
+
+```yaml
+models:
+  creative_writer:
+    model: gpt-4
+    temperature: 1.2
+    max_tokens: 3000
+    
+  code_analyzer:
+    model: claude-3-sonnet
+    temperature: 0.1
+    max_tokens: 4000
+    
+  quick_helper:
+    model: gpt-3.5-turbo
+    temperature: 0.7
+    max_tokens: 1000
+```
+
+Use with: `aia --model creative_writer my_prompt`
+
+### Tool Configuration
+
+Configure tool paths and permissions:
+
+```yaml
+# Global tool settings
+tool_paths:
+  - ~/.aia/tools
+  - /usr/local/share/aia-tools
+  - ./project-tools
+
+# Tool access control
+allowed_tools:
+  - file_reader
+  - web_scraper
+  - calculator
+
+rejected_tools:
+  - system_admin
+  - file_writer
+```
+
+### MCP Client Configuration
+
+Configure Model Context Protocol clients:
+
+```yaml
+mcp_clients:
+  - name: github
+    command: ["node", "/path/to/github-mcp-server"]
+    env:
+      GITHUB_TOKEN: "${GITHUB_TOKEN}"
+      
+  - name: filesystem
+    command: ["mcp-server-filesystem"]
+    args: ["/allowed/path1", "/allowed/path2"]
+```
+
+### Prompt Directory Structure
+
+Configure how AIA organizes prompts:
+
+```yaml
+# Prompt organization
+prompts_dir: ~/.prompts
+roles_prefix: roles          # ~/.prompts/roles/
+examples_prefix: examples    # ~/.prompts/examples/
+templates_prefix: templates  # ~/.prompts/templates/
+
+# Search paths (in order)
+prompt_search_paths:
+  - ~/.prompts
+  - ~/.aia/system_prompts  
+  - /usr/local/share/aia-prompts
+```
+
+## Configuration Examples
+
+### Development Setup
+
+```yaml
+# ~/.aia/config.yml - Development setup
+adapter: ruby_llm
+model: gpt-4
+temperature: 0.3
+verbose: true
+debug: true
+out_file: ./dev_output.md
+prompts_dir: ./prompts
+tool_paths: [./tools]
+```
+
+### Production Setup
+
+```yaml
+# ~/.aia/config.yml - Production setup  
+adapter: ruby_llm
+model: gpt-3.5-turbo
+temperature: 0.7
+verbose: false
+debug: false
+log_file: /var/log/aia.log
+prompts_dir: /etc/aia/prompts
+tool_paths: [/usr/share/aia-tools]
+allowed_tools: [safe_calculator, file_reader]
+```
+
+### Creative Writing Setup
+
+```yaml
+# ~/.aia/config.yml - Creative writing
+adapter: ruby_llm
+model: gpt-4
+temperature: 1.1
+max_tokens: 4000
+speak: true
+voice: nova
+markdown: true
+out_file: ~/writing/aia_output.md
+append: true
+```
+
+## Validation and Troubleshooting
+
+### Check Configuration
+
+Dump current configuration:
+
+```bash
+aia --dump config.yaml
+```
+
+### Validate Settings
+
+```bash
+# Test model access
+aia --available_models
+
+# Test configuration
+aia --debug --verbose hello_world
+
+# Test tools
+aia --tools ./my_tools --debug test_prompt
+```
+
+### Common Issues
+
+#### Model Not Found
+- Check your API keys are set
+- Verify the model name: `aia --available_models`
+- Check network connectivity
+
+#### Permission Errors  
+- Verify file permissions on config directory
+- Check tool file permissions
+- Ensure API keys are correctly set
+
+#### Tool Loading Errors
+- Verify tool paths exist and are readable
+- Check Ruby syntax in tool files
+- Use `--debug` to see detailed error messages
+
+## Configuration Migration
+
+### Updating from Older Versions
+
+AIA automatically migrates older configuration formats. To manually update:
+
+```bash
+# Backup current config
+cp ~/.aia/config.yml ~/.aia/config.yml.backup
+
+# Update configuration format
+aia --migrate-config
+```
+
+### Configuration Templates
+
+Generate configuration templates:
+
+```bash
+# Generate basic config
+aia --generate-config basic > ~/.aia/config.yml
+
+# Generate advanced config with all options
+aia --generate-config full > ~/.aia/config.advanced.yml
+```
+
+## Best Practices
+
+1. **Use Environment Variables** for sensitive data like API keys
+2. **Use Configuration Files** for stable settings
+3. **Use Command Line Arguments** for temporary overrides
+4. **Use Embedded Directives** for prompt-specific settings
+5. **Version Control** your configuration (excluding secrets)
+6. **Test Changes** with `--debug` and `--verbose` flags
+7. **Document Custom Configurations** for team sharing
+
+## Security Considerations
+
+- Never commit API keys to version control
+- Use restrictive file permissions on config files: `chmod 600 ~/.aia/config.yml`
+- Limit tool access with `allowed_tools` in production
+- Use separate configurations for different environments
+- Regularly rotate API keys

data/docs/contributing.md

@@ -0,0 +1,332 @@
+# Contributing to AIA
+
+We welcome contributions to AIA! This guide will help you get started with contributing to the project.
+
+## Ways to Contribute
+
+### 1. Report Issues
+- **Bug Reports**: Found a bug? Please report it with detailed steps to reproduce
+- **Feature Requests**: Have an idea for a new feature? We'd love to hear about it
+- **Documentation Issues**: Spot errors or areas for improvement in documentation
+
+### 2. Submit Code Changes
+- **Bug Fixes**: Help fix reported issues
+- **New Features**: Implement requested features or propose new ones
+- **Performance Improvements**: Optimize existing code
+- **Tests**: Improve test coverage and quality
+
+### 3. Improve Documentation
+- **User Guides**: Help improve user-facing documentation
+- **Code Comments**: Add or improve inline documentation
+- **Examples**: Contribute new examples or improve existing ones
+- **Tutorials**: Create learning materials for new users
+
+### 4. Contribute Examples
+- **Prompts**: Share useful prompt templates
+- **Tools**: Create Ruby tools that extend AIA's capabilities
+- **MCP Clients**: Develop Model Context Protocol integrations
+
+## Getting Started
+
+### Prerequisites
+- Ruby 3.0+ installed
+- Git for version control
+- Familiarity with AI/LLM concepts
+- Understanding of command-line tools
+
+### Setting Up Development Environment
+
+1. **Fork and Clone**
+   ```bash
+   git clone https://github.com/your-username/aia.git
+   cd aia
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   bundle install
+   ```
+
+3. **Run Tests**
+   ```bash
+   rake test
+   ```
+
+4. **Create Feature Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+## Development Guidelines
+
+### Code Standards
+
+#### Ruby Style Guide
+- Follow Ruby community conventions
+- Use descriptive variable and method names
+- Write clear, concise comments
+- Maintain consistent indentation (2 spaces)
+- Keep line length under 120 characters
+
+#### Testing Requirements
+- Write tests for all new functionality
+- Maintain or improve test coverage
+- Use descriptive test names
+- Include both unit and integration tests
+
+#### Documentation Standards
+- Update README if needed
+- Add inline documentation for public methods
+- Include usage examples
+- Update CHANGELOG.md for user-facing changes
+
+### Commit Message Format
+
+Use clear, descriptive commit messages following this format:
+
+```
+type(scope): brief description
+
+Longer description if needed
+
+- List key changes
+- Include breaking changes
+- Reference issues: Fixes #123
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `test`: Test-related changes
+- `refactor`: Code refactoring
+- `perf`: Performance improvements
+
+**Examples:**
+```
+feat(cli): add --fuzzy flag for prompt selection
+
+fix(config): resolve issue with nested YAML parsing
+
+docs(examples): add MCP client integration examples
+```
+
+## Contributing Examples
+
+### Prompt Examples
+
+#### File Structure
+```
+docs/examples/prompts/category/
+├── index.md                    # Category overview
+├── example_name.txt           # Prompt file
+└── example_name_usage.md      # Usage documentation
+```
+
+#### Prompt Template Format
+```markdown
+# Prompt Title
+
+Brief description of what this prompt does.
+
+## Prerequisites
+- List any required setup
+- Dependencies or tools needed
+- API keys or configurations
+
+## Usage
+```bash
+aia prompt_name input_file.txt
+```
+
+## Customization
+Explain how users can modify the prompt for their needs.
+
+## Related Examples
+- Link to similar or complementary examples
+```
+
+### Tool Examples
+
+#### File Structure
+```
+docs/examples/tools/
+├── index.md                    # Tools overview
+├── tool_name.rb               # Ruby tool implementation
+└── tool_name_usage.md         # Documentation
+```
+
+#### Tool Template
+```ruby
+# Tool implementation following RubyLLM::Tool pattern
+class ToolName < RubyLLM::Tool
+  description "Brief description of tool functionality"
+  
+  def method_name(parameter1, parameter2 = nil)
+    # Implementation with error handling
+    # Return structured results
+  end
+  
+  private
+  
+  def helper_method
+    # Internal helper methods
+  end
+end
+```
+
+### MCP Client Examples
+
+#### File Structure
+```
+docs/examples/mcp/
+├── index.md                    # MCP overview
+├── client_name.py             # Python MCP client
+├── client_name.js             # Node.js MCP client
+└── client_name_usage.md       # Documentation
+```
+
+## Pull Request Process
+
+### Before Submitting
+1. **Test Your Changes**
+   ```bash
+   rake test
+   rake integration_test
+   ```
+
+2. **Check Code Quality**
+   ```bash
+   rubocop
+   reek
+   ```
+
+3. **Update Documentation**
+   - Add/update relevant documentation
+   - Include examples if applicable
+   - Update CHANGELOG.md
+
+### Submitting the Pull Request
+
+1. **Create Descriptive Title**
+   - Use the same format as commit messages
+   - Be specific about what changed
+
+2. **Write Comprehensive Description**
+   ```markdown
+   ## Summary
+   Brief description of changes
+
+   ## Changes Made
+   - List key changes
+   - Explain design decisions
+   - Note any breaking changes
+
+   ## Testing
+   - Describe testing performed
+   - Include test results if relevant
+
+   ## Documentation
+   - List documentation updates
+   - Include screenshots if applicable
+   ```
+
+3. **Checklist**
+   - [ ] Tests pass locally
+   - [ ] Code follows style guidelines
+   - [ ] Documentation updated
+   - [ ] CHANGELOG.md updated (if user-facing)
+   - [ ] No breaking changes (or documented)
+
+### Review Process
+- Maintainers will review your pull request
+- Address feedback promptly and professionally
+- Be open to suggestions and improvements
+- Update your PR based on review comments
+
+## Community Guidelines
+
+### Communication
+- **Be Respectful**: Treat all community members with respect
+- **Be Constructive**: Provide helpful, actionable feedback
+- **Be Patient**: Maintainers and contributors are volunteers
+- **Be Collaborative**: Work together to improve the project
+
+### Issue Reporting
+- **Search First**: Check if the issue already exists
+- **Be Specific**: Provide detailed reproduction steps
+- **Include Context**: OS, Ruby version, AIA version
+- **Provide Examples**: Include relevant code or configuration
+
+### Feature Requests
+- **Describe Use Case**: Explain why the feature is needed
+- **Consider Alternatives**: Discuss other approaches
+- **Be Open to Discussion**: Feature scope may evolve
+
+## Security
+
+### Reporting Security Issues
+- **Do NOT** create public GitHub issues for security vulnerabilities
+- Email security issues to: [maintainer-email]
+- Include detailed description and reproduction steps
+- Allow reasonable time for response before public disclosure
+
+### Security Best Practices
+- Never commit API keys or secrets
+- Validate all user inputs
+- Use secure defaults in configurations
+- Follow principle of least privilege
+
+## Recognition
+
+### Contributors
+All contributors are recognized in:
+- CONTRIBUTORS.md file
+- Release notes for significant contributions
+- GitHub contributor statistics
+
+### Types of Recognition
+- **Code Contributors**: Code, tests, bug fixes
+- **Documentation Contributors**: Guides, examples, documentation
+- **Community Contributors**: Issue triage, user support
+- **Maintainers**: Ongoing project stewardship
+
+## Getting Help
+
+### Development Questions
+- **GitHub Discussions**: For general questions and ideas
+- **Issues**: For specific bugs or feature requests
+- **Documentation**: Check existing guides and examples
+
+### Code Review
+- Ask for reviews in PR comments
+- Mention specific maintainers if needed
+- Be patient - reviews take time
+
+### Community Support
+- Help other contributors
+- Share knowledge and experience
+- Mentor new contributors
+
+## Release Process
+
+### Version Management
+AIA follows semantic versioning (SemVer):
+- **MAJOR**: Breaking changes
+- **MINOR**: New features, backward compatible
+- **PATCH**: Bug fixes, backward compatible
+
+### Release Schedule
+- No fixed schedule - releases when ready
+- Security fixes released promptly
+- Feature releases coordinated with maintainers
+
+## Thank You!
+
+Thank you for considering contributing to AIA! Your contributions help make this tool better for everyone in the AI community.
+
+Questions? Feel free to open an issue or start a discussion on GitHub.
+
+---
+
+*Last updated: December 2024*