aia 0.9.24 → 0.10.2

data/lib/aia/config/cli_parser.rb

@@ -1,531 +1,531 @@
+# frozen_string_literal: true
+
 # lib/aia/config/cli_parser.rb
+#
+# Parses command-line arguments and returns a hash of overrides
+# for the Config class.
 
 require 'optparse'
-require 'ostruct'
+require_relative 'model_spec'
 
 module AIA
-  module ConfigModules
-    module CLIParser
-      class << self
-        def cli_options
-          config = OpenStruct.new
-
-          begin
-            opt_parser = create_option_parser(config)
-            opt_parser.parse!
-          rescue => e
-            STDERR.puts "ERROR: #{e.message}"
-            STDERR.puts "       use --help for usage report"
-            exit 1
-          end
-
-          parse_remaining_arguments(opt_parser, config)
-          config
-        end
-
-        def create_option_parser(config)
-          OptionParser.new do |opts|
-            setup_banner(opts)
-            setup_mode_options(opts, config)
-            setup_adapter_options(opts, config)
-            setup_model_options(opts, config)
-            setup_file_options(opts, config)
-            setup_prompt_options(opts, config)
-            setup_ai_parameters(opts, config)
-            setup_audio_image_options(opts, config)
-            setup_tool_options(opts, config)
-            setup_utility_options(opts, config)
-          end
+  module CLIParser
+    class << self
+      # Parse CLI arguments and return a hash of overrides
+      #
+      # @return [Hash] configuration overrides from CLI
+      def parse
+        options = {}
+
+        begin
+          parser = create_option_parser(options)
+          parser.parse!
+        rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+          STDERR.puts "ERROR: #{e.message}"
+          STDERR.puts "       use --help for usage report"
+          exit 1
         end
 
-        def setup_banner(opts)
-          opts.banner = "Usage: aia [options] [PROMPT_ID] [CONTEXT_FILE]*\n" +
-                        "       aia --chat [PROMPT_ID] [CONTEXT_FILE]*\n" +
-                        "       aia --chat [CONTEXT_FILE]*"
+        # Store remaining args for prompt_id and context files
+        options[:remaining_args] = ARGV.dup
+
+        options
+      end
+
+      private
+
+      def create_option_parser(options)
+        OptionParser.new do |opts|
+          setup_banner(opts)
+          setup_mode_options(opts, options)
+          setup_adapter_options(opts, options)
+          setup_model_options(opts, options)
+          setup_file_options(opts, options)
+          setup_prompt_options(opts, options)
+          setup_ai_parameters(opts, options)
+          setup_audio_image_options(opts, options)
+          setup_tool_options(opts, options)
+          setup_utility_options(opts, options)
         end
+      end
 
-        def setup_mode_options(opts, config)
-          opts.on("--chat", "Begin a chat session with the LLM after processing all prompts in the pipeline.") do
-            config.chat = true
-            puts "Debug: Setting chat mode to true" if config.debug
-          end
+      def setup_banner(opts)
+        opts.banner = "Usage: aia [options] [PROMPT_ID] [CONTEXT_FILE]*\n" +
+                      "       aia --chat [PROMPT_ID] [CONTEXT_FILE]*\n" +
+                      "       aia --chat [CONTEXT_FILE]*"
+      end
 
-          opts.on("-f", "--fuzzy", "Use fuzzy matching for prompt search") do
-            unless system("which fzf > /dev/null 2>&1")
-              STDERR.puts "Error: 'fzf' is not installed. Please install 'fzf' to use the --fuzzy option."
-              exit 1
-            end
-            config.fuzzy = true
-          end
+      def setup_mode_options(opts, options)
+        opts.on("--chat", "Begin a chat session with the LLM after processing all prompts in the pipeline.") do
+          options[:chat] = true
+        end
 
-          opts.on("--terse", "Adds a special instruction to the prompt asking the AI to keep responses short and to the point") do
-            config.terse = true
+        opts.on("-f", "--fuzzy", "Use fuzzy matching for prompt search") do
+          unless system("which fzf > /dev/null 2>&1")
+            STDERR.puts "Error: 'fzf' is not installed. Please install 'fzf' to use the --fuzzy option."
+            exit 1
           end
+          options[:fuzzy] = true
         end
 
