lex-llm 0.4.8 → 0.4.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1babd0169f0795262a38d54afd99e737b647e9dffd3a6066a480cdabd45ba072
-  data.tar.gz: f6b1433ab12a083ace1c22814a4b0525c57c0ce52ebddf710fdd4358bb92203e
+  metadata.gz: a203372d751b290a71cc289e382d80a49fafcc0687925c02594b8c5cfe6ef7aa
+  data.tar.gz: 95cfd5a03c002a16da80bac58914f1fb808a940db378d99035f97b6256240863
 SHA512:
-  metadata.gz: aebc2f2c85f5d06c4c5d9409d071f6043a6e3e53fbe23f474f0cfea9b452dc5ae2da44c7c44281562797d09621dc9287062c37f9d3710e76b02ea8d79d6712ec
-  data.tar.gz: 698e2b35ef850a75d845860ac5342b45f2eb4d0a570f77e1a3e76ea0e93bbe9cd6b44d9f7b1d1beecb1936c6cd4df58989a3ea394a3394f2978cd057b3b60935
+  metadata.gz: 645bde1f8e4b6701fa5092f2b92e2867f63d243c239341e691921efa9cc74a861b3382f00665efd8f4d1420976c462f9c47eaa89bdae93ae60655983681bcddc
+  data.tar.gz: f180a90275c427970e6129ae3f0ef285fabb68fa92a97059687fb37fcf9282f5e083b159f3757293a79ae4bf71f263a54fb9387469f55da25a23959e295d2371

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.10 - 2026-05-13
+
+- Add cache-backed `model_detail` lookup with 24-hour TTL; nil results are not cached; `fetch_model_detail` hook for subclasses to override with live API calls.
+- Build `model_detail_cache_key` from tier, slug, instance, and credential fingerprint so remote providers never share model detail entries across credentials.
+- Add `credential_cache_fragment` — includes an 8-char SHA-256 credential fingerprint in cache keys for non-local providers.
+- Add `source_tag`, `credential_fingerprint`, and `config_fingerprint` to `CredentialSources` for provenance tracking across discovered instances.
+- Suppress Faraday raw stacktrace dumps on connection failures by setting `errors: false` on the response logger middleware.
+- Rescue `Faraday::ConnectionFailed` in `discover_offerings` and return an empty list with a concise warning instead of propagating the exception.
+- Wire `model_allowed?` filtering into `discover_offerings` so whitelist/blacklist settings are enforced during live discovery (was dead code before).
+- Check instance config first for `model_whitelist`/`model_blacklist` before falling back to provider settings, enabling per-instance override.
+- Add `legion-cache >= 1.3.0` as a runtime dependency and include `Legion::Cache::Helper` in the base `Provider` class.
+
+## 0.4.9 - 2026-05-13
+
+- Route provider, tool, streaming, model, attachment, connection, credential, and fleet diagnostics through `Legion::Logging::Helper`.
+- Replace temporary provider and stream probes with helper-backed debug logs that preserve model, tool, parameter, and header-key context without stdout or fatal-level noise.
+- Add handled debug exception logging around provider discovery, credential probes, and fleet cleanup fallbacks.
+- Fix provider request debug logging when callers pass tools as a hash.
+
 ## 0.4.8 - 2026-05-11
 
 - Set `remote_invocable?` to false — this extension does not need remote AMQP topology (exchanges, queues, DLX).

data/lex-llm.gemspec

@@ -35,6 +35,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'faraday-multipart', '>= 1'
   spec.add_dependency 'faraday-net_http', '>= 1'
   spec.add_dependency 'faraday-retry', '>= 1'
+  spec.add_dependency 'legion-cache', '>= 1.3.0'
   spec.add_dependency 'legion-crypt', '>= 1.5.1'
   spec.add_dependency 'legion-json', '>= 1.2.1'
   spec.add_dependency 'legion-logging', '>= 1.3.2'

data/lib/legion/extensions/llm/attachment.rb

@@ -8,6 +8,8 @@ module Legion
     module Llm
       # A class representing a file attachment.
       class Attachment
