lex-llm 0.4.8 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1babd0169f0795262a38d54afd99e737b647e9dffd3a6066a480cdabd45ba072
-  data.tar.gz: f6b1433ab12a083ace1c22814a4b0525c57c0ce52ebddf710fdd4358bb92203e
+  metadata.gz: e2b7839d1fcb47e176aa62970f3ec40d04b9e25095418285d3cf6a5d492ccb8d
+  data.tar.gz: f444cd5054325a007f05749d6d4a2ca0933bf1f5b7004b2585daaa97745eb337
 SHA512:
-  metadata.gz: aebc2f2c85f5d06c4c5d9409d071f6043a6e3e53fbe23f474f0cfea9b452dc5ae2da44c7c44281562797d09621dc9287062c37f9d3710e76b02ea8d79d6712ec
-  data.tar.gz: 698e2b35ef850a75d845860ac5342b45f2eb4d0a570f77e1a3e76ea0e93bbe9cd6b44d9f7b1d1beecb1936c6cd4df58989a3ea394a3394f2978cd057b3b60935
+  metadata.gz: 7412bc0234b379941ae045fa826f267d97b1577dba15ee7268957d62c999808e27392d9acf65d0bf464c31aa7365e3912642a4b0041eb92294f108c4203d8f38
+  data.tar.gz: a90e99a7c61f6fda2ffc4d2e4fd6b2fcba6f69bf75d5da526cacef550c345aadd157ea1ee6efeae59e3f69160a8e6ad92237a31997e9ef259c69dc29a6db01e6

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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/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,9 +75,10 @@ module Legion
         end
 
         def setup_logging(faraday)
+          logger = faraday_logger
           faraday.response :logger,
-                           Legion::Extensions::Llm.logger,
-                           bodies: Legion::Extensions::Llm.logger.debug?,
+                           logger,
+                           bodies: debug_logger?(logger),
                            errors: true,
                            headers: false,
                            log_level: :debug do |logger|
@@ -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)
@@ -168,7 +177,8 @@ 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
 
@@ -199,7 +209,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 +232,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

@@ -75,6 +75,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(
@@ -330,7 +343,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,7 +366,8 @@ 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
 
@@ -368,7 +383,8 @@ module Legion
           return yield unless defined?(Legion::Cache)
 
           cache_local_instance? ? local_cache_fetch(key, ttl: ttl, &) : cache_fetch(key, ttl: ttl, &)
-        rescue StandardError
+        rescue StandardError => e
+          handle_exception(e, level: :debug, handled: true, operation: 'llm.provider.model_cache_fetch', key:)
           yield
         end
 
@@ -593,6 +609,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.9'
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.4.8
+  version: 0.4.9
 platform: ruby
 authors:
 - LegionIO