legion-llm 0.3.17 → 0.3.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f0427a4ddb7c7118e21cf0abd805ae05c994f78c35be322307858a9ad8d0b3c
-  data.tar.gz: b010081a1f8007df86babebd563d5fada164eeabcd573594e3aaa310317c1474
+  metadata.gz: 0a19ae18f6bbb96680e6bfbcad1e81bd3e67c6b1be72e0615cf24852a69b2e59
+  data.tar.gz: f293c1bc52cb97652e545efb4877b32592d8aa0d96d190bef4f2624d6b277a5a
 SHA512:
-  metadata.gz: e882a711b7c9a56d03c0fc3f1753c47cf6c148c7312cb3d50302dcaeda1ca67e09bef67ed37f295480625f981b4e32b1d0a4e96736fa9a6f3ac61af8cd1b57ec
-  data.tar.gz: 59cb342d0af6c92e94caff375f557de3dac75413c19821f28d5c471f319d748cdcfff99ebd8328ea1fcf0e4dff98614cf262eba69037f5b7ce3d72f567bf2499
+  metadata.gz: 488d6fec5178b75b4f48b9031cd3e172b9637d1044ca210912ff1bc0a5b91818d2fd379725426e8be58bfc30638f0cd6ef83a2f550e94e728f40b74b1a39a5ad
+  data.tar.gz: b738f793fc22c4dbf3400da0fb9c13d2bb427321fa1f1d8a594482a35239644d2e4d0fc96e9e08c295c95a2e3ff388e9f45b1cddf3e7db0f1bd00a4139c257ed

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Legion LLM Changelog
 
+## [0.3.18] - 2026-03-22
+
+### Added
+- Logging across routing, health tracking, caching, and discovery subsystems
+- `Router.resolve`: `.info` on route decision (tier/provider/model/rule), `.debug` on candidate filtering counts, `.debug` when no rules match
+- `Router::HealthTracker`: `.warn` on circuit state transitions (closed->open, half_open->open, open->half_open, any->closed), `.debug` on latency penalty applied
+- `Router::Rule`: `.debug` on intent mismatch, schedule constraint rejections (valid_from, valid_until, hours, days)
+- `Cache`: `.debug` on cache miss and cache write, `.warn` on swallowed get/set errors
+- `ResponseCache`: `.warn` on spool overflow to disk, `.debug` on async poll status, `.warn` on fail_request
+- `DaemonClient`: `.warn` on mark_unhealthy, `.warn` on 403/429 responses, `.info` on health check result
+- `StructuredOutput`: `.warn` on JSON parse failure with attempt count, `.debug` when using prompt-based fallback
+- `Compressor`: `.debug` on compression applied (level, original length, compressed length)
+- `Discovery::Ollama`: `.warn` on HTTP failure, `.debug` on model list refresh with count
+- `Discovery::System`: `.warn` on system command failures (sysctl, vm_stat, /proc/meminfo)
+- `ShadowEval`: `.debug` on evaluation triggered, `.warn` on failure
+- `Scheduling`: `.debug` on defer decision
+- `OffPeak`: `.debug` on peak hour check result
+- `Arbitrage`: `.debug` on model selection result
+
+### Changed
+- `Router::Rule#within_schedule?` refactored to extract `schedule_rejection` helper (reduces cyclomatic complexity)
+
 ## [0.3.17] - 2026-03-22
 
 ### Added

data/lib/legion/llm/arbitrage.rb

@@ -56,7 +56,9 @@ module Legion
 
           return nil if scored.empty?
 
-          scored.min_by { |_model, cost| cost }&.first
+          selected = scored.min_by { |_model, cost| cost }&.first
+          Legion::Logging.debug("Arbitrage selected model=#{selected} capability=#{capability}") if defined?(Legion::Logging)
+          selected
         end
 
         # Returns the merged cost table: defaults overridden by any settings-defined entries.

data/lib/legion/llm/cache.rb

@@ -27,10 +27,14 @@ module Legion
         return nil unless available?
 
         raw = Legion::Cache.get(cache_key)
-        return nil if raw.nil?
+        if raw.nil?
+          Legion::Logging.debug("LLM cache miss key=#{cache_key}") if defined?(Legion::Logging)
+          return nil
+        end
 
         ::JSON.parse(raw, symbolize_names: true)
