aia 1.1.1 → 2.0.0.0.pre.beta2

data/lib/aia/config/cli_parser.rb

@@ -11,6 +11,7 @@ require_relative 'model_spec'
 require_relative '../skill_utils'
 
 module AIA
+  # rubocop:disable Metrics/ModuleLength
   module CLIParser
     class << self
       # Parse CLI arguments and return a hash of overrides
@@ -23,8 +24,8 @@ module AIA
           parser = create_option_parser(options)
           parser.parse!
         rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
-          warn "ERROR: #{e.message}"
-          warn "       use --help for usage report"
+          $stderr.puts "ERROR: #{e.message}"
+          $stderr.puts "       use --help for usage report"
           exit 1
         end
 
@@ -51,10 +52,11 @@ module AIA
       end
 
       def setup_banner(opts)
-        opts.banner = "Usage: aia [options] [PROMPT_ID] [CONTEXT_FILE]*\n" +
-                      "       aia [options] --chat [PROMPT_ID] [CONTEXT_FILE]*"
+        opts.banner = "Usage: aia [options] [PROMPT_ID] [CONTEXT_FILE]*\n       " \
+                      "aia [options] --chat [PROMPT_ID] [CONTEXT_FILE]*"
       end
 
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
       def setup_mode_options(opts, options)
         opts.separator "\nMode Options:"
 
@@ -64,17 +66,38 @@ module AIA
 
         opts.on("-f", "--fuzzy", "Use fuzzy matching for prompt search") do
           unless system("which fzf > /dev/null 2>&1")
-            warn "Error: 'fzf' is not installed. Please install 'fzf' to use the --fuzzy option."
+            $stderr.puts "Error: 'fzf' is not installed. Please install 'fzf' to use the --fuzzy option."
             exit 1
           end
           options[:fuzzy] = true
         end
 
-        opts.on("--terse", "[DEPRECATED] No longer supported") do
-          warn "Warning: --terse is deprecated and has no effect."
+        opts.on("--expert-routing", "Route each prompt to a specialist robot based on domain classification") do
+          options[:expert_routing] = true
+        end
+
+        opts.on("--track-pipeline", "Track pipeline execution in TrakFlow") do
+          options[:track_pipeline] = true
+        end
+
+        opts.on("--concurrent-auto", "Automatically parallelize independent MCP servers") do
+          options[:concurrent_auto] = true
+        end
+
+        opts.on("-A", "--[no-]auto-tool-filter", "Use TF-IDF similarity-based tool filtering (default: on)") do |v|
+          options[:auto_tool_filter] = v
+        end
+
+        opts.on("--load", "Load persisted tool filter databases from ~/.config/aia/") do
+          options[:tool_filter_load] = true
+        end
+
+        opts.on("--save", "Save tool filter databases to ~/.config/aia/") do
+          options[:tool_filter_save] = true
         end
       end
 
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
       def setup_model_options(opts, options)
         opts.separator "\nModel Options:"
 
@@ -82,8 +105,10 @@ module AIA
           list_available_models(query)
         end
 
-        opts.on("-m MODEL", "--model MODEL", "Set LLM model(s) to use. Format: MODEL[=ROLE][,MODEL[=ROLE]]...") do |model_string|
-          options[:models] = parse_models_with_roles(model_string)
+        opts.on("-m MODEL", "--model MODEL",
+                "Set LLM model(s). Format: MODEL[=ROLE][,MODEL[=ROLE]]... " \
+                "Multiple models run in parallel; use --consensus to synthesize results") do |model_string|
+          options[:models] = (options[:models] || []) + parse_models_with_roles(model_string)
         end
 
         opts.on("--[no-]consensus", "Enable/disable consensus mode for multi-model responses") do |consensus|
@@ -104,6 +129,7 @@ module AIA
         end
       end
 
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
       def setup_file_options(opts, options)
         opts.separator "\nFile & Output Options:"
 
