legion-llm 0.14.17 → 0.14.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 911fae6cf0899e9ce7ed1fea909e023b411f3437ea0225d263bcc1cb95d6f9b6
-  data.tar.gz: e7f85c4c731a1e5fe8af13dfcc85f4497619256923b6eba39afc2d9e49574863
+  metadata.gz: eb744016e12f01c149812c027353b25ecba016826789d83a3a795a5b9cba2a19
+  data.tar.gz: 8ed359b0f6d0b9d147a04a419ad30bf26834a258b1448c625e0a6614187f5db3
 SHA512:
-  metadata.gz: bd8368de549a561693308531c6a5efd64ba2cbf09ca8f5cc638c76c335944392686a44418204eb5895e9386d388160550b79426c4ed832931c759dec0eee2c4d
-  data.tar.gz: cd03fa5498c7783c3be2a587c3d6ec8543ab203b19ddb3e6e207388107e30ed54b66f08980f7a5c2b9e64147d4c4defe23bbb62ed46ebf33257a96f3ceeae9d8
+  metadata.gz: 74db62246f4ff813981821a699374fa21e39d84b2d7496c28c969c3f2345ea777d7c74cd5a763222b5fa0014864eda6ae81332609a595b9f51a02162198af778
+  data.tar.gz: 46b000f6e78863046f6c05560ba24aa49a16d097f92cea59390735b9acb42b9fbed1f1f0d04715262b5a9f07b1b521c370484b11acb010822a6dc56737dde40c

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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

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]}",

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/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

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.17'
+    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.17
+  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