lex-llm 0.4.18 → 0.5.0

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

@@ -80,7 +80,7 @@ module Legion
             /reduce the length of messages/i
           ].freeze
 
-          def parse_error(provider:, response:) # rubocop:disable Metrics/PerceivedComplexity
+          def parse_error(provider:, response:)
             response = response_with_stream_error_body(response)
             message = provider&.parse_error(response)
 
@@ -88,9 +88,7 @@ module Legion
             when 200..399
               message
             when 400
-              if context_length_exceeded?(message)
-                raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
-              end
+              raise ContextLengthExceededError.new(response, message || 'Context length exceeded') if context_length_exceeded?(message)
 
               raise BadRequestError.new(response, message || 'Invalid request - please check your input')
             when 401
@@ -101,9 +99,7 @@ module Legion
               raise ForbiddenError.new(response,
                                        message || 'Forbidden - you do not have permission to access this resource')
             when 429
-              if context_length_exceeded?(message)
-                raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
-              end
+              raise ContextLengthExceededError.new(response, message || 'Context length exceeded') if context_length_exceeded?(message)
 
               raise RateLimitError.new(response, message || 'Rate limit exceeded - please wait a moment')
             when 500

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

@@ -14,9 +14,7 @@ module Legion
 
           def reject_legacy_options!
             LEGACY_OPTIONS.each do |key|
-              if @options.key?(key) || @options.key?(key.to_s)
-                raise ArgumentError, "#{key} is not supported by fleet protocol v2"
-              end
+              raise ArgumentError, "#{key} is not supported by fleet protocol v2" if @options.key?(key) || @options.key?(key.to_s)
             end
           end
 

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

@@ -119,9 +119,7 @@ module Legion
               raise ConfigurationError,
                     "fleet provider instance is not configured: #{instance_id}"
             end
-            unless truthy?(dig(instance_settings, :fleet, :respond_to_requests))
-              raise ConfigurationError, "fleet responses are disabled for provider instance: #{instance_id}"
-            end
+            raise ConfigurationError, "fleet responses are disabled for provider instance: #{instance_id}" unless truthy?(dig(instance_settings, :fleet, :respond_to_requests))
 
             provider_class.new(deep_symbolize(instance_settings))
           end

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

@@ -186,9 +186,7 @@ module Legion
           end
 
           def signing_key
-            if defined?(::Legion::Crypt) && ::Legion::Crypt.respond_to?(:cluster_secret)
-              return ::Legion::Crypt.cluster_secret
-            end
+            return ::Legion::Crypt.cluster_secret if defined?(::Legion::Crypt) && ::Legion::Crypt.respond_to?(:cluster_secret)
 
             raise TokenError, 'no signing key available - Legion::Crypt not initialized'
           rescue TokenError

data/lib/legion/extensions/llm/model/info.rb

@@ -19,7 +19,7 @@ module Legion
           :parameter_size, :quantization, :size_bytes,
           :modalities_input, :modalities_output, :metadata
         ) do
-          # rubocop:disable Metrics/ParameterLists, Metrics/PerceivedComplexity
+          # rubocop:disable Metrics/ParameterLists
           def initialize(
             id:, name: nil, provider: nil, instance: :default,
             family: nil, capabilities: [], context_length: nil,
@@ -46,7 +46,7 @@ module Legion
               metadata: metadata.is_a?(Hash) ? metadata : {}
             )
           end
-          # rubocop:enable Metrics/ParameterLists, Metrics/PerceivedComplexity
+          # rubocop:enable Metrics/ParameterLists
 
           # ── Capability predicates ─────────────────────────────────────
 
@@ -206,11 +206,9 @@ module Legion
           class << self
             private
 
-            def extract_modalities(data) # rubocop:disable Metrics/PerceivedComplexity
+            def extract_modalities(data)
               # New-style keys take priority (round-trip from to_h)