-      rescue StandardError
+      rescue StandardError => e
+        Legion::Logging.warn("LLM cache get error key=#{cache_key}: #{e.message}") if defined?(Legion::Logging)
         nil
       end
 
@@ -39,8 +43,10 @@ module Legion
         return false unless available?
 
         Legion::Cache.set(cache_key, ::JSON.dump(response), ttl)
+        Legion::Logging.debug("LLM cache write key=#{cache_key} ttl=#{ttl}") if defined?(Legion::Logging)
         true
-      rescue StandardError
+      rescue StandardError => e
+        Legion::Logging.warn("LLM cache set error key=#{cache_key}: #{e.message}") if defined?(Legion::Logging)
         false
       end
 

data/lib/legion/llm/compressor.rb

@@ -19,10 +19,12 @@ module Legion
         def compress(text, level: LIGHT)
           return text if text.nil? || text.empty? || level <= NONE
 
+          original_length = text.length
           segments = split_segments(text)
           result = segments.map { |seg| seg[:protected] ? seg[:text] : compress_prose(seg[:text], level) }.join
 
           result = collapse_whitespace(result) if level >= AGGRESSIVE
+          Legion::Logging.debug("Compressor applied level=#{level} original=#{original_length} compressed=#{result.length}") if defined?(Legion::Logging)
           result
         end
 

data/lib/legion/llm/daemon_client.rb

@@ -76,6 +76,7 @@ module Legion
         healthy = response.code == '200'
         @healthy           = healthy
         @health_checked_at = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+        Legion::Logging.info("Daemon health check result=#{healthy ? 'healthy' : 'unhealthy'} url=#{daemon_url}") if defined?(Legion::Logging)
         healthy
       rescue StandardError
         mark_unhealthy
@@ -84,6 +85,7 @@ module Legion
 
       # Marks the daemon as unhealthy and records the timestamp.
       def mark_unhealthy
+        Legion::Logging.warn("Daemon marked unhealthy url=#{daemon_url}") if defined?(Legion::Logging)
         @healthy           = false
         @health_checked_at = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       end
@@ -128,9 +130,11 @@ module Legion
           data = parsed.fetch(:data, {})
           { status: :accepted, request_id: data[:request_id], poll_key: data[:poll_key] }
         when 403
+          Legion::Logging.warn("Daemon returned 403 Denied url=#{daemon_url}") if defined?(Legion::Logging)
           { status: :denied, error: parsed.fetch(:error, parsed) }
         when 429
           retry_after = extract_retry_after(response, parsed)
+          Legion::Logging.warn("Daemon returned 429 RateLimited url=#{daemon_url} retry_after=#{retry_after}") if defined?(Legion::Logging)
           { status: :rate_limited, retry_after: retry_after }
         when 503
           { status: :unavailable }

data/lib/legion/llm/discovery/ollama.rb

@@ -30,10 +30,13 @@ module Legion
             if response.success?
               parsed = ::JSON.parse(response.body)
               @models = parsed['models'] || []
+              Legion::Logging.debug("Discovery::Ollama model list refreshed count=#{@models.size}") if defined?(Legion::Logging)
             else
+              Legion::Logging.warn("Discovery::Ollama HTTP failure status=#{response.status}") if defined?(Legion::Logging)
               @models ||= []
             end
-          rescue StandardError
+          rescue StandardError => e
+            Legion::Logging.warn("Discovery::Ollama HTTP failure: #{e.message}") if defined?(Legion::Logging)
             @models ||= []
           ensure
             @last_refreshed_at = Time.now

data/lib/legion/llm/discovery/system.rb

@@ -94,7 +94,8 @@ module Legion
           def fetch_macos_total
             raw = `sysctl -n hw.memsize`.strip.to_i
             @total_memory_mb = raw / 1024 / 1024
-          rescue StandardError
+          rescue StandardError => e
+            Legion::Logging.warn("Discovery::System sysctl command failed: #{e.message}") if defined?(Legion::Logging)
             @total_memory_mb = nil
           end
 
@@ -104,7 +105,8 @@ module Legion
             free     = vm_output[/Pages free:\s+(\d+)/, 1].to_i
             inactive = vm_output[/Pages inactive:\s+(\d+)/, 1].to_i
             @available_memory_mb = (free + inactive) * page_size / 1024 / 1024
-          rescue StandardError
+          rescue StandardError => e
+            Legion::Logging.warn("Discovery::System vm_stat command failed: #{e.message}") if defined?(Legion::Logging)
             @available_memory_mb = nil
           end
 
