ace-llm 0.30.2 → 0.36.3

data/lib/ace/llm/molecules/fallback_orchestrator.rb

@@ -2,6 +2,7 @@
 
 require_relative "../atoms/error_classifier"
 require_relative "../models/fallback_config"
+require_relative "provider_model_parser"
 
 module Ace
   module LLM
@@ -35,10 +36,12 @@ module Ace
           @visited_providers.clear
 
           # If fallback disabled, just execute with primary
-          return yield get_client(primary_provider, registry) if @config.disabled?
+          return yield(get_client(primary_provider, registry), primary_provider) if @config.disabled?
 
           # Try primary provider with retries
-          result = try_provider_with_retry(primary_provider, registry) { |client| yield client }
+          result = try_provider_with_retry(primary_provider, registry) do |client, provider_name|
+            yield client, provider_name
+          end
           return result if result
 
           # Try fallback providers in order (per-provider chain or default)
@@ -54,7 +57,9 @@ module Ace
 
             report_status("ℹ Trying fallback provider #{fallback_provider}...")
 
-            result = try_provider_with_retry(fallback_provider, registry) { |client| yield client }
+            result = try_provider_with_retry(fallback_provider, registry) do |client, provider_name|
+              yield client, provider_name
+            end
             return result if result
           end
 
@@ -77,7 +82,7 @@ module Ace
 
           loop do
             client = get_client(provider_name, registry)
-            return yield client
+            return yield client, provider_name
           rescue => error
             last_error = error
 
@@ -145,10 +150,11 @@ module Ace
           opts = {}
           opts[:timeout] = @timeout if @timeout
 
-          # Parse provider:model format if present
-          if provider_name.include?(":")
-            provider, model = provider_name.split(":", 2)
-            registry.get_client(provider, model: model, **opts)
+          parser = ProviderModelParser.new(registry: registry)
+          parsed = parser.parse(provider_name.to_s)
+
+          if parsed.valid?
+            registry.get_client(parsed.provider, model: parsed.model, **opts)
           else
             registry.get_client(provider_name, **opts)
           end

