aia 0.9.11 → 0.9.12

data/docs/index.md

@@ -0,0 +1,173 @@
+# AIA - AI Assistant
+
+<table border="0">
+<tr>
+<td width="30%" valign="top">
+  <img src="assets/images/aia.png" alt="AIA - May I take your prompt?" width="200" />
+  <div align="center">
+      <strong>The Prompt is the Code</strong>
+  </div>
+</td>
+<td width="70%" valign="top">
+
+Welcome to AIA, your powerful CLI tool for dynamic prompt management and AI interaction.
+<br/><br/>
+<strong>AIA (AI Assistant)</strong> is a Ruby-based command-line tool that revolutionizes how you interact with AI models. It's designed for generative AI workflows, enabling you to effortlessly manage AI prompts, integrate seamlessly with shell and embedded Ruby (ERB), run batch processes, and engage in interactive chats with user-defined directives, tools, and MCP clients.
+</td>
+</tr>
+</table>
+
+  <div align="center">
+      AIA treats prompts as executable programs, complete with configuration, logic, and workflows.
+  </div>
+
+## Key Features
+
+### 🚀 Dynamic Prompt Management
+- **Hierarchical Configuration**: Embedded directives > CLI args > environment variables > config files > defaults
+- **Prompt Sequences and Workflows**: Chain prompts together for complex AI workflows
+- **Role-based Prompts**: Use predefined roles to context your AI interactions
+- **Fuzzy Search**: Find prompts quickly with fuzzy matching (requires `fzf`)
+
+### 🔧 Powerful Integration
+- **Shell Integration**: Execute shell commands directly within prompts
+- **Ruby (ERB) Processing**: Use Ruby code in your prompts for dynamic content
+- **RubyLLM::Tool Support**: Function callbacks for enhanced AI capabilities
+- **MCP Client Support**: Integrate with Model Context Protocol clients
+
+### 💬 Interactive Chat Sessions
+- **Context Management**: Maintain conversation history and context
+- **Multi-model Support**: Use multiple AI models simultaneously
+- **Consensus Mode**: Get consensus responses from multiple models
+- **Voice Support**: Convert text to speech and back
+
+### 🎯 Advanced Features
+- **Executable Prompts**: Run prompts as executable scripts
+- **Parameter Extraction**: Use regex to extract parameters from prompts
+- **Image Generation**: Generate images with customizable parameters
+- **Tool Integration**: Use custom Ruby tools for enhanced functionality
+
+## Quick Start
+
+1. **Install AIA:**
+   ```bash
+   gem install aia
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   brew install fzf
+   ```
+
+3. **Create your first prompt:**
+   ```bash
+   mkdir -p ~/.prompts
+   echo "What is [TOPIC]?" > ~/.prompts/what_is.txt
+   ```
+
+4. **Run your prompt:**
+   ```bash
+   aia what_is
+   ```
+   You'll be prompted to enter a value for `[TOPIC]`, then AIA will send your question to the AI model.
+
+5. **Start an interactive chat:**
+   ```bash
+   aia --chat
+
+   # Or use multiple models for comparison
+   aia --chat --model "gpt-4o-mini,gpt-3.5-turbo"
+   ```
+
+When AIA starts, you'll see the friendly robot mascot:
+
+```plain
+
+       ,      ,
+       (\____/) AI Assistant (v0.9.7) is Online
+        (_oo_)   ["gpt-4o-mini", "gpt-5-mini"]
+         (O)       using ruby_llm (v1.6.4 MCP v0.6.1)
+       __||__    \) model db was last refreshed on
+     [/______\]  /    2025-08-27
+    / \__AI__/ \/      You can share my tools
+   /    /__\
+  (\   /____\
+
+```
+
+## Core Architecture
+
+AIA follows a modular Ruby gem structure with clear separation of concerns:
+
+### Component Overview
+
+```mermaid
+graph TD
+    A[CLI Input] --> B[Config System]
+    B --> C[Prompt Handler]
+    C --> D[Directive Processor]
+    D --> E[Context Manager]
+    E --> F[RubyLLM Adapter]
+    F --> G[AI Models]
+
+    H[Prompt Files] --> C
+    I[Role Files] --> C
+    J[Tools] --> F
+    K[MCP Clients] --> F
+
+    C --> L[Chat Processor Service]
+    L --> M[UI Presenter]
+    M --> N[Terminal Output]
+```
+
+### Core Components
+
+- **AIA::Config** - Configuration management with hierarchical precedence
+- **AIA::PromptHandler** - Main prompt processing orchestrator
+- **AIA::ChatProcessorService** - Interactive chat session management
+- **AIA::DirectiveProcessor** - Processes embedded directives (`//command params`)
+- **AIA::ContextManager** - Manages conversation context and history
+- **AIA::RubyLLMAdapter** - Interfaces with the ruby_llm gem for AI model communication
+- **AIA::ShellCommandExecutor** - Executes shell commands safely within prompts
+- **AIA::HistoryManager** - Manages prompt parameter history and user input
+- **AIA::UIPresenter** - Terminal output formatting and presentation
+- **AIA::Session** - Manages chat sessions and state
+- **AIA::Fzf** - Fuzzy finder integration for prompt selection
+
+### External Dependencies
+
+- **prompt_manager gem** - Core prompt management functionality
+- **ruby_llm gem** - AI model interface layer
+- **fzf** - Command-line fuzzy finder (external CLI tool)
+
+## Documentation Structure
+
+### Getting Started
+- [Installation](installation.md) - Get AIA up and running
+- [Configuration](configuration.md) - Configure AIA for your needs
+- [Getting Started Guide](guides/getting-started.md) - Your first steps with AIA
+
+### Guides
+- [Chat Mode](guides/chat.md) - Interactive conversations with AI
+- [Working with Models](guides/models.md) - Multi-model support and configuration
+- [Tools Integration](guides/tools.md) - Extend AIA with custom tools
+- [Advanced Prompting](advanced-prompting.md) - Master complex prompt techniques
+
+### Reference
+- [CLI Parameters](cli-reference.md) - Complete command-line reference
+- [Directives Reference](directives-reference.md) - All available directives
+- [Examples](examples/index.md) - Practical examples and use cases
+
+## Community & Support
+
+- **GitHub**: [madbomber/aia](https://github.com/MadBomber/aia)
+- **Issues**: [Report bugs and request features](https://github.com/MadBomber/aia/issues)
+- **RubyGems**: [aia gem](https://rubygems.org/gems/aia)
+
+## License
+
+AIA is open source software. See the [LICENSE](https://github.com/MadBomber/aia/blob/main/LICENSE) file for details.
+
+---
+
+Ready to get started? Head to the [Installation](installation.md) guide to begin your AIA journey!

data/docs/installation.md

@@ -0,0 +1,238 @@
+# Installation
+
+This guide will help you install AIA and get it running on your system.
+
+## Prerequisites
+
+### Required
+- **Ruby**: Version 3.0 or higher
+- **RubyGems**: Usually comes with Ruby
+
+### Recommended
+- **fzf**: For fuzzy prompt searching
+- **git**: For prompt management with version control
+
+## Installation Methods
+
+### Method 1: Install from RubyGems (Recommended)
+
+The easiest way to install AIA is through RubyGems:
+
+```bash
+gem install aia
+```
+
+### Method 2: Install from Source
+
+If you want the latest development version:
+
+```bash
+git clone https://github.com/MadBomber/aia.git
+cd aia
+bundle install
+rake install
+```
+
+### Method 3: Using Bundler
+
+Add to your Gemfile:
+
+```ruby
+gem 'aia'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Verify Installation
+
+After installation, verify that AIA is working:
+
+```bash
+aia --version
+```
+
+You should see the version number printed.
+
+## Initial Setup
+
+### 1. Create Prompts Directory
+
+AIA stores prompts in a directory (default: `~/.prompts`). Create it:
+
+```bash
+mkdir -p ~/.prompts
+```
+
+### 2. Create Configuration Directory
+
+Create the configuration directory:
+
+```bash
+mkdir -p ~/.aia
+```
+
+### 3. Basic Configuration File (Optional)
+
+Create a basic configuration file at `~/.aia/config.yml`:
+
+```yaml
+# Basic AIA configuration
+adapter: ruby_llm
+model: gpt-3.5-turbo
+prompts_dir: ~/.prompts
+temperature: 0.7
+verbose: false
+```
+
+### 4. Set Up API Keys
+
+AIA uses the RubyLLM gem, which supports multiple AI providers. Set up your API keys as environment variables:
+
+#### OpenAI
+```bash
+export OPENAI_API_KEY="your_openai_api_key_here"
+```
+
+#### Anthropic Claude
+```bash
+export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
+```
+
+#### Google Gemini
+```bash
+export GOOGLE_API_KEY="your_google_api_key_here"
+```
+
+#### Ollama (Local models)
+```bash
+export OLLAMA_URL="http://localhost:11434"
+```
+
+Add these to your shell profile (`.bashrc`, `.zshrc`, etc.) to make them permanent.
+
+## Optional Dependencies
+
+### Install fzf for Fuzzy Search
+
+AIA supports fuzzy searching for prompts using `fzf`. Install it:
+
+#### macOS (using Homebrew)
+```bash
+brew install fzf
+```
+
+#### Ubuntu/Debian
+```bash
+apt-get install fzf
+```
+
+#### Other systems
+See the [fzf installation guide](https://github.com/junegunn/fzf#installation).
+
+### Install Additional Ruby Gems
+
+Some features may require additional gems:
+
+```bash
+# For advanced audio processing
+gem install ruby-audio
+
+# For advanced image processing  
+gem install mini_magick
+
+# For enhanced terminal features
+gem install tty-prompt
+```
+
+## Testing Your Installation
+
+### 1. Check Available Models
+
+```bash
+aia --available_models
+```
+
+This will show all available AI models.
+
+### 2. Test Basic Functionality
+
+Create a simple prompt file:
+
+```bash
+echo "Hello, what can you help me with today?" > ~/.prompts/hello.txt
+```
+
+Run it:
+
+```bash
+aia hello
+```
+
+### 3. Test Chat Mode
+
+```bash
+aia --chat
+```
+
+This should start an interactive chat session.
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Command not found: aia"
+- Make sure Ruby's bin directory is in your PATH
+- Try reinstalling: `gem uninstall aia && gem install aia`
+
+#### "No models available"
+- Check that your API keys are set correctly
+- Verify your internet connection
+- Try: `aia --available_models` to diagnose
+
+#### "fzf not found" warning
+- Install fzf as described above
+- Or disable fuzzy search: `aia --no-fuzzy`
+
+#### Permission errors
+- Try installing with: `gem install aia --user-install`
+- Or use `sudo` (not recommended): `sudo gem install aia`
+
+### Getting Help
+
+If you encounter issues:
+
+1. Check the [FAQ](faq.md)
+2. Search existing [GitHub issues](https://github.com/MadBomber/aia/issues)
+3. Create a new issue with:
+   - Your OS and Ruby version
+   - The exact error message
+   - Steps to reproduce
+
+## Next Steps
+
+Once AIA is installed:
+
+1. Read the [Configuration Guide](configuration.md)
+2. Follow the [Getting Started Guide](guides/getting-started.md)
+3. Explore [Examples](examples/index.md)
+
+## Updating AIA
+
+To update to the latest version:
+
+```bash
+gem update aia
+```
+
+Or if installed from source:
+
+```bash
+cd path/to/aia
+git pull
+bundle install
+rake install
+```