@@ -112,13 +138,13 @@ module AIA
         end
 
         opts.on("-o", "--[no-]output [FILE]", "Write response to FILE (default: temp.md; --no-output to disable)") do |file|
-          if file == false
-            options[:output] = nil
-          elsif file.nil?
-            options[:output] = 'temp.md'
-          else
-            options[:output] = File.expand_path(file, Dir.pwd)
-          end
+          options[:output] = if file == false
+                               nil
+                             elsif file.nil?
+                               'temp.md'
+                             else
+                               File.expand_path(file, Dir.pwd)
+                             end
         end
 
         opts.on("-a", "--[no-]append", "Append to output file instead of overwriting") do |append|
@@ -134,6 +160,8 @@ module AIA
         end
       end
 
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
+      # :reek:DuplicateMethodCall -- options[:pipeline] is appended inside two separate OptionParser closures
       def setup_prompt_options(opts, options)
         opts.separator "\nPrompt Options:"
 
@@ -141,6 +169,10 @@ module AIA
           options[:prompts_dir] = dir
         end
 
+        opts.on("--plugins-dir DIR", "Set directory containing AIA plugin files") do |dir|
+          options[:plugins_dir] = dir
+        end
+
         opts.on("--roles-prefix PREFIX", "Set subdirectory name for role files (default: roles)") do |prefix|
           options[:roles_prefix] = prefix
         end
@@ -149,6 +181,19 @@ module AIA
           options[:role] = role
         end
 
+        opts.on("--skills-dir DIR", "Set directory containing skill subdirectories") do |dir|
+          options[:skills_dir] = dir
+        end
+
+        opts.on("-s", "--skill SKILL_IDS", "Append skill(s) to prompt; comma-separated IDs or paths") do |skill_ids|
+          options[:skills] ||= []
+          options[:skills] += skill_ids.split(',').map(&:strip).reject(&:empty?)
+        end
+
+        opts.on("--list-skills", "List available skills and exit") do
+          options[:list_skills] = true
+        end
+
         opts.on("-n", "--next PROMPT_ID", "Set next prompt to process") do |next_prompt|
           options[:pipeline] ||= []
           options[:pipeline] << next_prompt
@@ -159,32 +204,9 @@ module AIA
           options[:pipeline] += pipeline.split(',').map(&:strip)
         end
 
-
         opts.on("--system-prompt PROMPT_ID", "Set system prompt for chat sessions") do |prompt_id|
           options[:system_prompt] = prompt_id
         end
-
-        opts.on('--regex PATTERN', '[DEPRECATED] Parameter regex (PM v1.0.0 uses ERB parameters)') do |pattern|
-          warn "Warning: --regex is deprecated. PM v1.0.0 uses ERB parameters (<%= param %>)."
-          options[:parameter_regex] = pattern
-        end
-
-        opts.on("--skills-dir DIR", "Set directory containing skill subdirectories") do |dir|
-          options[:skills_dir] = dir
-        end
-
-        opts.on("--skills-prefix PREFIX", "Set subdirectory name for skill files (default: skills)") do |prefix|
-          options[:skills_prefix] = prefix
-        end
-
-        opts.on("-s", "--skill SKILL_IDS", "Prepend skill(s) to prompt (comma-separated IDs or paths)") do |ids|
-          options[:skills] ||= []
-          options[:skills] += ids.split(',').map(&:strip)
-        end
-
-        opts.on("--list-skills", "List available skills and exit") do
-          options[:list_skills] = true
-        end
       end
 
       def setup_ai_parameters(opts, options)
@@ -194,7 +216,7 @@ module AIA
           options[:temperature] = temp
         end
 
-        opts.on("--max-tokens TOKENS", Integer, "Set maximum tokens for text generation (default: 2048)") do |tokens|
+        opts.on("--max-tokens TOKENS", Integer, "Set maximum tokens for text generation (default: 32767)") do |tokens|
           options[:max_tokens] = tokens
         end
 
@@ -211,6 +233,7 @@ module AIA
         end
       end
 
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
       def setup_audio_image_options(opts, options)
         opts.separator "\nAudio & Image Options:"
 