-        def setup_adapter_options(opts, config)
-          opts.on("--adapter ADAPTER", "Interface that adapts AIA to the LLM") do |adapter|
-            adapter.downcase!
-            valid_adapters = %w[ ruby_llm ]  # NOTE: Add additional adapters here when needed
-            if valid_adapters.include? adapter
-              config.adapter = adapter
-            else
-              STDERR.puts "ERROR: Invalid adapter #{adapter} must be one of these: #{valid_adapters.join(', ')}"
-              exit 1
-            end
-          end
+        opts.on("--terse", "Adds a special instruction to the prompt asking the AI to keep responses short and to the point") do
+          options[:terse] = true
+        end
+      end
 
-          opts.on('--available_models [QUERY]', 'List (then exit) available models that match the optional query - a comma separated list of AND components like: openai,mini') do |query|
-            list_available_models(query)
+      def setup_adapter_options(opts, options)
+        opts.on("--adapter ADAPTER", "Interface that adapts AIA to the LLM") do |adapter|
+          adapter.downcase!
+          valid_adapters = %w[ruby_llm]
+          if valid_adapters.include?(adapter)
+            options[:adapter] = adapter
+          else
+            STDERR.puts "ERROR: Invalid adapter #{adapter} must be one of these: #{valid_adapters.join(', ')}"
+            exit 1
           end
         end
 
-        def setup_model_options(opts, config)
-          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('--available-models [QUERY]', 'List (then exit) available models that match the optional query') do |query|
+          list_available_models(query)
+        end
+      end
 
-          opts.on("--[no-]consensus", "Enable/disable consensus mode for multi-model responses (default: show individual responses)") do |consensus|
-            config.consensus = consensus
-          end
+      def setup_model_options(opts, options)
+        opts.on("-m MODEL", "--model MODEL", "Name of the LLM model(s) to use. Format: MODEL[=ROLE][,MODEL[=ROLE]]...") do |model_string|
+          options[:models] = parse_models_with_roles(model_string)
+        end
 
-          opts.on("--list-roles", "List available role files and exit") do
-            list_available_roles
-            exit 0
-          end
+        opts.on("--[no-]consensus", "Enable/disable consensus mode for multi-model responses") do |consensus|
+          options[:consensus] = consensus
+        end
 
-          opts.on("--sm", "--speech_model MODEL", "Speech model to use") do |model|
-            config.speech_model = model
-          end
+        opts.on("--list-roles", "List available role files and exit") do
+          list_available_roles
+          exit 0
+        end
 
-          opts.on("--tm", "--transcription_model MODEL", "Transcription model to use") do |model|
-            config.transcription_model = model
-          end
+        opts.on("--sm", "--speech-model MODEL", "Speech model to use") do |model|
+          options[:speech_model] = model
         end
 
-        def setup_file_options(opts, config)
-          opts.on("-c", "--config_file FILE", "Load config file") do |file|
-            FileLoader.load_config_file(file, config)
-          end
+        opts.on("--tm", "--transcription-model MODEL", "Transcription model to use") do |model|
+          options[:transcription_model] = model
+        end
+      end
 
-          opts.on("-o", "--[no-]out_file [FILE]", "Output file (default: temp.md)") do |file|
-            if file == false  # --no-out_file was used
-              config.out_file = nil
-            elsif file.nil?   # No argument provided
-              config.out_file = 'temp.md'
-            else              # File name provided
-              config.out_file = File.expand_path(file, Dir.pwd)
-            end
-          end
+      def setup_file_options(opts, options)
+        opts.on("-c", "--config-file FILE", "Load additional config file") do |file|
+          options[:extra_config_file] = file
+        end
 
-          opts.on("-a", "--[no-]append", "Append to output file instead of overwriting") do |append|
-            config.append = append
+        opts.on("-o", "--[no-]output [FILE]", "Output file (default: temp.md)") 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
+        end
 
-          opts.on("-l", "--[no-]log_file [FILE]", "Log file") do |file|
-            config.log_file = file
-          end
+        opts.on("-a", "--[no-]append", "Append to output file instead of overwriting") do |append|
+          options[:append] = append
+        end
 
-          opts.on("--md", "--[no-]markdown", "Format with Markdown") do |md|
-            config.markdown = md
-          end
+        opts.on("--[no-]history-file [FILE]", "Conversation history file") do |file|
+          options[:history_file] = file
         end
 
