lex-llm 0.7.3 → 0.8.0

data/spec/legion/extensions/llm/canonical/request_spec.rb

@@ -1,174 +1,112 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 RSpec.describe Legion::Extensions::Llm::Canonical::Request do
-  describe '.build' do
-    it 'creates a request with required fields' do
-      req = described_class.build(messages: [{ role: :user, content: 'hello' }])
-
-      expect(req.id).to start_with('req_')
-      expect(req.messages).to be_an(Array)
-      expect(req.messages.first).to be_a(Legion::Extensions::Llm::Canonical::Message)
-      expect(req.stream).to be false
-    end
-
-    it 'accepts all fields' do
-      req = described_class.build(
-        id: 'req-1',
-        messages: [{ role: :user, content: 'hello' }],
-        system: 'You are helpful',
-        tools: { search: Legion::Extensions::Llm::Canonical::ToolDefinition.build(name: 'search') },
-        tool_choice: :auto,
-        params: Legion::Extensions::Llm::Canonical::Params.from_hash(max_tokens: 4096),
-        thinking: Legion::Extensions::Llm::Canonical::Thinking::Config.build(effort: 'high'),
-        stream: true,
-        conversation_id: 'conv-1',
-        caller: 'test',
-        routing: { provider: 'anthropic' },
-        metadata: { source: 'cli' }
-      )
-
-      expect(req.id).to eq('req-1')
-      expect(req.system).to eq('You are helpful')
-      expect(req.tools).to be_a(Hash)
-      expect(req.tool_choice).to eq(:auto)
-      expect(req.params).to be_a(Legion::Extensions::Llm::Canonical::Params)
-      expect(req.thinking).to be_a(Legion::Extensions::Llm::Canonical::Thinking::Config)
-      expect(req.stream).to be true
-      expect(req.conversation_id).to eq('conv-1')
-      expect(req.caller).to eq('test')
-      expect(req.routing).to eq({ provider: 'anthropic' })
-      expect(req.metadata).to eq({ source: 'cli' })
-    end
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [:id] }
+  let(:type_source) do
+    {
+      id: 'req_1',
+      messages: [{ role: 'user', content: 'how are you' }],
+      system: 'be brief',
+      tools: [{ name: 'get_weather', description: 'd', parameters: { type: 'object', properties: {} } }],
+      tool_choice: 'auto',
+      params: { temperature: 0.5 },
+      thinking: { effort: 'low' },
+      stream: false,
+      conversation_id: 'conv_1',
+      caller: 'e2e',
+      routing: { provider: 'fake' },
+      metadata: { origin: 'client' }
+    }
+  end
 
-    it 'normalizes tool_choice string to symbol' do
-      req = described_class.build(tool_choice: 'auto')
+  it_behaves_like 'a canonical type'
 
-      expect(req.tool_choice).to eq(:auto)
+  describe 'H1 — .new is as strict as the factories' do
+    it 'rejects non-canonical messages in the member contract' do
+      expect { described_class.new(messages: [42]) }
+        .to raise_error(ArgumentError, /expected Hash, got Integer/)
     end
 
-    it 'normalizes params from hash' do
-      req = described_class.build(params: { max_tokens: 4096, temperature: 0.7 })
-
-      expect(req.params).to be_a(Legion::Extensions::Llm::Canonical::Params)
-      expect(req.params.max_tokens).to eq(4096)
+    it 'normalizes Hash tools to ToolDefinition like the factories' do
+      request = described_class.new(tools: [{ name: 'f', parameters: {} }])
+      expect(request.tools.values.first).to be_a(Legion::Extensions::Llm::Canonical::ToolDefinition)
     end
+  end
 
-    it 'normalizes thinking config from hash' do
-      req = described_class.build(thinking: { effort: 'high', budget: 10_000 })
-
-      expect(req.thinking).to be_a(Legion::Extensions::Llm::Canonical::Thinking::Config)
-      expect(req.thinking.effort).to eq('high')
+  describe 'F2 fix — strict message map (no silent drops)' do
+    it 'normalizes Hash messages and passes Canonical through (T7)' do
+      canonical = Legion::Extensions::Llm::Canonical::Message.build(role: :user, content: 'hi')
+      raw = { role: 'user', content: 'there' }
+      via_build = described_class.build(messages: [canonical, raw])
+      via_hash = described_class.from_hash(messages: [canonical, raw])
+      expect(via_build.messages.map { |m| [m.role, m.content, m.class] })
+        .to eq(via_hash.messages.map { |m| [m.role, m.content, m.class] })
+      expect(via_build.messages).to all(be_a(Legion::Extensions::Llm::Canonical::Message))
     end
 
