lex-llm 0.7.3 → 0.8.0

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

@@ -1,221 +1,85 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 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
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [] }
+  let(:type_source) do
+    {
+      name: 'get_weather',
+      description: 'Get the weather',
+      parameters: { type: 'object', properties: { location: { type: 'string' } } },
+      source: { type: :registry, tool_class: 'WeatherTool' },
+      metadata: { origin: 'client' }
+    }
   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 }
-      )
+  it_behaves_like 'a canonical type'
 
-      expect(tool.source).to eq({ type: :override })
+  describe 'O03a — no input_schema alias' do
+    it 'does not translate input_schema (it folds into metadata)' do
+      td = described_class.from_hash(name: 'x', input_schema: { type: 'object', properties: {} })
+      expect(td.parameters).to eq(type: 'object', properties: {})
+      expect(td.metadata).to eq(input_schema: { type: 'object', properties: {} })
     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)
+  describe 'L3 — no coercion of non-Hash input' do
+    it 'raises on non-Hash from_hash input (the {} fabrication is deleted)' do
+      expect { described_class.from_hash(nil) }
+        .to raise_error(ArgumentError, /expected Hash, got NilClass/)
+      expect { described_class.from_hash('raw') }
+        .to raise_error(ArgumentError, /expected Hash, got String/)
     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')
+  describe 'schema normalization (frozen inference rules)' do
+    it 'defaults missing/empty parameters to an empty object schema' do
+      expect(described_class.build(name: 'x').parameters).to eq(type: 'object', properties: {})
     end
 
-    it 'removes special characters' do
-      expect(described_class.sanitize_tool_name('my-tool!@#')).to eq('my-tool')
+    it 'wraps bare property maps in an object schema' do
+      td = described_class.build(name: 'x', parameters: { a: { type: 'string' } })
+      expect(td.parameters).to eq(type: 'object', properties: { a: { type: 'string' } })
     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')
+    it 'keeps explicit type and composite schemas as-is' do
+      expect(described_class.build(name: 'x', parameters: { type: 'string' }).parameters)
+        .to eq(type: 'string')
+      expect(described_class.build(name: 'x', parameters: { oneOf: [] }).parameters)
+        .to eq(oneOf: [])
     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'])
+  describe 'M5 — the name is authoritative (no rewrite, no fabrication)' do
+    it 'preserves the client/registry name verbatim (dialect rules live at the provider edge)' do
+      expect(described_class.build(name: 'get.weather').name).to eq('get.weather')
+      expect(described_class.build(name: 'a' * 80).name).to eq('a' * 80)
+      expect(described_class).not_to respond_to(:sanitize_tool_name)
     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)
+    it 'raises on a missing or empty name (the "tool" fabrication is deleted)' do
+      expect { described_class.build(name: nil) }
+        .to raise_error(ArgumentError, /name must be a non-empty String/)
+      expect { described_class.build(name: '') }
+        .to raise_error(ArgumentError, /name must be a non-empty String/)
+      expect { described_class.from_hash({}) }
+        .to raise_error(ArgumentError, /name must be a non-empty String/)
     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: {})
+    it 'does not fabricate a source (explicit or absent, never laundered to builtin)' do
+      expect(described_class.build(name: 'x').source).to be_nil
+      expect(described_class.build(name: 'x', source: { type: :client }).source).to eq(type: :client)
+      expect { described_class.build(name: 'x', source: 'client') }
+        .to raise_error(ArgumentError, /source expected Hash/)
     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
+  it 'builds from keyword args with defaults (empty description, absent source)' do
+    td = described_class.build(name: 'x')
+    expect(td.description).to eq('')
+    expect(td.source).to be_nil
   end
 end

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

@@ -3,81 +3,40 @@
 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
+  let(:tool_definition) do
     Legion::Extensions::Llm::Canonical::ToolDefinition.build(
-      name: 'get_weather', description: 'Weather lookup', parameters: full_schema
+      name: 'get_weather',
+      description: 'Get the weather',
+      parameters: { type: 'object', properties: { location: { type: 'string' } } }
     )
   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
