aia 0.9.18 → 0.9.20

data/README.md

@@ -1,7 +1,8 @@
 <div align="center">
   <h1>AI Assistant (AIA)</h1>
   <img src="docs/assets/images/aia.png" alt="Robots waiter ready to take your order."><br />
-  **The Prompt is the Code**
+  **The Prompt is the Code**<br />
+  <p>Check out the new <a href="http://madbomber.github.io/aia/guides/models/?h=inline+role+syntax#inline-role-syntax">Inline Role Syntax</a> when working with multiple concurrent models.</p>
 </div>
 
 AIA is a command-line utility that facilitates interaction with AI models through dynamic prompt management. It automates the management of pre-compositional prompts and executes generative AI commands with enhanced features including embedded directives, shell integration, embedded Ruby, history management, interactive chat, and prompt workflows.
@@ -202,10 +203,11 @@ aia --fuzzy
 | Option | Description | Example |
 |--------|-------------|---------|
 | `--chat` | Start interactive chat session | `aia --chat` |
-| `--model MODEL` | Specify AI model(s) to use | `aia --model gpt-4o-mini,gpt-3.5-turbo` |
+| `--model MODEL` | Specify AI model(s) to use. Supports `MODEL[=ROLE]` syntax | `aia --model gpt-4o-mini,gpt-3.5-turbo` or `aia --model gpt-4o=architect,claude=security` |
 | `--consensus` | Enable consensus mode for multi-model | `aia --consensus` |
 | `--no-consensus` | Force individual responses | `aia --no-consensus` |
-| `--role ROLE` | Use a role/system prompt | `aia --role expert` |
+| `--role ROLE` | Use a role/system prompt (default for all models) | `aia --role expert` |
+| `--list-roles` | List available role files | `aia --list-roles` |
 | `--out_file FILE` | Specify output file | `aia --out_file results.md` |
 | `--fuzzy` | Use fuzzy search for prompts | `aia --fuzzy` |
 | `--help` | Show complete help | `aia --help` |
@@ -759,6 +761,129 @@ Provide specific, actionable feedback.
 EOF
 ```
 
+**Per-Model Roles** (Multi-Model Role Assignment):
+
+Assign different roles to different models using inline `model=role` syntax:
+
+```bash
+# Different perspectives on the same design
+aia --model gpt-4o=architect,claude=security,gemini=performance design_doc.md
+
+# Output shows each model with its role:
+# from: gpt-4o (architect)
+# The proposed microservices architecture provides good separation...
+#
+# from: claude (security)
+# I'm concerned about the authentication flow between services...
+#
+# from: gemini (performance)
+# The database access pattern could become a bottleneck...
+```
+
+**Multiple Perspectives** (Same Model, Different Roles):
+
+```bash
+# Get optimistic, pessimistic, and realistic views
+aia --model gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist business_plan.md
+
+# Output shows instance numbers:
+# from: gpt-4o #1 (optimist)
+# This market opportunity is massive...
+#
+# from: gpt-4o #2 (pessimist)
+# The competition is fierce and our runway is limited...
+#
+# from: gpt-4o #3 (realist)
+# Given our current team size, we should focus on MVP first...
+```
+
+**Mixed Role Assignment:**
+
+```bash
+# Some models with roles, some with default
+aia --model gpt-4o=architect,claude,gemini=performance --role security design.md
+# gpt-4o gets architect (inline)
+# claude gets security (default from --role)
+# gemini gets performance (inline)
+```
+
+**Discovering Available Roles:**
+
+```bash
+# List all available role files
+aia --list-roles
+
+# Output:
+# Available roles in ~/.prompts/roles:
+#   - architect
+#   - performance
+#   - security
+#   - code_reviewer
+#   - specialized/senior_architect  # nested paths supported
+```
+
+**Role Organization:**
+
+Roles can be organized in subdirectories:
+
+```bash
+# Create nested role structure
+mkdir -p ~/.prompts/roles/specialized
+echo "You are a senior software architect..." > ~/.prompts/roles/specialized/senior_architect.txt
+
+# Use nested roles
+aia --model gpt-4o=specialized/senior_architect design.md
+```
+
+**Using Config Files for Model Roles** (v2):
+
+Define model-role assignments in your config file (`~/.aia/config.yml`) for reusable setups:
+
+```yaml
+# Array of hashes format (mirrors internal structure)
+model:
+  - model: gpt-4o
+    role: architect
+  - model: claude
+    role: security
+  - model: gemini
+    role: performance
+
+# Also supports models without roles
+model:
+  - model: gpt-4o
+    role: architect
+  - model: claude      # No role assigned
+```
+
+Then simply run:
+
+```bash
+aia design_doc.md  # Uses model configuration from config file
+```
+
+**Using Environment Variables** (v2):
+
+Set default model-role assignments via environment variable:
+
+```bash
+# Set in your shell profile (.bashrc, .zshrc, etc.)
+export AIA_MODEL="gpt-4o=architect,claude=security,gemini=performance"
+
+# Or for a single command
+AIA_MODEL="gpt-4o=architect,claude=security" aia design.md
+```
+
+**Configuration Precedence:**
+
+When model roles are specified in multiple places, the precedence is:
+
+1. **Command-line inline** (highest): `--model gpt-4o=architect`
+2. **Command-line flag**: `--model gpt-4o --role architect`
+3. **Environment variable**: `AIA_MODEL="gpt-4o=architect"`
+4. **Config file** (lowest): `model` array in `~/.aia/config.yml`
+```
+
 ### RubyLLM::Tool Support
 
 AIA supports function calling through RubyLLM tools for extended capabilities:

data/docs/cli-reference.md

@@ -84,6 +84,8 @@ aia --available_models openai,gpt,text_to_image
 ### `-m MODEL, --model MODEL`
 Name of the LLM model(s) to use. For multiple models, use comma-separated values.
 
+Supports inline role assignment using `MODEL=ROLE` syntax to assign specific roles to individual models.
+
 ```bash
 # Single model
 aia --model gpt-4 my_prompt
@@ -93,8 +95,22 @@ aia --model "gpt-4,claude-3-sonnet,gemini-pro" my_prompt
 
 # Short form
 aia -m gpt-3.5-turbo my_prompt
+
+# Single model with role (inline syntax)
+aia --model gpt-4o=architect design_review.md
+
+# Multiple models with different roles
+aia --model "gpt-4o=architect,claude=security,gemini=performance" my_prompt
+
+# Same model with multiple roles for diverse perspectives
+aia --model "gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist" project_plan.md
+
+# Mixed: some models with roles, some without
+aia --model "gpt-4o=expert,claude,gemini" my_prompt
 ```
 
+**See also**: `--role` for applying a role to all models, `--list-roles` for discovering available roles.
+
 ### `--[no-]consensus`
 Enable/disable consensus mode for multi-model responses. When enabled, AIA attempts to create a consensus response from multiple models.
 
@@ -206,13 +222,51 @@ aia --roles_prefix personas --role expert
 ```
 
 ### `-r, --role ROLE_ID`
-Role ID to prepend to the prompt.
+Role ID to prepend to the prompt. This applies the same role to all models.
+
+For per-model role assignment, use the inline `MODEL=ROLE` syntax with `--model` instead.
 
 ```bash
+# Apply role to all models
 aia --role expert my_prompt
 aia -r teacher explain_concept