-    it 'accepts tools as array' do
-      req = described_class.build(
-        tools: [{ name: 'search', description: 'Search' }]
-      )
-
-      expect(req.tools).to be_a(Hash)
-      expect(req.tools.keys).to include('search')
+    it 'raises on non-Message/non-Hash elements (the filter_map drop is deleted)' do
+      expect { described_class.build(messages: [42]) }
+        .to raise_error(ArgumentError, /expected Hash, got Integer/)
+      expect { described_class.build(messages: [nil]) }
+        .to raise_error(ArgumentError, /expected Hash, got NilClass/)
+      expect { described_class.from_hash(messages: ['str']) }
+        .to raise_error(ArgumentError, /expected Hash, got String/)
     end
 
-    it 'accepts tools as hash' do
-      req = described_class.build(
-        tools: { search: { name: 'search', description: 'Search' } }
-      )
-
-      expect(req.tools).to be_a(Hash)
-      expect(req.tools[:search]).to be_a(Legion::Extensions::Llm::Canonical::ToolDefinition)
+    it 'raises on a wrong-class messages member' do
+      expect { described_class.build(messages: 'nope') }
+        .to raise_error(ArgumentError, /messages expected Array, got String/)
     end
   end
 
-  describe '.from_hash' do
-    it 'parses from hash with symbol keys' do
-      req = described_class.from_hash(
-        messages: [{ role: :user, content: 'hello' }],
-        system: 'You are helpful',
-        stream: true
-      )
-
-      expect(req.system).to eq('You are helpful')
-      expect(req.stream).to be true
-      expect(req.messages.first).to be_a(Legion::Extensions::Llm::Canonical::Message)
+  describe 'L2 — tools/params/thinking normalizers shared by both factories' do
+    it 'normalizes tools to Hash<name, ToolDefinition> (T7)' do
+      via_build = described_class.build(tools: [{ name: 'get_weather', parameters: {} }])
+      via_hash = described_class.from_hash(tools: [{ name: 'get_weather', parameters: {} }])
+      expect(via_build.tools).to eq(via_hash.tools)
+      expect(via_build.tools.keys).to eq(%w[get_weather])
+      expect(via_build.tools.values.first).to be_a(Legion::Extensions::Llm::Canonical::ToolDefinition)
     end
 
-    it 'moves unknown keys to metadata' do
-      req = described_class.from_hash(
-        messages: [{ role: :user, content: 'hello' }],
-        custom_field: 'value',
-        another_custom: 123
-      )
-
-      expect(req.metadata[:custom_field]).to eq('value')
-      expect(req.metadata[:another_custom]).to eq(123)
-    end
-
-    it 'merges unknown keys with existing metadata' do
-      req = described_class.from_hash(
-        messages: [{ role: :user, content: 'hello' }],
-        metadata: { existing: 'data' },
-        custom_field: 'value'
-      )
-
-      expect(req.metadata[:existing]).to eq('data')
-      expect(req.metadata[:custom_field]).to eq('value')
+    it 'normalizes params to Canonical::Params and thinking to Thinking::Config' do
+      request = described_class.build(params: { temperature: 1 }, thinking: { effort: 'high' })
+      expect(request.params).to be_a(Legion::Extensions::Llm::Canonical::Params)
+      expect(request.thinking).to be_a(Legion::Extensions::Llm::Canonical::Thinking::Config)
+      expect(request.thinking.effort).to eq('high')
     end
 
-    it 'returns nil for nil source' do
-      expect(described_class.from_hash(nil)).to be_nil
+    it 'raises on wrong-class params/thinking' do
+      expect { described_class.build(params: 'nope') }
+        .to raise_error(ArgumentError, /params expected Hash, got String/)
+      expect { described_class.from_hash(thinking: 42) }
+        .to raise_error(ArgumentError, /thinking expected Hash, got Integer/)
     end
   end
 
