lex-llm 0.4.16 → 0.5.0

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Streaming do
+  let(:test_obj) do
+    Object.new.tap do |obj|
+      obj.extend(described_class)
+      obj.define_singleton_method(:build_chunk) { |data| "chunk:#{data['x']}" }
+    end
+  end
+
+  let(:env) { Struct.new(:status).new(200) }
+
+  before do
+    stub_const('Faraday::VERSION', '2.0.0')
+  end
+
+  it 'skips non-hash SSE payloads' do
+    yielded_chunks = []
+    handler = test_obj.send(:handle_stream) { |chunk| yielded_chunks << chunk }
+
+    expect { handler.call("data: true\n\n", 0, env) }.not_to raise_error
+    expect(yielded_chunks).to eq([])
+  end
+
+  it 'processes hash SSE payloads' do
+    yielded_chunks = []
+    handler = test_obj.send(:handle_stream) { |chunk| yielded_chunks << chunk }
+
+    handler.call("data: {\"x\":\"ok\"}\n\n", 0, env)
+
+    expect(yielded_chunks).to eq(['chunk:ok'])
+  end
+
+  describe '#handle_failed_response (private)' do
+    let(:error_env) { Struct.new(:status, :body).new(500, nil) }
+    let(:faraday_env) do
+      Struct.new(:status, :body) do
+        def [](key)
+          custom[key]
+        end
+
+        def []=(key, value)
+          custom[key] = value
+        end
+
+        private
+
+        def custom
+          @custom ||= {}
+        end
+      end.new(500, nil)
+    end
+    let(:non_mutable_env) { Struct.new(:status).new(500) }
+
+    it 'raises ServerError with extracted message when JSON is complete' do
+      buffer = +''
+      error_chunk = '{"error":{"message":"Model overloaded","code":500}}'
+      allow(test_obj).to receive(:handle_parsed_error) do
+        raise Legion::Extensions::Llm::ServerError, 'Model overloaded'
+      end
+      expect { test_obj.send(:handle_failed_response, error_chunk, buffer, error_env) }
+        .to raise_error(Legion::Extensions::Llm::ServerError)
+    end
+
+    it 'buffers partial JSON on mutable Faraday envs until the error body is complete' do
+      buffer = +''
+      first_chunk = '{"error":{"message":"The model is currently'
+      second_chunk = ' overloaded","code":500}}'
+      parsed_error = nil
+      allow(test_obj).to receive(:handle_parsed_error) do |data, _env|
+        parsed_error = data
+        raise Legion::Extensions::Llm::ServerError, 'The model is currently overloaded'
+      end
+
+      expect { test_obj.send(:handle_failed_response, first_chunk, buffer, error_env) }.not_to raise_error
+      expect(error_env.body).to eq(first_chunk)
+
+      expect { test_obj.send(:handle_failed_response, second_chunk, buffer, error_env) }
+        .to raise_error(Legion::Extensions::Llm::ServerError, /overloaded/)
+      expect(parsed_error.dig('error', 'message')).to eq('The model is currently overloaded')
+      expect(error_env.body).to eq("#{first_chunk}#{second_chunk}")
+    end
+
+    it 'stores partial JSON in a custom Faraday env key that final response handling will not overwrite' do
+      buffer = +''
+      first_chunk = '{"error":{"message":"The model is currently'
+
+      expect { test_obj.send(:handle_failed_response, first_chunk, buffer, faraday_env) }.not_to raise_error
+      expect(faraday_env[Legion::Extensions::Llm::ErrorMiddleware::STREAM_ERROR_BODY_KEY]).to eq(first_chunk)
+    end
+
+    it 'raises ServerError with partial message when the env cannot carry the buffered body' do
+      buffer = +''
+      truncated_chunk = '{"error":{"message":"The model is currently overloaded'
+      expect { test_obj.send(:handle_failed_response, truncated_chunk, buffer, non_mutable_env) }
+        .to raise_error(Legion::Extensions::Llm::ServerError, /Provider error.*The model is currently overloaded/)
+    end
+
+    it 'raises ServerError with generic message when no partial message is extractable and env cannot buffer' do
+      buffer = +''
+      partial_chunk = '{"error":{'
+      expect { test_obj.send(:handle_failed_response, partial_chunk, buffer, non_mutable_env) }
+        .to raise_error(Legion::Extensions::Llm::ServerError, /Provider error.*incomplete/)
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Tool do
+  describe '#name' do
+    it 'converts class name to snake_case and removes _tool suffix' do
+      stub_const('SampleTool', Class.new(described_class))
+      expect(SampleTool.new.name).to eq('sample')
+    end
+
+    # rubocop:disable Naming/AsciiIdentifiers
+
+    it 'normalizes class name Unicode characters to ASCII' do
+      stub_const('SàmpleTòol', Class.new(described_class))
+      expect(SàmpleTòol.new.name).to eq('sample')
+    end
+
+    it 'handles class names with unsupported characters' do
+      stub_const('SampleΨTool', Class.new(described_class))
+      expect(SampleΨTool.new.name).to eq('sample')
+    end
+
+    # rubocop:enable Naming/AsciiIdentifiers
+
+    it 'handles class names without Tool suffix' do
+      stub_const('AnotherSample', Class.new(described_class))
+      expect(AnotherSample.new.name).to eq('another_sample')
+    end
+
+    it 'strips :: for class in module namespace' do
+      stub_const('TestModule::SampleTool', Class.new(described_class))
+      expect(TestModule::SampleTool.new.name).to eq('test_module--sample')
+    end
+
+    it 'handles ASCII-8BIT encoded class names without raising Encoding::CompatibilityError' do
+      # This simulates a class name that is ASCII-8BIT encoded
+      tool_class = Class.new(described_class)
+      ascii_8bit_name = 'SampleTool'.dup.force_encoding('ASCII-8BIT')
+      allow(tool_class).to receive(:name).and_return(ascii_8bit_name)
+      expect(tool_class.new.name).to eq('sample')
+    end
+  end
+
+  describe '#call' do
+    it 'returns an error hash for unknown keyword arguments' do
+      stub_const('SignatureTool', Class.new(described_class) do
+        def execute(questions:)
+          questions
+        end
+      end)
+
+      result = SignatureTool.new.call({ 'questions' => [], 'isOther' => true })
+
+      expect(result).to eq({ error: 'Invalid tool arguments: unknown keyword: isOther' })
+    end
+
+    it 'returns an error hash for missing required keyword arguments' do
+      stub_const('RequiredTool', Class.new(described_class) do
+        def execute(questions:)
+          questions
+        end
+      end)
+
+      result = RequiredTool.new.call({})
+
+      expect(result).to eq({ error: 'Invalid tool arguments: missing keyword: questions' })
+    end
+
+    it 'allows extra keyword arguments when execute accepts keyrest' do
+      stub_const('FlexibleTool', Class.new(described_class) do
+        def execute(questions:, **extra)
+          { questions:, extra: }
+        end
+      end)
+
+      result = FlexibleTool.new.call({ 'questions' => [1], 'isOther' => true })
+
+      expect(result).to eq({ questions: [1], extra: { isOther: true } })
+    end
+
+    it 're-raises unrelated ArgumentError from inside execute' do
+      stub_const('ManualArgumentErrorTool', Class.new(described_class) do
+        def execute(questions:)
+          _ = questions
+          raise ArgumentError, 'bad value provided'
+        end
+      end)
+
+      expect { ManualArgumentErrorTool.new.call({ 'questions' => [] }) }
+        .to raise_error(ArgumentError, 'bad value provided')
+    end
+  end
+end