data/lib/ace/llm/molecules/interactive_command_builder.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Molecules
+      class InteractiveCommandBuilder
+        def initialize(registry: ClientRegistry.new)
+          @registry = registry
+          @parser = ProviderModelParser.new(registry: registry)
+        end
+
+        def build(provider_model:, prompt:, model: nil, preset: nil, system: nil, cli_args: nil,
+          system_append: nil, sandbox: nil, working_dir: nil, subprocess_env: nil)
+          parse_result = @parser.parse(provider_model)
+          raise Error, parse_result.error unless parse_result.valid?
+
+          resolved_preset = QueryInterface.send(:resolve_preset_name, parse_result.preset, preset)
+          final_model = model || parse_result.model
+          if final_model.nil? || final_model.empty?
+            raise Error, "No model specified and no default available for #{parse_result.provider}"
+          end
+
+          final_prompt = prompt.to_s
+          raise Error, "No prompt specified. Use positional prompt or --prompt." if final_prompt.empty?
+
+        generation_opts = QueryInterface.send(
+            :build_generation_opts,
+            provider: parse_result.provider,
+            preset: resolved_preset,
+            thinking_level: parse_result.thinking_level,
+            temperature: nil,
+            max_tokens: nil,
+            system_file: nil,
+            prompt_file: nil,
+            cli_args: cli_args,
+            system_append: system_append,
+            sandbox: sandbox,
+            working_dir: working_dir,
+            subprocess_env: subprocess_env,
+            subprocess_command_prefix: nil,
+            last_message_file: nil
+          )
+
+          client = @registry.get_client(parse_result.provider, model: final_model)
+          unless client.respond_to?(:interactive_supported?) && client.interactive_supported?
+            raise Error, "Provider '#{parse_result.provider}' does not support interactive mode"
+          end
+
+          messages = []
+          messages << {role: "system", content: system} if system && !system.empty?
+          messages << {role: "user", content: final_prompt}
+
+          invocation = client.build_interactive_invocation(messages, **generation_opts)
+          invocation.merge(
+            provider: parse_result.provider,
+            model: final_model,
+            preset: resolved_preset,
+            thinking_level: parse_result.thinking_level
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/molecules/provider_model_parser.rb

@@ -2,6 +2,7 @@
 
 require_relative "client_registry"
 require_relative "llm_alias_resolver"
+require_relative "role_resolver"
 
 module Ace
   module LLM
@@ -12,7 +13,7 @@ module Ace
         THINKING_LEVELS = %w[low medium high xhigh].freeze
 
         # Result object for parsed provider:model combinations.
-        ParseResult = Struct.new(:provider, :model, :preset, :thinking_level, :valid, :error, :original_input) do
+        ParseResult = Struct.new(:provider, :model, :preset, :thinking_level, :valid, :error, :original_input, :role_fallbacks) do
           def valid?
             valid
           end
@@ -33,6 +34,7 @@ module Ace
         def initialize(alias_resolver: nil, registry: nil)
           @alias_resolver = alias_resolver || LlmAliasResolver.new
           @registry = registry || ClientRegistry.new
+          @role_resolver = RoleResolver.new(registry: @registry)
         end
 
         # Parse a provider:model string or alias.
@@ -40,6 +42,70 @@ module Ace
           return create_error_result(input, "Input cannot be nil or empty") if input.nil? || input.strip.empty?
 
           original_input = input.strip
+          if role_reference?(original_input)
+            return parse_role_reference(original_input)
+          end
+
+          parse_standard_target(original_input)
+        rescue Ace::LLM::ConfigurationError => e
+          create_error_result(original_input, e.message)
+        end
+
+        def supported_providers
+          @registry.available_providers
+        end
+
+        def default_model_for(provider)
+          models = @registry.models_for_provider(provider)
+          models&.first
+        end
+
+        def dynamic_aliases
+          return {} unless @alias_resolver
+
+          global = @alias_resolver.available_aliases[:global] || {}
+          providers = @alias_resolver.available_aliases[:providers] || {}
+
+          flattened = {}
+          providers.each do |provider, aliases|
+            aliases.each do |alias_name, model|
+              flattened["#{provider}:#{alias_name}"] = "#{provider}:#{model}"
+            end
+          end
+
+          global.merge(flattened)
+        end
+
+        private
+
+        def parse_role_reference(original_input)
+          role_target, caller_preset, preset_error = split_preset_suffix(original_input)
+          return create_error_result(original_input, preset_error) if preset_error
+
+          role_value = role_target.sub(/\Arole:/, "")
+          role_name, caller_thinking, thinking_error = split_thinking_suffix(role_value)
+          return create_error_result(original_input, thinking_error) if thinking_error
+          return create_error_result(original_input, "Invalid target: role name cannot be empty") if role_name.to_s.strip.empty?
+
+          resolved_selector, remaining_candidates = @role_resolver.resolve_with_candidates(role_name)
+          resolved_parse = parse_standard_target(resolved_selector)
+          return resolved_parse if resolved_parse.invalid?
+
+          role_fallbacks = build_role_fallbacks(remaining_candidates, caller_preset, caller_thinking)
+
+          ParseResult.new(
+            resolved_parse.provider,
+            resolved_parse.model,
+            caller_preset || resolved_parse.preset,
+            caller_thinking || resolved_parse.thinking_level,
+            true,
+            nil,
+            original_input,
+            role_fallbacks
+          )
+        end
+
+        def parse_standard_target(original_input)
           provider_target, preset_name, preset_error = split_preset_suffix(original_input)
           return create_error_result(original_input, preset_error) if preset_error
 
@@ -83,32 +149,25 @@ module Ace
           ParseResult.new(resolved_provider, model, preset_name, thinking_level, true, nil, original_input)
         end
 
-        def supported_providers
-          @registry.available_providers
-        end
+        def build_role_fallbacks(candidates, caller_preset, caller_thinking)
+          return nil if candidates.nil? || candidates.empty?
 
-        def default_model_for(provider)
-          models = @registry.models_for_provider(provider)
-          models&.first
-        end
+          candidates.map do |candidate|
+            parsed = parse_standard_target(candidate)
+            next nil if parsed.invalid?
 
-        def dynamic_aliases
-          return {} unless @alias_resolver
-
-          global = @alias_resolver.available_aliases[:global] || {}
-          providers = @alias_resolver.available_aliases[:providers] || {}
-
-          flattened = {}
-          providers.each do |provider, aliases|
-            aliases.each do |alias_name, model|
-              flattened["#{provider}:#{alias_name}"] = "#{provider}:#{model}"
-            end
-          end
-
-          global.merge(flattened)
+            preset = caller_preset || parsed.preset
+            thinking = caller_thinking || parsed.thinking_level
+            base = "#{parsed.provider}:#{parsed.model}"
+            base += ":#{thinking}" if thinking
+            base += "@#{preset}" if preset
+            base
+          end.compact
         end
 
-        private
+        def role_reference?(input)
+          input.to_s.strip.start_with?("role:")
+        end
 
         def normalize_provider(provider)
           provider.strip.downcase.gsub(/[-_]/, "")
@@ -154,11 +213,13 @@ module Ace
             Provider '#{provider}' is inactive. It exists but is not in llm.providers.active.
             To enable it, add '#{provider}' to llm.providers.active in your config.
             Active providers: #{active_display}
+            Run `ace-llm --list-providers` for available providers and configuration guidance.
           MSG
         end
 
         def unknown_provider_error(provider, supported_providers)
-          "Unknown provider: #{provider}. Supported providers: #{supported_providers.join(", ")}"
+          "Unknown provider: #{provider}. Supported providers: #{supported_providers.join(", ")}. " \
+            "Run `ace-llm --list-providers` for available providers and configuration guidance."
         end
 
         def inactive_provider?(provider)

data/lib/ace/llm/molecules/role_resolver.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "../models/role_config"
+require_relative "client_registry"
+
+module Ace
+  module LLM
+    module Molecules
+      # RoleResolver maps role names to an available concrete selector.
+      class RoleResolver
+        THINKING_LEVELS = %w[low medium high xhigh].freeze
+
+        def initialize(registry: nil, configuration: nil)
+          @registry = registry || ClientRegistry.new
+          @configuration = configuration || Ace::LLM.configuration
+        end
+
+        # Resolve role name to first available candidate selector string.
+        # @param role_name [String]
+        # @return [String]
+        def resolve(role_name)
+          selector, _remaining = resolve_with_candidates(role_name)
+          selector
+        end
+
+        # Resolve role name and return both the selected candidate and remaining candidates.
+        # Remaining candidates can be used as a fallback chain at query time.
+        # @param role_name [String]
+        # @return [Array(String, Array<String>)] [resolved_selector, remaining_candidates]
+        def resolve_with_candidates(role_name)
+          normalized_role_name = role_name.to_s.strip
+          if normalized_role_name.empty?
+            raise Ace::LLM::ConfigurationError, "Invalid target: role name cannot be empty"
+          end
+
+          role_config = Models::RoleConfig.from_hash(@configuration.get("llm.roles"))
+          candidates = role_config.candidates_for(normalized_role_name)
+          unless candidates
+            available = role_config.role_names
+            available_display = available.empty? ? "(none)" : available.join(", ")
+            raise Ace::LLM::ConfigurationError,
+              "Unknown role: #{normalized_role_name}. Defined roles: #{available_display}"
+          end
+
+          candidates.each_with_index do |candidate, index|
+            if candidate_available?(candidate)
+              remaining = candidates[(index + 1)..]
+              return [candidate, remaining]
+            end
+          end
+
+          raise Ace::LLM::ConfigurationError,
+            "No available models for role '#{normalized_role_name}'. Tried: #{candidates.join(", ")}"
+        end
+
+        private
+
+        def candidate_available?(candidate)
+          provider = provider_for_candidate(candidate)
+          return false if provider.nil? || provider.empty?
+          return false if @configuration.provider_inactive?(provider)
+          return false unless @registry.provider_available?(provider)
+
+          true
+        end
+
+        def provider_for_candidate(candidate)
+          candidate_target, _preset, _preset_error = split_preset_suffix(candidate.to_s)
+          model_target, _thinking, _thinking_error = split_thinking_suffix(candidate_target)
+          resolved = @registry.resolve_alias(model_target)
+          provider = resolved.to_s.split(":", 2).first
+          normalize_provider(provider)
+        end
+
+        def normalize_provider(name)
+          name.to_s.strip.downcase.gsub(/[-_]/, "")
+        end
+
+        def split_preset_suffix(input)
+          provider_target, preset_name = input.split("@", 2)
+          return [input, nil, nil] unless input.include?("@")
+
+          [provider_target.to_s.strip, preset_name.to_s.strip, nil]
+        end
+
+        def split_thinking_suffix(model_input)
+          trimmed = model_input.to_s.strip
+          base, separator, suffix = trimmed.rpartition(":")
+          return [trimmed, nil, nil] if separator.empty?
+
+          normalized_level = suffix.to_s.strip.downcase
+          return [trimmed, nil, nil] unless THINKING_LEVELS.include?(normalized_level)
+          return [trimmed, nil, nil] if base.to_s.strip.empty?
+
+          [base.strip, normalized_level, nil]
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/query_interface.rb

@@ -35,6 +35,7 @@ module Ace
         sandbox: nil,
         working_dir: nil,
         subprocess_env: nil,
+        subprocess_command_prefix: nil,
         last_message_file: nil)
         registry = Molecules::ClientRegistry.new
         parser = Molecules::ProviderModelParser.new(registry: registry)
