ace-llm 0.30.2 → 0.32.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2eb129fd759362beb79ce68322986ba1378a4ba7a0fb2b9cc2964941bda4fbb9
-  data.tar.gz: 10383bb45c7f012164d6983da558ec7fd2d5fabbbc91faa8589c078c2aef60eb
+  metadata.gz: 9d2199db9c575bab6a4e80d9537115bbd643cdcf3ae9925b7af6469ec9fd0b0e
+  data.tar.gz: e20d96efca816db66196dd4c907f9814ab8d7c0cb759e33d1d11cfb5f98e6326
 SHA512:
-  metadata.gz: 76fb444f51fbdcd4b27cbde5ac785ca2bceffe4f350f6946b8b07aa89fe1bdfed7457cb1639a8c33b82fcc3446c05bcdd0a9d7626edab0a84ed16ef357ef4a8c
-  data.tar.gz: 7e0fc445cf15a599c1d60ffcf4483abd199b9233b40b1ae1cbeed195d3ea8f85a1d1d8cf4a664889f84e9e777a786335d901aa32103c0ec1dd9e8ee3a81c6b03
+  metadata.gz: 72d45697b419523ec93028ff004cc840c641336dcfdd985d13a18f4468ad0d1b2abede096887309c02c39bbbd10f6e0909afb7c92ac7d379b805ad52ef30560e
+  data.tar.gz: a92cce87e5212b2d8c201aa04265e2255e6f6d7022315622f53c70f2c24cfe704d890d07379ae2b86fb4889e6fb66f30e1b3aa025b77b28ae0e756a620a1290a

data/.ace-defaults/llm/config.yml

@@ -25,6 +25,99 @@ llm:
     chains: {}
     providers: []
 
+  # Named model roles for indirection across consumer configs.
+  # Each role lists candidates in priority order; RoleResolver returns
+  # the first available one. Every role covers codex, claude, and gemini
+  # so resolution succeeds even when a provider is unconfigured.
+  # Override in .ace/llm/config.yml for project-specific role assignments.
+  roles:
+    # --- Reusable candidate lists ---
+    _utility-lite: &utility-lite
+      - google:lite
+      - codex:mini
+      - claude:haiku
+    _assign-worker: &assign-worker
+      - codex:codex@yolo
+      - claude:sonnet@yolo
+      - gemini:pro-latest@yolo
+
+    # --- Diagnostic ---
+    doctor:
+      - gemini:flash-latest@yolo
+      - claude:haiku@yolo
+      - codex:mini@yolo
+
+    # --- Planning ---
+    planner:
+      - codex:gpt@ro
+      - claude:sonnet@ro
+      - gemini:pro-latest@ro
+
+    # --- Review (single-model and synthesis) ---
+    review-default:
+      - codex:codex@ro
+      - claude:sonnet@ro
+      - gemini:pro-latest@ro
+    review-synthesizer:
+      - codex:gpt@ro
+      - claude:sonnet@ro
+      - gemini:pro-latest@ro
+
+    # --- Review (provider-specific, for parallel multi-model review) ---
+    review-claude:
+      - claude:opus@ro
+      - codex:gpt@ro
+      - gemini:pro-latest@ro
+    review-codex:
+      - codex:gpt@ro
+      - claude:sonnet@ro
+      - gemini:pro-latest@ro
+    review-gemini:
+      - gemini:pro-latest@ro
+      - claude:sonnet@ro
+      - codex:gpt@ro
+
+    # --- Assignment ---
+    assign-executor: *assign-worker
+    assign-engineer: *assign-worker
+    assign-orchestrator:
+      - claude:sonnet
+      - codex:gpt
+      - gemini:pro-latest
+
+    # --- E2E testing ---
+    e2e-executor:
+      - claude:haiku@yolo
+      - codex:mini@yolo
+      - gemini:flash-latest@yolo
+    e2e-reporter:
+      - claude:haiku
+      - codex:mini
+      - gemini:flash-latest
+
+    # --- Utility ---
+    prompt-enhance: *utility-lite
+    commit:
+      - codex:mini
+      - claude:haiku
+      - gemini:flash-latest
+    docs-analysis: *utility-lite
+    idea-enhance:
+      - gemini:flash-latest
+      - codex:mini
+      - claude:haiku
+    compressor: *utility-lite
+
+    # --- Simulation ---
+    sim-primary:
+      - google:flash-preview
+      - claude:haiku
+      - codex:mini
+    sim-synthesis:
+      - claude:haiku
+      - codex:mini
+      - gemini:flash-latest
+
   # Default context limit for unknown models (in tokens)
   # Provider-specific limits are defined in providers/*.yml
   context_limit:

data/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.32.1] - 2026-04-01
+
+### Fixed
+- Made role-based fallback chain-aware so remaining role candidates are tried before global fallback providers on query failure.
+
+## [0.32.0] - 2026-03-31
+
+### Added
+- Shipped canonical role catalog with gem defaults so `role:*` selectors resolve without project-level config.
+
+### Fixed
+- Added type guard in `RoleConfig.from_hash` to raise `ConfigurationError` for non-Hash role config input.
+
+## [0.31.3] - 2026-03-31
+
+### Technical
+- Clarified provider fallback environment-key coupling in `ClientRegistry` to align credential resolution guidance with current setup behavior.
+
+## [0.31.2] - 2026-03-30
+
+### Technical
+- Removed the unused `api_key_present?` helper from `ClientRegistry` to keep provider credential routing focused on active call sites.
+
+## [0.31.1] - 2026-03-30
+
+### Technical
+- Added regression coverage for Google provider credential fallback when only `GOOGLE_API_KEY` is configured.
+
+## [0.31.0] - 2026-03-29
+
+### Added
+- Extended `ace-llm --list-providers` output with provider credential setup hints, including required environment variable names.
+- Added named model-role resolution via `role:<name>` selectors in `ProviderModelParser`, including strict runtime availability checks across candidate providers.
+
+### Changed
+- Made provider setup failures actionable by surfacing supported provider lists, ignored-provider guidance, and an explicit recovery path via `ace-llm --list-providers`.
+- Updated onboarding and usage documentation to align runtime errors with provider discovery and environment-variable setup guidance.
+- Added `llm.roles` configuration support and a dedicated `RoleResolver`/`RoleConfig` pipeline so callers can centralize provider-model selection and keep caller `:thinking` and `@preset` overrides authoritative.
+
+### Technical
+- Added focused coverage for role config validation, resolver behavior, and parser integration in `test/models/role_config_test.rb`, `test/molecules/role_resolver_test.rb`, and `test/molecules/provider_model_parser_test.rb`.
+
 ## [0.30.2] - 2026-03-29
 
 ### Technical

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

@@ -215,17 +215,27 @@ module Ace
 
             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"
+              credential_status = if provider[:api_key_required]
+                provider[:api_key_present] ? "Credentials configured" : "Credentials required"
               else
-                "No API key needed"
+                "No credentials required"
               end
 
               models = provider[:models] || []
               model_count = models.empty? ? "" : " \u00b7 #{models.length} models"
-              puts "#{status} #{provider[:name]}#{model_count} (#{api_status})"
+              puts "#{status} #{provider[:name]}#{model_count} (#{credential_status})"
 
               print_wrapped_list(models, indent: "  ") unless models.empty?
+              env_keys = provider[:credential_env_keys] || []
+              if provider[:api_key_required]
+                if env_keys.empty?
+                  puts "  Setup hint: credentials are required for this provider."
+                else
+                  puts "  Setup hint: set #{env_keys.join(' or ')}"
+                end
+              else
+                puts "  Setup hint: no credential environment variable required."
+              end
               puts "  Gem required: #{provider[:gem]}" unless provider[:available]
               puts ""
             end

data/lib/ace/llm/configuration.rb

@@ -59,6 +59,11 @@ module Ace
         Molecules::ConfigLoader.get(path)
       end
 
+      # Get configured role map (llm.roles) from config cascade.
+      def roles
+        get("llm.roles") || {}
+      end
+
       # Check if configuration exists
       def configured?
         !config.empty?
@@ -122,7 +127,10 @@ module Ace
         unknown = active_allow_list - available
         return if unknown.empty?
 