data/spec/legion/extensions/llm/transport/fleet_lane_spec.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm'
+
+RSpec.describe Legion::Extensions::Llm::Transport::FleetLane do
+  describe '.queue_options' do
+    it 'returns durable quorum live-work queue defaults' do
+      options = described_class.queue_options
+
+      expect(options[:durable]).to be(true)
+      expect(options[:auto_delete]).to be(false)
+      expect(options[:arguments]).to include(
+        'x-queue-type' => 'quorum',
+        'x-queue-leader-locator' => 'balanced',
+        'x-overflow' => 'reject-publish',
+        'x-expires' => 60_000,
+        'x-message-ttl' => 120_000,
+        'x-max-length' => 100,
+        'x-delivery-limit' => 3,
+        'x-consumer-timeout' => 300_000
+      )
+    end
+
+    it 'allows provider gems to override lane limits' do
+      options = described_class.queue_options(queue_max_length: 25, delivery_limit: 7)
+
+      expect(options[:arguments]['x-max-length']).to eq(25)
+      expect(options[:arguments]['x-delivery-limit']).to eq(7)
+    end
+  end
+
+  describe '.build_queue_class' do
+    it 'builds a queue class without requiring legion-transport at gem load time' do
+      exchange_class = Class.new
+      base_queue = Class.new do
+        attr_reader :bindings
+
+        def initialize
+          @bindings = []
+        end
+
+        def bind(exchange, routing_key:)
+          @bindings << [exchange, routing_key]
+        end
+      end
+
+      queue_class = described_class.build_queue_class(
+        queue_name: 'llm.fleet.embed.nomic-embed-text',
+        exchange_class: exchange_class,
+        base_queue_class: base_queue
+      )
+      queue = queue_class.new
+
+      expect(queue.queue_name).to eq('llm.fleet.embed.nomic-embed-text')
+      expect(queue.queue_options[:arguments]['x-queue-type']).to eq('quorum')
+      expect(queue.dlx_enabled).to be(false)
+      expect(queue.bindings.first.last).to eq('llm.fleet.embed.nomic-embed-text')
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Utils do
+  describe '.hash_get' do
+    it 'fetches a value using a symbol when the hash key is stored as a string' do
+      hash = { 'name' => 'Legion::Extensions::Llm' }
+
+      expect(described_class.hash_get(hash, :name)).to eq('Legion::Extensions::Llm')
+    end
+
+    it 'fetches a value using a string when the hash key is stored as a symbol' do
+      hash = { name: 'Legion::Extensions::Llm' }
+
+      expect(described_class.hash_get(hash, 'name')).to eq('Legion::Extensions::Llm')
+    end
+  end
+
+  describe '.to_safe_array' do
+    it 'returns the same array instance when the input is already an array' do
+      items = [1, 2, 3]
+
+      expect(described_class.to_safe_array(items)).to equal(items)
+    end
+
+    it 'wraps hashes in an array' do
+      hash = { key: 'value' }
+
+      expect(described_class.to_safe_array(hash)).to eq([hash])
+    end
+
+    it 'wraps non-collection values in an array' do
+      expect(described_class.to_safe_array('value')).to eq(['value'])
+    end
+  end
+
+  describe '.deep_merge' do
+    it 'merges nested hashes without mutating the originals' do
+      original = { config: { retries: 3, timeout: 5 }, mode: :safe }
+      overrides = { config: { timeout: 10 }, verbose: true }
+
+      result = described_class.deep_merge(original, overrides)
+
+      expect(result).to eq(
+        config: { retries: 3, timeout: 10 },
+        mode: :safe,
+        verbose: true
+      )
+      expect(original).to eq(config: { retries: 3, timeout: 5 }, mode: :safe)
+      expect(overrides).to eq(config: { timeout: 10 }, verbose: true)
+    end
+  end
+
+  describe '.deep_dup' do
+    it 'duplicates nested arrays and hashes' do
+      original = {
+        metadata: {
+          tags: %w[ruby llm],
+          info: { version: '1.0.0' }
+        }
+      }
+
+      duplicate = described_class.deep_dup(original)
+
+      expect(duplicate).to eq(original)
+      expect(duplicate).not_to equal(original)
+      expect(duplicate[:metadata]).not_to equal(original[:metadata])
+      expect(duplicate[:metadata][:tags]).not_to equal(original[:metadata][:tags])
+      expect(duplicate[:metadata][:info]).not_to equal(original[:metadata][:info])
+    end
+  end
+
+  describe '.deep_stringify_keys' do
+    it 'converts nested keys and symbol values to strings' do
+      data = {
+        config: {
+          retries: 3,
+          mode: :safe
+        },
+        'files' => [{ path: '/tmp/file.txt' }]
+      }
+
+      expect(described_class.deep_stringify_keys(data)).to eq(
+        'config' => {
+          'retries' => 3,
+          'mode' => 'safe'
+        },
+        'files' => [{ 'path' => '/tmp/file.txt' }]
+      )
+    end
+  end
+
+  describe '.deep_symbolize_keys' do
+    it 'converts nested string keys to symbols and preserves non-convertible keys' do
+      data = {
+        'config' => {
+          'retries' => 3,
+          'mode' => 'safe',
+          'options' => [{ 'path' => '/tmp/file.txt' }]
+        },
+        42 => 'answer'
+      }
+
+      result = described_class.deep_symbolize_keys(data)
+
+      expect(result[:config][:retries]).to eq(3)
+      expect(result[:config][:mode]).to eq('safe')
+      expect(result[:config][:options].first[:path]).to eq('/tmp/file.txt')
+      expect(result[42]).to eq('answer')
+    end
+  end
+end

