lex-llm 0.4.18 → 0.5.1

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::RegistryEventBuilder do
+  subject(:builder) { described_class.new(provider_family: :ollama) }
+
+  describe '#provider_family' do
+    it 'normalizes to a downcased symbol' do
+      b = described_class.new(provider_family: 'Anthropic')
+      expect(b.provider_family).to eq(:anthropic)
+    end
+  end
+
+  describe '#model_available' do
+    let(:model) do
+      Legion::Extensions::Llm::Model::Info.from_hash(
+        id: 'llama-3.1-8b',
+        name: 'Llama 3.1 8B',
+        provider: 'ollama',
+        capabilities: %w[completion streaming],
+        modalities: { input: %w[text], output: %w[text] },
+        context_window: 128_000,
+        max_output_tokens: 8192
+      )
+    end
+
+    let(:readiness) { { ready: true, configured: true } }
+
+    it 'builds a RegistryEvent with offering data' do
+      event = builder.model_available(model, readiness: readiness)
+      expect(event).to be_a(Legion::Extensions::Llm::Routing::RegistryEvent)
+      expect(event.event_type).to eq(:offering_available)
+      expect(event.offering.model).to eq('llama-3.1-8b')
+      expect(event.offering.provider_family).to eq(:ollama)
+    end
+
+    it 'includes model health from readiness' do
+      event = builder.model_available(model, readiness: readiness)
+      expect(event.health[:ready]).to be true
+      expect(event.health[:status]).to eq(:available)
+    end
+
+    it 'includes extension metadata' do
+      event = builder.model_available(model, readiness: readiness)
+      expect(event.metadata[:extension]).to eq(:llm_ollama)
+      expect(event.metadata[:provider]).to eq(:ollama)
+    end
+  end
+
+  describe '#readiness' do
+    it 'builds an available event when ready' do
+      event = builder.readiness({ ready: true, configured: true })
+      expect(event.event_type).to eq(:offering_available)
+    end
+
+    it 'builds an unavailable event when not ready' do
+      event = builder.readiness({ ready: false, configured: true })
+      expect(event.event_type).to eq(:offering_unavailable)
+    end
+
+    it 'preserves error details from health' do
+      event = builder.readiness({ ready: false, health: { error: 'ConnectionRefused', message: 'refused' } })
+      expect(event.health[:error_class]).to eq('ConnectionRefused')
+      expect(event.health[:error]).to eq('refused')
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::RegistryPublisher do
+  subject(:publisher) { described_class.new(provider_family: :ollama, builder: builder) }
+
+  let(:builder) { instance_double(Legion::Extensions::Llm::RegistryEventBuilder) }
+
+  describe '#app_id' do
+    it 'includes the provider family' do
+      expect(publisher.app_id).to eq('lex-llm-ollama')
+    end
+  end
+
+  describe '#provider_family' do
+    it 'normalizes to a downcased symbol' do
+      pub = described_class.new(provider_family: 'Anthropic', builder: builder)
+      expect(pub.provider_family).to eq(:anthropic)
+    end
+  end
+end