+
+# With multiple models (same role for all)
+aia --model "gpt-4,claude" --role architect design.md
+
+# Per-model roles (inline syntax - see --model)
+aia --model "gpt-4=architect,claude=security" design.md
 ```
 
+**See also**: `--model` for inline role syntax, `--list-roles` for discovering available roles.
+
+### `--list-roles`
+List all available roles and exit. Shows role IDs and their descriptions from the roles directory.
+
+```bash
+# List all available roles
+aia --list-roles
+
+# Example output:
+# Available roles in /Users/you/.prompts/roles:
+#   architect    - Software architecture expert
+#   security     - Security analysis specialist
+#   performance  - Performance optimization expert
+#   debugger     - Expert debugging assistant
+#   optimist     - Positive perspective analyzer
+#   pessimist    - Critical risk analyzer
+#   realist      - Balanced pragmatic analyzer
+```
+
+Roles are discovered from:
+- **Default location**: `~/.prompts/roles/`
+- **Custom location**: Set via `--prompts_dir` and `--roles_prefix`
+- **Nested directories**: Supports subdirectories like `roles/software/architect.txt`
+
+**Use case**: Discover available roles before using them with `--role` or inline `MODEL=ROLE` syntax.
+
+**See also**: `--role`, `--model`, `--prompts_dir`, `--roles_prefix`
+
 ### `-n, --next PROMPT_ID`
 Next prompt to process (can be used multiple times to build a pipeline).
 
@@ -556,24 +610,37 @@ aia --transcription_model whisper-1 --speech_model tts-1-hd --voice echo audio_p
 Many CLI options have corresponding environment variables with the `AIA_` prefix:
 
 ```bash
+# Basic model configuration
 export AIA_MODEL="gpt-4"