-        def setup_prompt_options(opts, config)
-          opts.on("--prompts_dir DIR", "Directory containing prompt files") do |dir|
-            config.prompts_dir = dir
-          end
+        opts.on("--md", "--[no-]markdown", "Format with Markdown") do |md|
+          options[:markdown] = md
+        end
+      end
 
-          opts.on("--roles_prefix PREFIX", "Subdirectory name for role files (default: roles)") do |prefix|
-            config.roles_prefix = prefix
-          end
+      def setup_prompt_options(opts, options)
+        opts.on("--prompts-dir DIR", "Directory containing prompt files") do |dir|
+          options[:prompts_dir] = dir
+        end
 
-          opts.on("-r", "--role ROLE_ID", "Role ID to prepend to prompt") do |role|
-            config.role = role
-          end
+        opts.on("--roles-prefix PREFIX", "Subdirectory name for role files (default: roles)") do |prefix|
+          options[:roles_prefix] = prefix
+        end
 
-          opts.on("-n", "--next PROMPT_ID", "Next prompt to process") do |next_prompt|
-            config.pipeline ||= []
-            config.pipeline << next_prompt
-          end
+        opts.on("-r", "--role ROLE_ID", "Role ID to prepend to prompt") do |role|
+          options[:role] = role
+        end
 
-          opts.on("-p PROMPTS", "--pipeline PROMPTS", "Pipeline of comma-seperated prompt IDs to process") do |pipeline|
-            config.pipeline ||= []
-            config.pipeline += pipeline.split(',').map(&:strip)
-          end
+        opts.on("-n", "--next PROMPT_ID", "Next prompt to process") do |next_prompt|
+          options[:pipeline] ||= []
+          options[:pipeline] << next_prompt
+        end
 
-          opts.on("-x", "--[no-]exec", "Used to designate an executable prompt file") do |value|
-            config.executable_prompt = value
-          end
+        opts.on("-p PROMPTS", "--pipeline PROMPTS", "Pipeline of comma-separated prompt IDs to process") do |pipeline|
+          options[:pipeline] ||= []
+          options[:pipeline] += pipeline.split(',').map(&:strip)
+        end
 
-          opts.on("--system_prompt PROMPT_ID", "System prompt ID to use for chat sessions") do |prompt_id|
-            config.system_prompt = prompt_id
-          end
+        opts.on("-x", "--[no-]exec", "Used to designate an executable prompt file") do |value|
+          options[:executable_prompt] = value
+        end
 
-          opts.on('--regex pattern', 'Regex pattern to extract parameters from prompt text') do |pattern|
-            config.parameter_regex = pattern
-          end
+        opts.on("--system-prompt PROMPT_ID", "System prompt ID to use for chat sessions") do |prompt_id|
+          options[:system_prompt] = prompt_id
         end
 
-        def setup_ai_parameters(opts, config)
-          opts.on("-t", "--temperature TEMP", Float, "Temperature for text generation") do |temp|
-            config.temperature = temp
-          end
+        opts.on('--regex PATTERN', 'Regex pattern to extract parameters from prompt text') do |pattern|
+          options[:parameter_regex] = pattern
+        end
+      end
 
-          opts.on("--max_tokens TOKENS", Integer, "Maximum tokens for text generation") do |tokens|
-            config.max_tokens = tokens
-          end
+      def setup_ai_parameters(opts, options)
+        opts.on("-t", "--temperature TEMP", Float, "Temperature for text generation") do |temp|
+          options[:temperature] = temp
+        end
 
-          opts.on("--top_p VALUE", Float, "Top-p sampling value") do |value|
-            config.top_p = value
-          end
+        opts.on("--max-tokens TOKENS", Integer, "Maximum tokens for text generation") do |tokens|
+          options[:max_tokens] = tokens
+        end
 
-          opts.on("--frequency_penalty VALUE", Float, "Frequency penalty") do |value|
-            config.frequency_penalty = value
-          end
+        opts.on("--top-p VALUE", Float, "Top-p sampling value") do |value|
+          options[:top_p] = value
+        end
 
-          opts.on("--presence_penalty VALUE", Float, "Presence penalty") do |value|
-            config.presence_penalty = value
-          end
+        opts.on("--frequency-penalty VALUE", Float, "Frequency penalty") do |value|
+          options[:frequency_penalty] = value
         end
 