data/spec/legion/extensions/llm/responses/response_objects_spec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# rubocop:disable RSpec/DescribeClass
+RSpec.describe 'LLM normalized response objects' do
+  let(:unsafe_metadata) do
+    {
+      reasoning_content: 'metadata secret',
+      reasoning: 'metadata reasoning',
+      thinking_text: 'metadata thinking',
+      raw: { reasoning_content: 'nested raw secret' },
+      'raw-response' => { reasoning_content: 'hyphen raw secret' },
+      'provider-body' => { thinking_text: 'hyphen body secret' },
+      vendor: 'vllm'
+    }
+  end
+  let(:unsafe_raw) { { 'choices' => [{ 'message' => { 'content' => '<think>raw secret</think>visible' } }] } }
+
+  it 'serializes chat responses without raw provider thinking fields' do
+    response = Legion::Extensions::Llm::Responses::ChatResponse.new(
+      content: "<think>tag secret</think>\nvisible",
+      metadata: unsafe_metadata,
+      raw: unsafe_raw
+    )
+
+    payload = response.to_h
+    encoded = Legion::JSON.dump(payload)
+
+    expect(payload).to eq(content: 'visible', metadata: { vendor: 'vllm' })
+    expect(encoded).not_to include('reasoning', 'reasoning_content', 'thinking_text', '<think>', 'raw secret',
+                                   'nested raw secret', 'hyphen raw secret', 'hyphen body secret')
+    expect(response.to_internal_h).to include(
+      thinking: 'metadata secretmetadata reasoningmetadata thinkingtag secret',
+      metadata: unsafe_metadata,
+      raw: unsafe_raw
+    )
+  end
+
+  it 'serializes stream chunks without raw provider thinking fields' do
+    chunk = Legion::Extensions::Llm::Responses::StreamChunk.new(
+      content: "<think>tag secret</think>\nvisible",
+      metadata: unsafe_metadata,
+      raw: unsafe_raw
+    )
+
+    payload = chunk.to_h
+    encoded = Legion::JSON.dump(payload)
+
+    expect(payload).to eq(content: 'visible', metadata: { vendor: 'vllm' })
+    expect(encoded).not_to include('reasoning', 'reasoning_content', 'thinking_text', '<think>', 'raw secret',
+                                   'nested raw secret', 'hyphen raw secret', 'hyphen body secret')
+    expect(chunk.to_internal_h).to include(
+      thinking: 'metadata secretmetadata reasoningmetadata thinkingtag secret',
+      metadata: unsafe_metadata,
+      raw: unsafe_raw
+    )
+  end
+
+  it 'serializes embedding responses without raw provider payloads' do
+    response = Legion::Extensions::Llm::Responses::EmbeddingResponse.new(
+      vectors: [[0.1]],
+      model: 'embed',
+      metadata: unsafe_metadata,
+      raw: unsafe_raw
+    )
+
+    payload = response.to_h
+
+    expect(payload).to eq(vectors: [[0.1]], model: 'embed', metadata: { vendor: 'vllm' })
+    expect(Legion::JSON.dump(payload)).not_to include('raw secret')
+    expect(response.to_internal_h).to include(metadata: unsafe_metadata, raw: unsafe_raw)
+  end
+end
+# rubocop:enable RSpec/DescribeClass

data/spec/legion/extensions/llm/responses/thinking_extractor_spec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Responses::ThinkingExtractor do
+  it 'extracts normal think tags' do
+    result = described_class.extract("<think>hidden</think>\n\nvisible")
+
+    expect(result.content).to eq('visible')
+    expect(result.thinking).to eq('hidden')
+  end
+
+  it 'extracts normal thinking tags' do
+    result = described_class.extract("<thinking>hidden</thinking>\n\nvisible")
+
+    expect(result.content).to eq('visible')
+    expect(result.thinking).to eq('hidden')
+  end
+
+  it 'extracts malformed trailing close tag' do
+    result = described_class.extract("hidden only\n</think>\n\nvisible")
+
+    expect(result.content).to eq('visible')
+    expect(result.thinking).to eq('hidden only')
+  end
+
+  it 'extracts malformed trailing thinking close tag' do
+    result = described_class.extract("hidden only\n</thinking>\n\nvisible")
+
+    expect(result.content).to eq('visible')
+    expect(result.thinking).to eq('hidden only')
+  end
+
+  it 'extracts unterminated think blocks instead of leaking them as visible content' do
+    result = described_class.extract("visible\n<think>hidden only")
+
+    expect(result.content).to eq('visible')
+    expect(result.thinking).to eq('hidden only')
+  end
+
+  it 'extracts untagged local-model reasoning preambles' do
+    result = described_class.extract(
+      "The user is just saying \"test\". Let me respond simply and confirm things are working.\n\n" \
+      'Hey! Things are working on my end. What can I help you with?'
+    )
+
+    expect(result.content).to eq('Hey! Things are working on my end. What can I help you with?')
+    expect(result.thinking)
+      .to eq('The user is just saying "test". Let me respond simply and confirm things are working.')
+  end
+
+  it 'leaves normal text visible' do
+    result = described_class.extract('visible only')
+
+    expect(result.content).to eq('visible only')
+    expect(result.thinking).to be_nil
+  end
+
+  it 'extracts provider-specific reasoning metadata without exposing reasoning fields as metadata' do
+    result = described_class.extract(
+      'visible',
+      metadata: {
+        'reasoning_content' => 'hidden',
+        'thinking_signature' => 'sig-1',
+        'reasoning-signature' => 'sig-2',
+        'vendor' => 'vllm'
+      }
+    )
+
+    expect(result.content).to eq('visible')
+    expect(result.thinking).to eq('hidden')
+    expect(result.signature).to eq('sig-1')
+    expect(result.metadata).to eq(vendor: 'vllm')
+  end
+end