+
+# Model with inline role syntax
+export AIA_MODEL="gpt-4o=architect"
+
+# Multiple models with roles
+export AIA_MODEL="gpt-4o=architect,claude=security,gemini=performance"
+
+# Other configuration
 export AIA_TEMPERATURE="0.8"
 export AIA_PROMPTS_DIR="/custom/prompts"
 export AIA_VERBOSE="true"
 export AIA_DEBUG="false"
 ```
 
+**Note**: The `AIA_MODEL` environment variable supports the same inline `MODEL=ROLE` syntax as the `--model` CLI option.
+
 See [Configuration](configuration.md#environment-variables) for a complete list.
 
 ## Configuration Precedence
 
 Options are resolved in this order (highest to lowest precedence):
 
-1. Command line arguments
-2. Environment variables
-3. Configuration files  
+1. Command line arguments (including inline `MODEL=ROLE` syntax)
+2. Environment variables (including inline syntax in `AIA_MODEL`)
+3. Configuration files (including array format with roles)
 4. Built-in defaults
 
+**Role-specific precedence**: When using the role feature, inline `MODEL=ROLE` syntax takes precedence over the `--role` flag, which takes precedence over roles in config files.
+
 ## Related Documentation
 
 - [Configuration Guide](configuration.md) - Detailed configuration options

data/docs/guides/models.md

@@ -162,11 +162,206 @@ Model Details:
 
 **Multi-Model Features:**
 - **Primary Model**: The first model in the list serves as the consensus orchestrator
-- **Concurrent Processing**: All models run simultaneously for better performance  
+- **Concurrent Processing**: All models run simultaneously for better performance
 - **Flexible Output**: Choose between individual responses or synthesized consensus
 - **Error Handling**: Invalid models are reported but don't prevent valid models from working
 - **Batch Mode Support**: Multi-model responses are properly formatted in output files
 
+### Per-Model Roles
+
+Assign specific roles to each model in multi-model mode to get diverse perspectives on your prompts. Each model receives a prepended role prompt that shapes its perspective.
+
+#### Inline Role Syntax
+
+Use the `MODEL=ROLE` syntax to assign roles directly on the command line:
+
+```bash
+# Single model with role
+aia --model gpt-4o=architect design_review.md
+
+# Multiple models with different roles
+aia --model gpt-4o=architect,claude=security,gemini=performance design_review.md
+
+# Mixed: some models with roles, some without
+aia --model gpt-4o=expert,claude analyze.md
+```
+
+#### Multiple Perspectives
+
+Use the same model multiple times with different roles for diverse viewpoints:
+
+```bash
+# Three instances of same model with different roles
+aia --model gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist project_plan.md
+
+# AI provides three distinct perspectives on the same input
+```
+
+**Output Format with Roles:**
+```
+from: gpt-4o (optimist)
+I see great potential in this approach! The architecture is solid...
+
+from: gpt-4o #2 (pessimist)
+We need to consider several risks here. The design has some concerning...
+
+from: gpt-4o #3 (realist)
+Let's look at this pragmatically. The proposal has both strengths and...
+```
+
+**Note**: When using duplicate models, AIA automatically numbers them (e.g., `gpt-4o`, `gpt-4o #2`, `gpt-4o #3`) and maintains separate conversation contexts for each instance.
+
+#### Role Discovery
+
+List all available roles in your prompts directory:
+
+```bash
+# List all roles
+aia --list-roles
+
+# Output shows role IDs and descriptions
+Available roles in /Users/you/.prompts/roles:
+  architect    - Software architecture expert
+  security     - Security analysis specialist
+  performance  - Performance optimization expert
+  optimist     - Positive perspective analyzer
+  pessimist    - Critical risk analyzer
+  realist      - Balanced pragmatic analyzer
+```
+
+#### Role Files
+
+Roles are stored as text files in your prompts directory:
+
+```bash
+# Default location: ~/.prompts/roles/
+~/.prompts/
+  roles/
+    architect.txt
+    security.txt
+    performance.txt
+    optimist.txt
+    pessimist.txt
+    realist.txt
+
+# Nested role organization
+~/.prompts/
+  roles/
+    software/
+      architect.txt
+      developer.txt
+    analysis/
+      optimist.txt
+      pessimist.txt
+      realist.txt
+```
+
+**Using Nested Roles:**
+```bash
+# Specify full path from roles directory
+aia --model gpt-4o=software/architect,claude=analysis/pessimist design.md
+```
+
+#### Configuration File Format
+
+Define model roles in your configuration file using array format:
+
+```yaml
+# ~/.aia/config.yml
+model:
+  - model: gpt-4o
+    role: architect
+  - model: claude-3-sonnet
+    role: security
+  - model: gemini-pro
+    role: performance
+
+# Duplicate models with different roles
+model:
+  - model: gpt-4o
+    role: optimist
+  - model: gpt-4o
+    role: pessimist
+  - model: gpt-4o
+    role: realist
+```
+
+**Note**: Models without roles work normally - simply omit the `role` key.
+
+#### Environment Variable Usage
+
+Set model roles via environment variables using the same inline syntax:
+
+```bash
+# Single model with role
+export AIA_MODEL="gpt-4o=architect"
+
+# Multiple models with roles
+export AIA_MODEL="gpt-4o=architect,claude=security,gemini=performance"
+
+# Duplicate models
+export AIA_MODEL="gpt-4o=optimist,gpt-4o=pessimist,gpt-4o=realist"
+
+# Then run AIA normally
+aia design_review.md
+```
+
+#### Role Configuration Precedence
+
+When roles are specified in multiple places, the precedence order is:
+
+1. **CLI inline syntax**: `--model gpt-4o=architect` (highest priority)
+2. **CLI role flag**: `--role architect` (applies to all models)
+3. **Environment variable**: `AIA_MODEL="gpt-4o=architect"`
+4. **Configuration file**: `model: [{model: gpt-4o, role: architect}]`
+
+**Example of precedence:**
+```bash
+# Config file specifies: model: [{model: gpt-4o, role: architect}]
+# Environment has: AIA_MODEL="claude=security"
+# Command line uses:
+aia --model gemini=performance my_prompt
+
+# Result: Uses gemini with performance role (CLI wins)
+```
+
+#### Role Validation
+
+AIA validates role files exist at parse time and provides helpful error messages:
+
+```bash
+# If role file doesn't exist
+$ aia --model gpt-4o=nonexistent my_prompt
+
+ERROR: Role file not found: ~/.prompts/roles/nonexistent.txt
+
+Available roles:
+  - architect
+  - security
+  - performance
+  - optimist
+  - pessimist
+  - realist
+```
+
+#### Creating Custom Roles
+
+Create new role files in your roles directory:
+
+```bash
+# Create a new role
+cat > ~/.prompts/roles/debugger.txt << 'EOF'
+You are an expert debugging assistant. When analyzing code:
+- Focus on identifying potential bugs and edge cases
+- Suggest specific debugging strategies
+- Explain the root cause of issues clearly
+- Provide actionable fix recommendations
+EOF
+
+# Use the new role
+aia --model gpt-4o=debugger analyze_bug.py
+```
+
 ### Model Comparison in Prompts
 ```markdown
 Compare responses from multiple models:

data/lib/aia/chat_processor_service.rb

@@ -63,13 +63,22 @@ module AIA
     end
 
 
-    # conversation is an Array of Hashes.  Each entry is an interchange
-    # with the LLM.
-    def send_to_client(conversation)
+    # conversation is an Array of Hashes (single model) or Hash of Arrays (multi-model per-model contexts)
+    # Each entry is an interchange with the LLM.
+    def send_to_client(conversation_or_conversations)
       maybe_change_model
 
-      puts "[DEBUG ChatProcessor] Sending conversation to client: #{conversation.inspect[0..500]}..." if AIA.config.debug
-      result = AIA.client.chat(conversation)
+      # Handle per-model conversations (Hash) or single conversation (Array) - ADR-002 revised
+      if conversation_or_conversations.is_a?(Hash)
+        # Multi-model with per-model contexts: pass Hash directly to adapter
+        puts "[DEBUG ChatProcessor] Sending per-model conversations to client" if AIA.config.debug
+        result = AIA.client.chat(conversation_or_conversations)
+      else
+        # Single conversation for single model
+        puts "[DEBUG ChatProcessor] Sending conversation to client: #{conversation_or_conversations.inspect[0..500]}..." if AIA.config.debug
+        result = AIA.client.chat(conversation_or_conversations)
+      end
+
       puts "[DEBUG ChatProcessor] Client returned: #{result.class} - #{result.inspect[0..500]}..." if AIA.config.debug
       result
     end

data/lib/aia/config/base.rb

@@ -209,7 +209,12 @@ module AIA
                     when Float
                       value.to_f
                     when Array
-                      value.split(',').map(&:strip)
+                      # Special handling for :model to support inline role syntax (ADR-005 v2)
+                      if key == :model && value.include?('=')
+                        CLIParser.parse_models_with_roles(value)
+                      else
+                        value.split(',').map(&:strip)
+                      end
                     else
                       value # defaults to String
                     end

data/lib/aia/config/cli_parser.rb

@@ -81,14 +81,19 @@ module AIA
         end
 
         def setup_model_options(opts, config)
-          opts.on("-m MODEL", "--model MODEL", "Name of the LLM model(s) to use (comma-separated for multiple models)") do |model|
-            config.model = model.split(',').map(&:strip)
+          opts.on("-m MODEL", "--model MODEL", "Name of the LLM model(s) to use. Format: MODEL[=ROLE][,MODEL[=ROLE]]...") do |model|
+            config.model = parse_models_with_roles(model)
           end
 
           opts.on("--[no-]consensus", "Enable/disable consensus mode for multi-model responses (default: show individual responses)") do |consensus|
             config.consensus = consensus
           end
 
+          opts.on("--list-roles", "List available role files and exit") do
+            list_available_roles
+            exit 0
+          end
+
           opts.on("--sm", "--speech_model MODEL", "Speech model to use") do |model|
             config.speech_model = model
           end
@@ -296,6 +301,115 @@ module AIA
           end
         end
 
+        def parse_models_with_roles(model_string)
+          models = []
+          model_counts = Hash.new(0)
+
+          model_string.split(',').each do |spec|
+            spec.strip!
+
+            # Validate syntax
+            if spec =~ /^=|=$/
+              raise ArgumentError, "Invalid model syntax: '#{spec}'. Expected format: MODEL[=ROLE]"
+            end
+
+            if spec.include?('=')
+              # Explicit role: "model=role" or "provider/model=role"
+              model_name, role_name = spec.split('=', 2)
+              model_name.strip!
+              role_name.strip!
+
+              # Validate role file exists (fail fast)
+              validate_role_exists(role_name)
+
+              # Track instance count for duplicates
+              model_counts[model_name] += 1
+              instance = model_counts[model_name]
+
+              models << {
+                model: model_name,
+                role: role_name,
+                instance: instance,
+                internal_id: instance > 1 ? "#{model_name}##{instance}" : model_name
+              }
+            else
+              # No explicit role, will use default from -r/--role
+              model_counts[spec] += 1
+              instance = model_counts[spec]
+
+              models << {
+                model: spec,
+                role: nil,
+                instance: instance,
+                internal_id: instance > 1 ? "#{spec}##{instance}" : spec
+              }
+            end
+          end
+
+          models
+        end
+
+        def validate_role_exists(role_id)
+          # Get prompts_dir from defaults or environment
+          prompts_dir = ENV.fetch('AIA_PROMPTS_DIR', File.join(ENV['HOME'], '.prompts'))
+          roles_prefix = ENV.fetch('AIA_ROLES_PREFIX', 'roles')
+
+          # Build role file path
+          unless role_id.start_with?(roles_prefix)
+            role_id = "#{roles_prefix}/#{role_id}"
+          end
+
+          role_file_path = File.join(prompts_dir, "#{role_id}.txt")
+
+          unless File.exist?(role_file_path)
+            available_roles = list_available_role_names(prompts_dir, roles_prefix)
+
+            error_msg = "Role file not found: #{role_file_path}\n\n"
+
+            if available_roles.empty?
+              error_msg += "No roles directory found at #{File.join(prompts_dir, roles_prefix)}\n"
+              error_msg += "Create the directory and add role files to use this feature."
+            else
+              error_msg += "Available roles:\n"
+              error_msg += available_roles.map { |r| "  - #{r}" }.join("\n")
+              error_msg += "\n\nCreate the role file or use an existing role."
+            end
+
+            raise ArgumentError, error_msg
+          end
+        end
+
+        def list_available_roles
+          prompts_dir = ENV.fetch('AIA_PROMPTS_DIR', File.join(ENV['HOME'], '.prompts'))
+          roles_prefix = ENV.fetch('AIA_ROLES_PREFIX', 'roles')
+          roles_dir = File.join(prompts_dir, roles_prefix)
+
+          if Dir.exist?(roles_dir)
+            roles = list_available_role_names(prompts_dir, roles_prefix)
+
+            if roles.empty?
+              puts "No role files found in #{roles_dir}"
+              puts "Create .txt files in this directory to define roles."
+            else
+              puts "Available roles in #{roles_dir}:"
+              roles.each { |role| puts "  - #{role}" }
+            end
+          else
+            puts "No roles directory found at #{roles_dir}"
+            puts "Create this directory and add role files to use roles."
+          end
+        end
+
+        def list_available_role_names(prompts_dir, roles_prefix)
+          roles_dir = File.join(prompts_dir, roles_prefix)
+          return [] unless Dir.exist?(roles_dir)
+
+          # Find all .txt files recursively, preserving paths
+          Dir.glob("**/*.txt", base: roles_dir)
+            .map { |f| f.chomp('.txt') }
+            .sort
+        end
+
         def list_available_models(query)
           # SMELL: mostly duplications the code in the vailable_models directive
           #        assumes that the adapter is for the ruby_llm gem