-        def setup_audio_image_options(opts, config)
-          opts.on("--speak", "Simple implementation. Uses the speech model to convert text to audio, then plays the audio. Fun with --chat. Supports configuration of speech model and voice.") do
-            config.speak = true
-          end
+        opts.on("--presence-penalty VALUE", Float, "Presence penalty") do |value|
+          options[:presence_penalty] = value
+        end
+      end
 
-          opts.on("--voice VOICE", "Voice to use for speech") do |voice|
-            config.voice = voice
-          end
+      def setup_audio_image_options(opts, options)
+        opts.on("--speak", "Convert text to audio and play it") do
+          options[:speak] = true
+        end
 
-          opts.on("--is", "--image_size SIZE", "Image size for image generation") do |size|
-            config.image_size = size
-          end
+        opts.on("--voice VOICE", "Voice to use for speech") do |voice|
+          options[:voice] = voice
+        end
 
-          opts.on("--iq", "--image_quality QUALITY", "Image quality for image generation") do |quality|
-            config.image_quality = quality
-          end
+        opts.on("--is", "--image-size SIZE", "Image size for image generation") do |size|
+          options[:image_size] = size
+        end
 
-          opts.on("--style", "--image_style STYLE", "Style for image generation") do |style|
-            config.image_style = style
-          end
+        opts.on("--iq", "--image-quality QUALITY", "Image quality for image generation") do |quality|
+          options[:image_quality] = quality
         end
 
-        def setup_tool_options(opts, config)
-          opts.on("--rq LIBS", "--require LIBS", "Ruby libraries to require for Ruby directive") do |libs|
-            config.require_libs ||= []
-            config.require_libs += libs.split(',')
-          end
+        opts.on("--style", "--image-style STYLE", "Style for image generation") do |style|
+          options[:image_style] = style
+        end
+      end
 
-          opts.on("--tools PATH_LIST", "Add a tool(s)") do |a_path_list|
-            process_tools_option(a_path_list, config)
-          end
+      def setup_tool_options(opts, options)
+        opts.on("--rq LIBS", "--require LIBS", "Ruby libraries to require for Ruby directive") do |libs|
+          options[:require_libs] ||= []
+          options[:require_libs] += libs.split(',')
+        end
 
-          opts.on("--at", "--allowed_tools TOOLS_LIST", "Allow only these tools to be used") do |tools_list|
-            process_allowed_tools_option(tools_list, config)
-          end
+        opts.on("--tools PATH_LIST", "Add tool(s) by path") do |path_list|
+          options[:tool_paths] = process_tools_paths(path_list)
+        end
 
-          opts.on("--rt", "--rejected_tools TOOLS_LIST", "Reject these tools") do |tools_list|
-            process_rejected_tools_option(tools_list, config)
-          end
+        opts.on("--at", "--allowed-tools TOOLS_LIST", "Allow only these tools to be used") do |tools_list|
+          options[:allowed_tools] ||= []
+          options[:allowed_tools] += tools_list.split(',').map(&:strip)
         end
 
-        def setup_utility_options(opts, config)
-          opts.on("-d", "--debug", "Enable debug output") do
-            config.debug = $DEBUG_ME = true
-          end
+        opts.on("--rt", "--rejected-tools TOOLS_LIST", "Reject these tools") do |tools_list|
+          options[:rejected_tools] ||= []
+          options[:rejected_tools] += tools_list.split(',').map(&:strip)
+        end
+      end
 
-          opts.on("--no-debug", "Disable debug output") do
-            config.debug = $DEBUG_ME = false
-          end
+      def setup_utility_options(opts, options)
+        opts.on("-d", "--debug", "Enable debug output and set all loggers to DEBUG level") do
+          options[:debug] = true
+          options[:log_level_override] = 'debug'
+          $DEBUG_ME = true
+        end
 
-          opts.on("-v", "--[no-]verbose", "Be verbose") do |value|
-            config.verbose = value
-          end
+        opts.on("--no-debug", "Disable debug output") do
+          options[:debug] = false
+          $DEBUG_ME = false
+        end
 
-          opts.on("--refresh DAYS", Integer, "Refresh models database interval in days") do |days|
-            config.refresh = days || 0
-          end
+        opts.on("--info", "Set all loggers to INFO level") do
+          options[:log_level_override] = 'info'
+        end
 
-          opts.on("--dump FILE", "Dump config to file") do |file|
-            config.dump_file = file
-          end
+        opts.on("--warn", "Set all loggers to WARN level") do
+          options[:log_level_override] = 'warn'
+        end
 