data/spec/legion/extensions/llm/routing/model_offering_spec.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Routing::ModelOffering do
+  subject(:offering) do
+    described_class.new(
+      provider_family: :ollama,
+      instance_id: :'macbook-m4-max',
+      transport: :rabbitmq,
+      model: 'qwen3.6:27b-q4_K_M',
+      capabilities: %i[chat tools thinking],
+      limits: { context_window: 32_768, max_output_tokens: 8192 },
+      policy_tags: %i[phi_allowed internal_only]
+    )
+  end
+
+  it 'normalizes provider-neutral offering metadata' do
+    expect(offering).to have_attributes(
+      offering_id: 'ollama:macbook-m4-max:inference:qwen3-6-27b-q4-k-m',
+      provider_family: :ollama,
+      provider_instance: :'macbook-m4-max',
+      instance_id: :'macbook-m4-max',
+      transport: :rabbitmq,
+      tier: :fleet,
+      model: 'qwen3.6:27b-q4_K_M',
+      canonical_model_alias: 'qwen3.6:27b-q4_K_M',
+      usage_type: :inference
+    )
+    expect(offering.capabilities).to eq(%i[chat tools thinking])
+    expect(offering.context_window).to eq(32_768)
+  end
+
+  it 'accepts expanded contract fields while preserving instance_id compatibility' do
+    expanded = described_class.new(
+      offering_id: 'azure:gpt4o-prod',
+      provider_family: :azure_foundry,
+      model_family: :openai,
+      provider_instance: :eastus,
+      model: 'gpt4o-prod',
+      canonical_model_alias: 'gpt-4o',
+      routing_metadata: { region: 'eastus', deployment: 'gpt4o-prod' },
+      capabilities: %i[chat tools]
+    )
+
+    expect(expanded).to have_attributes(
+      offering_id: 'azure:gpt4o-prod',
+      provider_family: :azure_foundry,
+      model_family: :openai,
+      provider_instance: :eastus,
+      instance_id: :eastus,
+      model: 'gpt4o-prod',
+      canonical_model_alias: 'gpt-4o',
+      routing_metadata: { region: 'eastus', deployment: 'gpt4o-prod' }
+    )
+    expect(expanded.to_h).to include(
+      provider_instance: :eastus,
+      instance_id: :eastus,
+      canonical_model_alias: 'gpt-4o',
+      routing_metadata: { region: 'eastus', deployment: 'gpt4o-prod' }
+    )
+  end
+
+  it 'lifts model family and aliases from legacy metadata' do
+    legacy = described_class.new(
+      provider_family: :bedrock,
+      instance_id: :'us-east-1',
+      model: 'anthropic.claude-3-haiku-20240307-v1:0',
+      metadata: { model_family: :anthropic, alias: 'claude-3-haiku' }
+    )
+
+    expect(legacy.model_family).to eq(:anthropic)
+    expect(legacy.canonical_model_alias).to eq('claude-3-haiku')
+    expect(legacy.model_alias?('claude-3-haiku')).to be true
+    expect(legacy.model_alias?('anthropic.claude-3-haiku-20240307-v1:0')).to be true
+  end
+
+  it 'checks route eligibility without provider-specific code' do
+    expect(
+      offering.eligible_for?(
+        usage_type: :inference,
+        required_capabilities: %i[tools thinking],
+        min_context_window: 32_000,
+        policy_tags: [:phi_allowed]
+      )
+    ).to be true
+
+    expect(offering.eligible_for?(min_context_window: 65_536)).to be false
+    expect(offering.eligible_for?(required_capabilities: [:vision])).to be false
+  end
+
+  it 'treats legacy function-calling capability names as tools support' do
+    legacy_tools = described_class.new(
+      provider_family: :vllm,
+      model: 'qwen-tools',
+      capabilities: %i[chat function_calling]
+    )
+
+    expect(legacy_tools.capabilities).to include(:function_calling, :tools)
+    expect(legacy_tools.eligible_for?(required_capabilities: [:tools])).to be true
+  end
+
+  it 'treats disabled offerings as ineligible' do
+    disabled = described_class.new(
+      provider_family: :ollama,
+      instance_id: :local,
+      model: 'qwen',
+      metadata: { enabled: false }
+    )
+
+    expect(disabled).not_to be_enabled
+    expect(disabled.eligible_for?).to be false
+  end
+
+  it 'generates clean fleet inference lane keys with context windows' do
+    expect(offering.lane_key).to eq('llm.fleet.inference.qwen3-6-27b-q4-k-m.ctx32768')
+  end
+
+  it 'uses canonical model aliases for fleet lanes when provider deployments hide the base model' do
+    deployment = described_class.new(
+      provider_family: :azure_foundry,
+      provider_instance: :default,
+      model: 'gpt4o-prod',
+      canonical_model_alias: 'gpt-4o',
+      limits: { context_window: 128_000 }
+    )
+
+    expect(deployment.lane_key).to eq('llm.fleet.inference.gpt-4o.ctx128000')
+  end
+
+  it 'generates embedding lanes without context suffixes' do
+    embedding = described_class.new(
+      provider_family: :ollama,
+      instance_id: :'gpu-01',
+      transport: :rabbitmq,
+      model: 'nomic-embed-text:latest',
+      usage_type: :embed,
+      capabilities: [:embedding]
+    )
+
+    expect(embedding).to be_embedding
+    expect(embedding.lane_key).to eq('llm.fleet.embed.nomic-embed-text-latest')
+  end
+
+  it 'can include an eligibility fingerprint when lanes need stricter matching' do
+    key = offering.lane_key(include_fingerprint: true)
+
+    expect(key).to match(/\Allm\.fleet\.inference\.qwen3-6-27b-q4-k-m\.ctx32768\.elig\.[0-9a-f]{10}\z/)
+    expect(offering.eligibility_fingerprint).to eq(key.split('.').last)
+  end
+
+  it 'normalizes string numeric limits from JSON-backed settings' do
+    string_limits = described_class.new(
+      provider_family: :ollama,
+      model: 'qwen',
+      limits: { context_window: '32768', max_output_tokens: '8192' }
+    )
+
+    expect(string_limits.context_window).to eq(32_768)
+    expect(string_limits.max_output_tokens).to eq(8192)
+    expect(string_limits.eligible_for?(min_context_window: 32_000)).to be true
+  end
+
+  it 'normalizes string-keyed JSON-backed offering fields' do
+    json_offering = described_class.new(
+      'provider_family' => 'ollama',
+      'instance_id' => 'macbook-m4-max',
+      'transport' => 'rabbitmq',
+      'model' => 'nomic-embed-text',
+      'type' => 'embed',
+      'capabilities' => %w[embedding],
+      'limits' => { 'context_window' => '8192' },
+      'metadata' => { 'enabled' => true }
+    )
+
+    expect(json_offering.provider_family).to eq(:ollama)
+    expect(json_offering.instance_id).to eq(:'macbook-m4-max')
+    expect(json_offering.transport).to eq(:rabbitmq)
+    expect(json_offering.usage_type).to eq(:embedding)
+    expect(json_offering.context_window).to eq(8192)
+    expect(json_offering).to be_enabled
+  end
+
+  it 'treats string-keyed disabled metadata as ineligible' do
+    disabled = described_class.new(
+      'provider_family' => 'ollama',
+      'model' => 'qwen',
+      'metadata' => { 'enabled' => false }
+    )
+
+    expect(disabled).not_to be_enabled
+    expect(disabled.eligible_for?).to be false
+  end
+
+  it 'keeps sensitive metadata out of eligibility fingerprints' do
+    safe = described_class.new(
+      provider_family: :ollama,
+      model: 'qwen',
+      metadata: { eligibility: { endpoint_url: 'http://gpu.internal', network_boundary: :corp_lan } }
+    )
+    changed_secret = described_class.new(
+      provider_family: :ollama,
+      model: 'qwen',
+      metadata: { eligibility: { endpoint_url: 'http://other.internal', network_boundary: :corp_lan } }
+    )
+
+    expect(safe.eligibility_fingerprint).to eq(changed_secret.eligibility_fingerprint)
+  end
+
+  it 'serializes the normalized shape used by routers and registries' do
+    expect(offering.to_h).to include(
+      offering_id: 'ollama:macbook-m4-max:inference:qwen3-6-27b-q4-k-m',
+      provider_family: :ollama,
+      provider_instance: :'macbook-m4-max',
+      instance_id: :'macbook-m4-max',
+      tier: :fleet,
+      canonical_model_alias: 'qwen3.6:27b-q4_K_M',
+      usage_type: :inference,
+      limits: { context_window: 32_768, max_output_tokens: 8192 }
+    )
+  end
+end