+        include Legion::Logging::Helper
+
         attr_reader :source, :filename, :mime_type
 
         def initialize(source, filename: nil)
@@ -50,9 +52,7 @@ module Legion
           elsif io_like?
             load_content_from_io
           else
-            Legion::Extensions::Llm.logger.warn(
-              "Source is neither a URL, path, ActiveStorage, nor IO-like: #{@source.class}"
-            )
+            log.warn { "Source is neither a URL, path, ActiveStorage, nor IO-like: #{@source.class}" }
             nil
           end
 

data/lib/legion/extensions/llm/configuration.rb

@@ -5,6 +5,8 @@ module Legion
     module Llm
       # Global configuration for Legion::Extensions::Llm
       class Configuration
+        include Legion::Logging::Helper
+
         class << self
           # Declare a single configuration option.
           def option(key, default = nil)
@@ -68,7 +70,7 @@ module Legion
           elsif Regexp.respond_to?(:timeout)
             @log_regexp_timeout = value
           else
-            Legion::Extensions::Llm.logger.warn("log_regexp_timeout is not supported on Ruby #{RUBY_VERSION}")
+            log.warn { "log_regexp_timeout is not supported on Ruby #{RUBY_VERSION}" }
             @log_regexp_timeout = value
           end
         end

data/lib/legion/extensions/llm/connection.rb

@@ -5,18 +5,34 @@ module Legion
     module Llm
       # Connection class for managing API connections to various providers.
       class Connection
+        include Legion::Logging::Helper
+
         attr_reader :provider, :connection, :config
 
-        def self.basic(&)
-          Faraday.new do |f|
-            f.response :logger,
-                       Legion::Extensions::Llm.logger,
-                       bodies: false,
-                       errors: true,
-                       headers: false,
-                       log_level: :debug
-            f.response :raise_error
-            yield f if block_given?
+        class << self
+          include Legion::Logging::Helper
+
+          def basic(&)
+            logger = faraday_logger
+            Faraday.new do |f|
+              f.response :logger,
+                         logger,
+                         bodies: false,
+                         errors: true,
+                         headers: false,
+                         log_level: :debug
+              f.response :raise_error
+              yield f if block_given?
+            end
+          end
+
+          private
+
+          def faraday_logger
+            config = Legion::Extensions::Llm.config
+            return config.logger if config.respond_to?(:logger) && config.logger
+
+            log
           end
         end
 
@@ -59,10 +75,11 @@ module Legion
         end
 
         def setup_logging(faraday)
+          logger = faraday_logger
           faraday.response :logger,
-                           Legion::Extensions::Llm.logger,
-                           bodies: Legion::Extensions::Llm.logger.debug?,
-                           errors: true,
+                           logger,
+                           bodies: debug_logger?(logger),
+                           errors: false,
                            headers: false,
                            log_level: :debug do |logger|
             logger.filter(logging_regexp('[A-Za-z0-9+/=]{100,}'), '[BASE64 DATA]')
@@ -70,6 +87,19 @@ module Legion
           end
         end
 
+        def faraday_logger
+          return config.logger if config.respond_to?(:logger) && config.logger
+
+          log
+        end
+
+        def debug_logger?(logger)
+          return logger.debug? if logger.respond_to?(:debug?)
+          return logger.level.to_i <= Logger::DEBUG if logger.respond_to?(:level)
+
+          false
+        end
+
         def logging_regexp(pattern)
           return Regexp.new(pattern) if @config.log_regexp_timeout.nil? || !Regexp.respond_to?(:timeout)
 

data/lib/legion/extensions/llm/credential_sources.rb

@@ -11,6 +11,9 @@ module Legion
       # network probes).  All methods are pure readers — the calling provider
       # decides what to do with the result.
       module CredentialSources
+        include Legion::Logging::Helper
+        extend Legion::Logging::Helper
+
         CLAUDE_SETTINGS = File.expand_path('~/.claude/settings.json')
         CLAUDE_PROJECT  = File.join(Dir.pwd, '.claude', 'settings.json')
         CODEX_AUTH      = File.expand_path('~/.codex/auth.json')