-              if data.key?(:modalities_input) || data.key?(:modalities_output)
-                return [Array(data[:modalities_input]), Array(data[:modalities_output])]
-              end
+              return [Array(data[:modalities_input]), Array(data[:modalities_output])] if data.key?(:modalities_input) || data.key?(:modalities_output)
 
               # Legacy: modalities is a hash or Modalities object
               modalities_data = data[:modalities]

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

@@ -123,7 +123,7 @@ module Legion
             fetch_provider_models(remote_only: remote_only)[:models]
           end
 
-          def resolve(model_id, provider: nil, assume_exists: false, config: nil) # rubocop:disable Metrics/PerceivedComplexity
+          def resolve(model_id, provider: nil, assume_exists: false, config: nil)
             config ||= Legion::Extensions::Llm.config
             provider_class = provider ? resolve_provider_class(provider) : nil
 
@@ -168,7 +168,7 @@ module Legion
             instance.respond_to?(method, include_private) || super
           end
 
-          def fetch_models_dev_models(existing_models) # rubocop:disable Metrics/PerceivedComplexity
+          def fetch_models_dev_models(existing_models)
             log.info 'Fetching models from models.dev API...'
 
             connection = Connection.basic do |f|
@@ -300,7 +300,7 @@ module Legion
             end
           end
 
-          def add_provider_metadata(models_dev_model, provider_model) # rubocop:disable Metrics/PerceivedComplexity
+          def add_provider_metadata(models_dev_model, provider_model)
             data = models_dev_model.to_h
             data[:name] = provider_model.name if blank_value?(data[:name])
             data[:family] = provider_model.family if blank_value?(data[:family])

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

@@ -92,12 +92,16 @@ module Legion
             return nil if tools.empty?
 
             tools.values.map do |tool|
+              # Tools can be ToolDefinition objects or plain Hashes from native_dispatch.
+              tool_name = tool.respond_to?(:name) ? tool.name : (tool[:name] || tool['name'])
+              tool_desc = tool.respond_to?(:description) ? tool.description : (tool[:description] || tool['description'] || '')
+              tool_params = tool.respond_to?(:params_schema) ? tool.params_schema : (tool[:parameters] || tool['parameters'] || {})
               {
                 type: 'function',
                 function: {
-                  name: tool.name,
-                  description: tool.description,
-                  parameters: tool.params_schema || { type: 'object', properties: {} }
+                  name: tool_name,
+                  description: tool_desc,
+                  parameters: tool_params || { type: 'object', properties: {} }
                 }
               }
             end

data/lib/legion/extensions/llm/routing/lane_key.rb

@@ -10,9 +10,7 @@ module Legion
 
           def for(offering, prefix: 'llm.fleet', include_context: true, include_fingerprint: false)
             parts = [prefix, lane_kind(offering), model_slug(lane_model(offering))]
-            if include_context && offering.inference? && offering.context_window
-              parts << "ctx#{offering.context_window}"
-            end
+            parts << "ctx#{offering.context_window}" if include_context && offering.inference? && offering.context_window
             parts.push('elig', eligibility_fingerprint(offering)) if include_fingerprint
             parts.join('.')
           end

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

@@ -39,7 +39,7 @@ module Legion
           log.debug { inspect } if Legion::Extensions::Llm.config.log_stream_debug
         end
 
-        def filtered_chunk(chunk) # rubocop:disable Metrics/PerceivedComplexity
+        def filtered_chunk(chunk)
           has_content = !@last_content_delta.empty?
           has_thinking = !@last_thinking_delta.empty?
           has_tokens = chunk.input_tokens&.positive? || chunk.output_tokens&.positive?

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

@@ -16,9 +16,7 @@ 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
+            log.debug { "Stream callback prepared: #{on_chunk.inspect}" } if Legion::Extensions::Llm.config.log_stream_debug
             if faraday_1?
               req.options[:on_data] = handle_stream(&on_chunk)
             else

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

@@ -235,9 +235,7 @@ module Legion
           def resolve_direct_schema(schema)
             return extract_schema(schema.to_json_schema) if schema.respond_to?(:to_json_schema)
             return Legion::Extensions::Llm::Utils.deep_dup(schema) if schema.is_a?(Hash)