@@ -43,12 +44,6 @@ module Ace
         raise Error, parse_result.error unless parse_result.valid?
 
         resolved_preset = resolve_preset_name(parse_result.preset, preset)
-        execution_overrides = load_execution_overrides(
-          provider: parse_result.provider,
-          preset: resolved_preset,
-          thinking_level: parse_result.thinking_level
-        )
-
         final_model = model || parse_result.model
         if final_model.nil? || final_model.empty?
           raise Error, "No model specified and no default available for #{parse_result.provider}"
@@ -63,38 +58,41 @@ module Ace
         messages << {role: "system", content: system} if system && !system.empty?
         messages << {role: "user", content: final_prompt}
 
-        generation_opts = {}
-        resolved_temperature = first_non_nil(temperature, execution_overrides["temperature"])
-        resolved_max_tokens = first_non_nil(max_tokens, execution_overrides["max_tokens"])
-        resolved_cli_args = first_non_nil(cli_args, execution_overrides["cli_args"])
-        resolved_system_append = first_non_empty(system_append, execution_overrides["system_append"])
-        resolved_sandbox = first_non_nil(sandbox, execution_overrides["sandbox"])
-        resolved_working_dir = first_non_nil(working_dir, execution_overrides["working_dir"])
-        resolved_subprocess_env = merge_hash_values(execution_overrides["subprocess_env"], subprocess_env)
-
-        generation_opts[:temperature] = resolved_temperature unless resolved_temperature.nil?
-        generation_opts[:max_tokens] = resolved_max_tokens unless resolved_max_tokens.nil?
-        generation_opts[:system_file] = system_file if system_file
-        generation_opts[:prompt_file] = prompt_file if prompt_file
-        generation_opts[:cli_args] = resolved_cli_args unless blank_value?(resolved_cli_args)
-        generation_opts[:system_append] = resolved_system_append unless blank_value?(resolved_system_append)
-        generation_opts[:sandbox] = resolved_sandbox if resolved_sandbox
-        generation_opts[:working_dir] = resolved_working_dir unless blank_value?(resolved_working_dir)
-        generation_opts[:subprocess_env] = resolved_subprocess_env unless resolved_subprocess_env.nil?
-        generation_opts[:last_message_file] = last_message_file if last_message_file
+        generation_opts = build_generation_opts(
+          provider: parse_result.provider,
+          preset: resolved_preset,
+          thinking_level: parse_result.thinking_level,
+          temperature: temperature,
+          max_tokens: max_tokens,
+          system_file: system_file,
+          prompt_file: prompt_file,
+          cli_args: cli_args,
+          system_append: system_append,
+          sandbox: sandbox,
+          working_dir: working_dir,
+          subprocess_env: subprocess_env,
+          subprocess_command_prefix: subprocess_command_prefix,
+          last_message_file: last_message_file
+        )
+        execution_overrides = load_execution_overrides(
+          provider: parse_result.provider,
+          preset: resolved_preset,
+          thinking_level: parse_result.thinking_level
+        )
 
         if debug
           warn "Provider: #{parse_result.provider}"
           warn "Model: #{final_model}"
           warn "Preset: #{resolved_preset}" if resolved_preset
           warn "Thinking level: #{parse_result.thinking_level}" if parse_result.thinking_level