data/spec/legion/extensions/llm_base_contract_spec.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm do
+  include_context 'with fake llm provider'
+
+  before do
+    stub_const(
+      'SpecSupport::EchoTool',
+      Class.new(Legion::Extensions::Llm::Tool) do
+        description 'Echo a numeric value'
+        param :value, type: :integer, desc: 'Value to echo'
+
+        def execute(value:)
+          "echo #{value}"
+        end
+      end
+    )
+  end
+
+  it 'loads and discovers provider classes from the namespace' do
+    provider_classes = Legion::Extensions::Llm::Models.scan_provider_classes
+    expect(provider_classes).to include(fake_llm: SpecSupport::FakeLLMProvider)
+    expect(Legion::Extensions::Llm::Routing::ModelOffering).to be_a(Class)
+  end
+
+  it 'lets a provider gem register options and satisfy chat through the shared API' do
+    chat = described_class.chat(model: 'fake-chat-model', provider: :fake_llm, assume_model_exists: true)
+    response = chat.ask('hello')
+
+    expect(response).to have_attributes(
+      role: :assistant,
+      content: 'fake response to hello',
+      model_id: 'fake-chat-model',
+      input_tokens: 10,
+      output_tokens: 5
+    )
+  end
+
+  it 'runs shared tool orchestration without provider-specific payload code' do
+    response = described_class.chat(model: 'fake-chat-model', provider: :fake_llm, assume_model_exists: true)
+                              .with_tool(SpecSupport::EchoTool)
+                              .ask('use the tool')
+
+    expect(response.content).to eq('tool result: echo 21')
+  end
+
+  it 'normalizes schema responses through the base chat layer' do
+    schema = {
+      name: 'answer',
+      schema: {
+        type: 'object',
+        properties: { answer: { type: 'integer' } },
+        required: ['answer']
+      }
+    }
+
+    response = described_class.chat(model: 'fake-chat-model', provider: :fake_llm, assume_model_exists: true)
+                              .with_schema(schema)
+                              .ask('structured')
+
+    expect(response.content).to eq({ 'answer' => 42 })
+  end
+
+  it 'delegates embedding, moderation, image, and transcription calls through registered providers' do
+    expect(described_class.embed('hello', model: 'fake-embed', provider: :fake_llm, assume_model_exists: true).vectors)
+      .to eq([0.5, 0.5, 0.5])
+
+    expect(described_class.moderate('safe', model: 'fake-moderation', provider: :fake_llm, assume_model_exists: true))
+      .not_to be_flagged
+
+    expect(described_class.paint('draw', model: 'fake-image', provider: :fake_llm, assume_model_exists: true).to_blob)
+      .to eq('fake-image')
+
+    expect(described_class.transcribe('audio.wav', model: 'fake-audio', provider: :fake_llm,
+                                                   assume_model_exists: true).text)
+      .to eq('fake transcript')
+  end
+
+  it 'connects model offerings to Legion fleet queue construction end to end' do
+    offering = Legion::Extensions::Llm::Routing::ModelOffering.new(
+      provider_family: :fake_llm,
+      instance_id: :worker_one,
+      transport: :rabbitmq,
+      model: 'fake-chat-model',
+      limits: { context_window: 16_384 }
+    )
+    exchange_class = Class.new
+    base_queue = Class.new do
+      attr_reader :bindings
+
+      def initialize
+        @bindings = []
+      end
+
+      def bind(exchange, routing_key:)
+        @bindings << [exchange, routing_key]
+      end
+    end
+
+    queue_class = Legion::Extensions::Llm::Transport::FleetLane.build_queue_class(
+      queue_name: offering.lane_key,
+      exchange_class: exchange_class,
+      base_queue_class: base_queue
+    )
+
+    expect(queue_class.new.queue_name).to eq('llm.fleet.inference.fake-chat-model.ctx16384')
+  end
+end