-            if schema.is_a?(Class) && schema.method_defined?(:to_json_schema)
-              return extract_schema(schema.new.to_json_schema)
-            end
+            return extract_schema(schema.new.to_json_schema) if schema.is_a?(Class) && schema.method_defined?(:to_json_schema)
 
             nil
           end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.4.18'
+      VERSION = '0.5.0'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -23,29 +23,125 @@ require 'marcel'
 require 'ruby_llm/schema'
 require 'securerandom'
 require 'time'
-require 'zeitwerk'
 require_relative 'llm/version'
 
 module Legion
   module Extensions
     # Legion-native namespace for the shared LLM provider framework.
     module Llm
-      loader = Zeitwerk::Loader.new
-      loader.tag = 'lex-llm'
-      loader.inflector.inflect(
-        'api' => 'API',
-        'llm' => 'Llm',
-        'open_ai_compatible' => 'OpenAICompatible',
-        'pdf' => 'PDF',
-        'ui' => 'UI'
-      )
-      loader.ignore("#{__dir__}/llm/version.rb")
-      loader.ignore("#{__dir__}/llm/auto_registration.rb")
-      loader.ignore("#{__dir__}/llm/credential_sources.rb")
-      loader.ignore("#{__dir__}/llm/transport/exchanges")
-      loader.ignore("#{__dir__}/llm/transport/messages")
-      loader.push_dir("#{__dir__}/llm", namespace: self)
-      loader.setup
+      # ------------------------------------------------------------------ #
+      #  Explicit requires (replaces Zeitwerk autoloading).                 #
+      #  Load order: base classes & canonical types first, then anything    #
+      #  that references them. All live under Legion::Extensions::Llm so    #
+      #  unqualified constant lookups resolve via Ruby scope.               #
+      # ------------------------------------------------------------------ #
+
+      # --- Base value objects (no internal deps) ---
+      require_relative 'llm/mime_type'
+      require_relative 'llm/model/info'
+      require_relative 'llm/model/modalities'
+      require_relative 'llm/model/pricing_category'
+      require_relative 'llm/model/pricing_tier'
+      require_relative 'llm/model/pricing'
+      require_relative 'llm/configuration'
+      require_relative 'llm/thinking'
+      require_relative 'llm/tokens'
+      require_relative 'llm/message'
+      require_relative 'llm/tool_call'
+      require_relative 'llm/content'
+      require_relative 'llm/errors/unsupported_capability'
+      require_relative 'llm/error'
+
+      # --- Build on message/base types ---
+      require_relative 'llm/chunk'
+      require_relative 'llm/model'
+      require_relative 'llm/attachment'
+
+      # --- Streaming fundamentals (must load before streaming/provider) ---
+      require_relative 'llm/stream_accumulator'
+      require_relative 'llm/responses/stream_chunk'
+      require_relative 'llm/streaming'
+
+      # --- Context, Connection ---
+      require_relative 'llm/context'
+      require_relative 'llm/connection'
+
+      # --- Response normalizers ---
+      require_relative 'llm/responses/chat_response'
+      require_relative 'llm/responses/embedding_response'
+      require_relative 'llm/responses/thinking_extractor'
+
+      # --- Provider base & allied modules ---
+      require_relative 'llm/provider_contract'
+      require_relative 'llm/provider_settings'
+      require_relative 'llm/provider'
+
+      # --- Provider subtypes ---
+      require_relative 'llm/provider/open_ai_compatible'
+
+      # --- Routing ---
+      require_relative 'llm/routing'
+      require_relative 'llm/routing/lane_key'
+      require_relative 'llm/routing/offering_registry'
+      require_relative 'llm/routing/registry_event'
+      require_relative 'llm/routing/model_offering'
+
+      # --- Models (scans for Provider subclasses) ---
+      require_relative 'llm/models'
+
+      # --- Agent & Chat (reference Provider, Context, Chat at method-time) ---
+      require_relative 'llm/agent'
+      require_relative 'llm/chat'
+
+      # --- Domain services ---
+      require_relative 'llm/embedding'
+      require_relative 'llm/moderation'
+      require_relative 'llm/image'
+      require_relative 'llm/transcription'
+
+      # --- Registry & misc support ---
+      require_relative 'llm/registry_event_builder'
+      require_relative 'llm/registry_publisher'
+      require_relative 'llm/auto_registration'
+      require_relative 'llm/credential_sources'
+      require_relative 'llm/tool'
+      require_relative 'llm/utils'
+      require_relative 'llm/aliases'
+
+      # --- Fleet protocol (depends on Provider, Models) ---
+      require_relative 'llm/fleet/protocol'
+      require_relative 'llm/fleet/settings'
+      require_relative 'llm/fleet/token_error'
+      require_relative 'llm/fleet/envelope_validation'
+      require_relative 'llm/fleet/publish_safety'
+      require_relative 'llm/fleet/default_exchange_reply'
+      require_relative 'llm/fleet/token_validator'
+      require_relative 'llm/fleet/worker_execution'
+      require_relative 'llm/fleet/provider_responder'
+
+      # --- Transport lane (references Fleet exchange/message autoloads) ---
+      require_relative 'llm/transport/fleet_lane'
+
+      # --- Canonical types — explicit self-contained loader ---
+      require_relative 'llm/canonical'
+
+      # --- Transport modules (lazy — depend on optional legion-transport) ---
+      # These remain as autoload so boot-time does not force legion-transport.
+      module Transport
+        # Shared AMQP exchange definitions for fleet routing.
+        # Lazy-loaded; only instantiated when legion-transport is available.
+        module Exchanges
+          autoload :Fleet, File.expand_path('llm/transport/exchanges/fleet', __dir__)
+        end
+
+        # Shared AMQP message envelopes for fleet request/response cycles.
+        # Lazy-loaded; only instantiated when legion-transport is available.
+        module Messages
+          autoload :FleetRequest, File.expand_path('llm/transport/messages/fleet_request', __dir__)
+          autoload :FleetResponse, File.expand_path('llm/transport/messages/fleet_response', __dir__)
+          autoload :FleetError, File.expand_path('llm/transport/messages/fleet_error', __dir__)
+        end
+      end
 
       Schema = ::RubyLLM::Schema unless const_defined?(:Schema, false)
 
