lex-llm 0.7.3 → 0.8.0

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

@@ -1,189 +1,109 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 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
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [] }
+  let(:type_source) do
+    { content: 'reasoning here', signature: 'sig-abc', metadata: { origin: 'provider' } }
+  end
 
-    it 'handles string keys' do
-      thinking = described_class.from_hash('content' => 'reasoning', 'signature' => 'sig-123')
+  it_behaves_like 'a canonical type'
 
+  describe 'T5/T4 — construction law' do
+    it 'builds from keyword args' do
+      thinking = described_class.build(content: 'reasoning', signature: 'sig')
       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
+      expect(thinking.signature).to eq('sig')
     end
 
-    it 'returns instance with only content' do
-      thinking = described_class.from_hash(content: 'just reasoning')
-
-      expect(thinking.content).to eq('just reasoning')
+    it 'normalizes empty strings to nil (absence, not data — 04 §8)' do
+      thinking = described_class.build(content: '', signature: '')
+      expect(thinking.content).to be_nil
       expect(thinking.signature).to be_nil
+      expect(thinking.empty?).to be(true)
     end
 
-    it 'returns instance with only signature' do
-      thinking = described_class.from_hash(signature: 'sig-only')
+    it 'raises on a wrong-class member' do
+      expect { described_class.build(content: 42) }
+        .to raise_error(ArgumentError, /content expected String, got Integer/)
+    end
 
-      expect(thinking.content).to be_nil
-      expect(thinking.signature).to eq('sig-only')
+    it 'survives build → to_h → JSON → from_hash (T4 signature)' do
+      thinking = described_class.build(content: 'x', signature: 'sig-1')
+      round_tripped = described_class.from_hash(Legion::JSON.load(Legion::JSON.dump(thinking.to_h)))
+      expect(round_tripped.content).to eq('x')
+      expect(round_tripped.signature).to eq('sig-1')
     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
+  describe Legion::Extensions::Llm::Canonical::Thinking::Config do
+    subject(:config_class) { described_class }
 
-      expect(hash).to eq(content: 'reasoning', signature: 'sig-1')
+    let(:type_class) { described_class }
+    let(:auto_generated_members) { [] }
+    let(:type_source) do
+      { effort: 'high', budget: 4096, metadata: { source: 'client' } }
     end
 
-    it 'omits nil values' do
-      thinking = described_class.new(content: 'reasoning', signature: nil)
-      hash = thinking.to_h
+    it_behaves_like 'a canonical type'
 
-      expect(hash).to eq(content: 'reasoning')
+    it 'converts from a plain class to a Data with one name (04 §8)' do
+      expect(config_class).to be_a(Class)
+      expect(config_class.new(effort: 'low', budget: nil, metadata: {})).to be_a(config_class)
     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
+    it 'normalizes symbol effort to String' do
+      config = config_class.build(effort: :low)
+      expect(config.effort).to eq('low')
     end
 
-    it 'returns false when content is present' do
-      thinking = described_class.new(content: 'reasoning', signature: nil)
-      expect(thinking.empty?).to be false
+    it 'raises on a wrong-class effort' do
+      expect { config_class.build(effort: 3) }
+        .to raise_error(ArgumentError, /effort expected String, got Integer/)
     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
+    describe 'H1/M4 — effort is a closed enum, validated in every constructor' do
+      it 'rejects an unrecognized effort in build, from_hash, and .new' do
+        expect { config_class.build(effort: 'banana') }
+          .to raise_error(ArgumentError, /Invalid effort: "banana"/)
+        expect { config_class.from_hash(effort: 'banana') }
+          .to raise_error(ArgumentError, /Invalid effort: "banana"/)
+        expect { config_class.new(effort: 'banana') }
+          .to raise_error(ArgumentError, /Invalid effort: "banana"/)
       end
 
-      it 'converts symbol effort to string' do
-        config = config_class.build(effort: :high)
-
-        expect(config.effort).to eq('high')
+      it 'accepts the enum case-insensitively (symbol or string)' do
+        expect(config_class.build(effort: :HIGH).effort).to eq('high')
+        expect(config_class.new(effort: 'Medium').effort).to eq('medium')
       end
 
-      it 'creates disabled config when no values' do
-        config = config_class.build
-
-        expect(config.enabled?).to be false
+      it 'resolved_budget derives from the validated effort (no silent medium fallback)' do
+        expect(config_class.new(effort: 'low').resolved_budget).to eq(1024)
+        expect(config_class.build(budget: 123).resolved_budget).to eq(123)
+        expect(config_class.build.resolved_budget).to be_nil
       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
+    it 'keeps the effort<->budget SSOT conversions' do
+      expect(config_class.build(effort: 'low').resolved_budget).to eq(1024)
+      expect(config_class.build(effort: 'medium').resolved_budget).to eq(8192)
+      expect(config_class.build(effort: 'high').resolved_budget).to eq(16_384)
+      expect(config_class.build(budget: 512).resolved_effort).to eq('low')
+      expect(config_class.build(budget: 8192).resolved_effort).to eq('medium')
+      expect(config_class.build(budget: 16_384).resolved_effort).to eq('high')
     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
+    it 'is enabled only when an axis is set' do
+      expect(config_class.build(effort: 'low').enabled?).to be(true)
+      expect(config_class.build(budget: 1).enabled?).to be(true)
+      expect(config_class.build.enabled?).to be(false)
     end
 
