ace-llm 0.30.0

data/lib/ace/llm/cli/commands/query.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/support/cli"
+
+module Ace
+  module LLM
+    module CLI
+      module Commands
+        # Query command for ace-llm
+        class Query < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Query an LLM provider"
+
+          argument :provider_model, required: false, desc: "PROVIDER[:MODEL] or alias (e.g., gflash, google:gemini-2.5-flash)"
+          argument :prompt_text, required: false, desc: "Prompt text (can also use --prompt flag)"
+
+          option :quiet, type: :boolean, default: false, desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, default: false, desc: "Show verbose output"
+          option :debug, type: :boolean, default: false, desc: "Show debug output"
+
+          option :output, type: :string, aliases: %w[o], desc: "Output file path"
+          option :format, type: :string, aliases: %w[f], desc: "Output format (text, json, markdown)"
+          option :temperature, type: :float, aliases: %w[t], desc: "Temperature (0.0-2.0)"
+          option :max_tokens, type: :integer, aliases: %w[m], desc: "Maximum output tokens"
+          option :system, type: :string, aliases: %w[s], desc: "System instruction/prompt"
+          option :system_append, type: :string, desc: "Append to system prompt"
+          option :preset, type: :string, desc: "Execution preset name (or use model@preset)"
+          option :cli_args, type: :string, desc: "Extra args for CLI providers (auto-prefixed with --; use --flag value or flag=value for values)"
+          option :timeout, type: :integer, desc: "Request timeout in seconds"
+          option :model, type: :string, desc: "Model name (overrides PROVIDER[:MODEL])"
+          option :prompt, type: :string, desc: "Prompt text (overrides positional PROMPT)"
+          option :force, type: :boolean, default: false, desc: "Force overwrite existing files"
+
+          option :version, type: :boolean, desc: "Show version information"
+          option :list_providers, type: :boolean, desc: "List available LLM providers"
+
+          def call(provider_model: nil, prompt_text: nil, **options)
+            if options[:version]
+              puts "ace-llm #{Ace::LLM::VERSION}"
+              return
+            end
+
+            if options[:list_providers]
+              list_providers
+              return
+            end
+
+            @provider_model = provider_model
+            if @provider_model.nil? && options[:model]
+              @provider_model = options[:model]
+              @model_from_option = true
+            end
+
+            @prompt = options[:prompt] || prompt_text
+
+            return show_help if @provider_model.nil? && @prompt.nil?
+            return show_provider_help if @prompt.nil? || @prompt.empty?
+            return show_help if @provider_model.nil? || @provider_model.empty?
+
+            display_config_summary(options)
+            execute_query(options)
+          rescue Ace::LLM::Error => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          rescue ArgumentError, EncodingError => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+
+          private
+
+          def show_help
+            puts "Usage: ace-llm PROVIDER[:MODEL] [PROMPT] [options]"
+            puts "       ace-llm PROVIDER --prompt PROMPT [options]"
+            puts "       ace-llm PROVIDER PROMPT --model MODEL [options]"
+            puts ""
+            puts "Query any LLM provider through a unified interface"
+            puts ""
+            puts "Options:"
+            puts "  -o, --output FILE              Output file path"
+            puts "  -f, --format FORMAT            Output format (text, json, markdown)"
+            puts "  -t, --temperature FLOAT        Temperature (0.0-2.0)"
+            puts "  -m, --max-tokens INT           Maximum output tokens"
+            puts "  -s, --system TEXT              System instruction/prompt"
+            puts "      --system-append TEXT       Append to system prompt"
+            puts "      --preset NAME              Execution preset name (or use model@preset)"
+            puts "      --cli-args TEXT            Extra args for CLI providers (auto-prefixed with --; use --flag value or flag=value)"
+            puts "      --timeout SECONDS          Request timeout in seconds"
+            puts "      --model MODEL              Model name (overrides PROVIDER[:MODEL])"
+            puts "      --prompt PROMPT            Prompt text (overrides positional PROMPT)"
+            puts "      --force                    Force overwrite existing files"
+            puts "  -q, --quiet                    Suppress config summary output"
+            puts "  -d, --debug                    Enable debug output"
+            puts "  -h, --help                     Show this help message"
+            puts ""
+            puts "Examples:"
+            puts '  ace-llm google:gemini-2.5-flash "What is Ruby?"'
+            puts '  ace-llm gflash "Quick question" # using alias'
+            puts '  ace-llm gflash@ro "Summarize this diff"'
+            puts '  ace-llm codex:gpt-5:high@ro "Review this code"'
+            puts '  ace-llm claude:sonnet "Summarize this diff" --preset rw'
+            puts '  ace-llm claude:sonnet "Hi" --cli-args "dangerously-skip-permissions"'
+            puts '  ace-llm claude:sonnet "Hi" --cli-args "--model=claude-sonnet-4-0 --verbose"'
+            puts ""
+            puts "Provider Aliases:"
+            puts "  Short aliases for common provider:MODEL combinations:"
+            puts "    gflash    → google:gemini-2.5-flash"
+            puts "    glite     → google:gemini-2.0-flash-lite"
+            puts "    gpt4      → openai:gpt-4"
+            puts "    claude    → anthropic:claude-3-5-sonnet"
+          end
+
+          def show_provider_help
+            puts "Available aliases for '#{@provider_model}':"
+            puts ""
+
+            resolver = Ace::LLM::Molecules::LlmAliasResolver.new
+            aliases = resolver.available_aliases
+
+            if aliases[:global] && !aliases[:global].empty?
+              puts "Global aliases:"
+              aliases[:global].each do |alias_name, target|
+                puts "  #{alias_name} → #{target}"
+              end
+            end
+
+            puts ""
+            puts "Use: ace-llm #{@provider_model} \"your prompt here\""
+          end
+
+          def display_config_summary(options)
+            return if quiet?(options)
+
+            require "ace/core"
+            summary_keys = %w[provider_model preset temperature max_tokens format timeout system_append cli_args]
+            Ace::Core::Atoms::ConfigSummary.display(
+              command: "query",
+              config: options.merge(provider_model: @provider_model),
+              defaults: {},
+              options: options,
+              quiet: false,
+              summary_keys: summary_keys
+            )
+          end
+
+          def execute_query(options)
+            file_handler = Ace::LLM::Molecules::FileIoHandler.new
+            prompt_text = file_handler.read_content(@prompt)
+            system_text = options[:system] ? file_handler.read_content(options[:system]) : nil
+            system_append_text = options[:system_append] ? file_handler.read_content(options[:system_append]) : nil
+            normalized_timeout = normalize_timeout(options[:timeout])
+
+            resolved_model_override = @model_from_option ? nil : options[:model]
+            response = Ace::LLM::QueryInterface.query(
+              @provider_model,
+              prompt_text,
+              temperature: options[:temperature],
+              max_tokens: options[:max_tokens],
+              system: system_text,
+              timeout: normalized_timeout,
+              debug: options[:debug],
+              model: resolved_model_override,
+              cli_args: options[:cli_args],
+              system_append: system_append_text,
+              preset: options[:preset]
+            )
+
+            output_response(response, options)
+          rescue Ace::LLM::ProviderError => e
+            if e.message.include?("not found") || e.message.include?("not registered")
+              available = begin
+                Ace::LLM::ClientRegistry.available_providers
+              rescue
+                []
+              end
+              raise Ace::Support::Cli::Error, "#{e.message}\nAvailable providers: #{available.join(", ")}"
+            end
+            raise
+          end
+
+          def output_response(response, options)
+            format = options[:format] || "text"
+            handler = Ace::LLM::Molecules::FormatHandlers.get_handler(format)
+            formatted_output = handler.format(response)
+
+            if options[:output]
+              file_handler = Ace::LLM::Molecules::FileIoHandler.new
+              file_handler.write_content(
+                formatted_output,
+                options[:output],
+                format: format,
+                force: options[:force]
+              )
+
+              puts handler.generate_summary(response, options[:output])
+            else
+              puts formatted_output
+            end
+          end
+
+          def list_providers
+            require "ace/llm/molecules/client_registry"
+
+            registry = Ace::LLM::Molecules::ClientRegistry.new
+            providers = registry.list_providers_with_status
+            configuration = Ace::LLM.configuration
+
+            if configuration.provider_filter_applied?
+              total = configuration.configured_provider_names.length
+              puts "Available LLM Providers (filtered - #{providers.length} of #{total} active):"
+            else
+              puts "Available LLM Providers:"
+            end
+            puts ""
+
+            providers.each do |provider|
+              status = provider[:available] ? "\u2713" : "\u2717"
+              api_status = if provider[:api_key_required]
+                provider[:api_key_present] ? "API key configured" : "API key required"
+              else
+                "No API key needed"
+              end
+
+              models = provider[:models] || []
+              model_count = models.empty? ? "" : " \u00b7 #{models.length} models"
+              puts "#{status} #{provider[:name]}#{model_count} (#{api_status})"
+
+              print_wrapped_list(models, indent: "  ") unless models.empty?
+              puts "  Gem required: #{provider[:gem]}" unless provider[:available]
+              puts ""
+            end
+
+            return unless configuration.provider_filter_applied?
+
+            inactive = configuration.inactive_provider_names
+            return if inactive.empty?
+
+            puts "Inactive providers (#{inactive.length}):"
+            print_wrapped_list(inactive, indent: "  ")
+            puts ""
+          end
+
+          def print_wrapped_list(items, indent: "  ", max_width: 78)
+            current_line = indent.dup
+
+            items.each_with_index do |item, i|
+              is_last = i == items.length - 1
+              entry = is_last ? item.to_s : "#{item},"
+
+              if current_line == indent
+                current_line << entry
+              elsif current_line.length + 1 + entry.length > max_width
+                puts current_line
+                current_line = "#{indent}#{entry}"
+              else
+                current_line << " #{entry}"
+              end
+            end
+
+            puts current_line unless current_line.strip.empty?
+          end
+
+          def error_output(message)
+            warn "Error: #{message}"
+          end
+
+          def normalize_timeout(value)
+            return nil if value.nil?
+            return value if value.is_a?(Numeric)
+
+            normalized = value.to_s.strip
+            Float(normalized)
+          rescue ArgumentError
+            raise ArgumentError, "timeout must be numeric, got #{value.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/cli.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+require_relative "../llm"
+# Commands
+require_relative "cli/commands/query"
+
+module Ace
+  module LLM
+    # CLI namespace for ace-llm command loading.
+    #
+    # ace-llm uses a single-command ace-support-cli entrypoint that calls
+    # CLI::Commands::Query directly from the executable.
+    module CLI
+      # Entry point for CLI invocation (used by tests via cli_helpers)
+      #
+      # @param args [Array<String>] Command-line arguments
+      def self.start(args)
+        Ace::Support::Cli::Runner.new(Commands::Query).call(args: args)
+      end
+    end
+  end
+end