@@ -148,6 +244,11 @@ module Legion
               require_policy: false,
               require_idempotency: true,
               idempotency_ttl_seconds: 600
+            },
+            request: {
+              logger: {
+                request_payload: false
+              }
             }
           }
         }
@@ -156,24 +257,6 @@ module Legion
       def self.provider_settings(...)
         ProviderSettings.build(...)
       end
-
-      require_relative 'llm/auto_registration'
-      require_relative 'llm/credential_sources'
-      loader.eager_load
-
-      module Transport
-        # Local autoloads for fleet exchange classes that depend on legion-transport.
-        module Exchanges
-          autoload :Fleet, File.expand_path('llm/transport/exchanges/fleet', __dir__)
-        end
-
-        # Local autoloads for fleet message classes that depend on legion-transport.
-        module Messages
-          autoload :FleetRequest, File.expand_path('llm/transport/messages/fleet_request', __dir__)
-          autoload :FleetResponse, File.expand_path('llm/transport/messages/fleet_response', __dir__)
-          autoload :FleetError, File.expand_path('llm/transport/messages/fleet_error', __dir__)
-        end
-      end
     end
   end
 end

data/spec/fixtures/ruby.txt

@@ -0,0 +1 @@
+Ruby is the best.

data/spec/fixtures/ruby.xml

@@ -0,0 +1 @@
+<truism>Ruby is the best</truism>

