legion-llm 0.14.16 → 0.14.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3eec433896cf314b65ac64111f414a55dc7e9639db3d54cc76359c9fb01ed567
-  data.tar.gz: 659857c6aa71573f6fbb795a655b7a59f2936672b0538db0bc14c18ae06ecfbd
+  metadata.gz: eb744016e12f01c149812c027353b25ecba016826789d83a3a795a5b9cba2a19
+  data.tar.gz: 8ed359b0f6d0b9d147a04a419ad30bf26834a258b1448c625e0a6614187f5db3
 SHA512:
-  metadata.gz: 648b2bd80386141477bf5b77b387814f768d5f64447a921d34ef828dde6d9469a15e63211e63c4173e7188e0a61c5d60eb366415ccb68c43c031a23cd4889ac3
-  data.tar.gz: 22f1a949a48470e5a6b543a683e2de4f9c86f44d1c21d706e704bb4a5f58672311ba632b03710647beb071987abed2947e6299e0ad69c06b73c72484398fb238
+  metadata.gz: 74db62246f4ff813981821a699374fa21e39d84b2d7496c28c969c3f2345ea777d7c74cd5a763222b5fa0014864eda6ae81332609a595b9f51a02162198af778
+  data.tar.gz: 46b000f6e78863046f6c05560ba24aa49a16d097f92cea59390735b9acb42b9fbed1f1f0d04715262b5a9f07b1b521c370484b11acb010822a6dc56737dde40c

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Legion LLM Changelog
 
+## [0.14.18] - 2026-07-24
+
+### Changed
+- `@applied_signals` rewritten from flat Array to structured Hash with named keys (`advisory_id`, `behavioral_synapse_ids`, `trace_ids`, `advisory_types`, `envelope_keys`, `prediction_id`, `response_stats`)
+- `step_response_return` implemented with `populate_response_stats`, `fire_pipeline_observation`, `record_applied_to_gaia`
+- `:response_return` removed from `ASYNC_SAFE_STEPS` (attribution must complete synchronously)
+- `gut_check` moved before `metering` in `POST_PROVIDER_STEPS`
+- GaiaCaller: `caller_class:`/`caller_client:` as explicit kwargs; `:class`/`:client` at top level of caller hash
+
+### Added
+- `fire_pipeline_observation` — calls `Gaia.observe_from_pipeline` for `:human` callers (forms bonds from API clients)
+- `gaia_preferred_lane` in TierAssigner — injects preferred provider/model for `gaia:*` callers from settings
+- `require_relative 'steps/gut_check'` in steps.rb (fixes boot crash)
+- `preferred_provider`/`preferred_model` in `gaia_defaults` settings
+
+### Removed
+- `record_advisory_meta_to_gaia` method and its call in `gaia_advisory` step (superseded by `@applied_signals` seeding)
+
+## [0.14.17] - 2026-07-22
+
+### Added
+- Physical Binning (SSoT v2): Router Range Sieve steers requests to hardware based on workload size
+  - 3-tier priority: specific range match → generalist → full eligible fallback
+  - Boundaries are lower-inclusive, upper-exclusive (`[min, max)`)
+  - Escalation drains each tier naturally via `tried_lanes`
+- Inventory lane enrichment: `preferred_min_context_tokens` / `preferred_max_context_tokens` injected from instance settings
+  - Works for ALL providers automatically (same settings path as instance weights)
+  - Settings path: `settings[:extensions][:llm][provider][:instances][id][:preferred_min/max_context_tokens]`
+
 ## [0.14.16] - 2026-07-14
 
 ### Fixed

data/lib/legion/llm/api/namespaces/anthropic/messages.rb

@@ -95,6 +95,7 @@ module Legion
                   stream:            false,
                   started_at:        request_started_at
                 )
+                set_routing_response_headers(pipeline_response: pipeline_response)
 
                 if canonical_format
                   status_code, response_headers, body_string = Legion::LLM::API::DebugFormats.render_canonical_response(

data/lib/legion/llm/api/namespaces/native/inference.rb

@@ -221,6 +221,7 @@ module Legion
                     tool_calls:        tool_calls,
                     stop_reason:       stop_reason
                   )