-          opts.on("--completion SHELL", "Show completion script for bash|zsh|fish - default is nil") do |shell|
-            config.completion = shell
-          end
+        opts.on("--error", "Set all loggers to ERROR level") do
+          options[:log_level_override] = 'error'
+        end
 
-          opts.on("--metrics", "Display token usage in chat mode") do
-            config.show_metrics = true
-          end
+        opts.on("--fatal", "Set all loggers to FATAL level") do
+          options[:log_level_override] = 'fatal'
+        end
 
-          opts.on("--cost", "Include cost calculations with metrics (requires --metrics)") do
-            config.show_cost = true
-            config.show_metrics = true  # Automatically enable metrics when cost is requested
-          end
+        opts.on("--log-to FILE", "Direct all loggers to FILE") do |file|
+          options[:log_file_override] = file
+        end
 
-          opts.on("--version", "Show version") do
-            puts AIA::VERSION
-            exit
-          end
+        opts.on("-v", "--[no-]verbose", "Be verbose") do |value|
+          options[:verbose] = value
+        end
 
-          opts.on("-h", "--help", "Prints this help") do
-            puts <<~HELP
+        opts.on("--refresh DAYS", Integer, "Refresh models database interval in days") do |days|
+          options[:refresh] = days || 0
+        end
 
-              AIA your AI Assistant
-                - designed for generative AI workflows,
-                - effortlessly manage AI prompts,
-                - integrate seamlessly with shell and embedded Ruby (ERB),
-                - run batch processes,
-                - engage in interactive chats,
-                - with user defined directives, tools and MCP clients.
+        opts.on("--dump FILE", "Dump config to file") do |file|
+          options[:dump_file] = file
+        end
 
-            HELP
+        opts.on("--completion SHELL", "Show completion script for bash|zsh|fish") do |shell|
+          options[:completion] = shell
+        end
 
-            puts opts
+        opts.on("--tokens", "Display token usage in chat mode") do
+          options[:tokens] = true
+        end
 
-            puts <<~EXTRA
+        opts.on("--cost", "Include cost calculations with token usage") do
+          options[:cost] = true
+          options[:tokens] = true  # --cost implies --tokens
+        end
 
-              Explore Further:
-              - AIA Report an Issue:   https://github.com/MadBomber/aia/issues
-              - AIA Documentation:     https://github.com/MadBomber/aia/blob/main/README.md
-              - AIA GitHub Repository: https://github.com/MadBomber/aia
-              - PromptManager Docs:    https://github.com/MadBomber/prompt_manager/blob/main/README.md
-              - ERB Documentation:     https://rubyapi.org/o/erb
-              - RubyLLM Tool Docs:     https://rubyllm.com/guides/tools
-              - MCP Client Docs:       https://github.com/patvice/ruby_llm-mcp/blob/main/README.md
+        opts.on("--mcp FILE", "Load MCP server(s) from JSON file (can be used multiple times)") do |file|
+          options[:mcp_files] ||= []
+          options[:mcp_files] << file
+        end
 
-            EXTRA
+        opts.on("--no-mcp", "Disable all MCP server processing") do
+          options[:no_mcp] = true
+        end
 
-            exit
-          end
+        opts.on("--version", "Show version") do
+          puts AIA::VERSION
+          exit
         end
 
-        def parse_models_with_roles(model_string)
-          models = []
-          model_counts = Hash.new(0)
+        opts.on("-h", "--help", "Prints this help") do
+          puts <<~HELP
 
-          model_string.split(',').each do |spec|
-            spec.strip!
+            AIA your AI Assistant
+              - designed for generative AI workflows,
+              - effortlessly manage AI prompts,
+              - integrate seamlessly with shell and embedded Ruby (ERB),
+              - run batch processes,
+              - engage in interactive chats,
+              - with user defined directives, tools and MCP clients.
 
-            # Validate syntax
-            if spec =~ /^=|=$/
-              raise ArgumentError, "Invalid model syntax: '#{spec}'. Expected format: MODEL[=ROLE]"
-            end
+          HELP
 
-            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
+          puts opts
 