data/lib/ace/llm/configuration.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "molecules/config_loader"
+
+module Ace
+  module LLM
+    # Central configuration management for ace-llm
+    class Configuration
+      attr_reader :config
+
+      def initialize
+        @config = Molecules::ConfigLoader.load
+      end
+
+      # Get all provider configurations from the cascade
+      # Uses ProviderConfigReader which handles project → home → gem discovery
+      def providers
+        @providers ||= filter_active_providers(all_providers)
+      end
+
+      # Get all configured provider configurations before allow-list filtering
+      def all_providers
+        @all_providers ||= begin
+          require "ace/support/models"
+          Ace::Support::Models::Atoms::ProviderConfigReader.read_all
+        end
+      end
+
+      # Get provider config by name
+      def provider(name)
+        normalized = normalize_provider_name(name)
+        _name, config = providers.find do |provider_name, provider_config|
+          normalize_provider_name(provider_name) == normalized ||
+            normalize_provider_name(provider_config["name"]) == normalized
+        end
+        config
+      end
+
+      # Check if provider exists
+      def provider?(name)
+        !provider(name).nil?
+      end
+
+      # Get all provider names
+      def provider_names
+        providers.keys
+      end
+
+      # Reload configuration
+      def reload!
+        @config = Molecules::ConfigLoader.load
+        @all_providers = nil
+        @providers = nil
+        self
+      end
+
+      # Get configuration value by path
+      def get(path)
+        Molecules::ConfigLoader.get(path)
+      end
+
+      # Check if configuration exists
+      def configured?
+        !config.empty?
+      end
+
+      # Returns true when allow-list filtering is active.
+      def provider_filter_applied?
+        !active_provider_allow_list.nil?
+      end
+
+      # Normalized names of all configured providers.
+      def configured_provider_names
+        all_providers.map do |provider_name, provider_config|
+          normalize_provider_name(provider_config["name"] || provider_name)
+        end.uniq.sort
+      end
+
+      # Normalized names of active providers after filtering.
+      def active_provider_names
+        providers.map do |provider_name, provider_config|
+          normalize_provider_name(provider_config["name"] || provider_name)
+        end.uniq.sort
+      end
+
+      # Normalized names that are configured but inactive under active filter.
+      def inactive_provider_names
+        return [] unless provider_filter_applied?
+
+        configured_provider_names - active_provider_names
+      end
+
+      # Returns true when provider exists in config but is excluded by allow-list.
+      def provider_inactive?(name)
+        normalized = normalize_provider_name(name)
+        return false if normalized.empty?
+        return false unless provider_filter_applied?
+
+        configured_provider_names.include?(normalized) && !active_provider_names.include?(normalized)
+      end
+
+      private
+
+      def filter_active_providers(provider_configs)
+        active_allow_list = active_provider_allow_list
+        return provider_configs if active_allow_list.nil?
+
+        filtered = provider_configs.select do |provider_name, provider_config|
+          normalized = normalize_provider_name(provider_config["name"] || provider_name)
+          active_allow_list.include?(normalized)
+        end
+
+        warn_on_unknown_active_entries(provider_configs, active_allow_list)
+        filtered
+      end
+
+      def warn_on_unknown_active_entries(provider_configs, active_allow_list)
+        available = provider_configs.map do |provider_name, provider_config|
+          normalize_provider_name(provider_config["name"] || provider_name)
+        end.uniq
+
+        unknown = active_allow_list - available
+        return if unknown.empty?
+
+        warn "Unknown providers in llm.providers.active: #{unknown.join(", ")} (ignored)"
+      end
+
+      def active_provider_allow_list
+        env_present, env_active = active_provider_allow_list_from_env
+        return env_active if env_present
+
+        normalize_provider_allow_list(get("llm.providers.active"))
+      end
+
+      def active_provider_allow_list_from_env
+        return [false, nil] unless ENV.key?("ACE_LLM_PROVIDERS_ACTIVE")
+
+        raw = ENV["ACE_LLM_PROVIDERS_ACTIVE"].to_s
+        parsed = normalize_provider_allow_list(raw.split(","))
+
+        # Empty env explicitly disables filtering (same as no active list).
+        [true, parsed]
+      end
+
+      def normalize_provider_allow_list(value)
+        normalized = Array(value).map { |entry| normalize_provider_name(entry) }.reject(&:empty?).uniq
+        normalized.empty? ? nil : normalized
+      end
+
+      def normalize_provider_name(name)
+        name.to_s.strip.downcase.gsub(/[-_]/, "")
+      end
+    end
+
+    # Module-level configuration accessor
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure block
+    def self.configure
+      yield(configuration)
+    end
+
+    # Reset configuration
+    def self.reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Get all providers (convenience method)
+    def self.providers
+      configuration.providers
+    end
+
+    # Get provider config by name (convenience method)
+    def self.provider(name)
+      configuration.provider(name)
+    end
+  end
+end