+                  set_routing_response_headers(pipeline_response: pipeline_response)
 
                   payload = {
                     request_id:           request_id,

data/lib/legion/llm/api/namespaces/openai/chat/completions.rb

@@ -106,6 +106,7 @@ module Legion
                       stream:            false,
                       started_at:        request_started_at
                     )
+                    set_routing_response_headers(pipeline_response: pipeline_response)
 
                     if canonical_format
                       status_code, response_headers, body_string = Legion::LLM::API::DebugFormats.render_canonical_response(

data/lib/legion/llm/api/namespaces/openai/responses.rb

@@ -104,6 +104,7 @@ module Legion
                     stream:            false,
                     started_at:        request_started_at
                   )
+                  set_routing_response_headers(pipeline_response: pipeline_response)
 
                   if canonical_format
                     status_code, response_headers, body_string = Legion::LLM::API::DebugFormats.render_canonical_response(

data/lib/legion/llm/api/shared_helpers.rb

@@ -211,6 +211,17 @@ module Legion
                           request_id: request_id)
         end
 
+        def set_routing_response_headers(pipeline_response:)
+          routing = pipeline_response.respond_to?(:routing) ? pipeline_response.routing || {} : {}
+          provider_val = api_hash_value(routing, :provider)
+          instance_val = api_hash_value(routing, :instance)
+          model_val = api_hash_value(routing, :model)
+
+          headers 'X-Legion-Provider' => provider_val.to_s if provider_val
+          headers 'X-Legion-Instance' => instance_val.to_s if instance_val
+          headers 'X-Legion-Model' => model_val.to_s if model_val
+        end
+
         def api_duration_ms(started_at)
           return 0 unless started_at
 

data/lib/legion/llm/inference/enrichment_injector.rb

@@ -20,7 +20,14 @@ module Legion
 
           # GAIA system prompt (highest priority enrichment)
           if (gaia = enrichments.dig('gaia:system_prompt', :content))
-            parts << gaia
+            prompt = gaia
+            if (partner = enrichments.dig('gaia:partner_model', :data))
+              # Render partner_model slots (e.g. {{partner_name}}, {{partner_standing}})
+              partner.each do |slot, value|
+                prompt = prompt.gsub("{{#{slot}}}", value.to_s)
+              end
+            end
+            parts << prompt
           end
 
           # Prior conversation history loaded by the context step.

data/lib/legion/llm/inference/executor/routing.rb

@@ -50,6 +50,8 @@ module Legion
             return unless assignment
 
             @proactive_tier_assignment = assignment