@@ -79,7 +82,9 @@ module Legion
           return nil unless defined?(::Legion::Settings)
 
           ::Legion::Settings.dig(*path)
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.setting',
+                              path: path.map(&:to_s))
           nil
         end
 
@@ -104,7 +109,9 @@ module Legion
             end
           end
           true
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.socket_open',
+                              host:, port:)
           false
         ensure
           sock&.close
@@ -120,7 +127,9 @@ module Legion
           end
           response = conn.get(path)
           response.status >= 200 && response.status < 300
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.http_ok',
+                              path:)
           false
         ensure
           conn&.close if conn.respond_to?(:close)
@@ -158,6 +167,30 @@ module Legion
           Digest::SHA256.hexdigest(val.to_s)
         end
 
+        # Build a human-readable source tag describing where a credential was found.
+        # Format: "type:location:key" e.g. "env:ANTHROPIC_API_KEY", "file:~/.claude/settings.json:anthropicApiKey"
+        def source_tag(type, location, key = nil)
+          parts = [type.to_s, location.to_s]
+          parts << key.to_s if key && !key.to_s.empty?
+          parts.join(':')
+        end
+
+        # Generate a short fingerprint (first 8 chars of SHA-256) for a credential value.
+        # Stable for the lifetime of the credential; safe to log and include in audit events.
+        def credential_fingerprint(value)
+          return nil if value.nil? || value.to_s.strip.empty?
+
+          Digest::SHA256.hexdigest(value.to_s)[0, 8]
+        end
+
+        # Extract fingerprint from a config hash by finding the first credential field.
+        def config_fingerprint(config)
+          val = config[:api_key] || config['api_key'] ||
+                config[:bearer_token] || config['bearer_token'] ||
+                config[:access_token] || config['access_token']
+          credential_fingerprint(val)
+        end
+
         # Returns true when the URL points to localhost / 127.0.0.1 / ::1.
         def localhost?(url)
           return false if url.nil?
@@ -168,14 +201,17 @@ module Legion
 
           normalized = host.delete_prefix('[').delete_suffix(']')
           %w[localhost 127.0.0.1 ::1].include?(normalized)
-        rescue URI::InvalidURIError
+        rescue URI::InvalidURIError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.localhost')
           false
         end
 
         module_function :env, :claude_config, :claude_config_value,
                         :claude_env_value, :codex_token, :codex_openai_key,
                         :setting, :socket_open?, :http_ok?,
-                        :dedup_credentials, :credential_hash, :localhost?
+                        :dedup_credentials, :credential_hash,
+                        :source_tag, :credential_fingerprint, :config_fingerprint,
+                        :localhost?
 
         # --- private helpers -----------------------------------------------
 
@@ -199,7 +235,9 @@ module Legion
           else
             ::JSON.parse(raw, symbolize_names: true)
           end
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.read_json',
+                              path:)
           {}
         end
 
@@ -220,7 +258,8 @@ module Legion
           return true if exp.nil?
 
           exp.to_i > Time.now.to_i
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.credential_sources.token_valid')
           true
         end
 

data/lib/legion/extensions/llm/fleet/provider_responder.rb

@@ -22,6 +22,9 @@ module Legion
       module Fleet
         # Shared implementation for provider-owned fleet responder runners.
         module ProviderResponder
+          include Legion::Logging::Helper
+          extend Legion::Logging::Helper
+
           class ConfigurationError < StandardError; end
 
           REQUIRED_FIELDS = %i[
@@ -71,6 +74,8 @@ module Legion
             ack(delivery || properties)
             response
           rescue StandardError => e
+            handle_exception(e, level: :warn, handled: false, operation: 'llm.fleet.provider_responder.call',
+                                provider_family:)
             safe_publish_error(envelope, e) if defined?(envelope) && envelope
             reject(delivery || properties, requeue: requeue_error?(e))
             raise
@@ -165,7 +170,10 @@ module Legion
 
           def safe_publish_error(envelope, error)
             publish_error(envelope, error)
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true,
+                                operation: 'llm.fleet.provider_responder.safe_publish_error',
+                                error_class: error.class.name)
             nil
           end
 

