lex-llm 0.4.18 → 0.5.0

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::Thinking do
+  describe '.from_hash' do
+    it 'returns a Thinking instance with content and signature' do
+      thinking = described_class.from_hash(content: 'reasoning here', signature: 'sig-abc')
+
+      expect(thinking).to be_a(described_class)
+      expect(thinking.content).to eq('reasoning here')
+      expect(thinking.signature).to eq('sig-abc')
+    end
+
+    it 'handles string keys' do
+      thinking = described_class.from_hash('content' => 'reasoning', 'signature' => 'sig-123')
+
+      expect(thinking.content).to eq('reasoning')
+      expect(thinking.signature).to eq('sig-123')
+    end
+
+    it 'returns nil for nil source' do
+      expect(described_class.from_hash(nil)).to be_nil
+    end
+
+    it 'returns nil for empty content and signature' do
+      result = described_class.from_hash(content: '', signature: '')
+
+      expect(result).to be_nil
+    end
+
+    it 'returns nil when both fields are nil' do
+      result = described_class.from_hash(content: nil, signature: nil)
+
+      expect(result).to be_nil
+    end
+
+    it 'returns instance with only content' do
+      thinking = described_class.from_hash(content: 'just reasoning')
+
+      expect(thinking.content).to eq('just reasoning')
+      expect(thinking.signature).to be_nil
+    end
+
+    it 'returns instance with only signature' do
+      thinking = described_class.from_hash(signature: 'sig-only')
+
+      expect(thinking.content).to be_nil
+      expect(thinking.signature).to eq('sig-only')
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes to compact hash' do
+      thinking = described_class.new(content: 'reasoning', signature: 'sig-1')
+      hash = thinking.to_h
+
+      expect(hash).to eq(content: 'reasoning', signature: 'sig-1')
+    end
+
+    it 'omits nil values' do
+      thinking = described_class.new(content: 'reasoning', signature: nil)
+      hash = thinking.to_h
+
+      expect(hash).to eq(content: 'reasoning')
+    end
+  end
+
+  describe '#empty?' do
+    it 'returns true when both fields are nil' do
+      thinking = described_class.new(content: nil, signature: nil)
+      expect(thinking.empty?).to be true
+    end
+
+    it 'returns false when content is present' do
+      thinking = described_class.new(content: 'reasoning', signature: nil)
+      expect(thinking.empty?).to be false
+    end
+  end
+
+  describe 'round-trip' do
+    it 'preserves content and signature through from_hash/to_h' do
+      original = { content: 'deep reasoning', signature: 'sig-xyz' }
+      thinking = described_class.from_hash(original)
+      serialized = thinking.to_h
+
+      expect(serialized).to eq(original)
+    end
+  end
+
+  describe '::Config' do
+    let(:config_class) { Legion::Extensions::Llm::Canonical::Thinking::Config }
+
+    describe '.build' do
+      it 'creates a config with effort and budget' do
+        config = config_class.build(effort: 'high', budget: 10_000)
+
+        expect(config.effort).to eq('high')
+        expect(config.budget).to eq(10_000)
+        expect(config.enabled?).to be true
+      end
+
+      it 'converts symbol effort to string' do
+        config = config_class.build(effort: :high)
+
+        expect(config.effort).to eq('high')
+      end
+
+      it 'creates disabled config when no values' do
+        config = config_class.build
+
+        expect(config.enabled?).to be false
+      end
+    end
+
+    describe '.from_hash' do
+      it 'parses config from hash' do
+        config = config_class.from_hash(effort: 'medium', budget: 5000)
+
+        expect(config.effort).to eq('medium')
+        expect(config.budget).to eq(5000)
+      end
+
+      it 'handles string keys' do
+        config = config_class.from_hash('effort' => 'low')
+
+        expect(config.effort).to eq('low')
+      end
+
+      it 'returns nil for nil source' do
+        expect(config_class.from_hash(nil)).to be_nil
+      end
+
+      it 'returns nil for empty hash' do
+        expect(config_class.from_hash({})).to be_nil
+      end
+    end
+
+    describe '#to_h' do
+      it 'serializes to compact hash' do
+        config = config_class.build(effort: 'high', budget: 10_000)
+        expect(config.to_h).to eq(effort: 'high', budget: 10_000)
+      end
+
+      it 'omits nil values' do
+        config = config_class.build(effort: 'low')
+        expect(config.to_h).to eq(effort: 'low')
+      end
+    end
+  end
+end

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

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::ToolCall do
+  describe '.build' do
+    it 'creates a tool call with required fields' do
+      tc = described_class.build(name: 'search', arguments: { query: 'test' })
+
+      expect(tc.name).to eq('search')
+      expect(tc.arguments).to eq({ query: 'test' })
+      expect(tc.id).to start_with('call_')
+      expect(tc.arguments).to be_a(Hash)
+    end
+
+    it 'generates a random id' do
+      tc1 = described_class.build(name: 'search')
+      tc2 = described_class.build(name: 'search')
+
+      expect(tc1.id).not_to eq(tc2.id)
+    end
+
+    it 'accepts all fields' do
+      tc = described_class.build(
+        id: 'call-1',
+        exchange_id: 'ex-1',
+        name: 'search',
+        arguments: { query: 'test' },
+        source: :registry,
+        status: :pending,
+        data_handling_classification: :public,
+        policy_decision: :allowed
+      )
+
+      expect(tc.id).to eq('call-1')
+      expect(tc.exchange_id).to eq('ex-1')
+      expect(tc.source).to eq(:registry)
+      expect(tc.status).to eq(:pending)
+      expect(tc.data_handling_classification).to eq(:public)
+      expect(tc.policy_decision).to eq(:allowed)
+    end
+
+    it 'defaults arguments to empty hash' do
+      tc = described_class.build(name: 'search')
+
+      expect(tc.arguments).to eq({})
+    end
+  end
+
+  describe '.from_hash' do
+    it 'parses from hash with symbol keys' do
+      tc = described_class.from_hash(
+        id: 'call-1',
+        name: 'search',
+        arguments: { query: 'test' },
+        source: :registry
+      )
+
+      expect(tc.id).to eq('call-1')
+      expect(tc.name).to eq('search')
+      expect(tc.arguments).to eq({ query: 'test' })
+      expect(tc.source).to eq(:registry)
+    end
+
+    it 'normalizes string source to symbol' do
+      tc = described_class.from_hash(name: 'search', source: 'registry')
+
+      expect(tc.source).to eq(:registry)
+    end
+
+    it 'normalizes string status to symbol' do
+      tc = described_class.from_hash(name: 'search', status: 'success')
+
+      expect(tc.status).to eq(:success)
+    end
+
+    it 'parses JSON string arguments to symbol keys per Legion::JSON convention' do
+      tc = described_class.from_hash(
+        name: 'search',
+        arguments: '{"query":"test","limit":10}'
+      )
+
+      expect(tc.arguments).to eq({ query: 'test', limit: 10 })
+    end
+
+    it 'handles string keys' do
+      tc = described_class.from_hash('name' => 'search', 'arguments' => '{}')
+
+      expect(tc.name).to eq('search')
+      expect(tc.arguments).to eq({})
+    end
+
+    it 'returns nil for nil source' do
+      expect(described_class.from_hash(nil)).to be_nil
+    end
+  end
+
+  describe '#with_result' do
+    it 'returns a new tool call with result' do
+      tc = described_class.build(name: 'search', source: :registry)
+      result_tc = tc.with_result(result: { hits: 5 }, status: :success, duration_ms: 100)
+
+      expect(result_tc.result).to eq({ hits: 5 })
+      expect(result_tc.status).to eq(:success)
+      expect(result_tc.duration_ms).to eq(100)
+      expect(result_tc.finished_at).to be_a(Time)
+    end
+
+    it 'sets error on error status' do
+      tc = described_class.build(name: 'search')
+      result_tc = tc.with_result(result: 'not found', status: :error)
+
+      expect(result_tc.error).to eq('not found')
+      expect(result_tc.status).to eq(:error)
+    end
+  end
+
+  describe 'predicates' do
+    it 'identifies successful calls' do
+      tc = described_class.build(name: 'search', status: :success)
+      expect(tc.success?).to be true
+      expect(tc.error?).to be false
+    end
+
+    it 'identifies error calls' do
+      tc = described_class.build(name: 'search', status: :error)
+      expect(tc.error?).to be true
+      expect(tc.success?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes to compact hash' do
+      tc = described_class.build(name: 'search', arguments: { query: 'test' })
+      hash = tc.to_h
+
+      expect(hash).to include(id: tc.id, name: 'search', arguments: { query: 'test' })
+    end
+  end
+
+  describe '#to_audit_hash' do
+    it 'includes compliance fields' do
+      tc = described_class.build(
+        name: 'search',
+        source: :registry,
+        data_handling_classification: :public,
+        policy_decision: :allowed
+      )
+      hash = tc.to_audit_hash
+
+      expect(hash).to include(
+        name: 'search',
+        source: :registry,
+        data_handling_classification: :public,
+        policy_decision: :allowed
+      )
+    end
+  end
+
+  describe 'SOURCE_VALUES' do
+    it 'includes all expected source types' do
+      expect(described_class::SOURCE_VALUES).to eq(%i[client registry special extension mcp])
+    end
+  end
+
+  describe 'STATUS_VALUES' do
+    it 'includes all expected status types' do
+      expect(described_class::STATUS_VALUES).to eq(%i[pending running success error])
+    end
+  end
+
+  describe 'round-trip' do
+    it 'preserves values through from_hash/to_h' do
+      original = {
+        id: 'call-1',
+        name: 'search',
+        arguments: { query: 'test' },
+        source: 'registry',
+        status: 'pending'
+      }
+      tc = described_class.from_hash(original)
+      serialized = tc.to_h
+
+      expect(serialized[:id]).to eq('call-1')
+      expect(serialized[:name]).to eq('search')
+      expect(serialized[:arguments]).to eq({ query: 'test' })
+      expect(serialized[:source]).to eq(:registry)
+      expect(serialized[:status]).to eq(:pending)
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::ToolDefinition do
+  describe '.build' do
+    it 'creates a tool definition with name and description' do
+      tool = described_class.build(name: 'search', description: 'Search the web')
+
+      expect(tool.name).to eq('search')
+      expect(tool.description).to eq('Search the web')
+      expect(tool.parameters).to eq({})
+      expect(tool.source).to eq({ type: :builtin })
+    end
+
+    it 'accepts parameters and source' do
+      tool = described_class.build(
+        name: 'search',
+        description: 'Search',
+        parameters: { type: 'object', properties: { query: { type: 'string' } } },
+        source: { type: :registry }
+      )
+
+      expect(tool.parameters).to eq({ type: 'object', properties: { query: { type: 'string' } } })
+      expect(tool.source).to eq({ type: :registry })
+    end
+
+    it 'sanitizes tool names' do
+      tool = described_class.build(name: 'My.Tool.Name!', description: 'test')
+
+      expect(tool.name).to eq('My_Tool_Name')
+    end
+
+    it 'truncates long tool names' do
+      long_name = 'a' * 100
+      tool = described_class.build(name: long_name)
+
+      expect(tool.name.length).to eq(64)
+    end
+
+    it 'provides fallback name for empty input' do
+      tool = described_class.build(name: '')
+
+      expect(tool.name).to eq('tool')
+    end
+
+    it 'converts nil description to empty string' do
+      tool = described_class.build(name: 'search')
+
+      expect(tool.description).to eq('')
+    end
+  end
+
+  describe '.from_hash' do
+    it 'parses from hash with symbol keys' do
+      tool = described_class.from_hash({ name: 'search', description: 'Search', parameters: { type: 'object' } })
+
+      expect(tool.name).to eq('search')
+      expect(tool.description).to eq('Search')
+      expect(tool.parameters).to eq({ type: 'object' })
+    end
+
+    it 'parses from hash with string keys' do
+      tool = described_class.from_hash({ 'name' => 'search', 'description' => 'Search' })
+
+      expect(tool.name).to eq('search')
+      expect(tool.description).to eq('Search')
+    end
+
+    it 'accepts input_schema as alias for parameters' do
+      tool = described_class.from_hash({ name: 'search', input_schema: { type: 'object' } })
+
+      expect(tool.parameters).to eq({ type: 'object' })
+    end
+
+    it 'accepts source parameter' do
+      tool = described_class.from_hash({ name: 'search', source: { type: :extension } })
+
+      expect(tool.source).to eq({ type: :extension })
+    end
+
+    it 'overrides source with keyword arg' do
+      tool = described_class.from_hash(
+        { name: 'search', source: { type: :builtin } },
+        source: { type: :override }
+      )
+
+      expect(tool.source).to eq({ type: :override })
+    end
+  end
+
+  describe '.from_registry_entry' do
+    it 'creates from registry entry with tool_class' do
+      entry = {
+        name: 'ruby',
+        description: 'Run Ruby code',
+        input_schema: { type: 'object' },
+        tool_class: 'RubyTool',
+        extension: 'legion-code',
+        runner: 'RubyRunner',
+        function: :execute
+      }
+      tool = described_class.from_registry_entry(entry)
+
+      expect(tool.name).to eq('ruby')
+      expect(tool.description).to eq('Run Ruby code')
+      expect(tool.parameters).to eq({ type: 'object' })
+      expect(tool.source[:type]).to eq(:registry)
+      expect(tool.source[:extension]).to eq('legion-code')
+    end
+
+    it 'creates from registry entry without tool_class' do
+      entry = {
+        name: 'custom',
+        description: 'Custom tool',
+        parameters: {},
+        extension: 'custom-ext'
+      }
+      tool = described_class.from_registry_entry(entry)
+
+      expect(tool.source[:type]).to eq(:extension)
+    end
+  end
+
+  describe '.sanitize_tool_name' do
+    it 'replaces dots with underscores' do
+      expect(described_class.sanitize_tool_name('my.tool')).to eq('my_tool')
+    end
+
+    it 'removes special characters' do
+      expect(described_class.sanitize_tool_name('my-tool!@#')).to eq('my-tool')
+    end
+
+    it 'preserves alphanumeric, underscores, and hyphens' do
+      expect(described_class.sanitize_tool_name('my-tool_123')).to eq('my-tool_123')
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes to hash with name, description, parameters' do
+      tool = described_class.build(
+        name: 'search',
+        description: 'Search the web',
+        parameters: { type: 'object' }
+      )
+      hash = tool.to_h
+
+      expect(hash).to eq(
+        name: 'search',
+        description: 'Search the web',
+        parameters: { type: 'object' }
+      )
+    end
+
+    it 'omits nil values' do
+      tool = described_class.new('search', '', nil, nil)
+      hash = tool.to_h
+
+      expect(hash).to eq(name: 'search')
+    end
+  end
+
+  describe 'round-trip' do
+    it 'preserves values through from_hash/to_h' do
+      original = { name: 'search', description: 'Search', parameters: { type: 'object' } }
+      tool = described_class.from_hash(original)
+      serialized = tool.to_h
+
+      expect(serialized[:name]).to eq('search')
+      expect(serialized[:description]).to eq('Search')
+      expect(serialized[:parameters]).to eq({ type: 'object' })
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::Usage do
+  describe '.from_hash' do
+    it 'returns a Usage instance with canonical fields' do
+      usage = described_class.from_hash(input_tokens: 100, output_tokens: 50)
+
+      expect(usage).to be_a(described_class)
+      expect(usage.input_tokens).to eq(100)
+      expect(usage.output_tokens).to eq(50)
+      expect(usage.cache_read_tokens).to be_nil
+      expect(usage.cache_write_tokens).to be_nil
+      expect(usage.thinking_tokens).to be_nil
+      expect(usage.units).to eq({})
+    end
+
+    it 'normalizes legacy key names' do
+      usage = described_class.from_hash(
+        input: 200, output: 100, cached: 50, cache_creation: 25, thinking: 10
+      )
+
+      expect(usage.input_tokens).to eq(200)
+      expect(usage.output_tokens).to eq(100)
+      expect(usage.cache_read_tokens).to eq(50)
+      expect(usage.cache_write_tokens).to eq(25)
+      expect(usage.thinking_tokens).to eq(10)
+    end
+
+    it 'normalizes prompt_tokens/completion_tokens aliases' do
+      usage = described_class.from_hash(prompt_tokens: 300, completion_tokens: 150)
+
+      expect(usage.input_tokens).to eq(300)
+      expect(usage.output_tokens).to eq(150)
+    end
+
+    it 'normalizes reasoning alias for thinking_tokens' do
+      usage = described_class.from_hash(reasoning: 75)
+
+      expect(usage.thinking_tokens).to eq(75)
+    end
+
+    it 'handles string keys' do
+      usage = described_class.from_hash('input_tokens' => '100', 'output_tokens' => '50')
+
+      expect(usage.input_tokens).to eq('100')
+      expect(usage.output_tokens).to eq('50')
+    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 'preserves units extension point' do
+      units = { images: 3, characters: 1500 }
+      usage = described_class.from_hash(input_tokens: 10, units: units)
+
+      expect(usage.units).to eq(units)
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes to compact hash' do
+      usage = described_class.new(
+        input_tokens: 100, output_tokens: 50,
+        cache_read_tokens: nil, cache_write_tokens: nil,
+        thinking_tokens: nil, units: {}
+      )
+      hash = usage.to_h
+
+      expect(hash).to eq(input_tokens: 100, output_tokens: 50, units: {})
+    end
+
+    it 'includes all non-nil fields' do
+      usage = described_class.new(
+        input_tokens: 200, output_tokens: 100,
+        cache_read_tokens: 50, cache_write_tokens: 25,
+        thinking_tokens: 10, units: { images: 2 }
+      )
+      hash = usage.to_h
+
+      expect(hash).to include(
+        input_tokens: 200, output_tokens: 100,
+        cache_read_tokens: 50, cache_write_tokens: 25,
+        thinking_tokens: 10, units: { images: 2 }
+      )
+    end
+  end
+
+  describe '#total_tokens' do
+    it 'sums all token categories' do
+      usage = described_class.new(
+        input_tokens: 100, output_tokens: 50,
+        cache_read_tokens: 20, cache_write_tokens: 10,
+        thinking_tokens: 5, units: {}
+      )
+
+      expect(usage.total_tokens).to eq(185)
+    end
+
+    it 'ignores nil values' do
+      usage = described_class.new(
+        input_tokens: 100, output_tokens: 50,
+        cache_read_tokens: nil, cache_write_tokens: nil,
+        thinking_tokens: nil, units: {}
+      )
+
+      expect(usage.total_tokens).to eq(150)
+    end
+  end
+
+  describe 'round-trip' do
+    it 'preserves values through from_hash/to_h' do
+      original = { input_tokens: 100, output_tokens: 50, cache_read_tokens: 10 }
+      usage = described_class.from_hash(original)
+      serialized = usage.to_h
+
+      expect(serialized[:input_tokens]).to eq(100)
+      expect(serialized[:output_tokens]).to eq(50)
+      expect(serialized[:cache_read_tokens]).to eq(10)
+    end
+
+    it 'preserves legacy key normalization through round-trip' do
+      original = { input: 200, output: 100, cached: 50 }
+      usage = described_class.from_hash(original)
+      serialized = usage.to_h
+
+      expect(serialized[:input_tokens]).to eq(200)
+      expect(serialized[:output_tokens]).to eq(100)
+      expect(serialized[:cache_read_tokens]).to eq(50)
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Configuration do
+  describe 'DSL defaults' do
+    subject(:config) { described_class.new }
+
+    it 'applies core default values' do
+      expect(config.request_timeout).to eq(300)
+      expect(config.max_retries).to eq(3)
+      expect(config.retry_interval).to eq(0.1)
+      expect(config.retry_backoff_factor).to eq(2)
+      expect(config.retry_interval_randomness).to eq(0.5)
+    end
+
+    it 'exposes a discoverable options API' do
+      expect(described_class.options).to include(
+        :request_timeout,
+        :default_model,
+        :default_embedding_model,
+        :model_registry_file
+      )
+    end
+
+    it 'includes prompt caching configuration options' do
+      expect(described_class.options).to include(:llm_cache_enabled, :cache_control_prefix_tokens)
+    end
+
+    it 'defaults llm_cache_enabled to true' do
+      expect(config.llm_cache_enabled).to be true
+    end
+
+    it 'defaults cache_control_prefix_tokens to 4' do
+      expect(config.cache_control_prefix_tokens).to eq(4)
+    end
+  end
+end