-    # SSOT / one-oracle for cross-provider thinking (NxN best-effort): a client
-    # dialect supplies only ONE axis (Anthropic = budget_tokens only, OpenAI =
-    # effort only). Every provider translator must still get a usable value for
-    # whichever axis IT needs, so thinking survives ANY client×provider pair
-    # instead of being silently dropped. The conversion lives HERE (the canonical
-    # config), not scattered/one-directional in each translator. Derived accessors
-    # do NOT mutate stored state or #to_h — they only fill the gap on read.
-    describe 'derived cross-axis accessors' do
-      it 'derives budget from effort when only effort was set' do
-        expect(config_class.build(effort: 'low').resolved_budget).to eq(1024)
-        expect(config_class.build(effort: 'medium').resolved_budget).to eq(8192)
-        expect(config_class.build(effort: 'high').resolved_budget).to eq(16_384)
-      end
-
-      it 'derives effort from budget by band (< medium=low, < high=medium, else high)' do
-        expect(config_class.build(budget: 500).resolved_effort).to eq('low') # < 8192
-        expect(config_class.build(budget: 10_000).resolved_effort).to eq('medium') # 8192..16383
-        expect(config_class.build(budget: 20_000).resolved_effort).to eq('high') # >= 16384
-      end
-
-      it 'prefers the explicitly-set value over derivation' do
-        c = config_class.build(effort: 'high', budget: 2048)
-        expect(c.resolved_budget).to eq(2048)
-        expect(c.resolved_effort).to eq('high')
-      end
-
-      it 'returns nil derivations when neither axis is set' do
-        c = config_class.build
-        expect(c.resolved_budget).to be_nil
-        expect(c.resolved_effort).to be_nil
-      end
-
-      it 'does not fabricate the missing axis in to_h (stored state stays faithful)' do
-        expect(config_class.build(effort: 'high').to_h).to eq(effort: 'high')
-        expect(config_class.build(budget: 2048).to_h).to eq(budget: 2048)
-      end
+    it 'to_h is faithful to what was set (no fabricated axis)' do
+      expect(config_class.build(effort: 'low').to_h).to eq(effort: 'low', metadata: {})
     end
   end
 end

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

@@ -1,191 +1,88 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 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
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [:id] }
+  let(:type_source) do
+    {
+      id: 'call_1',
+      name: 'get_weather',
+      arguments: { location: 'San Francisco' },
+      source: 'client',
+      status: 'pending',
+      category: 'weather',
+      metadata: { origin: 'model' }
+    }
   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
-      )
+  it_behaves_like 'a canonical type'
 
-      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)
+  describe 'H1 — .new is as strict as the factories' do
+    it 'rejects a poison source enum' do
+      expect { described_class.new(name: 'x', source: :bogus) }
+        .to raise_error(ArgumentError, /Invalid source: :bogus/)
     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)
+    it 'rejects JSON-string arguments (Hash only, O03a)' do
+      expect { described_class.new(name: 'x', arguments: '{"a":1}') }
+        .to raise_error(ArgumentError, /arguments expected Hash, got String/)
     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
+  describe 'T5 — enum law (declared enums enforced in both factories)' do
+    it 'validates source against SOURCE_VALUES' do
+      expect { described_class.build(name: 'x', source: 'client') }.not_to raise_error
+      expect(described_class.build(name: 'x', source: 'client').source).to eq(:client)
+      expect { described_class.build(name: 'x', source: :bogus) }
+        .to raise_error(ArgumentError, /Invalid source: :bogus/)
+      expect { described_class.from_hash(name: 'x', source: 'nope') }
+        .to raise_error(ArgumentError, /Invalid source: :nope/)
     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
+    it 'validates status against STATUS_VALUES' do
+      expect(described_class.build(name: 'x', status: 'running').status).to eq(:running)
+      expect { described_class.build(name: 'x', status: :finished) }
+        .to raise_error(ArgumentError, /Invalid status: :finished/)
+      expect { described_class.from_hash(name: 'x', status: 'done') }
+        .to raise_error(ArgumentError, /Invalid status: :done/)
     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' })
+  describe 'O03a — arguments Hash only' do
+    it 'does not parse JSON-string arguments (the parse + rescue are deleted)' do
+      expect { described_class.build(name: 'x', arguments: '{"a":1}') }
+        .to raise_error(ArgumentError, /arguments expected Hash, got String/)
+      expect { described_class.from_hash(name: 'x', arguments: '{\"a\":1}') }
+        .to raise_error(ArgumentError, /arguments expected Hash, got String/)
     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
-      )
+    it 'defaults nil arguments to {} (documented no-arguments default)' do
+      expect(described_class.build(name: 'x').arguments).to eq({})
+      expect(described_class.from_hash(name: 'x').arguments).to eq({})
     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 'with_result (canonical mutation-free update)' do
+    it 'attaches the result and normalizes error' do
+      tc = described_class.build(name: 'x', id: 'c1', status: 'running')
+      done = tc.with_result(result: 'ok', status: :success, duration_ms: 12)
+      expect(done.result).to eq('ok')
+      expect(done.status).to eq(:success)
+      expect(done.error).to be_nil
+      expect(done.success?).to be(true)
 
-  describe 'STATUS_VALUES' do
-    it 'includes all expected status types' do
-      expect(described_class::STATUS_VALUES).to eq(%i[pending running success error])
+      failed = tc.with_result(result: 'boom', status: :error)
+      expect(failed.error).to eq('boom')
+      expect(failed.error?).to be(true)
     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)
+    it 'validates the result status enum' do
+      tc = described_class.build(name: 'x', id: 'c1', status: 'running')
+      expect { tc.with_result(result: 'r', status: :bogus) }
+        .to raise_error(ArgumentError, /Invalid status: :bogus/)
     end
   end
 end