-  describe '#to_h' do
-    it 'serializes to hash with nested objects' do
-      req = described_class.build(
-        messages: [{ role: :user, content: 'hello' }],
-        system: 'You are helpful',
-        params: Legion::Extensions::Llm::Canonical::Params.from_hash(max_tokens: 4096)
-      )
-      hash = req.to_h
-
-      expect(hash[:id]).to start_with('req_')
-      expect(hash[:system]).to eq('You are helpful')
-      expect(hash[:params]).to eq({ max_tokens: 4096 })
-    end
-
-    it 'serializes messages as hashes' do
-      req = described_class.build(
-        messages: [{ role: :user, content: 'hello' }]
-      )
-      hash = req.to_h
-
-      expect(hash[:messages]).to be_an(Array)
-      expect(hash[:messages].first).to be_a(Hash)
-    end
-
-    it 'serializes tools as hashes' do
-      req = described_class.build(
-        tools: { search: Legion::Extensions::Llm::Canonical::ToolDefinition.build(name: 'search') }
+  describe 'T4 — member survival through the wire' do
+    it 'survives build → to_h → JSON → from_hash' do
+      request = described_class.build(
+        messages: [Legion::Extensions::Llm::Canonical::Message.build(role: :user, content: 'hi',
+                                                                     cache_control: { type: 'ephemeral' })],
+        params: { temperature: 0.25 }
       )
-      hash = req.to_h
-
-      expect(hash[:tools]).to be_a(Hash)
+      wire = Legion::JSON.load(Legion::JSON.dump(request.to_h))
+      round_tripped = described_class.from_hash(wire)
+      expect(round_tripped.messages.first.content).to eq('hi')
+      expect(round_tripped.messages.first.cache_control).to eq(type: 'ephemeral')
+      expect(round_tripped.params.temperature).to eq(0.25)
     end
   end
 
-  describe 'round-trip' do
-    it 'preserves values through from_hash/to_h' do
-      original = {
-        messages: [{ role: 'user', content: 'hello' }],
-        system: 'You are helpful',
-        stream: true,
-        conversation_id: 'conv-1'
-      }
-      req = described_class.from_hash(original)
-      serialized = req.to_h
-
-      expect(serialized[:system]).to eq('You are helpful')
-      expect(serialized[:stream]).to be true
-      expect(serialized[:conversation_id]).to eq('conv-1')
-    end
+  it 'defaults stream false, routing {} and auto-generates req ids' do
+    request = described_class.build(messages: [])
+    expect(request.stream).to be(false)
+    expect(request.routing).to eq({})
+    expect(request.id).to match(/\Areq_[0-9a-f]{24}\z/)
+    expect(request.messages).to eq([])
   end
 end

data/spec/legion/extensions/llm/canonical/response_spec.rb

@@ -1,234 +1,98 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 RSpec.describe Legion::Extensions::Llm::Canonical::Response do
-  describe '.from_hash' do
-    it 'returns a Response instance with canonical fields' do
-      resp = described_class.from_hash(
-        text: 'Hello world',
-        stop_reason: 'end_turn',
-        model: 'claude-sonnet-4-6'
-      )
-
-      expect(resp).to be_a(described_class)
-      expect(resp.text).to eq('Hello world')
-      expect(resp.stop_reason).to eq(:end_turn)
-      expect(resp.model).to eq('claude-sonnet-4-6')
-      expect(resp.tool_calls).to eq([])
-    end
-
-    it 'normalizes stop_reason to symbol' do
-      resp = described_class.from_hash(stop_reason: 'tool_use')
-
-      expect(resp.stop_reason).to eq(:tool_use)
-    end
-
-    it 'parses thinking from nested hash' do
-      resp = described_class.from_hash(
-        text: 'answer',
-        thinking: { content: 'reasoning', signature: 'sig-1' }
-      )
-
-      expect(resp.thinking).to be_a(Legion::Extensions::Llm::Canonical::Thinking)
-      expect(resp.thinking.content).to eq('reasoning')
-    end
-
-    it 'parses usage from nested hash' do
-      resp = described_class.from_hash(
-        text: 'answer',
-        usage: { input_tokens: 100, output_tokens: 50 }
-      )
-
-      expect(resp.usage).to be_a(Legion::Extensions::Llm::Canonical::Usage)
-      expect(resp.usage.input_tokens).to eq(100)
-    end
-
-    it 'parses tool_calls from array of hashes' do
-      resp = described_class.from_hash(
-        text: '',
-        tool_calls: [{ name: 'search', arguments: { query: 'test' } }]
-      )
-
-      expect(resp.tool_calls).to be_an(Array)
-      expect(resp.tool_calls.first).to be_a(Legion::Extensions::Llm::Canonical::ToolCall)
-    end
-
-    it 'accepts finish_reason as alias for stop_reason' do
-      resp = described_class.from_hash(finish_reason: 'max_tokens')
-
-      expect(resp.stop_reason).to eq(:max_tokens)
-    end
-
-    it 'accepts content as alias for text' do
-      resp = described_class.from_hash(content: 'Hello world')
-
-      expect(resp.text).to eq('Hello world')
-    end
-
-    it 'moves unknown keys to metadata' do
-      resp = described_class.from_hash(
-        text: 'answer',
-        cache_creation_input_tokens: 25,
-        custom_field: 'value'
-      )
-
-      expect(resp.metadata[:cache_creation_input_tokens]).to eq(25)
-      expect(resp.metadata[:custom_field]).to eq('value')
-    end
-
-    it 'merges unknown keys with existing metadata' do
-      resp = described_class.from_hash(
-        text: 'answer',
-        metadata: { existing: 'data' },
-        custom_field: 'value'
-      )
-
-      expect(resp.metadata[:existing]).to eq('data')
-      expect(resp.metadata[:custom_field]).to eq('value')
-    end
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [] }
+  let(:type_source) do
+    {
+      text: 'I am done',
+      thinking: { content: 'reasoning', signature: 'sig-1' },
+      tool_calls: [{ name: 'get_weather', arguments: { location: 'sf' } }],
+      usage: { input_tokens: 12, output_tokens: 10 },
+      stop_reason: 'end_turn',
+      model: 'fake-model',
+      routing: { lane_id: 'local:vllm:h200:inference:gemma4' },
+      metadata: { origin: 'provider' }
+    }
+  end
 
