lex-llm 0.4.18 → 0.5.1

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,221 @@
+# 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(type: 'object', properties: {})
+      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: { type: 'object', properties: { name: { type: 'string' } } },
+        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 '.normalize_parameters' do
+    it 'injects type: object when a schema has properties but no type' do
+      schema = { properties: { task: { type: 'string' } }, required: ['task'] }
+      result = described_class.normalize_parameters(schema)
+      expect(result[:type]).to eq('object')
+      expect(result[:properties]).to eq(task: { type: 'string' })
+      expect(result[:required]).to eq(['task'])
+    end
+
+    it 'passes schemas with an explicit type through unchanged' do
+      schema = { type: 'object', properties: { a: { type: 'string' } } }
+      expect(described_class.normalize_parameters(schema)).to eq(schema)
+    end
+
+    it 'wraps a bare property map under type:object/properties' do
+      expect(described_class.normalize_parameters(location: { type: 'string' }))
+        .to eq(type: 'object', properties: { location: { type: 'string' } })
+    end
+
+    it 'returns an empty object schema for nil/empty' do
+      expect(described_class.normalize_parameters(nil)).to eq(type: 'object', properties: {})
+      expect(described_class.normalize_parameters({})).to eq(type: 'object', properties: {})
+    end
+
+    it 'symbolizes top-level string keys' do
+      result = described_class.normalize_parameters('properties' => { 'a' => { 'type' => 'string' } })
+      expect(result[:type]).to eq('object')
+      expect(result).to have_key(:properties)
+    end
+
+    it 'leaves composite schemas (oneOf etc.) without forcing type' do
+      schema = { oneOf: [{ type: 'string' }, { type: 'integer' }] }
+      expect(described_class.normalize_parameters(schema)).to eq(schema)
+    end
+
+    it 'normalizes parameters at construction via .build' do
+      td = described_class.build(name: 'multi_agent_v1',
+                                 parameters: { properties: { task: { type: 'string' } } })
+      expect(td.parameters[:type]).to eq('object')
+    end
+
+    it 'normalizes nil parameters to empty object schema via .build' do
+      td = described_class.build(name: 'bare_tool')
+      expect(td.parameters).to eq(type: 'object', properties: {})
+    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/tool_schema_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::ToolSchema do
+  let(:full_schema) { { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] } }
+  let(:canonical_tool) do
+    Legion::Extensions::Llm::Canonical::ToolDefinition.build(
+      name: 'get_weather', description: 'Weather lookup', parameters: full_schema
+    )
+  end
+
+  describe '.extract' do
+    it 'extracts from a Canonical::ToolDefinition' do
+      result = described_class.extract(canonical_tool)
+      expect(result[:type]).to eq('object')
+      expect(result[:properties]).to eq(city: { type: 'string' })
+    end
+
+    it 'extracts from a Hash with :parameters' do
+      result = described_class.extract({ parameters: full_schema })
+      expect(result[:type]).to eq('object')
+      expect(result[:properties]).to eq(city: { type: 'string' })
+    end
+
+    it 'extracts from a Hash with :input_schema' do
+      result = described_class.extract({ input_schema: full_schema })
+      expect(result[:type]).to eq('object')
+      expect(result[:properties]).to eq(city: { type: 'string' })
+    end
+
+    it 'extracts from a Hash with :params_schema' do
+      result = described_class.extract({ params_schema: full_schema })
+      expect(result[:type]).to eq('object')
+      expect(result[:properties]).to eq(city: { type: 'string' })
+    end
+
+    it 'extracts from an object responding to params_schema' do
+      tool = Struct.new(:params_schema).new(full_schema)
+      result = described_class.extract(tool)
+      expect(result[:type]).to eq('object')
+      expect(result[:properties]).to eq(city: { type: 'string' })
+    end
+
+    it 'returns empty object schema for nil' do
+      expect(described_class.extract(nil)).to eq(type: 'object', properties: {})
+    end
+
+    it 'returns empty object schema for empty hash' do
+      expect(described_class.extract({})).to eq(type: 'object', properties: {})
+    end
+  end
+
+  describe '.tool_name' do
+    it 'gets name from Canonical::ToolDefinition' do
+      expect(described_class.tool_name(canonical_tool)).to eq('get_weather')
+    end
+
+    it 'gets name from Hash' do
+      expect(described_class.tool_name({ name: 'foo' })).to eq('foo')
+    end
+  end
+
+  describe '.tool_description' do
+    it 'gets description from Canonical::ToolDefinition' do
+      expect(described_class.tool_description(canonical_tool)).to eq('Weather lookup')
+    end
+
+    it 'gets description from Hash' do
+      expect(described_class.tool_description({ description: 'bar' })).to eq('bar')
+    end
+  end
+
+  describe 'ToolDefinition compatibility readers' do
+    it 'params_schema returns normalized parameters' do
+      expect(canonical_tool.params_schema).to eq(full_schema)
+    end
+
+    it 'input_schema aliases params_schema' do
+      expect(canonical_tool.input_schema).to eq(canonical_tool.params_schema)
+    end
+  end
+end