+            @applied_signals[:envelope_keys] << "tier_assigned:#{assignment[:source]}" if @applied_signals.is_a?(Hash)
+
             @audit[:'routing:tier_assignment'] = {
               outcome:     :success,
               detail:      "proactive tier=#{assignment[:tier]} source=#{assignment[:source]}",
@@ -204,20 +206,16 @@ module Legion
           # dispatch. Use ContextAccounting (walks canonical structs / content
           # blocks) for messages, estimate the INJECTED system (baseline + RAG +
           # skills + prior-history text), and count client tools. Messages are the
-          # lane-independent-reduced set — what actually goes on the wire.
           def estimate_request_tokens
-            # Mirror the dispatch shape EXACTLY: native_dispatch_messages sends
-            # @request.messages (lane-independent-reduced); the conversation
-            # history lives in the injected SYSTEM (via EnrichmentInjector), not
-            # in the messages array — counting it in both would double-count.
             reduced = reduce_messages_for_dispatch(Array(@request.messages))
 
-            estimated  = ContextAccounting.estimate_message_tokens(reduced)
-            estimated += ContextAccounting.estimate_text_tokens(routing_estimate_injected_system)
-            estimated += ContextAccounting.estimate_json_tokens(routing_estimate_tool_defs)
-            estimated += ContextAccounting.estimate_json_tokens(@request.tool_choice) if @request.tool_choice
-            estimated += ContextAccounting.estimate_json_tokens(@request.thinking) if @request.thinking.is_a?(Hash) && @request.thinking.any?
-            estimated
+            msg_tokens = ContextAccounting.estimate_message_tokens(reduced)
+            sys_tokens = ContextAccounting.estimate_text_tokens(routing_estimate_injected_system)
+            tool_tokens = ContextAccounting.estimate_json_tokens(routing_estimate_tool_defs)
+            choice_tokens = @request.tool_choice ? ContextAccounting.estimate_json_tokens(@request.tool_choice) : 0
+            thinking_tokens = @request.thinking.is_a?(Hash) && @request.thinking.any? ? ContextAccounting.estimate_json_tokens(@request.thinking) : 0
+
+            msg_tokens + sys_tokens + tool_tokens + choice_tokens + thinking_tokens
           end
 
           # The system prompt as it will be dispatched — baseline + GAIA + prior
@@ -227,17 +225,10 @@ module Legion
             EnrichmentInjector.inject(system: @request.system, enrichments: @enrichments || {})
           end
 
-          # The tool catalog dispatch will send (special + client + registry), NOT
-          # just @request.tools — the dispatch guard counts native_dispatch_tools,
-          # so routing must too or a heavy-tool request under-counts and picks a
-          # too-small lane. Built read-only here (never memoized) because
-          # native_tool_definitions caches and applies the local-provider cap
-          # against @resolved_provider, which is not set at routing time; an
-          # uncapped over-estimate is the safe direction for a "will it fit" filter.
           def routing_estimate_tool_defs
             defs = Tools::Special.pinned_definitions.map(&:to_h)
             Array(@request.tools).each { |t| defs << (t.respond_to?(:to_h) ? t.to_h : t) }
-            Legion::Settings::Extensions.filter_tools(deferred: false).each { |e| defs << e } if registry_tool_injection_requested?
+            Array(@discovered_tools).each { |t| defs << (t.respond_to?(:to_h) ? t.to_h : t) }
             defs
           rescue StandardError => e
             handle_exception(e, level: :warn, handled: true, operation: 'llm.pipeline.routing_estimate_tool_defs')

data/lib/legion/llm/inference/executor.rb

@@ -52,6 +52,7 @@ module Legion
         include Steps::StickyRunners
         include Steps::ToolHistory
         include Steps::StickyPersist
+        include Steps::GutCheck
 
         PRE_PROVIDER_STEPS = %i[
           tracing_init idempotency conversation_uuid context_load
@@ -61,14 +62,14 @@ module Legion
         ].freeze
 
         POST_PROVIDER_STEPS = %i[
-          response_normalization post_response metering debate confidence_scoring
+          response_normalization post_response gut_check metering debate confidence_scoring
           tool_calls sticky_persist
           context_store knowledge_capture response_return
         ].freeze
 
         STEPS = (PRE_PROVIDER_STEPS + %i[provider_call] + POST_PROVIDER_STEPS).freeze
 
-        ASYNC_SAFE_STEPS = %i[post_response knowledge_capture response_return].freeze
+        ASYNC_SAFE_STEPS = %i[post_response knowledge_capture].freeze
 
         THINKING_TAG_PAIRS = [
           ['<thinking>', '</thinking>'],
@@ -134,6 +135,15 @@ module Legion
           @injected_tool_map = {}
           @native_tool_source_map = {}
           @freshly_triggered_keys = []
+          @applied_signals = {
+            advisory_id:            nil,
+            behavioral_synapse_ids: [],
+            trace_ids:              [],
+            advisory_types:         [],
+            envelope_keys:          [],
+            prediction_id:          nil,
+            response_stats:         {}
+          }
           @context_accounting = ContextAccounting.empty
         end
 
@@ -1073,7 +1083,58 @@ module Legion
           handle_exception(e, level: :warn, operation: 'llm.pipeline.trigger_async_curation', conversation_id: conv_id)
         end
 
-        def step_response_return; end
+        def step_response_return
+          populate_response_stats
+          fire_pipeline_observation
+          record_applied_to_gaia
+        end
+
+        def populate_response_stats
+          @applied_signals[:response_stats] = {
+            output_tokens:   @extracted_tokens.respond_to?(:output_tokens) ? @extracted_tokens.output_tokens.to_i : 0,
+            provider:        @resolved_provider,
+            model:           @resolved_model,
+            tier:            @resolved_tier,
+            latency_ms:      if @timestamps&.dig(:provider_start) && @timestamps[:provider_end]
+                               ((@timestamps[:provider_end] - @timestamps[:provider_start]) * 1000).round
+                             else
+                               0
+                             end,
+            exchange_id:     @exchange_id,
+            conversation_id: @request.conversation_id
+          }
+        end
+
+        def fire_pipeline_observation
+          return unless defined?(::Legion::Gaia) && ::Legion::Gaia.respond_to?(:observe_from_pipeline)
+
+          identity = @request.caller&.dig(:requested_by, :identity)
+          caller_type = @request.caller&.dig(:requested_by, :type)
+          return unless identity && caller_type&.to_sym == :human
+
+          exchange_id = @exchange_id || @request.id
+          ::Legion::Gaia.observe_from_pipeline(
+            identity:    identity,
+            caller:      @request.caller,
+            exchange_id: exchange_id
+          )
+        rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'llm.pipeline.response_return.observe_pipeline')
+        end
+
+        def record_applied_to_gaia
+          return unless defined?(::Legion::Gaia) && ::Legion::Gaia.respond_to?(:record_response_applied)
+          return if @applied_signals[:advisory_id].nil? && @applied_signals[:behavioral_synapse_ids].empty?
+
+          identity = @request.caller&.dig(:requested_by, :identity)
+          ::Legion::Gaia.record_response_applied(
+            advisory_id: @applied_signals[:advisory_id],
+            identity:    identity,
+            applied:     @applied_signals.dup
+          )
+        rescue StandardError => e
+          handle_exception(e, level: :warn, operation: 'llm.pipeline.response_return.record_applied')
+        end
 
         def finalize_context_accounting
           tokens = @context_accounting[:tokens]
@@ -1178,6 +1239,10 @@ module Legion
 
           log.debug("[pipeline][build_response] action=build request_id=#{@request.id} provider=#{@resolved_provider} model=#{@resolved_model}")
 
+          # Synchronous delivery attribution hook (H2-llm)
+          # Records what signals (GAIA hints, role mappings, etc) were actually applied to the final route.
+          emit_final_delivery_attribution
+
           Response.build(
             request_id:      @request.id,
             conversation_id: @request.conversation_id || "conv_#{SecureRandom.hex(8)}",
@@ -1206,6 +1271,17 @@ module Legion
           )
         end
 
+        def emit_final_delivery_attribution
+          keys = @applied_signals.is_a?(Hash) ? @applied_signals[:envelope_keys] : []
+          return if keys.nil? || keys.empty?
+
+          log.info("[pipeline][attribution] action=emit_final_delivery signals=#{keys.join(',')}")
+          @audit[:'delivery:attribution'] = {
+            applied_signals: @applied_signals,
+            timestamp:       Time.now
+          }
+        end
+
         def requested_deferred_tool_names
           return [] unless @request.respond_to?(:metadata)
 

data/lib/legion/llm/inference/gaia_caller.rb

@@ -10,26 +10,30 @@ module Legion
 
         extend Legion::Logging::Helper
 
-        def chat(message:, phase: 'unknown', tick_trace_id: nil, tick_span_id: nil, caller: nil, **kwargs)
+        def chat(message:, phase: 'unknown', tick_trace_id: nil, tick_span_id: nil,
+                 caller: nil, caller_class: nil, caller_client: nil, **kwargs)
           log.info("[llm][gaia] chat phase=#{phase} model=#{kwargs[:model] || 'default'}")
+
           request = Request.build(
             messages: [{ role: :user, content: message }],
             system:   kwargs[:system],
             routing:  { provider: kwargs[:provider], model: kwargs[:model] }.compact,
-            caller:   caller || gaia_caller(phase),
+            caller:   caller || gaia_caller(phase, caller_class: caller_class, caller_client: caller_client),
             tracing:  gaia_tracing(phase, tick_trace_id, tick_span_id)
           )
           Executor.new(request).call
         end
 
-        def structured(message:, schema:, phase: 'unknown', tick_trace_id: nil, tick_span_id: nil, caller: nil, **kwargs)
+        def structured(message:, schema:, phase: 'unknown', tick_trace_id: nil, tick_span_id: nil,
+                       caller: nil, caller_class: nil, caller_client: nil, **kwargs)
           log.info("[llm][gaia] structured phase=#{phase} model=#{kwargs[:model] || 'default'}")
+
           request = Request.build(
             messages:        [{ role: :user, content: message }],
             system:          kwargs[:system],
             routing:         { provider: kwargs[:provider], model: kwargs[:model] }.compact,
             response_format: { type: :json_schema, schema: schema },
-            caller:          caller || gaia_caller(phase),
+            caller:          caller || gaia_caller(phase, caller_class: caller_class, caller_client: caller_client),
             tracing:         gaia_tracing(phase, tick_trace_id, tick_span_id)
           )
           Executor.new(request).call
@@ -40,8 +44,8 @@ module Legion
           LLM.embed(text, **)
         end
 
-        def gaia_caller(phase)
-          {
+        def gaia_caller(phase, caller_class: nil, caller_client: nil)
+          hash = {
             requested_by: {
               identity:   "gaia:tick:#{phase}",
               type:       :system,
@@ -49,6 +53,9 @@ module Legion
               name:       "GAIA #{phase.to_s.tr('_', ' ').capitalize}"
             }
           }
+          hash[:class]  = caller_class  if caller_class
+          hash[:client] = caller_client if caller_client
+          hash
         end
 
         def gaia_tracing(phase, trace_id, span_id)

data/lib/legion/llm/inference/steps/debate.rb

@@ -90,6 +90,7 @@ module Legion
               "original_chars=#{original_chars} synthetic_chars=#{debate_result[:synthetic_response].content.to_s.length} " \
               "rounds=#{debate_result[:rounds]}"
             )
+            @applied_signals[:envelope_keys] << 'debate:applied' if @applied_signals.is_a?(Hash)
             @enrichments['debate:result'] = {
               content:   "debate completed: #{debate_result[:rounds]} rounds, judge synthesis produced",
               data:      debate_result[:metadata],

data/lib/legion/llm/inference/steps/gaia_advisory.rb

@@ -44,16 +44,12 @@ module Legion
               timestamp: Time.now
             }
 
-            if advisory[:system_prompt]
-              log_step_info(:gaia_advisory, :system_prompt_injected, chars: advisory[:system_prompt].to_s.length)
-              @enrichments['gaia:system_prompt'] = {
-                content:   advisory[:system_prompt],
-                timestamp: Time.now
-              }
-            end
+            # system_prompt is injected via gaia:system_prompt enrichment key below
 
             if advisory[:routing_hint]
-              log_step_info(:gaia_advisory, :routing_hint_injected, tier: advisory[:routing_hint][:recommended_tier] || 'none')
+              hint = advisory[:routing_hint]
+              tier_value = hint[:tier] || hint[:recommended_tier] || 'none'
+              log_step_info(:gaia_advisory, :routing_hint_injected, tier: tier_value)
               @enrichments['gaia:routing_hint'] = {
                 data:      advisory[:routing_hint],
                 timestamp: Time.now
@@ -66,7 +62,12 @@ module Legion
               from: 'gaia', to: 'pipeline'
             )
 
-            record_advisory_meta_to_gaia(advisory)
+            advisory_id = advisory[:advisory_id] || advisory['advisory_id']
+            if advisory_id
+              @applied_signals[:advisory_id]    = advisory_id
+              @applied_signals[:advisory_types] = classify_advisory_types(advisory)
+            end
+
             log_step_info(
               :gaia_advisory,
               :complete,
@@ -228,29 +229,6 @@ module Legion
             nil
           end
 
-          def record_advisory_meta_to_gaia(advisory)
-            unless defined?(::Legion::Gaia) && ::Legion::Gaia.respond_to?(:record_advisory_meta)
-              log_step_debug(:gaia_advisory, :record_meta_skipped, reason: :gaia_unavailable)
-              return
-            end
-            unless advisory[:partner_context]
-              log_step_debug(:gaia_advisory, :record_meta_skipped, reason: :no_partner_context)
-              return
-            end
-
-            advisory_id = SecureRandom.uuid
-            advisory_types = classify_advisory_types(advisory)
-
-            ::Legion::Gaia.record_advisory_meta(
-              advisory_id:    advisory_id,
-              advisory_types: advisory_types
-            )
-            log_step_debug(:gaia_advisory, :record_meta, advisory_id: advisory_id, advisory_type_count: advisory_types.size)
-          rescue StandardError => e
-            handle_exception(e, level: :warn, operation: 'llm.pipeline.steps.gaia_advisory.record_meta')
-            nil
-          end
-
           def classify_advisory_types(advisory)
             types = []
             pc = advisory[:partner_context]

data/lib/legion/llm/inference/steps/gut_check.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'legion/logging/helper'
+require_relative 'logging'
+
+module Legion
+  module LLM
+    module Inference
+      module Steps
+        module GutCheck
+          include Legion::Logging::Helper
+          include Steps::Logging
+
+          def step_gut_check
+            unless defined?(::Legion::Gaia::Gut) && ::Legion::Gaia::Gut.respond_to?(:check)
+              log_step_debug(:gut_check, :skipped, reason: :gaia_gut_unavailable)
+              return
+            end
+
+            # Gather draft stats for conflict detection.
+            # This typically includes things like routing source, applied signals, and model used.
+            draft_stats = {
+              resolved_provider: @resolved_provider,
+              resolved_model:    @resolved_model,
+              applied_signals:   @applied_signals,
+              tier:              @resolved_tier || @proactive_tier_assignment&.dig(:tier)
+            }
+
+            identity = @request.caller&.dig(:requested_by, :identity) || 'unknown'
+
+            log_step_debug(:gut_check, :checking, identity: identity)
+
+            result = ::Legion::Gaia::Gut.check(
+              identity:    identity,
+              draft_stats: draft_stats
+            )
+
+            if result && result[:conflict]
+              log_step_info(:gut_check, :conflict_detected,
+                            severity: result[:severity],
+                            reason:   result[:reason])
+
+              @warnings << "Cognitive conflict detected by GAIA Gut Check: #{result[:reason]}"
+
+              # If the conflict is critical, we could potentially trigger an escalation
+              # or mark the response as suspect. For now, we follow the requirement to detect.
+              @audit[:'delivery:gut_check'] = {
+                outcome:   :conflict,
+                severity:  result[:severity],
+                reason:    result[:reason],
+                timestamp: Time.now
+              }
+            else
+              log_step_debug(:gut_check, :no_conflict)
+            end
+          rescue StandardError => e
+            @warnings << "Gut check error: #{e.message}"
+            handle_exception(e, level: :warn, operation: 'llm.pipeline.steps.gut_check')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/inference/steps/rag_context.rb

@@ -38,6 +38,7 @@ module Legion
             result = apollo_retrieve(query: query, strategy: strategy)
             record_rag_enrichment(result, strategy)
             record_rag_timeline(result, strategy, start_time)
+            @applied_signals[:envelope_keys] << "rag_context:#{strategy}" if @applied_signals.is_a?(Hash)
           rescue StandardError => e
             @warnings << "RAG context error: #{e.message}"
             handle_exception(e, level: :warn, operation: 'llm.pipeline.steps.rag_context')

data/lib/legion/llm/inference/steps/tier_assigner.rb

@@ -33,7 +33,12 @@ module Legion
             end
 
             # 1. GAIA routing hint
-            recommended = nested_value(gaia_hint, :data, :recommended_tier)
+            recommended = nested_value(gaia_hint, :data, :tier)
+            if recommended.nil? && nested_value(gaia_hint, :data, :recommended_tier)
+              log.warn('[llm][routing] gaia_hint uses deprecated :recommended_tier; GAIA advisory should emit :tier')
+              recommended = nested_value(gaia_hint, :data, :recommended_tier)
+            end
+
             if recommended
               log.info("[llm][routing] tier_assigned source=gaia tier=#{recommended}")
               return { tier: recommended.to_sym, source: :gaia }
@@ -78,11 +83,22 @@ module Legion
 
               tier = value(mapping, :tier)
               log.info("[llm][routing] tier_mapping identity=#{identity} tier=#{tier}")
-              return { tier: tier&.to_sym, intent: value(mapping, :intent), source: :role_mapping }
+              result = { tier: tier&.to_sym, intent: value(mapping, :intent), source: :role_mapping }
+              result.merge!(gaia_preferred_lane) if identity.start_with?('gaia:')
+              return result
             end
             nil
           end
 
+          def gaia_preferred_lane
+            provider = Legion::Settings.dig(:llm, :gaia, :preferred_provider)
+            model    = Legion::Settings.dig(:llm, :gaia, :preferred_model)
+            extras   = {}
+            extras[:provider] = provider.to_sym if provider
+            extras[:model]    = model.to_s      if model
+            extras
+          end
+
           def tier_mappings
             configured = Legion::Settings[:llm][:routing][:tier_mappings]
             configured.nil? || configured.empty? ? DEFAULT_MAPPINGS : configured

data/lib/legion/llm/inference/steps/token_budget.rb

@@ -16,9 +16,11 @@ module Legion
             session_limit = Legion::LLM::Metering::Tokens.summary[:session_max_tokens]
             log_step_debug(:token_budget, :checking, max_input_tokens: max_input || 'none',
                                                      session_total: session_total, session_limit: session_limit || 'none')
+
             check_input_cap(max_input) if max_input&.positive?
             check_session_budget
             log_step_debug(:token_budget, :passed, max_input_tokens: max_input || 'none')
+            @applied_signals[:envelope_keys] << 'token_budget:passed' if @applied_signals.is_a?(Hash)
           rescue Legion::LLM::TokenBudgetExceeded
             log_step_info(:token_budget, :blocked)
             raise

data/lib/legion/llm/inference/steps.rb

@@ -31,5 +31,6 @@ require_relative 'steps/confidence_scoring'
 require_relative 'steps/token_budget'
 require_relative 'steps/prompt_cache'
 require_relative 'steps/debate'
+require_relative 'steps/gut_check'
 require_relative 'steps/tool_history'
 require_relative 'steps/sticky_persist'

data/lib/legion/llm/inference.rb

@@ -10,6 +10,7 @@ require_relative 'inference/profile'
 require_relative 'inference/timeline'
 require_relative 'inference/tracing'
 require_relative 'inference/steps'
+require_relative 'inference/steps/gut_check'
 require_relative 'inference/tool_dispatcher'
 require_relative 'inference/audit_publisher'
 require_relative 'inference/enrichment_injector'

data/lib/legion/llm/inventory.rb

@@ -25,6 +25,8 @@ module Legion
           validate_lane!(lane: lane)
           return policy_skip(lane: lane) if policy_denied?(lane: lane)
 
+          lane = enrich_lane_range(lane: lane)
+
           existing = live_map[lane[:id]]
           resolved_health = if health == :preserve
                               existing&.dig(:health) || default_health
@@ -180,6 +182,26 @@ module Legion
           (base * health_mult).to_i
         end
 
+        def enrich_lane_range(lane:)
+          provider_settings = Legion::Settings.dig(:extensions, :llm, lane[:provider_family].to_sym)
+          return lane unless provider_settings.is_a?(Hash)
+
+          instances = provider_settings[:instances]
+          return lane unless instances.is_a?(Hash)
+
+          inst_cfg = instances[lane[:instance_id]] || instances[lane[:instance_id]&.to_sym]
+          return lane unless inst_cfg.is_a?(Hash)
+
+          min_val = inst_cfg[:preferred_min_context_tokens]
+          max_val = inst_cfg[:preferred_max_context_tokens]
+          return lane if min_val.nil? && max_val.nil?
+
+          enriched = lane.dup
+          enriched[:preferred_min_context_tokens] = min_val if min_val
+          enriched[:preferred_max_context_tokens] = max_val if max_val
+          enriched
+        end
+
         def lane_weights_from_settings(lane:)
           tier_weights    = Legion::Settings.dig(:llm, :routing, :tier_weights) || {}
           provider_sym    = lane[:provider_family].to_sym

data/lib/legion/llm/router.rb

@@ -57,6 +57,35 @@ module Legion
           rng: default_rng,
           **
         )
+          # 0. GAIA Preferred Provider/Model (OP2)
+          if type == :inference && (tiers.include?(:gaia) || tiers.include?('gaia'))
+            pref_provider = Legion::Settings.dig(:llm, :gaia, :preferred_provider)
+            pref_model    = Legion::Settings.dig(:llm, :gaia, :preferred_model)
+
+            if pref_provider || pref_model
+              # If either is set, we try to force a lane matching both (if both set) or either.
+              # We prioritize this over general weights for the :gaia tier.
+              candidates = Legion::LLM::Inventory.lanes_for(
+                provider: pref_provider,
+                model:    pref_model,
+                type:     type
+              )
+
+              if candidates&.any?
+                # Filter candidates by hard constraints (privacy, context, etc)
+                passing = candidates.select do |lane|
+                  lane_passes_hard_filters?(
+                    lane: lane, type: type, tiers: tiers, providers: providers, instances: instances,
+                    models: models, capabilities: capabilities, thinking: thinking, privacy: privacy,
+                    estimated_context: estimated_context
+                  )
+                end
+                # Use the first one that passes hard filters as the preferred selection
+                return passing.first if passing.any?
+              end
+            end
+          end
+
           candidates = if providers.size == 1 && instances.size <= 1
                          Legion::LLM::Inventory.lanes_for(
                            provider: providers.first, instance: instances.first, type: type
@@ -76,7 +105,9 @@ module Legion
 
           return nil if eligible.empty?
 
-          eligible
+          pool = range_sieve(eligible: eligible, estimated_context: estimated_context)
+
+          pool
             .group_by { |lane| lane[:lane_weight] }
             .max_by { |weight, _| weight }
             .last
@@ -190,6 +221,30 @@ module Legion
 
         private
 
+        def range_sieve(eligible:, estimated_context:)
+          return eligible if estimated_context.nil?
+
+          specific, generalist = eligible.partition { |lane| lane_has_range?(lane) }
+          matched = specific.select { |lane| lane_in_range?(lane: lane, estimated_context: estimated_context) }
+
+          return matched unless matched.empty?
+          return generalist unless generalist.empty?
+
+          eligible
+        end
+
+        def lane_has_range?(lane)
+          !lane[:preferred_min_context_tokens].nil? || !lane[:preferred_max_context_tokens].nil?
+        end
+
+        def lane_in_range?(lane:, estimated_context:)
+          lower = (lane[:preferred_min_context_tokens] || 0).to_i
+          upper = lane[:preferred_max_context_tokens]
+          upper = upper ? upper.to_i : Float::INFINITY
+
+          estimated_context >= lower && estimated_context < upper
+        end
+
         def lane_passes_hard_filters?(lane:, type:, tiers:, providers:, instances:, models:,
                                       capabilities:, thinking:, privacy:, estimated_context:, **)
           return false if lane[:type] != type

data/lib/legion/llm/settings.rb

@@ -330,7 +330,9 @@ module Legion
 
       def self.gaia_defaults
         {
-          advisory_enabled: true
+          advisory_enabled:   true,
+          preferred_provider: nil,
+          preferred_model:    nil
         }
       end
 

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.14.16'
+    VERSION = '0.14.18'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.14.16
+  version: 0.14.18
 platform: ruby
 authors:
 - Esity
@@ -360,6 +360,7 @@ files:
 - lib/legion/llm/inference/steps/confidence_scoring.rb
 - lib/legion/llm/inference/steps/debate.rb
 - lib/legion/llm/inference/steps/gaia_advisory.rb
+- lib/legion/llm/inference/steps/gut_check.rb
 - lib/legion/llm/inference/steps/knowledge_capture.rb
 - lib/legion/llm/inference/steps/logging.rb
 - lib/legion/llm/inference/steps/mcp_discovery.rb