@@ -218,10 +241,22 @@ module AIA
           options[:speak] = true
         end
 
-        opts.on("--voice VOICE", "Set voice for speech output (default: alloy)") do |voice|
+        opts.on("--voice VOICE", "Set voice for speech output") do |voice|
           options[:voice] = voice
         end
 
+        opts.on("--speak-command CMD", "Command used for TTS (default: say)") do |cmd|
+          options[:speak_command] = cmd
+        end
+
+        opts.on("--paint", "Generate an image from the prompt instead of a text response") do
+          options[:paint] = true
+        end
+
+        opts.on("--im", "--image-model MODEL", "Set image model for generation (default: dall-e-3)") do |model|
+          options[:image_model] = model
+        end
+
         opts.on("--is", "--image-size SIZE", "Set image size for generation (default: 1024x1024)") do |size|
           options[:image_size] = size
         end
@@ -235,9 +270,14 @@ module AIA
         end
       end
 
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
       def setup_tool_options(opts, options)
         opts.separator "\nTool & Extension Options:"
 
+        opts.on('--allow-ruby-eval', 'Enable /ruby directive (executes arbitrary Ruby code with full process privileges)') do
+          options[:allow_ruby_eval] = true
+        end
+
         opts.on("--rq LIBS", "--require LIBS", "Require Ruby libraries for Ruby directive") do |libs|
           options[:require_libs] ||= []
           options[:require_libs] += libs.split(',')
@@ -264,11 +304,18 @@ module AIA
 
       def setup_utility_options(opts, options)
         opts.separator "\nUtility Options:"
+        setup_logging_options(opts, options)
+        setup_output_options(opts, options)
+        setup_mcp_options(opts, options)
+        setup_meta_options(opts, options)
+      end
 
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
+      def setup_logging_options(opts, options)
         opts.on("--log-level LEVEL", "Set log level (debug|info|warn|error|fatal)") do |level|
           level = level.downcase
           unless %w[debug info warn error fatal].include?(level)
-            warn "ERROR: Invalid log level '#{level}'. Must be one of: debug, info, warn, error, fatal"
+            $stderr.puts "ERROR: Invalid log level '#{level}'. Must be one of: debug, info, warn, error, fatal"
             exit 1
           end
           options[:log_level_override] = level
@@ -296,6 +343,22 @@ module AIA
         opts.on("-v", "--[no-]verbose", "Enable verbose output") do |value|
           options[:verbose] = value
         end
+      end
+
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
+      def setup_output_options(opts, options)
+        opts.on("--[no-]thinking", "Show raw thinking/reasoning blocks in output (default: off)") do |v|
+          options[:thinking] = v
+        end
+
+        opts.on("--tokens", "Display token usage and elapsed response time after each turn") do
+          options[:tokens] = true
+        end
+
+        opts.on("--cost", "Display cost calculations and elapsed time (implies --tokens)") do
+          options[:cost] = true
+          options[:tokens] = true
+        end
 
         opts.on("--refresh DAYS", Integer, "Set refresh interval (days) for cached models list (default: 7)") do |days|
           options[:refresh] = days || 0
@@ -308,16 +371,10 @@ module AIA
         opts.on("--completion SHELL", "Generate shell completion script (bash|zsh|fish) and exit") do |shell|
           options[:completion] = shell
         end
+      end
 
-        opts.on("--tokens", "Display token usage") do
-          options[:tokens] = true
-        end
-
-        opts.on("--cost", "Display cost calculations (implies --tokens)") do
-          options[:cost] = true
-          options[:tokens] = true  # --cost implies --tokens
-        end
-
+      # :reek:TooManyStatements -- one opts.on registration per CLI flag; splitting the group would scatter related flags
+      def setup_mcp_options(opts, options)
         opts.on("--mcp FILE", "Load MCP server(s) from JSON file (repeatable)") do |file|
           options[:mcp_files] ||= []
           options[:mcp_files] << file