data/spec/legion/extensions/llm/routing/offering_registry_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Routing::OfferingRegistry do
+  subject(:registry) { described_class.new([chat, embedding]) }
+
+  let(:chat) do
+    Legion::Extensions::Llm::Routing::ModelOffering.new(
+      provider_family: :azure_foundry,
+      model_family: :openai,
+      provider_instance: :eastus,
+      model: 'gpt4o-prod',
+      canonical_model_alias: 'gpt-4o',
+      capabilities: %i[chat tools],
+      limits: { context_window: 128_000 }
+    )
+  end
+
+  let(:embedding) do
+    Legion::Extensions::Llm::Routing::ModelOffering.new(
+      provider_family: :bedrock,
+      model_family: :amazon,
+      instance_id: :'us-east-1',
+      model: 'amazon.titan-embed-text-v2:0',
+      canonical_model_alias: 'titan-embed-text-v2',
+      usage_type: :embedding,
+      capabilities: [:embedding]
+    )
+  end
+
+  it 'registers hashes and offerings by normalized offering_id' do
+    replacement = registry.register(
+      chat.to_h.merge(capabilities: %i[chat vision])
+    )
+
+    expect(registry.find(chat.offering_id)).to eq(replacement)
+    expect(registry.find(chat.offering_id).capabilities).to eq(%i[chat vision])
+    expect(registry.count).to eq(2)
+  end
+
+  it 'finds and filters offerings by the expanded routing contract' do
+    expect(registry.find_by_model_alias('gpt-4o')).to eq(chat)
+    expect(registry.filter(provider_family: :azure_foundry)).to eq([chat])
+    expect(registry.filter(model_family: :openai)).to eq([chat])
+    expect(registry.filter(provider_instance: :eastus)).to eq([chat])
+    expect(registry.filter(capability: :embedding)).to eq([embedding])
+    expect(registry.filter(model_alias: 'titan-embed-text-v2', usage_type: :embedding)).to eq([embedding])
+  end
+end