data/spec/legion/extensions/llm_extension_spec.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm'
+
+RSpec.describe Legion::Extensions::Llm do
+  it 'exposes the Legion-native extension namespace for autoloading' do
+    expect(described_class::Types::ModelOffering).to equal(Legion::Extensions::Llm::Routing::ModelOffering)
+    expect(described_class::Types::OfferingRegistry).to equal(Legion::Extensions::Llm::Routing::OfferingRegistry)
+    expect(described_class::Routing::LaneKey).to equal(Legion::Extensions::Llm::Routing::LaneKey)
+    expect(described_class::Routing::OfferingRegistry).to equal(Legion::Extensions::Llm::Routing::OfferingRegistry)
+  end
+
+  it 'provides complete default fleet settings' do
+    defaults = described_class.default_settings
+
+    expect(defaults.dig(:fleet, :consumer, :scheduler)).to eq(:basic_get)
+    expect(defaults.dig(:fleet, :consumer, :queue_expires_ms)).to eq(60_000)
+    expect(defaults.dig(:fleet, :consumer, :consumer_ack_timeout_ms)).to eq(90_000)
+    expect(defaults.dig(:fleet, :auth, :accepted_issuers)).to eq(['legion-llm'])
+    expect(defaults.dig(:fleet, :auth, :audience)).to eq('lex-llm-fleet-worker')
+    expect(defaults.dig(:fleet, :auth, :algorithm)).to eq('HS256')
+    expect(defaults.dig(:fleet, :auth, :replay_ttl_seconds)).to eq(600)
+    expect(defaults.dig(:fleet, :responder, :require_idempotency)).to be(true)
+    expect(defaults.dig(:fleet, :responder, :idempotency_ttl_seconds)).to eq(600)
+  end
+
+  it 'reads fleet settings from extension settings before falling back to core llm settings' do
+    data = {
+      extensions: { llm: { fleet: { auth: { accepted_issuers: ['extension'] } } } },
+      llm: {
+        fleet: {
+          auth: { audience: 'core-audience', accepted_issuers: ['core'] },
+          responder: { require_auth: false }
+        }
+      }
+    }
+    settings = Module.new
+    settings.define_singleton_method(:[]) { |key| data[key] }
+
+    stub_const('Legion::Settings', settings)
+
+    expect(Legion::Extensions::Llm::Fleet::Settings.value(:fleet, :auth, :accepted_issuers, default: []))
+      .to eq(['extension'])
+    expect(Legion::Extensions::Llm::Fleet::Settings.value(:fleet, :auth, :audience, default: nil))
+      .to eq('core-audience')
+    expect(Legion::Extensions::Llm::Fleet::Settings.value(:fleet, :responder, :require_auth, default: true))
+      .to be(false)
+  end
+
+  it 'builds provider defaults with shared fleet settings' do
+    settings = described_class.provider_settings(
+      family: :ollama,
+      instance: {
+        base_url: 'http://localhost:11434',
+        fleet: { enabled: true, consumer_priority: 10 }
+      }
+    )
+
+    expect(settings[:provider_family]).to eq(:ollama)
+    expect(settings.dig(:discovery, :interval_seconds)).to eq(300)
+    expect(settings.dig(:fleet, :consumer, :scheduler)).to eq(:basic_get)
+    expect(settings.dig(:instances, :default, :base_url)).to eq('http://localhost:11434')
+    expect(settings.dig(:instances, :default, :fleet)).to include(
+      enabled: true,
+      consumer_priority: 10,
+      prefetch: 1
+    )
+  end
+
+  it 'deep duplicates provider defaults between calls' do
+    first = described_class.provider_settings(family: :vllm)
+    second = described_class.provider_settings(family: :vllm)
+
+    first.dig(:instances, :default, :fleet)[:prefetch] = 99
+
+    expect(second.dig(:instances, :default, :fleet, :prefetch)).to eq(1)
+  end
+end