data/lib/legion/extensions/llm/fleet/publish_safety.rb

@@ -6,6 +6,8 @@ module Legion
       module Fleet
         # Publish-result helpers kept local to fleet messages so they work with older legion-transport releases.
         module PublishSafety
+          include Legion::Logging::Helper
+
           private
 
           def return_publish_result?(options)

data/lib/legion/extensions/llm/fleet/settings.rb

@@ -6,6 +6,9 @@ module Legion
       module Fleet
         # Reads fleet settings from Legion::Settings when available, falling back to lex-llm defaults.
         module Settings
+          include Legion::Logging::Helper
+          extend Legion::Logging::Helper
+
           module_function
 
           def value(*path, default:)
@@ -29,7 +32,8 @@ module Legion
             llm = safe_fetch(::Legion::Settings, :llm)
             configured << llm if llm.respond_to?(:key?)
             configured
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'llm.fleet.settings.configured')
             []
           end
 
@@ -49,7 +53,9 @@ module Legion
 
           def safe_fetch(source, key)
             source[key] || source[key.to_s]
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'llm.fleet.settings.safe_fetch',
+                                key: key.to_s)
             nil
           end
 

data/lib/legion/extensions/llm/fleet/token_validator.rb

@@ -12,6 +12,9 @@ module Legion
       module Fleet
         # Verifies responder-side fleet JWTs and prevents replay on provider nodes.
         module TokenValidator
+          include Legion::Logging::Helper
+          extend Legion::Logging::Helper
+
           @seen_jtis = Concurrent::Map.new
           @replay_mutex = Mutex.new
 
@@ -35,6 +38,7 @@ module Legion
           rescue TokenError
             raise
           rescue StandardError => e
+            handle_exception(e, level: :warn, handled: false, operation: 'llm.fleet.token_validator.validate')
             raise TokenError, "fleet token verification failed: #{e.message}"
           end
 
@@ -167,6 +171,7 @@ module Legion
           rescue TokenError
             raise
           rescue StandardError => e
+            handle_exception(e, level: :warn, handled: false, operation: 'llm.fleet.token_validator.signing_key')
             raise TokenError, "no signing key available: #{e.message}"
           end
 

data/lib/legion/extensions/llm/fleet/worker_execution.rb

@@ -11,6 +11,9 @@ module Legion
       module Fleet
         # Applies responder-side policy and dispatches a fleet request to a local lex-llm provider.
         module WorkerExecution
+          include Legion::Logging::Helper
+          extend Legion::Logging::Helper
+
           class PolicyError < StandardError; end
 
           @idempotency_keys = Concurrent::Map.new
@@ -29,10 +32,12 @@ module Legion
             TokenValidator.mark_replay!(claims[:jti]) if claims.is_a?(Hash)
             response
           rescue TokenError => e
+            handle_exception(e, level: :warn, handled: false, operation: 'llm.fleet.worker_execution.identity')
             release_idempotency!(idempotency_key) if idempotency_key
             release_replay!(claims)
             raise PolicyError, e.message
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: false, operation: 'llm.fleet.worker_execution.call')
             release_idempotency!(idempotency_key) if idempotency_key
             release_replay!(claims)
             raise

data/lib/legion/extensions/llm/models.rb

@@ -169,7 +169,7 @@ module Legion
           end
 
           def fetch_models_dev_models(existing_models) # rubocop:disable Metrics/PerceivedComplexity
-            Legion::Extensions::Llm.logger.info 'Fetching models from models.dev API...'
+            log.info 'Fetching models from models.dev API...'
 
             connection = Connection.basic do |f|
               f.request :json
@@ -202,11 +202,11 @@ module Legion
           end
 
           def log_provider_fetch(provider_fetch)