@@ -112,7 +114,8 @@ module Legion
             meminfo = File.read('/proc/meminfo')
             total_kb = meminfo[/MemTotal:\s+(\d+)/, 1].to_i
             @total_memory_mb = total_kb / 1024
-          rescue StandardError
+          rescue StandardError => e
+            Legion::Logging.warn("Discovery::System /proc/meminfo read failed: #{e.message}") if defined?(Legion::Logging)
             @total_memory_mb = nil
           end
 
@@ -121,7 +124,8 @@ module Legion
             free_kb     = meminfo[/MemFree:\s+(\d+)/, 1].to_i
             inactive_kb = meminfo[/Inactive:\s+(\d+)/, 1].to_i
             @available_memory_mb = (free_kb + inactive_kb) / 1024
-          rescue StandardError
+          rescue StandardError => e
+            Legion::Logging.warn("Discovery::System /proc/meminfo available read failed: #{e.message}") if defined?(Legion::Logging)
             @available_memory_mb = nil
           end
 

data/lib/legion/llm/off_peak.rb

@@ -12,7 +12,9 @@ module Legion
         # @param time [Time] time to check (defaults to now)
         # @return [Boolean]
         def peak_hour?(time = Time.now.utc)
-          PEAK_HOURS.cover?(time.hour)
+          result = PEAK_HOURS.cover?(time.hour)
+          Legion::Logging.debug("OffPeak peak_hour check hour=#{time.hour} peak=#{result}") if defined?(Legion::Logging)
+          result
         end
 
         # Returns true when a non-urgent request should be deferred to off-peak.

data/lib/legion/llm/response_cache.rb

@@ -26,6 +26,7 @@ module Legion
 
       # Writes error details and marks status as :error.
       def fail_request(request_id, code:, message:, ttl: DEFAULT_TTL)
+        Legion::Logging.warn("ResponseCache fail_request request_id=#{request_id} code=#{code} message=#{message}") if defined?(Legion::Logging)
         payload = ::JSON.dump({ code: code, message: message })
         cache_set(error_key(request_id), payload, ttl)
         cache_set(status_key(request_id), 'error', ttl)
@@ -69,6 +70,7 @@ module Legion
 
         loop do
           current = status(request_id)
+          Legion::Logging.debug("ResponseCache poll request_id=#{request_id} status=#{current}") if defined?(Legion::Logging)
 
           case current
           when :done
@@ -120,6 +122,7 @@ module Legion
 
       private_class_method def self.write_response(request_id, response_text, ttl)
         if response_text.bytesize > SPOOL_THRESHOLD
+          Legion::Logging.warn("ResponseCache spool overflow request_id=#{request_id} bytes=#{response_text.bytesize}") if defined?(Legion::Logging)
           FileUtils.mkdir_p(SPOOL_DIR)
           path = File.join(SPOOL_DIR, "#{request_id}.txt")
           File.write(path, response_text)

data/lib/legion/llm/router/health_tracker.rb

@@ -49,7 +49,10 @@ module Legion
 
           if circuit[:state] == :open
             elapsed = Time.now - circuit[:opened_at]
-            return :half_open if elapsed >= @cooldown_seconds
+            if elapsed >= @cooldown_seconds
+              Legion::Logging.warn("Circuit open->half_open for provider=#{provider} (cooldown elapsed)") if defined?(Legion::Logging)
+              return :half_open
+            end
           end
 
           circuit[:state]
@@ -82,11 +85,13 @@ module Legion
             if circuit_state(provider) == :half_open
               circuit[:state]     = :open
               circuit[:opened_at] = Time.now
+              Legion::Logging.warn("Circuit half_open->open for provider=#{provider} (error during probe)") if defined?(Legion::Logging)
             else
               circuit[:failures] += 1.0
               if circuit[:failures] >= @failure_threshold
                 circuit[:state]     = :open
                 circuit[:opened_at] = Time.now
+                Legion::Logging.warn("Circuit closed->open for provider=#{provider} (failures=#{circuit[:failures]})") if defined?(Legion::Logging)
               end
             end
           end
@@ -94,10 +99,12 @@ module Legion
           register_handler(:success) do |payload|
             provider = payload[:provider]
             ensure_circuit(provider)
+            prev_state          = circuit_state(provider)
             circuit             = @circuits[provider]
             circuit[:failures]  = 0
             circuit[:state]     = :closed
             circuit[:opened_at] = nil