data/spec/legion/extensions/llm/agent_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Agent do
+  include_context 'with configured Legion::Extensions::Llm'
+  include_context 'with fake llm provider'
+
+  it 'builds a configured plain chat via .chat with runtime inputs' do
+    tool_class = Class.new(Legion::Extensions::Llm::Tool) do
+      def name = 'echo_tool'
+    end
+
+    agent_class = Class.new(Legion::Extensions::Llm::Agent) do
+      model 'fake-chat-model', provider: :fake_llm, assume_model_exists: true
+      inputs :display_name
+      instructions { "Hello #{display_name}" }
+      tools { [tool_class.new] }
+      params { { max_tokens: 12 } }
+    end
+
+    chat = agent_class.chat(display_name: 'Ava')
+
+    expect(chat.messages.first.role).to eq(:system)
+    expect(chat.messages.first.content).to eq('Hello Ava')
+    expect(chat.tools.keys).to include(:echo_tool)
+    expect(chat.params).to eq(max_tokens: 12)
+  end
+
+  it 'exposes Legion::Extensions::Llm::Chat as chat in execution context for .chat' do
+    agent_class = Class.new(Legion::Extensions::Llm::Agent) do
+      model 'fake-chat-model', provider: :fake_llm, assume_model_exists: true
+      instructions { chat.class.name }
+    end
+
+    chat = agent_class.chat
+    expect(chat.messages.first.content).to eq('Legion::Extensions::Llm::Chat')
+  end
+
+  it 'raises when instructions default prompt is missing' do
+    agent_class = Class.new(Legion::Extensions::Llm::Agent) do
+      model 'fake-chat-model', provider: :fake_llm, assume_model_exists: true
+      instructions
+    end
+
+    expect { agent_class.chat }.to raise_error(Legion::Extensions::Llm::PromptNotFoundError, /Prompt file not found/)
+  end
+
+  it 'supports inline schema DSL via schema do ... end' do
+    agent_class = Class.new(Legion::Extensions::Llm::Agent) do
+      model 'fake-chat-model', provider: :fake_llm, assume_model_exists: true
+      schema do
+        string :verdict, enum: %w[pass revise]
+        string :feedback
+      end
+    end
+
+    chat = agent_class.chat
+
+    expect(chat.schema).to include(name: 'Schema', strict: true, schema: include(type: 'object'))
+    expect(chat.schema.dig(:schema, :properties)).to include(
+      verdict: include(type: 'string'),
+      feedback: include(type: 'string')
+    )
+  end
+
+  it 'supports runtime-evaluated schema blocks that return a schema value' do
+    agent_class = Class.new(Legion::Extensions::Llm::Agent) do
+      model 'fake-chat-model', provider: :fake_llm, assume_model_exists: true
+      inputs :strict
+
+      schema do
+        if strict
+          {
+            type: 'object',
+            properties: { answer: { type: 'string' } },
+            required: ['answer'],
+            additionalProperties: false
+          }
+        end
+      end
+    end
+
+    strict_chat = agent_class.chat(strict: true)
+    loose_chat = agent_class.chat(strict: false)
+
+    expect(strict_chat.schema).to include(name: 'response', strict: true, schema: include(type: 'object'))
+    expect(loose_chat.schema).to be_nil
+  end
+
+  it 'can ask using a registered provider' do
+    agent_class = Class.new(Legion::Extensions::Llm::Agent) do
+      model 'fake-chat-model', provider: :fake_llm, assume_model_exists: true
+      instructions 'Answer questions clearly.'
+    end
+
+    stub_const('SpecChatAgent', agent_class)
+
+    response = SpecChatAgent.new.ask('hello')
+    expect(response.content).to include('fake response to hello')
+    expect(response.role).to eq(:assistant)
+  end
+
+  it 'delegates add_message to the underlying chat interface' do
+    agent_class = Class.new(Legion::Extensions::Llm::Agent) do
+      model 'fake-chat-model', provider: :fake_llm, assume_model_exists: true
+    end
+
+    agent = agent_class.new
+    message = agent.add_message(role: :user, content: 'Hello')
+
+    expect(message.role).to eq(:user)
+    expect(message.content).to eq('Hello')
+    expect(agent.chat.messages.last).to eq(message)
+  end
+
+  it 'exposes messages like Legion::Extensions::Llm::Chat' do
+    agent_class = Class.new(Legion::Extensions::Llm::Agent) do
+      model 'fake-chat-model', provider: :fake_llm, assume_model_exists: true
+    end
+
+    agent = agent_class.new
+    agent.add_message(role: :user, content: 'First')
+
+    expect(agent.messages).to eq(agent.chat.messages)
+    expect(agent.messages.last.content).to eq('First')
+  end
+
+  it 'delegates callback hooks to the underlying chat' do
+    fake_chat = Class.new do
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      def on_new_message(&)
+        @events << :new_message
+        self
+      end
+
+      def on_end_message(&)
+        @events << :end_message
+        self
+      end
+
+      def on_tool_call(&)
+        @events << :tool_call
+        self
+      end
+
+      def on_tool_result(&)
+        @events << :tool_result
+        self
+      end
+    end.new
+
+    agent = Class.new(described_class).new(chat: fake_chat)
+
+    expect(agent.on_new_message { :ok }).to eq(fake_chat)
+    expect(agent.on_end_message { :ok }).to eq(fake_chat)
+    expect(agent.on_tool_call { :ok }).to eq(fake_chat)
+    expect(agent.on_tool_result { :ok }).to eq(fake_chat)
+    expect(fake_chat.events).to eq(%i[new_message end_message tool_call tool_result])
+  end
+
+  it 'supports Enumerable by delegating each to chat' do
+    fake_chat = Class.new do
+      def each(&)
+        return enum_for(:each) unless block_given?
+
+        %w[first second].each(&)
+      end
+    end.new
+
+    agent = Class.new(described_class).new(chat: fake_chat)
+    expect(agent.map(&:upcase)).to eq(%w[FIRST SECOND])
+  end
+end