data/spec/legion/extensions/llm_root_spec.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm do
+  describe '.logger' do
+    let(:logger) { instance_double(Logger) }
+    let(:log_file) { double }
+    let(:log_level) { double }
+
+    before do
+      described_class.instance_variable_set(:@config, nil)
+      described_class.instance_variable_set(:@logger, nil)
+    end
+
+    after do
+      described_class.instance_variable_set(:@config, nil)
+      described_class.instance_variable_set(:@logger, nil)
+    end
+
+    context 'with configuration options' do
+      before do
+        described_class.configure do |config|
+          config.log_file = log_file
+          config.log_level = log_level
+        end
+      end
+
+      it 'returns a default Logger' do
+        allow(Logger).to receive(:new).with(log_file, progname: 'Legion::Extensions::Llm',
+                                                      level: log_level).and_return(logger)
+
+        expect(described_class.logger).to eq(logger)
+      end
+    end
+
+    context 'with a custom logger' do
+      before do
+        described_class.configure do |config|
+          config.logger = logger
+          config.log_file = log_file
+          config.log_level = log_level
+        end
+      end
+
+      it 'returns a the custom Logger' do
+        expect(described_class.logger).to eq(logger)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+begin
+  require 'dotenv/load'
+rescue LoadError
+  nil
+end
+
+begin
+  require 'simplecov'
+  require 'simplecov-cobertura'
+  require_relative 'support/simplecov_configuration'
+rescue LoadError
+  nil
+end
+
+require 'bundler/setup'
+require 'fileutils'
+require 'tempfile'
+require 'legion/extensions/llm'
+require 'ruby_llm/schema'
+require_relative 'support/rspec_configuration'
+require_relative 'support/llm_configuration'
+require_relative 'support/fake_llm_provider'