-          models
+          puts <<~EXTRA
+
+            Explore Further:
+            - AIA Report an Issue:   https://github.com/MadBomber/aia/issues
+            - AIA Documentation:     https://github.com/MadBomber/aia/blob/main/README.md
+            - AIA GitHub Repository: https://github.com/MadBomber/aia
+            - PromptManager Docs:    https://github.com/MadBomber/prompt_manager/blob/main/README.md
+            - ERB Documentation:     https://rubyapi.org/o/erb
+            - RubyLLM Tool Docs:     https://rubyllm.com/guides/tools
+            - MCP Client Docs:       https://github.com/patvice/ruby_llm-mcp/blob/main/README.md
+
+          EXTRA
+
+          exit
         end
+      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')
+      # 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
+      def parse_models_with_roles(model_string)
+        models = []
+        model_counts = Hash.new(0)
 
-          # Build role file path
-          unless role_id.start_with?(roles_prefix)
-            role_id = "#{roles_prefix}/#{role_id}"
+        model_string.split(',').each do |spec|
+          spec.strip!
+
+          if spec =~ /^=|=$/
+            raise ArgumentError, "Invalid model syntax: '#{spec}'. Expected format: MODEL[=ROLE]"
           end
 
-          role_file_path = File.join(prompts_dir, "#{role_id}.txt")
+          if spec.include?('=')
+            model_name, role_name = spec.split('=', 2)
+            model_name.strip!
+            role_name.strip!
 
-          unless File.exist?(role_file_path)
-            available_roles = list_available_role_names(prompts_dir, roles_prefix)
+            validate_role_exists(role_name)
 
-            error_msg = "Role file not found: #{role_file_path}\n\n"
+            model_counts[model_name] += 1
+            instance = model_counts[model_name]
 
-            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
+            models << {
+              name: model_name,
+              role: role_name,
+              instance: instance,
+              internal_id: instance > 1 ? "#{model_name}##{instance}" : model_name
+            }
+          else
+            model_counts[spec] += 1
+            instance = model_counts[spec]
 
-            raise ArgumentError, error_msg
+            models << {
+              name: spec,
+              role: nil,
+              instance: instance,
+              internal_id: instance > 1 ? "#{spec}##{instance}" : spec
+            }
           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)
+        models
+      end
 
-          if Dir.exist?(roles_dir)
-            roles = list_available_role_names(prompts_dir, roles_prefix)
+      def validate_role_exists(role_id)
+        prompts_dir = ENV.fetch('AIA_PROMPTS__DIR', File.join(ENV['HOME'], '.prompts'))
+        roles_prefix = ENV.fetch('AIA_PROMPTS__ROLES_PREFIX', 'roles')
 
-            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
+        unless role_id.start_with?(roles_prefix)
+          role_id = "#{roles_prefix}/#{role_id}"
         end
 
-        def list_available_role_names(prompts_dir, roles_prefix)
-          roles_dir = File.join(prompts_dir, roles_prefix)
-          return [] unless Dir.exist?(roles_dir)
+        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
 
-          # Find all .txt files recursively, preserving paths
-          Dir.glob("**/*.txt", base: roles_dir)
-            .map { |f| f.chomp('.txt') }
-            .sort
+          raise ArgumentError, error_msg
         end
+      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
-          #        should this be moved to the Utilities class as a common method?
+      def list_available_roles
+        prompts_dir = ENV.fetch('AIA_PROMPTS__DIR', File.join(ENV['HOME'], '.prompts'))
+        roles_prefix = ENV.fetch('AIA_PROMPTS__ROLES_PREFIX', 'roles')
+        roles_dir = File.join(prompts_dir, roles_prefix)
 
-          if query.nil?
-            query = []
+        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
-            query = query.split(',')
+            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
 
-          header    = "\nAvailable LLMs"
-          header   += " for #{query.join(' and ')}" if query
+      def list_available_role_names(prompts_dir, roles_prefix)
+        roles_dir = File.join(prompts_dir, roles_prefix)
+        return [] unless Dir.exist?(roles_dir)
 
-          puts header + ':'
-          puts
+        Dir.glob("**/*.txt", base: roles_dir)
+          .map { |f| f.chomp('.txt') }
+          .sort
+      end
 
-          q1 = query.select{|q| q.include?('_to_')}.map{|q| ':'==q[0] ? q[1...] : q}
-          q2 = query.reject{|q| q.include?('_to_')}
+      def list_available_models(query)
+        require 'ruby_llm'
 
