lex-llm 0.4.18 → 0.5.0

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

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::Params do
+  describe '.from_hash' do
+    it 'returns a Params instance with canonical fields' do
+      params = described_class.from_hash(max_tokens: 4096, temperature: 0.7)
+
+      expect(params).to be_a(described_class)
+      expect(params.max_tokens).to eq(4096)
+      expect(params.temperature).to eq(0.7)
+      expect(params.top_p).to be_nil
+    end
+
+    it 'normalizes max_output_tokens to max_tokens' do
+      params = described_class.from_hash(max_output_tokens: 2048)
+
+      expect(params.max_tokens).to eq(2048)
+    end
+
+    it 'normalizes num_predict to max_tokens' do
+      params = described_class.from_hash(num_predict: 1024)
+
+      expect(params.max_tokens).to eq(1024)
+    end
+
+    it 'normalizes budget_tokens to max_thinking_tokens' do
+      params = described_class.from_hash(budget_tokens: 5000)
+
+      expect(params.max_thinking_tokens).to eq(5000)
+    end
+
+    it 'normalizes thinking_budget to max_thinking_tokens' do
+      params = described_class.from_hash(thinking_budget: 8000)
+
+      expect(params.max_thinking_tokens).to eq(8000)
+    end
+
+    it 'normalizes stop to stop_sequences' do
+      params = described_class.from_hash(stop: ['\n', 'END'])
+
+      expect(params.stop_sequences).to eq(['\n', 'END'])
+    end
+
+    it 'handles string keys' do
+      params = described_class.from_hash('max_tokens' => '4096', 'temperature' => '0.5')
+
+      expect(params.max_tokens).to eq('4096')
+      expect(params.temperature).to eq('0.5')
+    end
+
+    it 'returns nil for nil source' do
+      expect(described_class.from_hash(nil)).to be_nil
+    end
+
+    it 'returns nil for empty hash' do
+      expect(described_class.from_hash({})).to be_nil
+    end
+
+    it 'returns nil when no known keys present' do
+      result = described_class.from_hash(unknown_key: 'value')
+
+      expect(result).to be_nil
+    end
+
+    it 'filters unknown keys' do
+      params = described_class.from_hash(
+        max_tokens: 4096,
+        temperature: 0.7,
+        unknown_param: 'should_be_filtered',
+        another_unknown: 123
+      )
+
+      expect(params.max_tokens).to eq(4096)
+      expect(params.temperature).to eq(0.7)
+    end
+
+    it 'accepts all G18 standard params' do
+      params = described_class.from_hash(
+        max_tokens: 4096,
+        max_thinking_tokens: 10_000,
+        temperature: 0.7,
+        top_p: 0.95,
+        top_k: 50,
+        stop_sequences: ['END'],
+        seed: 42,
+        frequency_penalty: 0.5,
+        presence_penalty: 0.1,
+        response_format: { type: 'json_object' }
+      )
+
+      expect(params.max_tokens).to eq(4096)
+      expect(params.max_thinking_tokens).to eq(10_000)
+      expect(params.temperature).to eq(0.7)
+      expect(params.top_p).to eq(0.95)
+      expect(params.top_k).to eq(50)
+      expect(params.stop_sequences).to eq(['END'])
+      expect(params.seed).to eq(42)
+      expect(params.frequency_penalty).to eq(0.5)
+      expect(params.presence_penalty).to eq(0.1)
+      expect(params.response_format).to eq({ type: 'json_object' })
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes to compact hash' do
+      params = described_class.new(
+        max_tokens: 4096, temperature: 0.7,
+        max_thinking_tokens: nil, top_p: nil, top_k: nil,
+        stop_sequences: nil, seed: nil,
+        frequency_penalty: nil, presence_penalty: nil,
+        response_format: nil
+      )
+      hash = params.to_h
+
+      expect(hash).to eq(max_tokens: 4096, temperature: 0.7)
+    end
+
+    it 'includes all non-nil fields' do
+      params = described_class.new(
+        max_tokens: 4096, max_thinking_tokens: 10_000,
+        temperature: 0.7, top_p: 0.95, top_k: 50,
+        stop_sequences: ['END'], seed: 42,
+        frequency_penalty: 0.5, presence_penalty: 0.1,
+        response_format: { type: 'json_object' }
+      )
+      hash = params.to_h
+
+      expect(hash).to include(
+        max_tokens: 4096, max_thinking_tokens: 10_000,
+        temperature: 0.7, top_p: 0.95, top_k: 50,
+        stop_sequences: ['END'], seed: 42,
+        frequency_penalty: 0.5, presence_penalty: 0.1,
+        response_format: { type: 'json_object' }
+      )
+    end
+  end
+
+  describe 'round-trip' do
+    it 'preserves values through from_hash/to_h' do
+      original = { max_tokens: 4096, temperature: 0.7, top_p: 0.95 }
+      params = described_class.from_hash(original)
+      serialized = params.to_h
+
+      expect(serialized).to eq(original)
+    end
+
+    it 'normalizes provider keys through round-trip' do
+      original = { max_output_tokens: 2048, budget_tokens: 5000, stop: ['END'] }
+      params = described_class.from_hash(original)
+      serialized = params.to_h
+
+      expect(serialized[:max_tokens]).to eq(2048)
+      expect(serialized[:max_thinking_tokens]).to eq(5000)
+      expect(serialized[:stop_sequences]).to eq(['END'])
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+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
+
+    it 'normalizes tool_choice string to symbol' do
+      req = described_class.build(tool_choice: 'auto')
+
+      expect(req.tool_choice).to eq(:auto)
+    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)
+    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')
+    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')
+    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)
+    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)
+    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')
+    end
+
+    it 'returns nil for nil source' do
+      expect(described_class.from_hash(nil)).to be_nil
+    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') }
+      )
+      hash = req.to_h
+
+      expect(hash[:tools]).to be_a(Hash)
+    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
+  end
+end

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

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+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
+
+    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 'returns nil for nil source' do
+      expect(described_class.from_hash(nil)).to be_nil
+    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)
+    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({})
+    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/)
+    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)
+    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')]
+      )
+
+      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
+    end
+
+    it 'returns false for non-error responses' do
+      resp = described_class.build(stop_reason: :end_turn)
+
+      expect(resp.error?).to be false
+    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
+  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
+  end
+end