+            Legion::Logging.warn("Circuit #{prev_state}->closed for provider=#{provider}") if defined?(Legion::Logging) && prev_state != :closed
           end
 
           register_handler(:quality_failure) do |payload|
@@ -108,11 +115,13 @@ module Legion
             if circuit_state(provider) == :half_open
               circuit[:state]     = :open
               circuit[:opened_at] = Time.now
+              Legion::Logging.warn("Circuit half_open->open for provider=#{provider} (quality failure during probe)") if defined?(Legion::Logging)
             else
               circuit[:failures] += 0.5
               if circuit[:failures] >= @failure_threshold
                 circuit[:state]     = :open
                 circuit[:opened_at] = Time.now
+                Legion::Logging.warn("Circuit closed->open for provider=#{provider} (quality failures=#{circuit[:failures]})") if defined?(Legion::Logging)
               end
             end
           end
@@ -152,7 +161,9 @@ module Legion
           return 0 if avg <= LATENCY_THRESHOLD_MS
 
           multiplier = (avg / LATENCY_THRESHOLD_MS).floor
-          [LATENCY_PENALTY_STEP * multiplier, OPEN_PENALTY].max
+          penalty = [LATENCY_PENALTY_STEP * multiplier, OPEN_PENALTY].max
+          Legion::Logging.debug("Latency penalty applied to provider=#{provider} avg_ms=#{avg.round} penalty=#{penalty}") if defined?(Legion::Logging)
+          penalty
         end
       end
     end

data/lib/legion/llm/router/rule.rb

@@ -39,9 +39,17 @@ module Legion
 
         def matches_intent?(intent)
           @conditions.all? do |key, value|
-            return false unless intent.key?(key)
+            unless intent.key?(key)
+              Legion::Logging.debug("Rule '#{@name}' rejected: missing intent key=#{key}") if defined?(Legion::Logging)
+              return false
+            end
 
-            intent[key].to_s == value.to_s
+            unless intent[key].to_s == value.to_s
+              Legion::Logging.debug("Rule '#{@name}' rejected: intent #{key}=#{intent[key]} != #{value}") if defined?(Legion::Logging)
+              return false
+            end
+
+            true
           end
         end
 
@@ -60,17 +68,32 @@ module Legion
 
           sched = @schedule.transform_keys(&:to_s)
           now = localize(now, sched['timezone'])
-
-          return false if sched['valid_from']  && now < Time.parse(sched['valid_from'])
-          return false if sched['valid_until'] && now > Time.parse(sched['valid_until'])
-          return false if sched['hours'] && !within_hours?(sched['hours'], now)
-          return false if sched['days']  && !on_allowed_day?(sched['days'], now)
-
-          true
+          schedule_rejection(sched, now).nil?
         end
 
         private
 
+        def schedule_rejection(sched, now)
+          if sched['valid_from'] && now < Time.parse(sched['valid_from'])
+            Legion::Logging.debug("Rule '#{@name}' rejected: before valid_from=#{sched['valid_from']}") if defined?(Legion::Logging)
+            return :valid_from
+          end
+          if sched['valid_until'] && now > Time.parse(sched['valid_until'])
+            Legion::Logging.debug("Rule '#{@name}' rejected: after valid_until=#{sched['valid_until']}") if defined?(Legion::Logging)
+            return :valid_until
+          end
+          if sched['hours'] && !within_hours?(sched['hours'], now)
+            Legion::Logging.debug("Rule '#{@name}' rejected: outside schedule hours=#{sched['hours']}") if defined?(Legion::Logging)
+            return :hours
+          end
+          if sched['days'] && !on_allowed_day?(sched['days'], now)
+            Legion::Logging.debug("Rule '#{@name}' rejected: outside schedule days=#{sched['days']}") if defined?(Legion::Logging)
+            return :days
+          end
+
+          nil
+        end
+
         def localize(time, timezone_name)
           return time unless timezone_name
 

data/lib/legion/llm/router.rb

@@ -28,7 +28,17 @@ module Legion
           rules = load_rules
           candidates = select_candidates(rules, merged)
           best = pick_best(candidates)
