lex-llm 0.4.18 → 0.5.1

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