-    it 'rejects invalid stop_reasons' do
-      expect do
-        described_class.from_hash(stop_reason: 'invalid_reason')
-      end.to raise_error(ArgumentError, /Invalid stop_reason/)
-    end
+  it_behaves_like 'a canonical type'
 
-    it 'returns nil for nil source' do
-      expect(described_class.from_hash(nil)).to be_nil
+  describe 'H1 — .new is as strict as the factories' do
+    it 'rejects a poison stop_reason' do
+      expect { described_class.new(text: 'x', stop_reason: :bogus_reason) }
+        .to raise_error(ArgumentError, /Invalid stop_reason/)
     end
 
-    it 'handles string keys' do
-      resp = described_class.from_hash(
-        'text' => 'Hello',
-        'stop_reason' => 'end_turn',
-        'model' => 'claude-sonnet-4-6'
-      )
-
-      expect(resp.text).to eq('Hello')
-      expect(resp.stop_reason).to eq(:end_turn)
+    it 'rejects a wrong-class usage member' do
+      expect { described_class.new(usage: 'nope') }
+        .to raise_error(ArgumentError, /usage expected Hash, got String/)
     end
   end
 
-  describe '.build' do
-    it 'creates a response with defaults' do
-      resp = described_class.build
-
-      expect(resp.text).to eq('')
-      expect(resp.tool_calls).to eq([])
-      expect(resp.routing).to eq({})
-      expect(resp.metadata).to eq({})
+  describe 'T5 — stop_reason enum (validated in both factories)' do
+    it 'accepts every canonical stop reason in both factories' do
+      described_class::STOP_REASONS.each do |reason|
+        expect(described_class.build(text: 'x', stop_reason: reason).stop_reason).to eq(reason)
+        expect(described_class.from_hash(text: 'x', stop_reason: reason.to_s).stop_reason).to eq(reason)
+      end
     end
 
-    it 'creates a response with all fields' do
-      thinking = Legion::Extensions::Llm::Canonical::Thinking.new(content: 'reasoning', signature: 'sig')
-      usage = Legion::Extensions::Llm::Canonical::Usage.new(
-        input_tokens: 100, output_tokens: 50,
-        cache_read_tokens: nil, cache_write_tokens: nil,
-        thinking_tokens: nil, units: {}
-      )
-      resp = described_class.build(
-        text: 'answer',
-        thinking: thinking,
-        tool_calls: [],
-        usage: usage,
-        stop_reason: :end_turn,
-        model: 'claude-sonnet-4-6'
-      )
-
-      expect(resp.text).to eq('answer')
-      expect(resp.thinking).to eq(thinking)
-      expect(resp.usage).to eq(usage)
-      expect(resp.stop_reason).to eq(:end_turn)
-      expect(resp.model).to eq('claude-sonnet-4-6')
-    end
-
-    it 'rejects invalid stop_reasons' do
-      expect do
-        described_class.build(stop_reason: :invalid_reason)
-      end.to raise_error(ArgumentError, /Invalid stop_reason/)
+    it 'raises on an invalid stop reason in both factories' do
+      expect { described_class.build(stop_reason: :invalid_reason, text: 'test') }
+        .to raise_error(ArgumentError, /Invalid stop_reason/)
+      expect { described_class.from_hash(stop_reason: 'bogus', text: 'test') }
+        .to raise_error(ArgumentError, /Invalid stop_reason/)
     end
   end
 