-        warn "Unknown providers in llm.providers.active: #{unknown.join(", ")} (ignored)"
+        warn "Unknown providers in llm.providers.active: #{unknown.join(", ")} (ignored). " \
+          "These names do not match configured providers and were skipped. " \
+          "Update llm.providers.active to use supported provider names, or run " \
+          "`ace-llm --list-providers` for available providers and configuration guidance."
       end
 
       def active_provider_allow_list

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Models
+      # RoleConfig represents llm.roles configuration with validation.
+      class RoleConfig
+        attr_reader :roles
+
+        def initialize(roles: {})
+          @roles = normalize_roles(roles).freeze
+          validate!
+        end
+
+        def self.from_hash(hash)
+          return new unless hash
+
+          unless hash.is_a?(Hash)
+            raise Ace::LLM::ConfigurationError, "llm.roles config must be a Hash, got: #{hash.class}"
+          end
+
+          roles = hash.fetch(:roles, hash.fetch("roles", hash))
+          new(roles: roles)
+        end
+
+        def role_names
+          @roles.keys.sort
+        end
+
+        def candidates_for(role_name)
+          normalized = normalize_role_name(role_name)
+          @roles[normalized]
+        end
+
+        private
+
+        def normalize_roles(roles)
+          return {} if roles.nil?
+
+          unless roles.is_a?(Hash)
+            raise Ace::LLM::ConfigurationError, "llm.roles must be a hash, got: #{roles.class}"
+          end
+
+          roles.each_with_object({}) do |(name, candidates), acc|
+            normalized_name = normalize_role_name(name)
+            acc[normalized_name] = Array(candidates).map { |candidate| candidate.to_s.strip }
+          end
+        end
+
+        def normalize_role_name(name)
+          name.to_s.strip
+        end
+
+        def validate!
+          @roles.each do |name, candidates|
+            if name.empty?
+              raise Ace::LLM::ConfigurationError, "role name cannot be empty"
+            end
+
+            unless candidates.is_a?(Array) && !candidates.empty?
+              raise Ace::LLM::ConfigurationError, "role '#{name}' must define at least one candidate"
+            end
+
+            candidates.each do |candidate|
+              if candidate.empty?
+                raise Ace::LLM::ConfigurationError, "role '#{name}' contains an empty candidate"
+              end
+
+              if candidate.start_with?("role:")
+                raise Ace::LLM::ConfigurationError,
+                  "role '#{name}' cannot reference nested role candidate '#{candidate}'"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -112,17 +112,39 @@ module Ace
         # @return [Hash] Provider status information
         def list_providers_with_status
           @providers.map do |name, config|
+            credential = credential_status(config, name)
             {
               name: name,
               models: config["models"] || [],
               gem: config["gem"],
               available: provider_available?(name),
-              api_key_required: config.dig("api_key", "required") || false,
-              api_key_present: api_key_present?(config["api_key"])
+              api_key_required: credential[:required],
+              api_key_present: credential[:present],
+              credential_env_keys: credential[:env_keys]
             }
           end
         end
 
+        # Whether provider config marks API key as required.
+        # @param provider_name [String]
+        # @return [Boolean]
+        def provider_api_key_required?(provider_name)
+          provider = get_provider(provider_name)
+          return false unless provider
+
+          provider.dig("api_key", "required") || false
+        end
+
+        # Whether provider has a present API key according to its api_key config.
+        # @param provider_name [String]
+        # @return [Boolean]
+        def provider_api_key_present?(provider_name)
+          provider = get_provider(provider_name)
+          return false unless provider
+
+          api_key_present?(provider["api_key"])
+        end
+
         # Reload all configurations
         def reload!
           @providers.clear
@@ -299,14 +321,30 @@ module Ace
           end
         end
 
-        # Check if API key is present
-        # @param api_key_config [Hash, String, nil] API key configuration
-        # @return [Boolean] True if API key is configured and present
-        def api_key_present?(api_key_config)
-          return false if api_key_config.nil?
+        # Build normalized credential status for provider output.
+        # @param provider_config [Hash] provider configuration hash
+        # @param provider_name [String] normalized provider name
+        # @return [Hash] credential status
+        def credential_status(provider_config, provider_name)
+          env_keys = extract_credential_env_keys(provider_config, provider_name)
+          explicit_required = provider_config.dig("api_key", "required")
+          required = explicit_required.nil? ? !env_keys.empty? : explicit_required
+
+          present = if provider_config["api_key"].is_a?(String) && !provider_config["api_key"].empty?
+            true
+          elsif provider_config["api_key"].is_a?(Hash) && provider_config["api_key"]["value"]
+            !provider_config["api_key"]["value"].to_s.empty?
+          elsif provider_config["api_key"].is_a?(Hash) && provider_config["api_key"]["env"]
+            !ENV[provider_config["api_key"]["env"]].to_s.empty?
+          else
+            env_keys.any? { |key| !ENV[key].to_s.empty? }
+          end
 