-          warn "Temperature: #{resolved_temperature}" unless resolved_temperature.nil?
-          warn "Max tokens: #{resolved_max_tokens}" unless resolved_max_tokens.nil?
+          warn "Temperature: #{generation_opts[:temperature]}" unless generation_opts[:temperature].nil?
+          warn "Max tokens: #{generation_opts[:max_tokens]}" unless generation_opts[:max_tokens].nil?
         end
 
         fallback_config = load_fallback_config(fallback, fallback_providers, parser: parser)
         timeout_value = first_non_nil(timeout, execution_overrides["timeout"], Molecules::ConfigLoader.get("llm.timeout"), 120)
         resolved_timeout = normalize_timeout(timeout_value)
+        parser_for_options = Molecules::ProviderModelParser.new(registry: registry)
 
         response = execute_with_fallback(
           provider: parse_result.provider,
@@ -104,7 +102,40 @@ module Ace
           registry: registry,
           fallback_config: fallback_config,
           timeout: resolved_timeout,
-          debug: debug
+          debug: debug,
+          role_fallbacks: parse_result.role_fallbacks,
+          preset: resolved_preset,
+          thinking_level: parse_result.thinking_level,
+          option_builder: lambda { |target_selector|
+            parsed_target = parser_for_options.parse(target_selector.to_s)
+            target_provider = parsed_target.valid? ? parsed_target.provider : parse_result.provider
+            target_preset = if parsed_target.valid? && parsed_target.preset
+              parsed_target.preset
+            else
+              resolved_preset
+            end
+            target_thinking = if parsed_target.valid?
+              parsed_target.thinking_level
+            else
+              parse_result.thinking_level
+            end
+            build_generation_opts(
+              provider: target_provider,
+              preset: target_preset,
+              thinking_level: target_thinking,
+              temperature: temperature,
+              max_tokens: max_tokens,
+              system_file: system_file,
+              prompt_file: prompt_file,
+              cli_args: cli_args,
+              system_append: system_append,
+              sandbox: sandbox,
+              working_dir: working_dir,
+              subprocess_env: subprocess_env,
+              subprocess_command_prefix: subprocess_command_prefix,
+              last_message_file: last_message_file
+            )
+          }
         )
 
         text_content = extract_text_content(response)