-          best&.to_resolution
+          resolution = best&.to_resolution
+
+          if resolution
+            if defined?(Legion::Logging)
+              Legion::Logging.info("Routed to tier=#{resolution.tier} provider=#{resolution.provider} model=#{resolution.model} via rule='#{resolution.rule}'")
+            end
+          elsif defined?(Legion::Logging)
+            Legion::Logging.debug('Router: no rules matched, resolution is nil')
+          end
+
+          resolution
         end
 
         def resolve_chain(intent: nil, tier: nil, model: nil, provider: nil, max_escalations: nil)
@@ -100,6 +110,8 @@ module Legion
         end
 
         def select_candidates(rules, intent)
+          Legion::Logging.debug("Router: selecting candidates from #{rules.size} rules") if defined?(Legion::Logging)
+
           # 1. Collect constraints from constraint rules that match the intent
           constraints = rules
                         .select { |r| r.constraint && r.matches_intent?(intent) }
@@ -118,7 +130,11 @@ module Legion
           discovered = unconstrained.reject { |r| excluded_by_discovery?(r) }
 
           # 5. Filter by tier availability
-          discovered.select { |r| tier_available?(r.target[:tier] || r.target['tier']) }
+          final = discovered.select { |r| tier_available?(r.target[:tier] || r.target['tier']) }
+
+          Legion::Logging.debug("Router: #{final.size} candidates after filtering (started with #{rules.size})") if defined?(Legion::Logging)
+
+          final
         end
 
         def excluded_by_constraint?(rule, constraints)

data/lib/legion/llm/scheduling.rb

@@ -24,7 +24,9 @@ module Legion
           return false unless enabled?
           return false if urgency.to_sym == :immediate
 
-          eligible_for_deferral?(intent.to_sym) && peak_hours?
+          result = eligible_for_deferral?(intent.to_sym) && peak_hours?
+          Legion::Logging.debug("Scheduling defer decision intent=#{intent} urgency=#{urgency} defer=#{result}") if defined?(Legion::Logging)
+          result
         end
 
         # Returns true if the current UTC hour falls within the configured peak window.

data/lib/legion/llm/shadow_eval.rb

@@ -17,6 +17,7 @@ module Legion
 
         def evaluate(primary_response:, messages: nil, shadow_model: nil) # rubocop:disable Lint/UnusedMethodArgument
           shadow_model ||= Legion::Settings.dig(:llm, :shadow, :model) || 'gpt-4o-mini'
+          Legion::Logging.debug("ShadowEval triggered primary_model=#{primary_response[:model]} shadow_model=#{shadow_model}") if defined?(Legion::Logging)
 
           shadow_response = Legion::LLM.send(:chat_single,
                                              model: shadow_model, provider: nil,
@@ -27,6 +28,7 @@ module Legion
           Legion::Events.emit('llm.shadow_eval', comparison) if defined?(Legion::Events)
           comparison
         rescue StandardError => e
+          Legion::Logging.warn("ShadowEval failed shadow_model=#{shadow_model}: #{e.message}") if defined?(Legion::Logging)
           { error: e.message, shadow_model: shadow_model }
         end
 

data/lib/legion/llm/structured_output.rb

@@ -26,6 +26,7 @@ module Legion
                                                 json_schema: { name: 'response', schema: schema } },
                              **opts.except(:attempt))
           else
+            Legion::Logging.debug("StructuredOutput using prompt-based fallback for model=#{model}") if defined?(Legion::Logging)
             instruction = "You MUST respond with valid JSON matching this schema:\n" \
                           "```json\n#{Legion::JSON.dump(schema)}\n```\n" \
                           'Respond with ONLY the JSON object, no other text.'
@@ -37,8 +38,10 @@ module Legion
         end
 
         def handle_parse_error(error, messages, schema, model, result, **opts)
-          if retry_enabled? && (opts[:attempt] || 0) < max_retries
-            retry_with_instruction(messages, schema, model, attempt: (opts[:attempt] || 0) + 1, **opts)
+          attempt = opts[:attempt] || 0
+          Legion::Logging.warn("StructuredOutput JSON parse failure attempt=#{attempt} model=#{model}: #{error.message}") if defined?(Legion::Logging)
+          if retry_enabled? && attempt < max_retries
+            retry_with_instruction(messages, schema, model, attempt: attempt + 1, **opts)
           else
             { data: nil, error: "JSON parse failed: #{error.message}", raw: result&.dig(:content), valid: false }
           end

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.3.17'
+    VERSION = '0.3.18'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.3.17
+  version: 0.3.18
 platform: ruby
 authors:
 - Esity