data/spec/legion/extensions/llm/attachment_spec.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'open3'
+require 'rbconfig'
+
+RSpec.describe Legion::Extensions::Llm::Attachment do
+  it 'supports path attachments from the public API' do
+    script = <<~'RUBY'
+      require 'legion/extensions/llm'
+
+      content = Legion::Extensions::Llm::Content.new('What is in this file?', 'spec/fixtures/ruby.txt')
+      attachment = content.attachments.first
+      puts "#{attachment.filename},#{attachment.mime_type}"
+    RUBY
+
+    stdout, stderr, status = Open3.capture3(
+      RbConfig.ruby, '-Ilib', '-e', script,
+      chdir: File.expand_path('../../../..', __dir__)
+    )
+
+    expect(status.success?).to be(true), stderr
+    expect(stdout.strip).to eq('ruby.txt,text/plain')
+  end
+end

data/spec/legion/extensions/llm/auto_registration_spec.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::AutoRegistration do
+  # Build a fake provider module that extends AutoRegistration,
+  # mimicking what a real lex-llm-* provider would look like.
+  let(:fake_provider_class) { Class.new }
+
+  let(:provider_module) do
+    klass = fake_provider_class
+    mod = Module.new do
+      extend Legion::Extensions::Llm::AutoRegistration
+
+      const_set(:PROVIDER_FAMILY, :fake_provider)
+
+      define_singleton_method(:provider_class) { klass }
+    end
+    mod
+  end
+
+  describe '#discover_instances' do
+    it 'returns an empty hash by default' do
+      expect(provider_module.discover_instances).to eq({})
+    end
+  end
+
+  describe '#provider_aliases' do
+    it 'returns an empty alias list by default' do
+      expect(provider_module.provider_aliases).to eq([])
+    end
+  end
+
+  it 'does not expose legion-llm registry mutation hooks' do
+    expect(provider_module).not_to respond_to(:register_discovered_instances)
+    expect(provider_module).not_to respond_to(:rediscover!)
+  end
+end