@@ -173,6 +204,43 @@ module Ace
       end
       private_class_method :load_execution_overrides
 
+      def self.build_generation_opts(provider:, preset:, thinking_level:, temperature:, max_tokens:, system_file:,
+        prompt_file:, cli_args:, system_append:, sandbox:, working_dir:, subprocess_env:, subprocess_command_prefix:,
+        last_message_file:)
+        execution_overrides = load_execution_overrides(
+          provider: provider,
+          preset: preset,
+          thinking_level: thinking_level
+        )
+
+        generation_opts = {}
+        resolved_temperature = first_non_nil(temperature, execution_overrides["temperature"])
+        resolved_max_tokens = first_non_nil(max_tokens, execution_overrides["max_tokens"])
+        resolved_cli_args = append_cli_args(execution_overrides["cli_args"], cli_args)
+        resolved_system_append = first_non_empty(system_append, execution_overrides["system_append"])
+        resolved_sandbox = first_non_nil(sandbox, execution_overrides["sandbox"])
+        resolved_working_dir = first_non_nil(working_dir, execution_overrides["working_dir"])
+        resolved_subprocess_env = merge_hash_values(execution_overrides["subprocess_env"], subprocess_env)
+        resolved_subprocess_command_prefix = first_non_nil(
+          subprocess_command_prefix,
+          execution_overrides["subprocess_command_prefix"]
+        )
+
+        generation_opts[:temperature] = resolved_temperature unless resolved_temperature.nil?
+        generation_opts[:max_tokens] = resolved_max_tokens unless resolved_max_tokens.nil?
+        generation_opts[:system_file] = system_file if system_file
+        generation_opts[:prompt_file] = prompt_file if prompt_file
+        generation_opts[:cli_args] = resolved_cli_args unless blank_value?(resolved_cli_args)
+        generation_opts[:system_append] = resolved_system_append unless blank_value?(resolved_system_append)
+        generation_opts[:sandbox] = resolved_sandbox if resolved_sandbox
+        generation_opts[:working_dir] = resolved_working_dir unless blank_value?(resolved_working_dir)
+        generation_opts[:subprocess_env] = resolved_subprocess_env unless resolved_subprocess_env.nil?
+        generation_opts[:subprocess_command_prefix] = resolved_subprocess_command_prefix unless blank_value?(resolved_subprocess_command_prefix)
+        generation_opts[:last_message_file] = last_message_file if last_message_file
+        generation_opts
+      end
+      private_class_method :build_generation_opts
+
       def self.merge_execution_overrides(base, overlay)
         left = base.respond_to?(:to_h) ? deep_stringify_keys(base.to_h) : deep_stringify_keys(base || {})
         right = overlay.respond_to?(:to_h) ? deep_stringify_keys(overlay.to_h) : deep_stringify_keys(overlay || {})