+  it 'extracts the normalized schema from a ToolDefinition' do
+    expect(described_class.extract(tool_definition)).to eq(
+      type: 'object', properties: { location: { type: 'string' } }
+    )
   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
+  it 'returns the tool name and description' do
+    expect(described_class.tool_name(tool_definition)).to eq('get_weather')
+    expect(described_class.tool_description(tool_definition)).to eq('Get the weather')
   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)
+  describe '04 §6 — ToolDefinition ONLY (dual-shape accessors deleted)' do
+    it 'raises on a raw Hash' do
+      expect { described_class.extract({ name: 'x' }) }
+        .to raise_error(ArgumentError, /expected Canonical::ToolDefinition, got Hash/)
+      expect { described_class.tool_name({ name: 'x' }) }
+        .to raise_error(ArgumentError, /expected Canonical::ToolDefinition, got Hash/)
+      expect { described_class.tool_description({ name: 'x' }) }
+        .to raise_error(ArgumentError, /expected Canonical::ToolDefinition, got Hash/)
+    end
+
+    it 'raises on nil and other wrong classes' do
+      expect { described_class.extract(nil) }
+        .to raise_error(ArgumentError, /expected Canonical::ToolDefinition, got NilClass/)
+      expect { described_class.tool_name('str') }
+        .to raise_error(ArgumentError, /expected Canonical::ToolDefinition, got String/)
     end
   end
 end

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

@@ -1,178 +1,69 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require_relative '../conformance/conformance'
 
 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
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [] }
+  let(:type_source) do
+    {
+      input_tokens: 100,
+      output_tokens: 50,
+      cache_read_tokens: 10,
+      cache_write_tokens: 5,
+      thinking_tokens: 25,
+      units: { images: 1 },
+      metadata: { source: 'provider' }
+    }
   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
+  it_behaves_like 'a canonical type'
 
-      expect(hash).to include(
-        input_tokens: 200, output_tokens: 100,
-        cache_read_tokens: 50, cache_write_tokens: 25,
-        thinking_tokens: 10, units: { images: 2 }
-      )
+  describe 'H1/M3 — Integer token validation in every constructor' do
+    it 'rejects a string token count in build, from_hash, and .new' do
+      expect { described_class.build(input_tokens: 'many') }
+        .to raise_error(ArgumentError, /input_tokens expected Integer, got String/)
+      expect { described_class.from_hash(output_tokens: 3.5) }
+        .to raise_error(ArgumentError, /output_tokens expected Integer, got Float/)
+      expect { described_class.new(thinking_tokens: 'x', units: 42) }
+        .to raise_error(ArgumentError)
     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)
+  describe 'O03a — canonical keys only' do
+    it 'does not translate provider spellings (they fold into metadata)' do
+      usage = described_class.from_hash(prompt_tokens: 7, completion_tokens: 3)
+      expect(usage.input_tokens).to be_nil
+      expect(usage.output_tokens).to be_nil
+      expect(usage.metadata).to eq(prompt_tokens: 7, completion_tokens: 3)
     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)
+    it 'does not dig nested *_tokens_details (edge concern)' do
+      usage = described_class.from_hash(prompt_tokens_details: { cached_tokens: 9 })
+      expect(usage.cache_read_tokens).to be_nil
+      expect(usage.metadata).to eq(prompt_tokens_details: { cached_tokens: 9 })
     end
   end
 