@@ -340,55 +397,65 @@ module AIA
           options[:mcp_skip] ||= []
           options[:mcp_skip] += names.split(',').map(&:strip)
         end
+      end
 
+      def setup_meta_options(opts, _options)
         opts.on("--version", "Show version and exit") do
           puts AIA::VERSION
           exit
         end
 
         opts.on("-h", "--help", "Show this help and exit") do
-          puts <<~HELP
-
-            AIA - Your AI Assistant (v#{AIA::VERSION})
-              - Manage AI prompts with embedded directives
-              - Integrate with shell and Ruby (ERB) processing
-              - Run batch processes and prompt pipelines
-              - Engage in interactive chat sessions
-              - Use custom tools and MCP servers
-
-          HELP
-
-          puts opts
-
-          puts <<~EXTRA
-
-            Explore Further:
-            - AIA GitHub Repository: https://github.com/MadBomber/aia
-            - AIA Documentation:     https://madbomber.github.io/aia
-            - AIA Changelog:         https://github.com/MadBomber/aia/blob/main/CHANGELOG.md
-            - AIA Examples:          https://github.com/MadBomber/aia/tree/main/examples
-            - Report an Issue:       https://github.com/MadBomber/aia/issues
-            - RubyLLM Documentation: https://rubyllm.com
-            - RubyLLM Tool Docs:     https://rubyllm.com/guides/tools
-            - PromptManager Docs:    https://madbomber.github.io/prompt_manager
-            - ERB Documentation:     https://docs.ruby-lang.org/en/master/ERB.html
-            - MCP Specification:     https://modelcontextprotocol.io
-            - MCP Client Docs:       https://github.com/patvice/ruby_llm-mcp/blob/main/README.md
-
-          EXTRA
-
+          print_help(opts)
           exit
         end
       end
 
+      def print_help(opts)
+        puts <<~HELP
+
+          AIA - Your AI Assistant (v#{AIA::VERSION})
+            - Manage AI prompts with embedded directives
+            - Integrate with shell and Ruby (ERB) processing
+            - Run batch processes and prompt pipelines
+            - Engage in interactive chat sessions
+            - Use custom tools and MCP servers
+            - Compare the same prompt across multiple models (--model m1,m2,m3 [--consensus])
+            - Measure response time and token usage with --tokens; add cost with --cost
+            - Benchmark concurrent vs. serial performance (/decompose reports speedup metrics)
+
+        HELP
+
+        puts opts
+
+        puts <<~EXTRA
+
+          Explore Further:
+          - AIA GitHub Repository: https://github.com/MadBomber/aia
+          - AIA Documentation:     https://madbomber.github.io/aia
+          - AIA Changelog:         https://github.com/MadBomber/aia/blob/main/CHANGELOG.md
+          - AIA Examples:          https://github.com/MadBomber/aia/tree/main/examples
+          - Report an Issue:       https://github.com/MadBomber/aia/issues
+          - RubyLLM Documentation: https://rubyllm.com
+          - RubyLLM Tool Docs:     https://rubyllm.com/guides/tools
+          - PromptManager Docs:    https://madbomber.github.io/prompt_manager
+          - ERB Documentation:     https://docs.ruby-lang.org/en/master/ERB.html
+          - MCP Specification:     https://modelcontextprotocol.io
+          - MCP Client Docs:       https://github.com/patvice/ruby_llm-mcp/blob/main/README.md
+
+        EXTRA
+      end
+
       # Parse model string into array of ModelSpec-compatible hashes
       #
       # @param model_string [String] comma-separated models with optional roles
       # @return [Array<Hash>] array of model specs
+      # :reek:TooManyStatements -- one-pass parser over MODEL[=ROLE] specs sharing the instance counter
       def parse_models_with_roles(model_string)
         models = []
         model_counts = Hash.new(0)
 
+        # rubocop:disable-next Metrics/BlockLength
         model_string.split(',').each do |spec|
           spec.strip!
 
@@ -429,42 +496,42 @@ module AIA
       end
 
       def validate_role_exists(role_id)
-        if AIA::SkillUtils.path_based_id?(role_id)
-          expanded = File.expand_path(role_id)
-          expanded += '.md' if File.extname(expanded).empty?
-          raise ArgumentError, "Role file not found: #{expanded}" unless File.exist?(expanded)
-          return
-        end
+        return validate_role_path!(role_id) if AIA::SkillUtils.path_based_id?(role_id)
 
-        prompts_dir = ENV.fetch('AIA_PROMPTS__DIR', File.join(ENV['HOME'], '.prompts'))
+        prompts_dir  = ENV.fetch('AIA_PROMPTS__DIR', File.join(Dir.home, '.prompts'))
         roles_prefix = ENV.fetch('AIA_PROMPTS__ROLES_PREFIX', 'roles')
-
-        unless role_id.start_with?(roles_prefix)
-          role_id = "#{roles_prefix}/#{role_id}"
-        end
+        role_id      = "#{roles_prefix}/#{role_id}" unless role_id.start_with?(roles_prefix)
 
         role_file_path = File.join(prompts_dir, "#{role_id}.md")
+        return if File.exist?(role_file_path)
 
-        unless File.exist?(role_file_path)
-          available_roles = list_available_role_names(prompts_dir, roles_prefix)
+        raise ArgumentError, role_not_found_message(role_file_path, prompts_dir, roles_prefix)
+      end
 
-          error_msg = "Role file not found: #{role_file_path}\n\n"
+      # A path-based role id must resolve to an existing file.
+      def validate_role_path!(role_id)
+        expanded = File.expand_path(role_id)
+        expanded += '.md' if File.extname(expanded).empty?
+        raise ArgumentError, "Role file not found: #{expanded}" unless File.exist?(expanded)
+      end
 
-          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
+      def role_not_found_message(role_file_path, prompts_dir, roles_prefix)
+        available_roles = list_available_role_names(prompts_dir, roles_prefix)
+        message = "Role file not found: #{role_file_path}\n\n"
 
-          raise ArgumentError, error_msg
+        if available_roles.empty?
+          message + "No roles directory found at #{File.join(prompts_dir, roles_prefix)}\n" \
+                    "Create the directory and add role files to use this feature."
+        else
+          message + "Available roles:\n" +
+            available_roles.map { |r| "  - #{r}" }.join("\n") +
+            "\n\nCreate the role file or use an existing role."
         end
       end
 
+      # :reek:TooManyStatements -- sequential terminal report: guards, then a markdown table per role; exits after printing
       def list_available_roles
-        prompts_dir = ENV.fetch('AIA_PROMPTS__DIR', File.join(ENV['HOME'], '.prompts'))
+        prompts_dir = ENV.fetch('AIA_PROMPTS__DIR', File.join(Dir.home, '.prompts'))
         roles_prefix = ENV.fetch('AIA_PROMPTS__ROLES_PREFIX', 'roles')
         roles_dir = File.join(prompts_dir, roles_prefix)
 
@@ -484,13 +551,16 @@ module AIA
 
         roles.each do |role_id|
           role_file = File.join(roles_dir, "#{role_id}.md")
-          fm = AIA::SkillUtils.parse_front_matter(role_file)
+          front_matter = AIA::SkillUtils.parse_front_matter(role_file)
 
           puts "## #{role_id}"
           puts
           puts "| Key | Value |"
           puts "|-----|-------|"
-          fm.each { |key, value| puts "| #{key} | #{value} |" }
+          front_matter.each do |key, value|
+            safe_value = value.to_s.gsub('|', '\\|')
+            puts "| #{key} | #{safe_value} |"
+          end
           puts
         end
       end
@@ -500,74 +570,76 @@ module AIA
         return [] unless Dir.exist?(roles_dir)
 
         Dir.glob("**/*.md", base: roles_dir)
-          .map { |f| f.chomp('.md') }
-          .reject { |f| f.split('/').any? { |part| part.start_with?('_') } }
-          .sort
+           .map { |f| f.chomp('.md') }
+           .reject { |f| f.split('/').any? { |part| part.start_with?('_') } }
+           .sort
       end
 
+      # :reek:TooManyStatements -- sequential --available-models report: parse query, print matches, summary, exit
       def list_available_models(query)
         require 'ruby_llm'
 
-        if query.nil?
-          query = []
-        else
-          query = query.split(',')
-        end
+        query = query.nil? ? [] : query.split(',')
+        modality_terms, substring_terms = parse_model_query(query)
 
         header = "\nAvailable LLMs"
         header += " for #{query.join(' and ')}" if query.any?
-
         puts header + ':'
         puts
 
-        q1 = query.select { |q| q.include?('_to_') }.map { |q| q[0] == ':' ? q[1..] : q }
-        q2 = query.reject { |q| q.include?('_to_') }
-
-        counter = 0
-
-        RubyLLM.models.all.each do |llm|
-          inputs = llm.modalities.input.join(',')
-          outputs = llm.modalities.output.join(',')
-          entry = "- #{llm.id} (#{llm.provider}) #{inputs} to #{outputs}"
+        counter = print_matching_models(modality_terms, substring_terms)
 
-          if query.nil? || query.empty?
-            counter += 1
-            puts entry
-            next
-          end
+        puts if counter.positive?
+        puts "#{counter} LLMs matching your query"
+        puts
 
-          show_it = true
-          q1.each { |q| show_it &&= llm.modalities.send("#{q}?") }
-          q2.each { |q| show_it &&= entry.include?(q) }
+        exit
+      end
 
-          if show_it
-            counter += 1
-            puts entry
-          end
+      # Print each matching model entry; returns the number printed.
+      def print_matching_models(modality_terms, substring_terms)
+        RubyLLM.models.all.count do |llm|
+          entry = format_model_entry(llm)
+          visible = model_entry_visible?(llm, entry, modality_terms, substring_terms)
+          puts entry if visible
+          visible
         end
+      end
 
-        puts if counter > 0
-        puts "#{counter} LLMs matching your query"
-        puts
+      # Split a query into modality terms (e.g. "text_to_text", leading ':'
+      # stripped) and plain substring terms.
+      def parse_model_query(query)
+        modality, substrings = query.partition { |q| q.include?('_to_') }
+        [modality.map { |q| q.delete_prefix(':') }, substrings]
+      end
 
-        exit
+      def format_model_entry(llm)
+        modalities = llm.modalities
+        "- #{llm.id} (#{llm.provider}) #{modalities.input.join(',')} to #{modalities.output.join(',')}"
+      end
+
+      def model_entry_visible?(llm, entry, modality_terms, substring_terms)
+        modality_terms.all? { |q| llm.modalities.send("#{q}?") } &&
+          substring_terms.all? { |q| entry.include?(q) }
       end
+      # rubocop:enable Metrics/ModuleLength
 
+      # :reek:DuplicateMethodCall -- each `exit 1` terminates a distinct validation failure; there is no value to hoist
       def process_tools_paths(path_list)
         paths = []
 
         if path_list.empty?
-          warn "No list of paths for --tools option"
+          $stderr.puts "No list of paths for --tools option"
           exit 1
         end
 
         path_list.split(',').map(&:strip).uniq.each do |a_path|
           if File.exist?(a_path)
             if File.file?(a_path)
-              if '.rb' == File.extname(a_path)
+              if File.extname(a_path) == '.rb'
                 paths << a_path
               else
-                warn "file should have *.rb extension: #{a_path}"
+                $stderr.puts "file should have *.rb extension: #{a_path}"
                 exit 1
               end
             elsif File.directory?(a_path)
@@ -575,7 +647,7 @@ module AIA
               paths += rb_files
             end
           else
-            warn "file/dir path is not valid: #{a_path}"
+            $stderr.puts "file/dir path is not valid: #{a_path}"
             exit 1
           end
         end