data/lib/ace/llm/models/fallback_config.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Models
+      # FallbackConfig represents fallback configuration settings
+      # This is a model - pure data structure with validation
+      class FallbackConfig
+        attr_reader :enabled, :retry_count, :retry_delay, :providers, :chains, :max_total_timeout
+
+        # Default configuration values
+        DEFAULT_ENABLED = true
+        DEFAULT_RETRY_COUNT = 3
+        DEFAULT_RETRY_DELAY = 1.0
+        DEFAULT_PROVIDERS = [].freeze
+        DEFAULT_CHAINS = {}.freeze
+        DEFAULT_MAX_TOTAL_TIMEOUT = 30.0
+
+        # @param enabled [Boolean] Whether fallback is enabled
+        # @param retry_count [Integer] Number of retries before fallback
+        # @param retry_delay [Float] Initial retry delay in seconds
+        # @param providers [Array<String>] Default fallback provider chain
+        # @param chains [Hash{String => Array<String>}] Per-provider fallback chains
+        # @param max_total_timeout [Float] Maximum total time for all retries and fallbacks
+        def initialize(enabled: DEFAULT_ENABLED,
+          retry_count: DEFAULT_RETRY_COUNT,
+          retry_delay: DEFAULT_RETRY_DELAY,
+          providers: DEFAULT_PROVIDERS,
+          chains: DEFAULT_CHAINS,
+          max_total_timeout: DEFAULT_MAX_TOTAL_TIMEOUT)
+          @enabled = enabled
+          @retry_count = retry_count
+          @retry_delay = retry_delay
+          @providers = providers.freeze
+          @chains = chains
+          @max_total_timeout = max_total_timeout
+
+          validate!
+
+          @chains = normalize_chains(@chains).freeze
+        end
+
+        # Create FallbackConfig from a hash (e.g., from YAML)
+        # @param hash [Hash] Configuration hash
+        # @return [FallbackConfig] New instance
+        def self.from_hash(hash)
+          return new unless hash
+
+          new(
+            enabled: fetch_key(hash, :enabled, DEFAULT_ENABLED),
+            retry_count: fetch_key(hash, :retry_count, DEFAULT_RETRY_COUNT),
+            retry_delay: fetch_key(hash, :retry_delay, DEFAULT_RETRY_DELAY),
+            providers: fetch_key(hash, :providers, DEFAULT_PROVIDERS),
+            chains: fetch_key(hash, :chains, DEFAULT_CHAINS),
+            max_total_timeout: fetch_key(hash, :max_total_timeout, DEFAULT_MAX_TOTAL_TIMEOUT)
+          )
+        end
+
+        # Return fallback providers for a specific primary provider
+        # Uses per-provider chain if configured, otherwise falls back to default providers
+        # @param primary [String] Primary provider name
+        # @return [Array<String>] Ordered fallback provider list
+        def providers_for(primary)
+          key = primary.to_s
+          @chains[key] || @providers
+        end
+
+        # Convert to hash representation
+        # @return [Hash] Configuration as hash
+        def to_h
+          {
+            enabled: @enabled,
+            retry_count: @retry_count,
+            retry_delay: @retry_delay,
+            providers: @providers.dup,
+            chains: @chains.transform_values(&:dup),
+            max_total_timeout: @max_total_timeout
+          }
+        end
+
+        # Check if fallback is enabled
+        # @return [Boolean]
+        def enabled?
+          @enabled == true
+        end
+
+        # Check if fallback is disabled
+        # @return [Boolean]
+        def disabled?
+          !enabled?
+        end
+
+        # Check if there are any fallback providers configured
+        # @return [Boolean]
+        def has_providers?
+          @providers && !@providers.empty?
+        end
+
+        # Merge with another config (other takes precedence)
+        # @param other [FallbackConfig, Hash] Config to merge
+        # @return [FallbackConfig] New merged config
+        def merge(other)
+          other_hash = other.is_a?(Hash) ? other : other.to_h
+
+          merged_chains = @chains.dup
+          if other_hash.key?(:chains)
+            other_hash[:chains].each { |k, v| merged_chains[k.to_s] = v }
+          end
+
+          self.class.new(
+            enabled: other_hash.fetch(:enabled, @enabled),
+            retry_count: other_hash.fetch(:retry_count, @retry_count),
+            retry_delay: other_hash.fetch(:retry_delay, @retry_delay),
+            providers: other_hash.fetch(:providers, @providers),
+            chains: merged_chains,
+            max_total_timeout: other_hash.fetch(:max_total_timeout, @max_total_timeout)
+          )
+        end
+
+        private
+
+        # Helper to fetch key from hash supporting both symbol and string keys
+        # @param hash [Hash] Hash to fetch from
+        # @param key [Symbol] Key to fetch
+        # @param default [Object] Default value if key not found
+        # @return [Object] Value from hash or default
+        def self.fetch_key(hash, key, default)
+          hash.fetch(key, hash.fetch(key.to_s, default))
+        end
+
+        # Normalize chains hash keys to strings
+        # @param chains [Hash] Raw chains hash
+        # @return [Hash{String => Array<String>}] Normalized chains
+        def normalize_chains(chains)
+          chains.each_with_object({}) do |(key, value), result|
+            result[key.to_s] = value
+          end
+        end
+
+        # Validate configuration values
+        # @raise [ConfigurationError] If configuration is invalid
+        def validate!
+          validate_retry_count!
+          validate_retry_delay!
+          validate_providers!
+          validate_chains!
+          validate_max_total_timeout!
+        end
+
+        def validate_retry_count!
+          unless @retry_count.is_a?(Integer) && @retry_count >= 0
+            raise Ace::LLM::ConfigurationError,
+              "retry_count must be a non-negative integer, got: #{@retry_count.inspect}"
+          end
+        end
+
+        def validate_retry_delay!
+          unless @retry_delay.is_a?(Numeric) && @retry_delay > 0
+            raise Ace::LLM::ConfigurationError,
+              "retry_delay must be a positive number, got: #{@retry_delay.inspect}"
+          end
+        end
+
+        def validate_providers!
+          unless @providers.is_a?(Array)
+            raise Ace::LLM::ConfigurationError,
+              "providers must be an array, got: #{@providers.class}"
+          end
+
+          # Check for duplicates
+          duplicates = @providers.group_by { |p| p }.select { |_, v| v.size > 1 }.keys
+          unless duplicates.empty?
+            raise Ace::LLM::ConfigurationError,
+              "providers contains duplicates: #{duplicates.join(", ")}"
+          end
+
+          # Validate each provider string format
+          @providers.each do |provider|
+            unless provider.is_a?(String) && !provider.empty?
+              raise Ace::LLM::ConfigurationError,
+                "each provider must be a non-empty string, got: #{provider.inspect}"
+            end
+          end
+        end
+
+        def validate_chains!
+          unless @chains.is_a?(Hash)
+            raise Ace::LLM::ConfigurationError,
+              "chains must be a hash, got: #{@chains.class}"
+          end
+
+          @chains.each do |key, chain|
+            unless chain.is_a?(Array)
+              raise Ace::LLM::ConfigurationError,
+                "chains value for '#{key}' must be an array, got: #{chain.class}"
+            end
+
+            chain.each do |provider|
+              unless provider.is_a?(String) && !provider.empty?
+                raise Ace::LLM::ConfigurationError,
+                  "each provider in chains['#{key}'] must be a non-empty string, got: #{provider.inspect}"
+              end
+            end
+          end
+        end
+
+        def validate_max_total_timeout!
+          unless @max_total_timeout.is_a?(Numeric) && @max_total_timeout > 0
+            raise Ace::LLM::ConfigurationError,
+              "max_total_timeout must be a positive number, got: #{@max_total_timeout.inspect}"
+          end
+        end
+      end
+    end
+  end
+end