-  describe '#to_h' do
-    it 'serializes to compact hash' do
-      resp = described_class.build(text: 'answer', stop_reason: :end_turn, model: 'claude-sonnet-4-6')
-      hash = resp.to_h
-
-      expect(hash).to eq(
-        text: 'answer',
-        stop_reason: :end_turn,
-        model: 'claude-sonnet-4-6'
-      )
-    end
-
-    it 'serializes nested objects' do
-      thinking = Legion::Extensions::Llm::Canonical::Thinking.new(content: 'reasoning', signature: 'sig')
-      usage = Legion::Extensions::Llm::Canonical::Usage.new(
-        input_tokens: 100, output_tokens: 50,
-        cache_read_tokens: nil, cache_write_tokens: nil,
-        thinking_tokens: nil, units: {}
-      )
-      resp = described_class.build(text: 'answer', thinking: thinking, usage: usage)
-      hash = resp.to_h
-
-      expect(hash[:thinking]).to eq(content: 'reasoning', signature: 'sig')
-      expect(hash[:usage]).to include(input_tokens: 100, output_tokens: 50)
+  describe 'O03a — finish_reason alias deleted' do
+    it 'does not translate finish_reason (it folds into metadata)' do
+      response = described_class.from_hash(text: 'x', finish_reason: 'stop')
+      expect(response.stop_reason).to be_nil
+      expect(response.metadata).to eq(finish_reason: 'stop')
     end
   end
 
-  describe 'predicates' do
-    it 'identifies tool call responses' do
-      resp = described_class.build(
-        text: '',
-        tool_calls: [Legion::Extensions::Llm::Canonical::ToolCall.build(name: 'search')]
+  describe 'L2 — build and from_hash share the member normalizers (T7)' do
+    it 'normalizes tool_calls / usage / thinking identically' do
+      raw_tool_calls = [{ id: 'tc_1', name: 'x', arguments: { a: 1 } }]
+      via_build = described_class.build(
+        tool_calls: raw_tool_calls,
+        usage: { input_tokens: 3 },
+        thinking: { content: 'hmm' }
       )
-
-      expect(resp.tool_call?).to be true
-    end
-
-    it 'returns false for empty tool calls' do
-      resp = described_class.build(text: 'answer', tool_calls: [])
-
-      expect(resp.tool_call?).to be false
-    end
-
-    it 'identifies error responses' do
-      resp = described_class.build(stop_reason: :error)
-
-      expect(resp.error?).to be true
+      via_hash = described_class.from_hash(
+        tool_calls: raw_tool_calls,
+        usage: { input_tokens: 3 },
+        thinking: { content: 'hmm' }
+      )
+      expect(via_build.tool_calls).to eq(via_hash.tool_calls)
+      expect(via_build.usage).to eq(via_hash.usage)
+      expect(via_build.thinking).to eq(via_hash.thinking)
     end
 
-    it 'returns false for non-error responses' do
-      resp = described_class.build(stop_reason: :end_turn)
-
-      expect(resp.error?).to be false
+    it 'raises on wrong-class members' do
+      expect { described_class.build(usage: 'nope') }
+        .to raise_error(ArgumentError, /usage expected Hash, got String/)
+      expect { described_class.from_hash(tool_calls: 'nope') }
+        .to raise_error(ArgumentError, /tool_calls expected Array, got String/)
     end
   end
 
-  describe 'STOP_REASONS' do
-    it 'includes all expected stop reasons' do
-      expect(described_class::STOP_REASONS).to eq(
-        %i[end_turn tool_use max_tokens stop_sequence content_filter error]
-      )
-    end
+  it 'defaults to an empty canonical response from {}' do
+    response = described_class.from_hash({})
+    expect(response.text).to eq('')
+    expect(response.tool_calls).to eq([])
+    expect(response.stop_reason).to be_nil
   end
 
-  describe 'round-trip' do
-    it 'preserves values through from_hash/to_h' do
-      original = {
-        text: 'Hello world',
-        stop_reason: 'end_turn',
-        model: 'claude-sonnet-4-6',
-        usage: { input_tokens: 100, output_tokens: 50 }
-      }
-      resp = described_class.from_hash(original)
-      serialized = resp.to_h
-
-      expect(serialized[:text]).to eq('Hello world')
-      expect(serialized[:stop_reason]).to eq(:end_turn)
-      expect(serialized[:model]).to eq('claude-sonnet-4-6')
-      expect(serialized[:usage]).to include(input_tokens: 100, output_tokens: 50)
-    end
+  it 'is the provider-boundary contract: error? and tool_call? predicates' do
+    expect(described_class.build(stop_reason: :error).error?).to be(true)
+    tc = Legion::Extensions::Llm::Canonical::ToolCall.build(name: 'x')
+    expect(described_class.build(tool_calls: [tc]).tool_call?).to be(true)
   end
 end