-            Legion::Extensions::Llm.logger.info(
+            log.info(
               "Fetching models from providers: #{provider_fetch[:configured_names].join(', ')}"
             )
             provider_fetch[:failed].each do |failure|
-              Legion::Extensions::Llm.logger.warn(
+              log.warn(
                 "Failed to fetch #{failure[:name]} models (#{failure[:error].class}: #{failure[:error].message}). " \
                 'Keeping existing.'
               )
@@ -216,7 +216,7 @@ module Legion
           def log_models_dev_fetch(models_dev_fetch)
             return if models_dev_fetch[:fetched]
 
-            Legion::Extensions::Llm.logger.warn('Using cached models.dev data due to fetch failure.')
+            log.warn('Using cached models.dev data due to fetch failure.')
           end
 
           def merge_with_existing(existing_models, provider_fetch, models_dev_fetch)

data/lib/legion/extensions/llm/provider.rb

@@ -28,6 +28,7 @@ module Legion
       class Provider
         include Streaming
         include Legion::Logging::Helper
+        include Legion::Cache::Helper
 
         attr_reader :config, :connection
 
@@ -75,6 +76,19 @@ module Legion
         def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, thinking: nil,
                      tool_prefs: nil, &)
           normalized_temperature = maybe_normalize_temperature(temperature, model)
+          log_provider_request(
+            messages: messages,
+            tools: tools,
+            temperature: temperature,
+            normalized_temperature: normalized_temperature,
+            model: model,
+            params: params,
+            headers: headers,
+            schema: schema,
+            thinking: thinking,
+            tool_prefs: tool_prefs,
+            streaming: block_given?
+          )
 
           payload = Utils.deep_merge(
             render_payload(
@@ -110,10 +124,14 @@ module Legion
           provider_health = health(live:)
           @cached_offerings = Array(list_models(live:, **filters)).filter_map do |model|
             next unless model_matches_filters?(model, filters)
+            next unless model_allowed?(model.id)
 
             offering_from_model(model, health: provider_health)
           end
           @cached_offerings
+        rescue Faraday::ConnectionFailed => e
+          log.warn("[#{slug}] instance=#{provider_instance_id} unreachable: #{e.message}")
+          []
         end
 
         def health(live: false)
@@ -271,12 +289,14 @@ module Legion
         # ── Model allow-list / deny-list filtering ────────────────────────
 
         def model_whitelist
-          wl = settings[:model_whitelist] if respond_to?(:settings)
+          wl = config.model_whitelist if config.respond_to?(:model_whitelist)
+          wl ||= settings[:model_whitelist] if respond_to?(:settings)
           Array(wl).map { |p| p.to_s.downcase }
         end
 
         def model_blacklist
-          bl = settings[:model_blacklist] if respond_to?(:settings)
+          bl = config.model_blacklist if config.respond_to?(:model_blacklist)
+          bl ||= settings[:model_blacklist] if respond_to?(:settings)
           Array(bl).map { |p| p.to_s.downcase }
         end
 
@@ -330,7 +350,8 @@ module Legion
           uri = URI.parse(url)
           Socket.tcp(uri.host, uri.port, connect_timeout: 1).close
           true
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.provider.url_reachable', url:)
           false
         end
 
@@ -352,24 +373,29 @@ module Legion
           return nil unless defined?(Legion::Cache)
 
           cache_local_instance? ? local_cache_get(key) : cache_get(key)
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.provider.model_cache_get', key:)
           nil
         end
 
-        def model_cache_set(key, value, ttl:)
-          return unless defined?(Legion::Cache)
+        def model_detail(model_name)
+          key = model_detail_cache_key(model_name)
+          cached = cache_get(key)
+          return cached if cached
 
-          cache_local_instance? ? local_cache_set(key, value, ttl: ttl) : cache_set(key, value, ttl: ttl)
+          result = fetch_model_detail(model_name)
+          cache_set(key, result, ttl: 86_400) if result
+          result
         rescue StandardError => e
-          handle_exception(e, level: :debug, handled: true, operation: 'lex.provider.model_cache_set')
+          handle_exception(e, level: :warn, handled: true, operation: 'llm.provider.model_detail',
+                              model: model_name)
+          nil
         end
 
-        def model_cache_fetch(key, ttl:, &)
-          return yield unless defined?(Legion::Cache)
-
-          cache_local_instance? ? local_cache_fetch(key, ttl: ttl, &) : cache_fetch(key, ttl: ttl, &)
-        rescue StandardError
-          yield
+        # Override in subclasses to make a live API call for model detail.
+        # Must return a Hash with symbol keys (e.g. { context_window: 128000 }).
+        def fetch_model_detail(_model_name)
+          nil
         end
 
         def cache_instance_key
@@ -432,6 +458,26 @@ module Legion
 
         private
 
+        def model_detail_cache_key(model_name)
+          tier = offering_tier
+          instance_key = cache_instance_key
+          cred_fp = credential_cache_fragment
+          key_parts = ['model_info', tier, slug, instance_key, cred_fp, model_name].compact
+          key_parts.join('.')
+        end
+
+        def credential_cache_fragment
+          return nil if cache_local_instance?
+
+          cred = config.respond_to?(:bearer_token) && config.bearer_token
+          cred ||= config.respond_to?(:api_key) && config.api_key
+          cred ||= config.respond_to?(:bedrock_access_key_id) && config.bedrock_access_key_id
+          return nil unless cred
+
+          require 'digest'
+          Digest::SHA256.hexdigest(cred.to_s)[0, 8]
+        end
+
         def validate_paint_inputs!(with:, mask:)
           return if with.nil? && mask.nil?
 
@@ -593,6 +639,53 @@ module Legion
           temperature
         end
 
+        def log_provider_request(context)
+          log.debug do
+            "Preparing provider completion: provider=#{slug} model=#{debug_model_id(context[:model])} " \
+              "streaming=#{context[:streaming]} messages=#{Array(context[:messages]).size} " \
+              "tools=#{debug_tool_names(context[:tools]).inspect} " \
+              "temperature=#{context[:temperature].inspect} " \
+              "normalized_temperature=#{context[:normalized_temperature].inspect} " \
+              "param_keys=#{debug_hash_keys(context[:params]).inspect} " \
+              "header_keys=#{debug_hash_keys(context[:headers]).inspect} " \
+              "schema=#{debug_value_summary(context[:schema])} " \
+              "thinking=#{debug_value_summary(context[:thinking])} " \
+              "tool_prefs=#{debug_value_summary(context[:tool_prefs])}"
+          end
+        end
+
+        def debug_model_id(model)
+          return model.id if model.respond_to?(:id)
+
+          model
+        end
+
+        def debug_tool_names(tools)
+          tool_definitions = tools.is_a?(Hash) ? tools.values : Array(tools)
+
+          tool_definitions.filter_map do |tool|
+            if tool.respond_to?(:name)
+              tool.name
+            elsif tool.is_a?(Hash)
+              tool[:name] || tool['name']
+            else
+              tool.class.name
+            end
+          end
+        end
+
+        def debug_hash_keys(value)
+          value.respond_to?(:keys) ? value.keys.map(&:to_s).sort : []
+        end
+
+        def debug_value_summary(value)
+          return 'nil' if value.nil?
+          return "#{value.class}(keys=#{debug_hash_keys(value).inspect})" if value.respond_to?(:keys)
+          return "#{value.class}(size=#{value.size})" if value.respond_to?(:size)
+
+          value.class.name
+        end
+
         def endpoint_methods
           {
             completion: :completion_url,

data/lib/legion/extensions/llm/stream_accumulator.rb

@@ -25,7 +25,7 @@ module Legion
         end
 
         def add(chunk)
-          Legion::Extensions::Llm.logger.debug { chunk.inspect } if Legion::Extensions::Llm.config.log_stream_debug
+          log.debug { chunk.inspect } if Legion::Extensions::Llm.config.log_stream_debug
           @model_id ||= chunk.model_id
 
           @last_content_delta = +''
@@ -33,7 +33,7 @@ module Legion
           handle_chunk_content(chunk)
           append_thinking_from_chunk(chunk)
           count_tokens chunk
-          Legion::Extensions::Llm.logger.debug { inspect } if Legion::Extensions::Llm.config.log_stream_debug
+          log.debug { inspect } if Legion::Extensions::Llm.config.log_stream_debug
         end
 
         def filtered_chunk(chunk) # rubocop:disable Metrics/PerceivedComplexity
@@ -101,9 +101,7 @@ module Legion
         end
 
         def accumulate_tool_calls(new_tool_calls)
-          if Legion::Extensions::Llm.config.log_stream_debug
-            Legion::Extensions::Llm.logger.debug { "Accumulating tool calls: #{new_tool_calls}" }
-          end
+          log.debug { "Accumulating tool calls: #{new_tool_calls}" } if Legion::Extensions::Llm.config.log_stream_debug
           new_tool_calls.each_value do |tool_call|
             if tool_call.id
               start_tool_call(tool_call)

data/lib/legion/extensions/llm/streaming.rb

@@ -5,6 +5,9 @@ module Legion
     module Llm
       # Handles streaming responses from AI providers.
       module Streaming
+        include Legion::Logging::Helper
+        extend Legion::Logging::Helper
+
         module_function
 
         def stream_response(connection, payload, additional_headers = {}, &block)
@@ -13,6 +16,9 @@ module Legion
           response = connection.post stream_url, payload do |req|
             req.headers = additional_headers.merge(req.headers) unless additional_headers.empty?
             on_chunk = build_stream_callback(accumulator, block)
+            if Legion::Extensions::Llm.config.log_stream_debug
+              log.debug { "Stream callback prepared: #{on_chunk.inspect}" }
+            end
             if faraday_1?
               req.options[:on_data] = handle_stream(&on_chunk)
             else
@@ -21,7 +27,7 @@ module Legion
           end
 
           message = accumulator.to_message(response)
-          Legion::Extensions::Llm.logger.debug { "Stream completed: #{message.content}" }
+          log.debug { "Stream completed: #{message.content}" }
           message
         end
 
@@ -57,9 +63,7 @@ module Legion
         end
 
         def process_stream_chunk(chunk, parser, env, &)
-          if Legion::Extensions::Llm.config.log_stream_debug
-            Legion::Extensions::Llm.logger.debug { "Received chunk: #{chunk}" }
-          end
+          log.debug { "Received chunk: #{chunk}" } if Legion::Extensions::Llm.config.log_stream_debug
 
           if error_chunk?(chunk)
             handle_error_chunk(chunk, env)

data/lib/legion/extensions/llm/tool.rb

@@ -19,6 +19,8 @@ module Legion
 
       # Base class for creating tools that AI models can use
       class Tool
+        include Legion::Logging::Helper
+
         # Stops conversation continuation after tool execution
         class Halt
           attr_reader :content
@@ -105,9 +107,9 @@ module Legion
           validation_error = validate_keyword_arguments(normalized_args)
           return { error: "Invalid tool arguments: #{validation_error}" } if validation_error
 
-          Legion::Extensions::Llm.logger.debug { "Tool #{name} called with: #{normalized_args.inspect}" }
+          log.debug { "Tool #{name} called with: #{normalized_args.inspect}" }
           result = execute(**normalized_args)
-          Legion::Extensions::Llm.logger.debug { "Tool #{name} returned: #{result.inspect}" }
+          log.debug { "Tool #{name} returned: #{result.inspect}" }
           result
         end
 

data/lib/legion/extensions/llm/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.4.8'
+      VERSION = '0.4.10'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -9,6 +9,15 @@ require 'faraday/multipart'
 require 'faraday/retry'
 require 'legion/json'
 require 'legion/logging'
+# legion/cache writes DEBUG lines to $stdout on first load; suppress them here
+# so callers that capture our stdout (e.g. Open3-based integration tests) are unaffected.
+begin
+  old_stdout = $stdout
+  $stdout = File.open(File::NULL, 'w')
+  require 'legion/cache'
+ensure
+  $stdout = old_stdout
+end
 require 'logger'
 require 'marcel'
 require 'ruby_llm/schema'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.4.8
+  version: 0.4.10
 platform: ruby
 authors:
 - LegionIO
@@ -108,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1'
+- !ruby/object:Gem::Dependency
+  name: legion-cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
 - !ruby/object:Gem::Dependency
   name: legion-crypt
   requirement: !ruby/object:Gem::Requirement