-          key = resolve_api_key(api_key_config)
-          !key.nil? && !key.empty?
+          {
+            required: required,
+            present: present,
+            env_keys: env_keys
+          }
         end
 
         # Build alias maps from provider configurations
@@ -330,6 +368,47 @@ module Ace
             end
           end
         end
+
+        def extract_credential_env_keys(provider_config, provider_name)
+          env_keys = []
+
+          api_key_env = provider_config.dig("api_key", "env")
+          env_keys << api_key_env if api_key_env
+
+          backends = provider_config["backends"]
+          if backends.is_a?(Hash)
+            backends.each_value do |backend|
+              next unless backend.is_a?(Hash)
+
+              env_key = backend["env_key"]
+              Array(env_key).each do |key|
+                env_keys << key if key
+              end
+            end
+          end
+
+          # Keep parity with BaseClient/provider.yml defaults for providers that rely on
+          # fallback keys. If new providers are added, update this fallback map as well.
+          env_keys.concat(default_env_keys_for_provider(provider_name)) if env_keys.empty?
+          env_keys.map(&:to_s).map(&:strip).reject(&:empty?).uniq
+        end
+
+        def default_env_keys_for_provider(provider_name)
+          case provider_name.to_s.downcase
+          when "google"
+            %w[GEMINI_API_KEY GOOGLE_API_KEY]
+          when "openai"
+            ["OPENAI_API_KEY"]
+          when "anthropic"
+            ["ANTHROPIC_API_KEY"]
+          when "mistral"
+            ["MISTRAL_API_KEY"]
+          when "togetherai"
+            %w[TOGETHER_API_KEY TOGETHERAI_API_KEY]
+          else
+            []
+          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,101 @@
+# 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)
+          return false if @registry.provider_api_key_required?(provider) && !@registry.provider_api_key_present?(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

@@ -104,7 +104,8 @@ module Ace
           registry: registry,
           fallback_config: fallback_config,
           timeout: resolved_timeout,
-          debug: debug
+          debug: debug,
+          role_fallbacks: parse_result.role_fallbacks
         )
 
         text_content = extract_text_content(response)
@@ -290,12 +291,21 @@ 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)
         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
+        if role_fallbacks&.any?
+          existing_chain = fallback_config.providers_for(primary_provider_string)
+          merged_chain = role_fallbacks + (existing_chain - role_fallbacks)
+          fallback_config = fallback_config.merge(chains: {primary_provider_string => merged_chain})
+        end
+
         status_callback = ->(msg) { warn msg }
 
         orchestrator = Molecules::FallbackOrchestrator.new(
@@ -304,8 +314,6 @@ 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)
         end

data/lib/ace/llm/version.rb

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

data/lib/ace/llm.rb

@@ -19,9 +19,11 @@ 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"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-llm
 version: !ruby/object:Gem::Version
-  version: 0.30.2
+  version: 0.32.1
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-03-29 00:00:00.000000000 Z
+date: 2026-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -267,6 +267,7 @@ files:
 - lib/ace/llm/cli/commands/query.rb
 - lib/ace/llm/configuration.rb
 - lib/ace/llm/models/fallback_config.rb
+- lib/ace/llm/models/role_config.rb
 - lib/ace/llm/molecules/client_registry.rb
 - lib/ace/llm/molecules/config_loader.rb
 - lib/ace/llm/molecules/fallback_orchestrator.rb
@@ -277,6 +278,7 @@ files:
 - lib/ace/llm/molecules/preset_loader.rb
 - lib/ace/llm/molecules/provider_loader.rb
 - lib/ace/llm/molecules/provider_model_parser.rb
+- lib/ace/llm/molecules/role_resolver.rb
 - lib/ace/llm/molecules/thinking_level_loader.rb
 - lib/ace/llm/organisms/anthropic_client.rb
 - lib/ace/llm/organisms/base_client.rb