data/spec/legion/extensions/llm/routing/registry_event_spec.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Routing::RegistryEvent do
+  subject(:event) do
+    described_class.new(
+      event_id: 'evt-123',
+      event_type: :offering_available,
+      occurred_at: Time.utc(2026, 4, 28, 14, 30, 15, 123_456),
+      offering: offering,
+      runtime: { host_id: 'macbook-m4-max', process: { pid: 12_345 } },
+      capacity: { concurrency: 4, queued: 0 },
+      health: { ready: true, latency_ms: 180 },
+      lane: 'llm.fleet.inference.qwen3-6.ctx32768',
+      metadata: { observed_by: :lex_llm_ollama }
+    )
+  end
+
+  let(:offering) do
+    Legion::Extensions::Llm::Routing::ModelOffering.new(
+      provider_family: :ollama,
+      provider_instance: :'macbook-m4-max',
+      transport: :rabbitmq,
+      model: 'qwen3.6',
+      capabilities: %i[chat tools],
+      limits: { context_window: 32_768 },
+      credentials: { api_key: 'secret' },
+      metadata: { enabled: true, api_key: 'secret' }
+    )
+  end
+
+  it 'serializes a provider-neutral registry envelope' do
+    expect(event).to have_attributes(
+      event_id: 'evt-123',
+      event_type: :offering_available,
+      occurred_at: Time.utc(2026, 4, 28, 14, 30, 15, 123_456)
+    )
+
+    expect(event.to_h).to include(
+      event_id: 'evt-123',
+      event_type: :offering_available,
+      occurred_at: '2026-04-28T14:30:15.123456Z',
+      runtime: { host_id: 'macbook-m4-max', process: { pid: 12_345 } },
+      capacity: { concurrency: 4, queued: 0 },
+      health: { ready: true, latency_ms: 180 },
+      lane: 'llm.fleet.inference.qwen3-6.ctx32768',
+      metadata: { observed_by: :lex_llm_ollama }
+    )
+    expect(event.to_h[:offering]).to include(
+      offering_id: 'ollama:macbook-m4-max:inference:qwen3-6',
+      provider_family: :ollama,
+      provider_instance: :'macbook-m4-max',
+      model: 'qwen3.6',
+      capabilities: %i[chat tools],
+      limits: { context_window: 32_768 },
+      metadata: { enabled: true }
+    )
+  end
+
+  it 'omits sensitive offering fields before publishing' do
+    envelope = event.to_h
+
+    expect(envelope[:offering]).not_to have_key(:credentials)
+    expect(envelope[:offering][:metadata]).not_to have_key(:api_key)
+  end
+
+  it 'normalizes hash offerings through ModelOffering' do
+    event = described_class.heartbeat(
+      {
+        'provider_family' => 'bedrock',
+        'provider_instance' => 'us-east-1',
+        'model' => 'amazon.titan-embed-text-v2:0',
+        'usage_type' => 'embedding',
+        'capabilities' => ['embedding']
+      },
+      event_id: 'evt-heartbeat',
+      occurred_at: '2026-04-28T14:31:00Z'
+    )
+
+    expect(event.to_h).to include(
+      event_id: 'evt-heartbeat',
+      event_type: :offering_heartbeat,
+      occurred_at: '2026-04-28T14:31:00.000000Z'
+    )
+    expect(event.to_h[:offering]).to include(
+      provider_family: :bedrock,
+      provider_instance: :'us-east-1',
+      usage_type: :embedding,
+      capabilities: [:embedding]
+    )
+  end
+
+  it 'provides event-type helpers' do
+    expect(described_class.available(offering).event_type).to eq(:offering_available)
+    expect(described_class.unavailable(offering).event_type).to eq(:offering_unavailable)
+    expect(described_class.degraded(offering).event_type).to eq(:offering_degraded)
+    expect(described_class.heartbeat(offering).event_type).to eq(:offering_heartbeat)
+  end
+
+  it 'rejects unknown event types' do
+    expect do
+      described_class.new(event_type: :available, offering: offering)
+    end.to raise_error(ArgumentError, /unsupported registry event type/)
+  end
+
+  it 'rejects sensitive runtime, capacity, health, lane, and metadata keys' do
+    %i[runtime capacity health lane metadata].each do |field|
+      attributes = {
+        event_type: :offering_degraded,
+        offering: offering,
+        field => { 'nested' => { 'api_key' => 'secret' } }
+      }
+
+      expect do
+        described_class.new(**attributes)
+      end.to raise_error(ArgumentError, /#{field} contains sensitive key: nested.api_key/)
+    end
+  end
+end