-  describe 'OpenAI nested details extraction' do
-    it 'extracts cached_tokens from prompt_tokens_details (Chat API)' do
-      usage = described_class.from_hash(
-        prompt_tokens: 1000,
-        completion_tokens: 200,
-        prompt_tokens_details: { cached_tokens: 800 },
-        completion_tokens_details: { reasoning_tokens: 50 }
-      )
-
-      expect(usage.input_tokens).to eq(1000)
-      expect(usage.output_tokens).to eq(200)
-      expect(usage.cache_read_tokens).to eq(800)
-      expect(usage.thinking_tokens).to eq(50)
-    end
-
-    it 'extracts cached_tokens from input_tokens_details (Responses API)' do
-      usage = described_class.from_hash(
-        input_tokens: 500,
-        output_tokens: 100,
-        input_tokens_details: { cached_tokens: 400 },
-        output_tokens_details: { reasoning_tokens: 30 }
-      )
-
-      expect(usage.input_tokens).to eq(500)
-      expect(usage.output_tokens).to eq(100)
-      expect(usage.cache_read_tokens).to eq(400)
-      expect(usage.thinking_tokens).to eq(30)
-    end
-
-    it 'prefers top-level cache_read_tokens over nested details' do
-      usage = described_class.from_hash(
-        input_tokens: 500,
-        cache_read_tokens: 300,
-        prompt_tokens_details: { cached_tokens: 400 }
-      )
-
-      expect(usage.cache_read_tokens).to eq(300)
+  describe 'construction law' do
+    it 'from_hash({}) is a valid all-nil Usage with empty units (never nil)' do
+      usage = described_class.from_hash({})
+      expect(usage).to be_a(described_class)
+      expect(usage.input_tokens).to be_nil
+      expect(usage.units).to eq({})
     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)
+    it 'builds from keyword args' do
+      usage = described_class.build(input_tokens: 1, output_tokens: 2)
+      expect(usage.total_tokens).to eq(3)
     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)
+    it 'survives build → to_h → JSON → from_hash (T4 units)' do
+      usage = described_class.build(input_tokens: 1, units: { images: 2 })
+      round_tripped = described_class.from_hash(Legion::JSON.load(Legion::JSON.dump(usage.to_h)))
+      expect(round_tripped.units).to eq(images: 2)
+      expect(round_tripped.input_tokens).to eq(1)
     end
   end
 end

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

@@ -15,11 +15,13 @@ RSpec.describe Legion::Extensions::Llm::Configuration do
     end
 
     it 'exposes a discoverable options API' do
-      expect(described_class.options).to include(
-        :request_timeout,
-        :default_model,
-        :default_embedding_model,
-        :model_registry_file
+      expect(described_class.options).to include(:request_timeout)
+    end
+
+    it 'declares no model-defaulting options (H4: model choice belongs to the router)' do
+      expect(described_class.options).not_to include(
+        :default_model, :default_embedding_model, :default_moderation_model,
+        :default_image_model, :default_transcription_model
       )
     end
 
@@ -36,6 +38,30 @@ RSpec.describe Legion::Extensions::Llm::Configuration do
     end
   end
 
+  describe 'L5 — log defaults come from the settings system (no ENV reads)' do
+    around do |example|
+      original_extensions = Legion::Settings.loader.settings[:extensions]
+      example.run
+    ensure
+      Legion::Settings.loader.settings[:extensions] = original_extensions
+    end
+
+    it 'defaults log_level to INFO and log_stream_debug to false when settings are unset' do
+      Legion::Settings.loader.settings[:extensions] = {}
+      expect(described_class.log_settings_defaults).to eq(level: Logger::INFO, stream_debug: false)
+    end
+
+    it 'reads log_level / log_stream_debug from extensions.llm settings' do
+      Legion::Settings.loader.settings[:extensions] = { llm: { log_level: :debug, log_stream_debug: true } }
+      expect(described_class.log_settings_defaults).to eq(level: Logger::DEBUG, stream_debug: true)
+    end
+
+    it 'raises on an unknown log_level name (configuration error, no fallback)' do
+      Legion::Settings.loader.settings[:extensions] = { llm: { log_level: :bogus } }
+      expect { described_class.log_settings_defaults }.to raise_error(NameError)
+    end
+  end
+
   describe '.register_provider_options' do
     after do
       # Clean up test options to avoid polluting other specs