-          counter = 0
+        if query.nil?
+          query = []
+        else
+          query = query.split(',')
+        end
 
-          RubyLLM.models.all.each do |llm|
-            inputs  = llm.modalities.input.join(',')
-            outputs = llm.modalities.output.join(',')
-            entry   = "- #{llm.id} (#{llm.provider}) #{inputs} to #{outputs}"
+        header = "\nAvailable LLMs"
+        header += " for #{query.join(' and ')}" if query.any?
 
-            if query.nil? || query.empty?
-              counter += 1
-              puts entry
-              next
-            end
+        puts header + ':'
+        puts
 
-            show_it = true
-            q1.each{|q| show_it &&= llm.modalities.send("#{q}?")}
-            q2.each{|q| show_it &&= entry.include?(q)}
+        q1 = query.select { |q| q.include?('_to_') }.map { |q| q[0] == ':' ? q[1..] : q }
+        q2 = query.reject { |q| q.include?('_to_') }
 
-            if show_it
-              counter += 1
-              puts entry
-            end
-          end
+        counter = 0
 
-          puts if counter > 0
-          puts "#{counter} LLMs matching your query"
-          puts
+        RubyLLM.models.all.each do |llm|
+          inputs = llm.modalities.input.join(',')
+          outputs = llm.modalities.output.join(',')
+          entry = "- #{llm.id} (#{llm.provider}) #{inputs} to #{outputs}"
 
-          exit
-        end
+          if query.nil? || query.empty?
+            counter += 1
+            puts entry
+            next
+          end
 
-        def parse_remaining_arguments(opt_parser, config)
-          args = ARGV.dup
+          show_it = true
+          q1.each { |q| show_it &&= llm.modalities.send("#{q}?") }
+          q2.each { |q| show_it &&= entry.include?(q) }
 
-          # Parse the command line arguments
-          begin
-            config.remaining_args = opt_parser.parse(args)
-          rescue OptionParser::InvalidOption => e
-            puts e.message
-            puts opt_parser
-            exit 1
+          if show_it
+            counter += 1
+            puts entry
           end
         end
 
-        def process_tools_option(a_path_list, config)
-          config.tool_paths ||= []
+        puts if counter > 0
+        puts "#{counter} LLMs matching your query"
+        puts
 
-          if a_path_list.empty?
-            STDERR.puts "No list of paths for --tools option"
-            exit 1
-          else
-            paths = a_path_list.split(',').map(&:strip).uniq
-          end
+        exit
+      end
 
-          paths.each do |a_path|
-            if File.exist?(a_path)
-              if File.file?(a_path)
-                if  '.rb' == File.extname(a_path)
-                  config.tool_paths << a_path
-                else
-                  STDERR.puts "file should have *.rb extension: #{a_path}"
-                  exit 1
-                end
-              elsif File.directory?(a_path)
-                rb_files = Dir.glob(File.join(a_path, '*.rb'))
-                config.tool_paths += rb_files
-              end
-            else
-              STDERR.puts "file/dir path is not valid: #{a_path}"
-              exit 1
-            end
-          end
+      def process_tools_paths(path_list)
+        paths = []
 
-          config.tool_paths.uniq!
+        if path_list.empty?
+          STDERR.puts "No list of paths for --tools option"
+          exit 1
         end
 
-        def process_allowed_tools_option(tools_list, config)
-          config.allowed_tools ||= []
-          if tools_list.empty?
-            STDERR.puts "No list of tool names provided for --allowed_tools option"
-            exit 1
+        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)
+                paths << a_path
+              else
+                STDERR.puts "file should have *.rb extension: #{a_path}"
+                exit 1
+              end
+            elsif File.directory?(a_path)
+              rb_files = Dir.glob(File.join(a_path, '*.rb'))
+              paths += rb_files
+            end
           else
-            config.allowed_tools += tools_list.split(',').map(&:strip)
-            config.allowed_tools.uniq!
-          end
-        end
-
-        def process_rejected_tools_option(tools_list, config)
-          config.rejected_tools ||= []
-          if tools_list.empty?
-            STDERR.puts "No list of tool names provided for --rejected_tools option"
+            STDERR.puts "file/dir path is not valid: #{a_path}"
             exit 1
-          else
-            config.rejected_tools += tools_list.split(',').map(&:strip)
-            config.rejected_tools.uniq!
           end
         end
+
+        paths.uniq
       end
     end
   end