lex-llm 0.4.18 → 0.5.0

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

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::Chunk do
+  describe '.text_delta' do
+    it 'creates a text delta chunk' do
+      chunk = described_class.text_delta(delta: 'hello', request_id: 'req-1')
+
+      expect(chunk.type).to eq(:text_delta)
+      expect(chunk.delta).to eq('hello')
+      expect(chunk.request_id).to eq('req-1')
+      expect(chunk.index).to eq(0)
+      expect(chunk.timestamp).to be_a(Time)
+    end
+
+    it 'accepts block_index and item_id' do
+      chunk = described_class.text_delta(
+        delta: 'hello',
+        request_id: 'req-1',
+        block_index: 0,
+        item_id: 'item-1'
+      )
+
+      expect(chunk.block_index).to eq(0)
+      expect(chunk.item_id).to eq('item-1')
+    end
+  end
+
+  describe '.thinking_delta' do
+    it 'creates a thinking delta chunk' do
+      chunk = described_class.thinking_delta(
+        delta: 'reasoning',
+        request_id: 'req-1',
+        signature: 'sig-partial'
+      )
+
+      expect(chunk.type).to eq(:thinking_delta)
+      expect(chunk.delta).to eq('reasoning')
+      expect(chunk.signature).to eq('sig-partial')
+    end
+  end
+
+  describe '.tool_call_delta' do
+    it 'creates a tool call delta chunk' do
+      tool_call = Legion::Extensions::Llm::Canonical::ToolCall.build(name: 'search')
+      chunk = described_class.tool_call_delta(tool_call: tool_call, request_id: 'req-1')
+
+      expect(chunk.type).to eq(:tool_call_delta)
+      expect(chunk.tool_call).to eq(tool_call)
+    end
+  end
+
+  describe '.usage_chunk' do
+    it 'creates a usage chunk' do
+      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: {}
+      )
+      chunk = described_class.usage_chunk(usage: usage, request_id: 'req-1')
+
+      expect(chunk.type).to eq(:usage)
+      expect(chunk.usage).to eq(usage)
+    end
+  end
+
+  describe '.done' do
+    it 'creates a done chunk' do
+      chunk = described_class.done(request_id: 'req-1', stop_reason: :end_turn)
+
+      expect(chunk.type).to eq(:done)
+      expect(chunk.stop_reason).to eq(:end_turn)
+    end
+
+    it 'includes usage when provided' do
+      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: {}
+      )
+      chunk = described_class.done(request_id: 'req-1', usage: usage, stop_reason: :end_turn)
+
+      expect(chunk.usage).to eq(usage)
+    end
+  end
+
+  describe '.error_chunk' do
+    it 'creates an error chunk' do
+      chunk = described_class.error_chunk(error: 'timeout', request_id: 'req-1')
+
+      expect(chunk.type).to eq(:error)
+      expect(chunk.stop_reason).to eq(:error)
+      expect(chunk.metadata[:error]).to eq('timeout')
+    end
+
+    it 'merges additional metadata' do
+      chunk = described_class.error_chunk(
+        error: 'timeout',
+        request_id: 'req-1',
+        metadata: { provider: 'anthropic' }
+      )
+
+      expect(chunk.metadata[:error]).to eq('timeout')
+      expect(chunk.metadata[:provider]).to eq('anthropic')
+    end
+  end
+
+  describe '.from_hash' do
+    it 'parses from hash with symbol keys' do
+      chunk = described_class.from_hash(
+        type: :text_delta,
+        delta: 'hello',
+        request_id: 'req-1'
+      )
+
+      expect(chunk.type).to eq(:text_delta)
+      expect(chunk.delta).to eq('hello')
+      expect(chunk.request_id).to eq('req-1')
+    end
+
+    it 'normalizes type string to symbol' do
+      chunk = described_class.from_hash(type: 'text_delta', delta: 'hello', request_id: 'req-1')
+
+      expect(chunk.type).to eq(:text_delta)
+    end
+
+    it 'parses nested tool_call' do
+      chunk = described_class.from_hash(
+        type: :tool_call_delta,
+        request_id: 'req-1',
+        tool_call: { name: 'search', arguments: { query: 'test' } }
+      )
+
+      expect(chunk.tool_call).to be_a(Legion::Extensions::Llm::Canonical::ToolCall)
+      expect(chunk.tool_call.name).to eq('search')
+    end
+
+    it 'parses nested usage' do
+      chunk = described_class.from_hash(
+        type: :usage,
+        request_id: 'req-1',
+        usage: { input_tokens: 100, output_tokens: 50 }
+      )
+
+      expect(chunk.usage).to be_a(Legion::Extensions::Llm::Canonical::Usage)
+    end
+
+    it 'normalizes stop_reason' do
+      chunk = described_class.from_hash(
+        type: :done,
+        request_id: 'req-1',
+        stop_reason: 'end_turn'
+      )
+
+      expect(chunk.stop_reason).to eq(:end_turn)
+    end
+
+    it 'accepts finish_reason as alias' do
+      chunk = described_class.from_hash(
+        type: :done,
+        request_id: 'req-1',
+        finish_reason: 'tool_use'
+      )
+
+      expect(chunk.stop_reason).to eq(:tool_use)
+    end
+
+    it 'returns nil for nil source' do
+      expect(described_class.from_hash(nil)).to be_nil
+    end
+
+    it 'handles string keys' do
+      chunk = described_class.from_hash(
+        'type' => 'text_delta',
+        'delta' => 'hello',
+        'request_id' => 'req-1'
+      )
+
+      expect(chunk.type).to eq(:text_delta)
+      expect(chunk.delta).to eq('hello')
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes to compact hash' do
+      chunk = described_class.text_delta(delta: 'hello', request_id: 'req-1')
+      hash = chunk.to_h
+
+      expect(hash).to include(type: :text_delta, delta: 'hello', request_id: 'req-1')
+    end
+
+    it 'serializes nested objects' do
+      tool_call = Legion::Extensions::Llm::Canonical::ToolCall.build(name: 'search')
+      chunk = described_class.tool_call_delta(tool_call: tool_call, request_id: 'req-1')
+      hash = chunk.to_h
+
+      expect(hash[:tool_call]).to be_a(Hash)
+      expect(hash[:tool_call][:name]).to eq('search')
+    end
+  end
+
+  describe 'type predicates' do
+    it 'identifies text_delta chunks' do
+      chunk = described_class.text_delta(delta: 'hello', request_id: 'req-1')
+      expect(chunk.text_delta?).to be true
+      expect(chunk.content?).to be true
+    end
+
+    it 'identifies thinking_delta chunks' do
+      chunk = described_class.thinking_delta(delta: 'reasoning', request_id: 'req-1')
+      expect(chunk.thinking_delta?).to be true
+      expect(chunk.content?).to be true
+    end
+
+    it 'identifies tool_call_delta chunks' do
+      tc = Legion::Extensions::Llm::Canonical::ToolCall.build(name: 'search')
+      chunk = described_class.tool_call_delta(tool_call: tc, request_id: 'req-1')
+      expect(chunk.tool_call_delta?).to be true
+      expect(chunk.content?).to be false
+    end
+
+    it 'identifies usage chunks' do
+      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: {}
+      )
+      chunk = described_class.usage_chunk(usage: usage, request_id: 'req-1')
+      expect(chunk.usage?).to be true
+    end
+
+    it 'identifies done chunks' do
+      chunk = described_class.done(request_id: 'req-1')
+      expect(chunk.done?).to be true
+    end
+
+    it 'identifies error chunks' do
+      chunk = described_class.error_chunk(error: 'timeout', request_id: 'req-1')
+      expect(chunk.error?).to be true
+    end
+  end
+
+  describe 'CHUNK_TYPES' do
+    it 'includes all expected chunk types' do
+      expect(described_class::CHUNK_TYPES).to eq(
+        %i[text_delta thinking_delta tool_call_delta usage done error]
+      )
+    end
+  end
+
+  describe 'round-trip' do
+    it 'preserves text_delta through from_hash/to_h' do
+      original = {
+        type: 'text_delta',
+        delta: 'hello',
+        request_id: 'req-1',
+        block_index: 0,
+        item_id: 'item-1'
+      }
+      chunk = described_class.from_hash(original)
+      serialized = chunk.to_h
+
+      expect(serialized[:type]).to eq(:text_delta)
+      expect(serialized[:delta]).to eq('hello')
+      expect(serialized[:block_index]).to eq(0)
+      expect(serialized[:item_id]).to eq('item-1')
+    end
+
+    it 'preserves done chunk through from_hash/to_h' do
+      original = {
+        type: 'done',
+        request_id: 'req-1',
+        stop_reason: 'end_turn',
+        usage: { input_tokens: 100, output_tokens: 50 }
+      }
+      chunk = described_class.from_hash(original)
+      serialized = chunk.to_h
+
+      expect(serialized[:type]).to eq(:done)
+      expect(serialized[:stop_reason]).to eq(:end_turn)
+      expect(serialized[:usage]).to include(input_tokens: 100, output_tokens: 50)
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::ContentBlock do
+  describe '.text' do
+    it 'creates a text content block' do
+      block = described_class.text('hello world')
+
+      expect(block.type).to eq(:text)
+      expect(block.text).to eq('hello world')
+    end
+
+    it 'accepts cache_control' do
+      block = described_class.text('hello', cache_control: { type: 'ephemeral' })
+
+      expect(block.cache_control).to eq({ type: 'ephemeral' })
+    end
+  end
+
+  describe '.thinking' do
+    it 'creates a thinking content block' do
+      block = described_class.thinking('reasoning here')
+
+      expect(block.type).to eq(:thinking)
+      expect(block.text).to eq('reasoning here')
+    end
+  end
+
+  describe '.tool_use' do
+    it 'creates a tool_use content block' do
+      block = described_class.tool_use(id: 'toolu-1', name: 'search', input: { query: 'test' })
+
+      expect(block.type).to eq(:tool_use)
+      expect(block.id).to eq('toolu-1')
+      expect(block.name).to eq('search')
+      expect(block.input).to eq({ query: 'test' })
+    end
+  end
+
+  describe '.tool_result' do
+    it 'creates a tool_result content block' do
+      block = described_class.tool_result(tool_use_id: 'toolu-1', content: 'result')
+
+      expect(block.type).to eq(:tool_result)
+      expect(block.tool_use_id).to eq('toolu-1')
+      expect(block.text).to eq('result')
+      expect(block.is_error).to be false
+    end
+
+    it 'marks error results' do
+      block = described_class.tool_result(tool_use_id: 'toolu-1', content: 'error', is_error: true)
+
+      expect(block.is_error).to be true
+    end
+  end
+
+  describe '.image' do
+    it 'creates an image content block with media_type (G20a)' do
+      block = described_class.image(data: 'base64data', media_type: 'image/png')
+
+      expect(block.type).to eq(:image)
+      expect(block.data).to eq('base64data')
+      expect(block.media_type).to eq('image/png')
+      expect(block.source_type).to eq(:base64)
+    end
+
+    it 'accepts custom source_type and detail' do
+      block = described_class.image(data: 'img.png', media_type: 'image/png', source_type: :url, detail: 'high')
+
+      expect(block.source_type).to eq(:url)
+      expect(block.detail).to eq('high')
+    end
+  end
+
+  describe '.from_hash' do
+    it 'parses a content block from hash' do
+      block = described_class.from_hash(type: 'text', text: 'hello')
+
+      expect(block.type).to eq(:text)
+      expect(block.text).to eq('hello')
+    end
+
+    it 'handles string keys' do
+      block = described_class.from_hash('type' => 'thinking', 'text' => 'reasoning')
+
+      expect(block.type).to eq(:thinking)
+      expect(block.text).to eq('reasoning')
+    end
+
+    it 'returns nil for nil source' do
+      expect(described_class.from_hash(nil)).to be_nil
+    end
+
+    it 'preserves all fields' do
+      hash = {
+        type: 'tool_use',
+        id: 'toolu-1',
+        name: 'search',
+        input: { query: 'test' },
+        cache_control: { type: 'ephemeral' }
+      }
+      block = described_class.from_hash(hash)
+
+      expect(block.type).to eq(:tool_use)
+      expect(block.id).to eq('toolu-1')
+      expect(block.name).to eq('search')
+      expect(block.input).to eq({ query: 'test' })
+      expect(block.cache_control).to eq({ type: 'ephemeral' })
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes to compact hash' do
+      block = described_class.text('hello')
+      hash = block.to_h
+
+      expect(hash).to eq(type: :text, text: 'hello')
+    end
+
+    it 'omits nil values' do
+      block = described_class.new(
+        type: :text, text: 'hello', data: nil, source_type: nil,
+        media_type: nil, detail: nil, name: nil, file_id: nil,
+        id: nil, input: nil, tool_use_id: nil, is_error: nil,
+        source: nil, start_index: nil, end_index: nil,
+        code: nil, message: nil, cache_control: nil
+      )
+      hash = block.to_h
+
+      expect(hash).to eq(type: :text, text: 'hello')
+    end
+  end
+
+  describe 'type predicates' do
+    it 'identifies text blocks' do
+      block = described_class.text('hello')
+      expect(block.text?).to be true
+      expect(block.thinking?).to be false
+      expect(block.tool_use?).to be false
+      expect(block.tool_result?).to be false
+    end
+
+    it 'identifies thinking blocks' do
+      block = described_class.thinking('reasoning')
+      expect(block.thinking?).to be true
+      expect(block.text?).to be false
+    end
+
+    it 'identifies tool_use blocks' do
+      block = described_class.tool_use(id: '1', name: 'search', input: {})
+      expect(block.tool_use?).to be true
+    end
+
+    it 'identifies tool_result blocks' do
+      block = described_class.tool_result(tool_use_id: '1', content: 'result')
+      expect(block.tool_result?).to be true
+    end
+  end
+
+  describe 'CONTENT_BLOCK_TYPES' do
+    it 'includes all expected types' do
+      expect(described_class::CONTENT_BLOCK_TYPES).to include(
+        :text, :thinking, :tool_use, :tool_result, :image, :audio, :video
+      )
+    end
+  end
+
+  describe 'round-trip' do
+    it 'preserves text block through from_hash/to_h' do
+      original = { type: 'text', text: 'hello world' }
+      block = described_class.from_hash(original)
+      serialized = block.to_h
+
+      expect(serialized[:type]).to eq(:text)
+      expect(serialized[:text]).to eq('hello world')
+    end
+  end
+end

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

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::Message do
+  describe '.build' do
+    it 'creates a message with required fields' do
+      msg = described_class.build(role: :user, content: 'hello')
+
+      expect(msg.role).to eq(:user)
+      expect(msg.content).to eq('hello')
+      expect(msg.id).to start_with('msg_')
+      expect(msg.status).to eq(:created)
+      expect(msg.version).to eq(1)
+    end
+
+    it 'accepts all fields' do
+      msg = described_class.build(
+        id: 'msg-1',
+        parent_id: 'msg-0',
+        role: :assistant,
+        content: 'response',
+        tool_calls: [],
+        conversation_id: 'conv-1'
+      )
+
+      expect(msg.id).to eq('msg-1')
+      expect(msg.parent_id).to eq('msg-0')
+      expect(msg.role).to eq(:assistant)
+      expect(msg.conversation_id).to eq('conv-1')
+    end
+
+    it 'normalizes string role to symbol' do
+      msg = described_class.build(role: 'user', content: 'hello')
+
+      expect(msg.role).to eq(:user)
+    end
+
+    it 'rejects invalid roles' do
+      expect do
+        described_class.build(role: :invalid, content: 'hello')
+      end.to raise_error(ArgumentError, /Invalid role/)
+    end
+
+    it 'defaults to user role' do
+      msg = described_class.build(content: 'hello')
+
+      expect(msg.role).to eq(:user)
+    end
+
+    it 'sets timestamp automatically' do
+      msg = described_class.build(content: 'hello')
+
+      expect(msg.timestamp).to be_a(Time)
+    end
+  end
+
+  describe '.from_hash' do
+    it 'parses from hash with symbol keys' do
+      msg = described_class.from_hash(role: :user, content: 'hello')
+
+      expect(msg.role).to eq(:user)
+      expect(msg.content).to eq('hello')
+    end
+
+    it 'normalizes string role to symbol' do
+      msg = described_class.from_hash(role: 'assistant', content: 'response')
+
+      expect(msg.role).to eq(:assistant)
+    end
+
+    it 'parses content blocks from array of hashes' do
+      msg = described_class.from_hash(
+        role: :user,
+        content: [{ type: 'text', text: 'hello' }]
+      )
+
+      expect(msg.content).to be_an(Array)
+      expect(msg.content.first).to be_a(Legion::Extensions::Llm::Canonical::ContentBlock)
+      expect(msg.content.first.type).to eq(:text)
+    end
+
+    it 'parses single content block from hash' do
+      msg = described_class.from_hash(
+        role: :user,
+        content: { type: 'text', text: 'hello' }
+      )
+
+      expect(msg.content).to be_a(Legion::Extensions::Llm::Canonical::ContentBlock)
+    end
+
+    it 'parses tool calls from array of hashes' do
+      msg = described_class.from_hash(
+        role: :assistant,
+        tool_calls: [{ name: 'search', arguments: { query: 'test' } }]
+      )
+
+      expect(msg.tool_calls).to be_an(Array)
+      expect(msg.tool_calls.first).to be_a(Legion::Extensions::Llm::Canonical::ToolCall)
+    end
+
+    it 'handles string keys' do
+      msg = described_class.from_hash('role' => 'user', 'content' => 'hello')
+
+      expect(msg.role).to eq(:user)
+      expect(msg.content).to eq('hello')
+    end
+
+    it 'returns nil for nil source' do
+      expect(described_class.from_hash(nil)).to be_nil
+    end
+  end
+
+  describe '.wrap' do
+    it 'passes through existing Message instances' do
+      msg = described_class.build(role: :user, content: 'hello')
+      wrapped = described_class.wrap(msg)
+
+      expect(wrapped).to eq(msg)
+    end
+
+    it 'parses Hash input' do
+      wrapped = described_class.wrap({ role: :user, content: 'hello' })
+
+      expect(wrapped).to be_a(described_class)
+      expect(wrapped.content).to eq('hello')
+    end
+
+    it 'returns nil for unsupported input' do
+      expect(described_class.wrap('hello')).to be_nil
+    end
+  end
+
+  describe '#text' do
+    it 'returns content when it is a String' do
+      msg = described_class.build(role: :user, content: 'hello')
+
+      expect(msg.text).to eq('hello')
+    end
+
+    it 'extracts text from ContentBlock array' do
+      blocks = [
+        Legion::Extensions::Llm::Canonical::ContentBlock.text('hello'),
+        Legion::Extensions::Llm::Canonical::ContentBlock.text(' world')
+      ]
+      msg = described_class.build(role: :user, content: blocks)
+
+      expect(msg.text).to eq('hello world')
+    end
+
+    it 'skips non-text blocks' do
+      blocks = [
+        Legion::Extensions::Llm::Canonical::ContentBlock.text('hello'),
+        Legion::Extensions::Llm::Canonical::ContentBlock.thinking('reasoning')
+      ]
+      msg = described_class.build(role: :user, content: blocks)
+
+      expect(msg.text).to eq('hello')
+    end
+
+    it 'returns empty string for nil content' do
+      msg = described_class.build(role: :user, content: nil)
+
+      expect(msg.text).to eq('')
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes to compact hash' do
+      msg = described_class.build(role: :user, content: 'hello')
+      hash = msg.to_h
+
+      expect(hash).to include(id: msg.id, role: :user, content: 'hello')
+    end
+  end
+
+  describe '#to_provider_hash' do
+    it 'returns minimal provider-facing hash' do
+      msg = described_class.build(role: :user, content: 'hello')
+      hash = msg.to_provider_hash
+
+      expect(hash).to eq(role: 'user', content: 'hello')
+    end
+  end
+
+  describe 'ROLES' do
+    it 'includes all expected roles' do
+      expect(described_class::ROLES).to eq(%i[system user assistant tool])
+    end
+  end
+
+  describe 'round-trip' do
+    it 'preserves values through from_hash/to_h' do
+      original = { role: 'user', content: 'hello', conversation_id: 'conv-1' }
+      msg = described_class.from_hash(original)
+      serialized = msg.to_h
+
+      expect(serialized[:role]).to eq(:user)
+      expect(serialized[:content]).to eq('hello')
+      expect(serialized[:conversation_id]).to eq('conv-1')
+    end
+  end
+end