@@ -290,12 +358,22 @@ module Ace
       end
 
       def self.execute_with_fallback(provider:, model:, messages:, generation_opts:,
-        registry:, fallback_config:, timeout:, debug:)
+        registry:, fallback_config:, timeout:, debug:, role_fallbacks: nil, preset: nil, thinking_level: nil, option_builder:)
         if fallback_config.disabled?
           client = registry.get_client(provider, model: model, timeout: timeout)
           return client.generate(messages, **generation_opts)
         end
 
+        primary_provider_string = model ? "#{provider}:#{model}" : provider
+
+        # Inject remaining role candidates ahead of the global fallback chain
+        normalized_role_fallbacks = normalize_fallback_providers(role_fallbacks, Molecules::ProviderModelParser.new(registry: registry))
+        if role_fallbacks&.any?
+          existing_chain = fallback_config.providers_for(primary_provider_string)
+          merged_chain = normalized_role_fallbacks + (existing_chain - normalized_role_fallbacks)
+          fallback_config = fallback_config.merge(chains: {primary_provider_string => merged_chain})
+        end
+
         status_callback = ->(msg) { warn msg }
 
         orchestrator = Molecules::FallbackOrchestrator.new(
@@ -304,10 +382,13 @@ module Ace
           timeout: timeout
         )
 
-        primary_provider_string = model ? "#{provider}:#{model}" : provider
-
-        orchestrator.execute(primary_provider: primary_provider_string, registry: registry) do |client|
-          client.generate(messages, **generation_opts)
+        orchestrator.execute(primary_provider: primary_provider_string, registry: registry) do |client, target_selector|
+          opts = if target_selector.to_s == primary_provider_string
+            generation_opts
+          else
+            option_builder.call(target_selector)
+          end
+          client.generate(messages, **opts)
         end
       end
 
@@ -372,7 +453,7 @@ module Ace
 
           parse_result = parser.parse(provider)
           canonical_provider = if parse_result.valid?
-            "#{parse_result.provider}:#{parse_result.model}"
+            parse_result.to_s
           else
             provider
           end

data/lib/ace/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module LLM
-    VERSION = '0.30.2'
+    VERSION = '0.36.3'
   end
 end

data/lib/ace/llm.rb

@@ -19,13 +19,16 @@ require_relative "llm/atoms/xdg_directory_resolver"
 require_relative "llm/atoms/error_classifier"
 
 require_relative "llm/models/fallback_config"
+require_relative "llm/models/role_config"
 
 require_relative "llm/molecules/file_io_handler"
 require_relative "llm/molecules/llm_alias_resolver"
+require_relative "llm/molecules/role_resolver"
 require_relative "llm/molecules/provider_model_parser"
 require_relative "llm/molecules/format_handlers"
 require_relative "llm/molecules/client_registry"
 require_relative "llm/molecules/fallback_orchestrator"
+require_relative "llm/molecules/interactive_command_builder"
 
 require_relative "llm/query_interface"