lex-llm 0.8.0 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6482361b65a465a6eb683fb1789cd47a6a1a80c709c344eefb57205321e90c12
-  data.tar.gz: b2dd262d310f469fd1c89fa0b00eb1199822397bdb762c17c056b05cbad1b1d6
+  metadata.gz: 2798bd117208f95e197b523f01bbd4937d7128f98fd8661ecfc609db33cb0a43
+  data.tar.gz: 0ad1e3cbc9654be5959d8bbd66fe13f1b6f9711150a62d06aa1436f1e0029974
 SHA512:
-  metadata.gz: 64cb921e6ccf8361704df0fe4846fb80b3d074ed09b6940f4cff2c2440c8260e36258acda18ed786415d8052a111e33dcd17ad0f1cef1240dd634f14c30f0172
-  data.tar.gz: e2bb88cc4d672f4a11a64cdc91cc922964e67eab8baa85ad3108c40cc269363dc8009684162c70d1f98dbf8d0a0757d0ca8790838eb066ddab59a1edf37cb28d
+  metadata.gz: 6ebaf6abe1388508ee2be7f365a129b3c83c5846a3cae522758323d000bb97e965a64c7dfb5ed4d4efc093e8f6b8245cc860861a725238da862faee01820f1fd
+  data.tar.gz: 119413c94340f70c038782af0724835c00becfef3d1794f7de5b43a9c3c5e633663cafb73e5c67d68c22a3fdd0bd403e2cdfb86f4bc25f2edadd729709f2968b

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.8.4 - 2026-08-25
+
+### Changed
+- **OpenAI-compatible transposer routes thinking through the canonical bridge.**
+  `Provider::OpenAICompatible#openai_reasoning_effort` now returns `nil` (omitting
+  `reasoning_effort`) when thinking is absent or `enabled: false`, and uses
+  `Thinking::Config#resolved_effort` instead of the raw `effort` — so a budget-only
+  request derives an effort instead of being silently dropped. Added spec coverage.
+- **`Responses::ToolArguments.parse!` accepts every legitimate wire form (10 U2).**
+  An already-decoded `Hash` passes through unchanged (it is the canonical Hash); a
+  `null`/empty/whitespace-only string and a JSON `null` resolve to `{}` (the documented
+  no-arguments default, not tolerance). Genuinely corrupt arguments — a non-object JSON
+  value or invalid JSON — still raise; they are never fabricated into `{}`.
+
+## 0.8.3 - 2026-08-25
+
+### Removed
+- **Removed `Canonical::Params#max_thinking_tokens`.** Thinking budget now lives solely
+  on `Thinking::Config#budget`. The redundant dual-home on Params is deleted from the
+  `Data.define` member list, `.build`, `.from_hash`, and the strict `.new` validation
+  block. Any wire payload carrying `max_thinking_tokens` in params will now fold into
+  `metadata` as an unknown key (04 L5).
+
+## 0.8.2 - 2026-08-25
+
+### Changed
+- **Expand `Thinking::Config` to the common superset shape.** The canonical struct
+  is now `Data.define(:enabled, :effort, :budget, :summary, :metadata)`:
+  - `enabled` — explicit Boolean (true/false). Default true when a Config is built;
+    nil request.thinking means "client said nothing"; `enabled: false` means explicit
+    OFF. Validated strictly (non-boolean raises).
+  - `effort` — closed 6-level enum: `none`, `low`, `medium`, `high`, `xhigh`, `max`
+    (downcased strings). Unknown values raise at construction.
+  - `budget` — positive Integer or nil. Zero and negatives rejected at construction
+    (off rides `enabled: false`; dynamic rides `enabled: true` + no axis).
+  - `summary` — closed enum `{nil, :auto, :none, :concise, :detailed}` for
+    thought-visibility; independent of the effort/budget axes.
+  - `metadata` — unchanged passthrough Hash.
+  - `EFFORT_BUDGET` extended to the full ladder:
+    `{'low'=>1024,'medium'=>8192,'high'=>16384,'xhigh'=>24576,'max'=>32768}`.
+    `none` resolves to nil budget. `resolved_budget` and `resolved_effort` only FILL
+    an axis the client didn't supply — never overwrite a supplied one.
+  - `enabled?` returns the `enabled` member directly.
+
+## 0.8.1 - 2026-08-25
+
+### Changed
+- **Extract `Thinking::Config` to its own file.** `Canonical::Thinking::Config` (the
+  `Data.define` type and its constants) now lives in `canonical/thinking_config.rb`
+  instead of being nested inside `canonical/thinking.rb`. Spec coverage split into a
+  matching `thinking_config_spec.rb`. Pure refactor — no behavior changes.
+
 ## 0.8.0 - 2026-08-20
 
 **The SSOT v4 contract cut.** This is a complete contract line, not a patch wave:

data/lib/legion/extensions/llm/canonical/chunk.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
@@ -207,4 +207,3 @@ module Legion
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/legion/extensions/llm/canonical/content_block.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
@@ -149,4 +149,3 @@ module Legion
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/legion/extensions/llm/canonical/message.rb

@@ -2,7 +2,7 @@
 
 require 'securerandom'
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
@@ -138,4 +138,3 @@ module Legion
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/legion/extensions/llm/canonical/params.rb

@@ -11,19 +11,19 @@ module Legion
         # Per G18: all standard/useful params are first-class, mapped per provider by translators.
         # Canonical keys only (O03a): provider spellings are translated at the edges.
         Params = ::Data.define(
-          :max_tokens, :max_thinking_tokens, :temperature, :top_p, :top_k,
+          :max_tokens, :temperature, :top_p, :top_k,
           :stop_sequences, :seed, :frequency_penalty, :presence_penalty,
           :response_format, :metadata
         ) do
           # rubocop:disable Metrics/ParameterLists -- factory methods have many params
           # Build from keyword args (primary constructor).
           def self.build(
-            max_tokens: nil, max_thinking_tokens: nil, temperature: nil, top_p: nil, top_k: nil,
+            max_tokens: nil, temperature: nil, top_p: nil, top_k: nil,
             stop_sequences: nil, seed: nil, frequency_penalty: nil, presence_penalty: nil,
             response_format: nil, metadata: {}
           )
             new(
-              max_tokens:, max_thinking_tokens:, temperature:, top_p:, top_k:,
+              max_tokens:, temperature:, top_p:, top_k:,
               stop_sequences:, seed:, frequency_penalty:, presence_penalty:,
               response_format:, metadata: Strict.metadata!(metadata, self::BUILD_SITE)
             )
@@ -39,7 +39,6 @@ module Legion
             metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
             build(
               max_tokens: hash[:max_tokens],
-              max_thinking_tokens: hash[:max_thinking_tokens],
               temperature: hash[:temperature],
               top_p: hash[:top_p],
               top_k: hash[:top_k],
@@ -73,7 +72,6 @@ module Legion
           # wire. The factories fill their defaults and delegate here.
           Strict.install_strict_new!(self) do |values, site|
             values[:max_tokens] = Strict.expect_type!(values[:max_tokens], [::Integer], site, :max_tokens)
-            values[:max_thinking_tokens] = Strict.expect_type!(values[:max_thinking_tokens], [::Integer], site, :max_thinking_tokens)
             values[:temperature] = Strict.expect_type!(values[:temperature], [::Numeric], site, :temperature)
             values[:top_p] = Strict.expect_type!(values[:top_p], [::Numeric], site, :top_p)
             values[:top_k] = Strict.expect_type!(values[:top_k], [::Integer], site, :top_k)

data/lib/legion/extensions/llm/canonical/request.rb

@@ -2,7 +2,7 @@
 
 require 'securerandom'
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
@@ -136,4 +136,3 @@ module Legion
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/legion/extensions/llm/canonical/response.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
@@ -115,4 +115,3 @@ module Legion
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/legion/extensions/llm/canonical/thinking.rb

@@ -69,105 +69,9 @@ module Legion
         Thinking::BUILD_SITE = 'Canonical::Thinking.build'
         Thinking::FROM_HASH_SITE = 'Canonical::Thinking.from_hash'
         Thinking::NEW_SITE = 'Canonical::Thinking.new'
-
-        # Normalized config for thinking across providers — one name, one shape
-        # (04 §8): Canonical::Thinking::Config. # -- required for Data.define block scope
-        Thinking::Config = ::Data.define(:effort, :budget, :metadata) do
-          def self.build(effort: nil, budget: nil, metadata: {})
-            new(effort: effort_string!(effort, self::BUILD_SITE), budget:,
-                metadata: Strict.metadata!(metadata, self::BUILD_SITE))
-          end
-
-          # Build from a Hash.
-          def self.from_hash(source)
-            Strict.require_hash!(source, self::FROM_HASH_SITE)
-            hash = Strict.symbolize_keys(source)
-            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
-            build(effort: hash[:effort], budget: hash[:budget], metadata:)
-          end
-
-          # M4: effort is a closed enum (the EFFORT_BUDGET keys), not an
-          # unbounded string — an unrecognized effort is a contract error at
-          # construction, never a silently-derived budget.
-          def self.effort_string!(effort, site)
-            return nil if effort.nil?
-
-            value = effort.is_a?(::Symbol) ? effort.to_s : Strict.expect_type!(effort, [::String], site, :effort)
-            normalized = value.downcase
-            allowed = self::EFFORT_BUDGET.keys
-            raise ArgumentError, "#{site}: Invalid effort: #{value.inspect}. Must be one of: #{allowed.join(', ')}" unless allowed.include?(normalized)
-
-            normalized
-          end
-
-          # Serialize to a Hash for AMQP/fleet/wire transport. Faithful to what was
-          # SET — never fabricates the missing axis (use resolved_* for that).
-          def to_h
-            super.compact
-          end
-
-          def as_json(*)
-            to_h
-          end
-
-          def to_json(*)
-            to_h.to_json(*)
-          end
-
-          # Whether thinking is configured.
-          def enabled?
-            !effort.nil? || !budget.nil?
-          end
-
-          # Budget for a provider that needs a token budget (e.g. Anthropic),
-          # derived from effort when budget was not explicitly set. nil only
-          # when neither axis is configured. M4: effort is enum-validated at
-          # construction, so the lookup cannot miss — the silent medium
-          # fallback is deleted.
-          def resolved_budget
-            return budget unless budget.nil?
-            return nil if effort.nil?
-
-            self.class::EFFORT_BUDGET[effort]
-          end
-
-          # Effort for a provider that needs an effort level (e.g. OpenAI),
-          # derived from budget when effort was not explicitly set. nil only
-          # when neither axis is configured.
-          def resolved_effort
-            return effort unless effort.nil?
-            return nil if budget.nil?
-
-            bands = self.class::EFFORT_BUDGET
-            if budget < bands['medium'] then 'low'
-            elsif budget < bands['high'] then 'medium'
-            else 'high'
-            end
-          end
-
-          # H1/M4: the single strict constructor — .new runs the same member
-          # contract as the factories (effort enum, Integer budget); the
-          # factories fill their defaults and delegate here.
-          Strict.install_strict_new!(self) do |values, site|
-            values[:effort] = effort_string!(values[:effort], site)
-            values[:budget] = Strict.expect_type!(values[:budget], [::Integer], site, :budget)
-            values[:metadata] = Strict.metadata!(values[:metadata], site)
-            values
-          end
-        end
-
-        # SSOT for the effort<->budget conversion. A client dialect supplies only
-        # ONE axis (Anthropic = budget_tokens only; OpenAI = effort only), but a
-        # provider translator may need the OTHER. This single map lets every
-        # provider ask for whichever axis it needs and always get a usable value,
-        # so thinking survives any client x provider pair (best-effort, never
-        # silently dropped). effort -> budget is exact; budget -> effort uses the
-        # band boundaries above.
-        Thinking::Config::EFFORT_BUDGET = { 'low' => 1024, 'medium' => 8192, 'high' => 16_384 }.freeze
-        Thinking::Config::BUILD_SITE = 'Canonical::Thinking::Config.build'
-        Thinking::Config::FROM_HASH_SITE = 'Canonical::Thinking::Config.from_hash'
-        Thinking::Config::NEW_SITE = 'Canonical::Thinking::Config.new'
       end
     end
   end
 end
+
+require_relative 'thinking_config'

data/lib/legion/extensions/llm/canonical/thinking_config.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# -- extracted from thinking.rb; depends on Thinking being defined first
+module Legion
+  module Extensions
+    # -- module doc is in canonical.rb entry point
+    module Llm
+      # -- required for Data.define block scope
+      module Canonical
+        # Normalized config for thinking across providers — one name, one shape
+        # (04 §8): Canonical::Thinking::Config.
+        # Members: enabled, effort, budget, summary, metadata
+        Thinking::Config = ::Data.define(:enabled, :effort, :budget, :summary, :metadata) do
+          def self.build(enabled: true, effort: nil, budget: nil, summary: nil, metadata: {})
+            new(enabled: enabled, effort: effort_string!(effort, self::BUILD_SITE), budget: budget,
+                summary: summary, metadata: Strict.metadata!(metadata, self::BUILD_SITE))
+          end
+
+          # Build from a Hash.
+          def self.from_hash(source)
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(enabled: hash.key?(:enabled) ? hash[:enabled] : true,
+                  effort: hash[:effort], budget: hash[:budget],
+                  summary: hash[:summary], metadata: metadata)
+          end
+
+          # M4: effort is a closed enum (the EFFORT_BUDGET keys), not an
+          # unbounded string — an unrecognized effort is a contract error at
+          # construction, never a silently-derived budget.
+          def self.effort_string!(effort, site)
+            return nil if effort.nil?
+
+            value = effort.is_a?(::Symbol) ? effort.to_s : Strict.expect_type!(effort, [::String], site, :effort)
+            normalized = value.downcase
+            allowed = self::EFFORT_LEVELS
+            raise ArgumentError, "#{site}: Invalid effort: #{value.inspect}. Must be one of: #{allowed.join(', ')}" unless allowed.include?(normalized)
+
+            normalized
+          end
+
+          # Validate summary is a closed enum.
+          def self.summary_enum!(value, site)
+            return nil if value.nil?
+
+            sym = value.is_a?(::String) ? value.to_sym : value
+            Strict.expect_type!(sym, [::Symbol], site, :summary)
+            allowed = self::SUMMARY_LEVELS
+            unless allowed.include?(sym)
+              raise ArgumentError,
+                    "#{site}: Invalid summary: #{value.inspect}. Must be one of: #{allowed.map(&:inspect).join(', ')}"
+            end
+
+            sym
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport. Faithful to what was
+          # SET — never fabricates the missing axis (use resolved_* for that).
+          def to_h
+            super.compact
+          end
+
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
+          # Whether thinking is enabled (the enabled member).
+          def enabled?
+            enabled
+          end
+
+          # Budget for a provider that needs a token budget (e.g. Anthropic),
+          # derived from effort when budget was not explicitly set. nil when
+          # effort is 'none' or neither axis is configured. Only FILLS — never
+          # overwrites a supplied budget. Both axes may be carried together.
+          def resolved_budget
+            return budget unless budget.nil?
+            return nil if effort.nil?
+            return nil if effort == 'none'
+
+            self.class::EFFORT_BUDGET[effort]
+          end
+
+          # Effort for a provider that needs an effort level (e.g. OpenAI),
+          # derived from budget when effort was not explicitly set. nil only
+          # when neither axis is configured. Only FILLS — never overwrites a
+          # supplied effort.
+          def resolved_effort
+            return effort unless effort.nil?
+            return nil if budget.nil?
+
+            bands = self.class::EFFORT_BUDGET
+            if budget <= bands['low'] then 'low'
+            elsif budget <= bands['medium'] then 'medium'
+            elsif budget <= bands['high'] then 'high'
+            elsif budget <= bands['xhigh'] then 'xhigh'
+            else 'max'
+            end
+          end
+
+          # H1/M4: the single strict constructor — .new runs the same member
+          # contract as the factories (enabled bool, effort enum, Integer budget,
+          # summary enum); the factories fill their defaults and delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            # enabled: must be true or false
+            raise ArgumentError, "#{site}: enabled must be true or false, got #{values[:enabled].inspect}" unless [true, false].include?(values[:enabled])
+
+            values[:effort] = effort_string!(values[:effort], site)
+
+            # budget: must be a positive Integer or nil
+            values[:budget] = Strict.expect_type!(values[:budget], [::Integer], site, :budget)
+            raise ArgumentError, "#{site}: budget must be positive, got #{values[:budget]}" if values[:budget] && !values[:budget].positive?
+
+            values[:summary] = summary_enum!(values[:summary], site)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
+        end
+
+        # Closed set of valid effort levels.
+        Thinking::Config::EFFORT_LEVELS = %w[none low medium high xhigh max].freeze
+
+        # SSOT for the effort<->budget conversion. A client dialect supplies only
+        # ONE axis (Anthropic = budget_tokens only; OpenAI = effort only), but a
+        # provider translator may need the OTHER. This single map lets every
+        # provider ask for whichever axis it needs and always get a usable value,
+        # so thinking survives any client x provider pair (best-effort, never
+        # silently dropped). effort -> budget is exact; budget -> effort uses the
+        # band boundaries above. 'none' has no budget — resolves to nil.
+        Thinking::Config::EFFORT_BUDGET = {
+          'low' => 1024, 'medium' => 8192, 'high' => 16_384,
+          'xhigh' => 24_576, 'max' => 32_768
+        }.freeze
+
+        # Closed set of valid summary levels.
+        Thinking::Config::SUMMARY_LEVELS = %i[auto none concise detailed].freeze
+
+        Thinking::Config::BUILD_SITE = 'Canonical::Thinking::Config.build'
+        Thinking::Config::FROM_HASH_SITE = 'Canonical::Thinking::Config.from_hash'
+        Thinking::Config::NEW_SITE = 'Canonical::Thinking::Config.new'
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/canonical/tool_call.rb

@@ -2,7 +2,7 @@
 
 require 'securerandom'
 
-# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+# rubocop:disable-next Metrics/ParameterLists -- factory methods have many params
 module Legion
   module Extensions
     module Llm
@@ -132,4 +132,3 @@ module Legion
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/legion/extensions/llm/canonical.rb

@@ -2,6 +2,7 @@
 
 require_relative 'canonical/strict'
 require_relative 'canonical/thinking'
+require_relative 'canonical/thinking_config'
 require_relative 'canonical/usage'
 require_relative 'canonical/params'
 require_relative 'canonical/content_block'

data/lib/legion/extensions/llm/provider/open_ai_compatible.rb

@@ -154,10 +154,16 @@ module Legion
             { type: 'json_schema', json_schema: schema_hash }
           end
 
+          # Transpose canonical thinking -> OpenAI `reasoning_effort` (edge, O03a).
+          # Omit the key when there is no thinking or it is explicitly disabled
+          # (a reasoning model then uses its own default). resolved_effort fills
+          # the effort axis from budget when the client supplied only a budget,
+          # so a budget-only request is never silently dropped.
           def openai_reasoning_effort(thinking)
             return nil unless thinking.is_a?(Canonical::Thinking::Config)
+            return nil unless thinking.enabled
 
-            thinking.effort
+            thinking.resolved_effort
           end
 
           # One response-parse boundary (08 R2): returns Canonical::Response.

data/lib/legion/extensions/llm/responses/tool_arguments.rb

@@ -12,15 +12,29 @@ module Legion
         module ToolArguments
           module_function
 
-          # Parse assembled tool-call arguments JSON into a Hash.
-          # nil / empty string means "no arguments" and returns {} (documented
-          # default, not tolerance).
+          # Parse tool-call arguments into the canonical Hash (10 U2).
+          #
+          # The provider wire legitimately encodes the arguments in a few
+          # forms; this ONE parser maps every legitimate form to the canonical
+          # Hash so every lex-llm-* provider parses arguments identically:
+          #   - nil, empty/whitespace String, or JSON null  -> {} (no arguments;
+          #     documented default, not tolerance)
+          #   - an already-decoded wire object (Hash)       -> passed through
+          #     (it IS the canonical Hash)
+          #   - a JSON-object String                        -> parsed to Hash
+          #
+          # Genuinely corrupted arguments still raise — a non-object JSON value
+          # (array/number/string) or invalid JSON is a contract error, never a
+          # fabricated {} (04 L1/L7; the old rescue-to-{} policies are deleted).
           def parse!(raw)
             return {} if raw.nil?
-            return {} if raw.is_a?(::String) && raw.strip.empty?
-            raise ArgumentError, "tool call arguments expected JSON String, got #{raw.class}" unless raw.is_a?(::String)
+            return raw if raw.is_a?(::Hash)
+            return {} if raw.is_a?(::String) && (raw.strip.empty? || raw.strip.casecmp?('null'))
+
+            raise ArgumentError, "tool call arguments expected JSON String or Hash, got #{raw.class}" unless raw.is_a?(::String)
 
             parsed = ::Legion::JSON.parse(raw, symbolize_names: false)
+            return {} if parsed.nil?
             raise ArgumentError, "tool call arguments must be a JSON object, got #{parsed.class}" unless parsed.is_a?(::Hash)
 
             parsed

data/lib/legion/extensions/llm/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.8.0'
+      VERSION = '0.8.4'
     end
   end
 end

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

@@ -9,7 +9,6 @@ RSpec.describe Legion::Extensions::Llm::Canonical::Params do
   let(:type_source) do
     {
       max_tokens: 1024,
-      max_thinking_tokens: 512,
       temperature: 0.7,
       top_p: 0.9,
       top_k: 40,
@@ -28,7 +27,6 @@ RSpec.describe Legion::Extensions::Llm::Canonical::Params do
     it 'does not translate provider spellings (they fold into metadata)' do
       params = described_class.from_hash(max_output_tokens: 999, num_predict: 888, stop: ['x'])
       expect(params.max_tokens).to be_nil
-      expect(params.max_thinking_tokens).to be_nil
       expect(params.stop_sequences).to be_nil
       expect(params.metadata).to eq(max_output_tokens: 999, num_predict: 888, stop: ['x'])
     end

data/spec/legion/extensions/llm/canonical/thinking/config_spec.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require_relative '../../conformance/conformance'
+
+RSpec.describe Legion::Extensions::Llm::Canonical::Thinking::Config do
+  subject(:config_class) { described_class }
+
+  let(:type_class) { described_class }
+  let(:auto_generated_members) { [] }
+  let(:type_source) do
+    { enabled: true, effort: 'high', budget: 4096, summary: :concise, metadata: { source: 'client' } }
+  end
+
+  it_behaves_like 'a canonical type'
+
+  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(enabled: true, effort: 'low', budget: nil, summary: nil, metadata: {})).to be_a(config_class)
+  end
+
+  it 'normalizes symbol effort to String' do
+    config = config_class.build(effort: :low)
+    expect(config.effort).to eq('low')
+  end
+
+  it 'raises on a wrong-class effort' do
+    expect { config_class.build(effort: 3) }
+      .to raise_error(ArgumentError, /effort expected String, got Integer/)
+  end
+
+  describe 'enabled member' do
+    it 'defaults to true in .build' do
+      config = config_class.build
+      expect(config.enabled).to be(true)
+    end
+
+    it 'defaults to true in .from_hash when key absent' do
+      config = config_class.from_hash({})
+      expect(config.enabled).to be(true)
+    end
+
+    it 'accepts explicit true' do
+      config = config_class.build(enabled: true)
+      expect(config.enabled).to be(true)
+    end
+
+    it 'accepts explicit false' do
+      config = config_class.build(enabled: false)
+      expect(config.enabled).to be(false)
+    end
+
+    it 'rejects non-boolean in .new' do
+      expect { config_class.new(enabled: 'yes', effort: nil, budget: nil, summary: nil, metadata: {}) }
+        .to raise_error(ArgumentError, /enabled must be true or false/)
+    end
+
+    it 'rejects nil in .new (must be an explicit boolean)' do
+      expect { config_class.new(enabled: nil, effort: nil, budget: nil, summary: nil, metadata: {}) }
+        .to raise_error(ArgumentError, /enabled must be true or false/)
+    end
+
+    it 'enabled? returns the enabled member' do
+      expect(config_class.build(enabled: true).enabled?).to be(true)
+      expect(config_class.build(enabled: false).enabled?).to be(false)
+    end
+  end
+
+  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(enabled: true, effort: 'banana', budget: nil, summary: nil, metadata: {}) }
+        .to raise_error(ArgumentError, /Invalid effort: "banana"/)
+    end
+
+    it 'accepts the enum case-insensitively (symbol or string)' do
+      expect(config_class.build(effort: :HIGH).effort).to eq('high')
+      expect(config_class.new(enabled: true, effort: 'Medium', budget: nil, summary: nil, metadata: {}).effort).to eq('medium')
+    end
+
+    it 'accepts all six effort levels' do
+      %w[none low medium high xhigh max].each do |level|
+        expect(config_class.build(effort: level).effort).to eq(level)
+      end
+    end
+
+    it 'resolved_budget derives from the validated effort (no silent medium fallback)' 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(effort: 'xhigh').resolved_budget).to eq(24_576)
+      expect(config_class.build(effort: 'max').resolved_budget).to eq(32_768)
+      expect(config_class.build(effort: 'none').resolved_budget).to be_nil
+      expect(config_class.build(budget: 123).resolved_budget).to eq(123)
+      expect(config_class.build(enabled: false).resolved_budget).to be_nil
+    end
+  end
+
+  describe 'budget validation' do
+    it 'accepts a positive integer' do
+      expect(config_class.build(budget: 1).budget).to eq(1)
+      expect(config_class.build(budget: 50_000).budget).to eq(50_000)
+    end
+
+    it 'accepts nil' do
+      expect(config_class.build(budget: nil).budget).to be_nil
+    end
+
+    it 'rejects zero' do
+      expect { config_class.build(budget: 0) }
+        .to raise_error(ArgumentError, /budget must be positive/)
+    end
+
+    it 'rejects negative integers' do
+      expect { config_class.build(budget: -1) }
+        .to raise_error(ArgumentError, /budget must be positive/)
+      expect { config_class.build(budget: -100) }
+        .to raise_error(ArgumentError, /budget must be positive/)
+    end
+
+    it 'rejects non-Integer types' do
+      expect { config_class.build(budget: 1.5) }
+        .to raise_error(ArgumentError, /budget expected Integer/)
+      expect { config_class.build(budget: '1024') }
+        .to raise_error(ArgumentError, /budget expected Integer/)
+    end
+  end
+
+  describe 'summary enum' do
+    it 'accepts nil (default)' do
+      expect(config_class.build(summary: nil).summary).to be_nil
+    end
+
+    it 'accepts :auto, :none, :concise, :detailed' do
+      %i[auto none concise detailed].each do |level|
+        expect(config_class.build(summary: level).summary).to eq(level)
+      end
+    end
+
+    it 'coerces string to symbol' do
+      expect(config_class.from_hash(summary: 'concise').summary).to eq(:concise)
+    end
+
+    it 'rejects invalid summary values' do
+      expect { config_class.build(summary: :verbose) }
+        .to raise_error(ArgumentError, /Invalid summary/)
+      expect { config_class.build(summary: :full) }
+        .to raise_error(ArgumentError, /Invalid summary/)
+    end
+
+    it 'rejects non-symbol/string types' do
+      expect { config_class.build(summary: 42) }
+        .to raise_error(ArgumentError, /summary expected Symbol/)
+    end
+  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(effort: 'xhigh').resolved_budget).to eq(24_576)
+    expect(config_class.build(effort: 'max').resolved_budget).to eq(32_768)
+    expect(config_class.build(budget: 512).resolved_effort).to eq('low')
+    expect(config_class.build(budget: 1024).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')
+    expect(config_class.build(budget: 24_576).resolved_effort).to eq('xhigh')
+    expect(config_class.build(budget: 32_768).resolved_effort).to eq('max')
+    expect(config_class.build(budget: 50_000).resolved_effort).to eq('max')
+  end
+
+  describe 'resolved_effort band boundaries' do
+    it 'maps budget at boundary to the correct effort level' do
+      # At the low boundary
+      expect(config_class.build(budget: 1024).resolved_effort).to eq('low')
+      # Just above low
+      expect(config_class.build(budget: 1025).resolved_effort).to eq('medium')
+      # At medium boundary
+      expect(config_class.build(budget: 8192).resolved_effort).to eq('medium')
+      # Just above medium
+      expect(config_class.build(budget: 8193).resolved_effort).to eq('high')
+      # At high boundary
+      expect(config_class.build(budget: 16_384).resolved_effort).to eq('high')
+      # Just above high
+      expect(config_class.build(budget: 16_385).resolved_effort).to eq('xhigh')
+      # At xhigh boundary
+      expect(config_class.build(budget: 24_576).resolved_effort).to eq('xhigh')
+      # Just above xhigh
+      expect(config_class.build(budget: 24_577).resolved_effort).to eq('max')
+    end
+
+    it 'returns nil when budget is nil (no fabrication)' do
+      expect(config_class.build.resolved_effort).to be_nil
+    end
+
+    it 'returns the supplied effort when both are set (no overwrite)' do
+      config = config_class.build(effort: 'low', budget: 30_000)
+      expect(config.resolved_effort).to eq('low')
+      expect(config.resolved_budget).to eq(30_000)
+    end
+  end
+
+  it 'to_h is faithful to what was set (no fabricated axis)' do
+    expect(config_class.build(effort: 'low').to_h).to eq(enabled: true, effort: 'low', metadata: {})
+    # enabled:false is explicit OFF signal — it IS set, so it appears in to_h
+    expect(config_class.build(enabled: false).to_h).to eq(enabled: false, metadata: {})
+  end
+
+  it 'to_h omits nil members (compact)' do
+    config = config_class.build(enabled: true, effort: 'high', budget: 4096, summary: :detailed)
+    expect(config.to_h).to eq(enabled: true, effort: 'high', budget: 4096, summary: :detailed, metadata: {})
+  end
+
+  it 'from_hash round-trips through to_h' do
+    original = config_class.build(enabled: true, effort: 'xhigh', budget: 24_576, summary: :auto)
+    rebuilt = config_class.from_hash(original.to_h)
+    expect(rebuilt).to eq(original)
+  end
+end

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

@@ -38,72 +38,4 @@ RSpec.describe Legion::Extensions::Llm::Canonical::Thinking do
       expect(round_tripped.signature).to eq('sig-1')
     end
   end
-
-  describe Legion::Extensions::Llm::Canonical::Thinking::Config do
-    subject(:config_class) { described_class }
-
-    let(:type_class) { described_class }
-    let(:auto_generated_members) { [] }
-    let(:type_source) do
-      { effort: 'high', budget: 4096, metadata: { source: 'client' } }
-    end
-
-    it_behaves_like 'a canonical type'
-
-    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
-
-    it 'normalizes symbol effort to String' do
-      config = config_class.build(effort: :low)
-      expect(config.effort).to eq('low')
-    end
-
-    it 'raises on a wrong-class effort' do
-      expect { config_class.build(effort: 3) }
-        .to raise_error(ArgumentError, /effort expected String, got Integer/)
-    end
-
-    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 '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 '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
-
-    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
-
-    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
-
-    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/conformance/client_translator_examples.rb

@@ -10,7 +10,7 @@
 #
 # Usage:
 #   it_behaves_like 'a canonical client translator', MyClientTranslatorClass
-# rubocop:disable Lint/NonLocalExitFromIterator -- return guard is idiomatic in shared_example blocks
+# rubocop:disable-next Lint/NonLocalExitFromIterator -- return guard is idiomatic in shared_example blocks
 RSpec.shared_examples 'a canonical client translator' do |translator_class|
   let(:translator) { translator_class.new }
   let(:canonical) { Legion::Extensions::Llm::Canonical }
@@ -429,4 +429,3 @@ RSpec.shared_examples 'a canonical client translator' do |translator_class|
     end
   end
 end
-# rubocop:enable Lint/NonLocalExitFromIterator

data/spec/legion/extensions/llm/conformance/fixtures/canonical_fleet_round_trip.json

@@ -21,7 +21,7 @@
       }
     },
     "params": { "max_tokens": 1024, "temperature": 0.5 },
-    "thinking": { "effort": "low", "budget": 1024 },
+    "thinking": { "enabled": true, "effort": "low", "budget": 1024 },
     "stream": false,
     "conversation_id": "conv_fleet_rt_001",
     "caller": { "type": "anthropic_messages", "client_id": "test_client" },

data/spec/legion/extensions/llm/conformance/fixtures/canonical_thinking_request.json

@@ -8,12 +8,12 @@
     }
   ],
   "thinking": {
+    "enabled": true,
     "effort": "high",
     "budget": 4096
   },
   "params": {
-    "max_tokens": 2048,
-    "max_thinking_tokens": 4096
+    "max_tokens": 2048
   },
   "stream": false
 }

data/spec/legion/extensions/llm/conformance/ssot_contract_conformance_spec.rb

@@ -9,7 +9,7 @@ require_relative 'ssot_contract_examples'
 # Kit self-test: the B/F/R shared examples run against a real Provider-derived
 # callable, the real Registry, and the real fleet responder/worker — proving
 # the examples provider gems will load are executable and meaningful.
-# rubocop:disable RSpec/DescribeClass, RSpec/MultipleMemoizedHelpers -- kit host
+# rubocop:disable-next RSpec/DescribeClass, RSpec/MultipleMemoizedHelpers -- kit host
 RSpec.describe 'SSOT v4 contract conformance kit' do
   include SsotRegistryHelpers
 
@@ -34,7 +34,7 @@ RSpec.describe 'SSOT v4 contract conformance kit' do
         Legion::Extensions::Llm::Canonical::Response.build(text: 'ok', model: model, stop_reason: :end_turn)
       end
 
-      # rubocop:disable Lint/UnusedMethodArgument -- model: mirrors the 0.8.0 callable contract
+      # rubocop:disable-next Lint/UnusedMethodArgument -- model: mirrors the 0.8.0 callable contract
       def stream_chat(messages, model: nil, tools: nil, **_contract, &block)
         enforce_canonical_messages!(messages)
         enforce_canonical_tools!(tools)
@@ -43,7 +43,6 @@ RSpec.describe 'SSOT v4 contract conformance kit' do
                                                                    usage: Legion::Extensions::Llm::Canonical::Usage.build(input_tokens: 1)))
         nil
       end
-      # rubocop:enable Lint/UnusedMethodArgument
 
       def count_tokens(messages:, **_contract)
         enforce_canonical_messages!(messages)
@@ -127,4 +126,3 @@ RSpec.describe 'SSOT v4 contract conformance kit' do
   it_behaves_like 'R4 — weight law (07 §4)'
   it_behaves_like 'R5 — callable lifecycle (07 §6)'
 end
-# rubocop:enable RSpec/DescribeClass, RSpec/MultipleMemoizedHelpers

data/spec/legion/extensions/llm/conformance/ssot_contract_examples.rb

@@ -44,10 +44,9 @@ RSpec.shared_examples 'B1 — central canonical enforcement (08 F2)' do
     end
 
     it "stream_chat rejects #{label} with a typed ArgumentError" do
-      # rubocop:disable Lint/EmptyBlock -- the block never runs: enforcement raises first
+      # rubocop:disable-next Lint/EmptyBlock -- the block never runs: enforcement raises first
       expect { callable.stream_chat(bad_messages, model: 'm') { |_c| } }
         .to raise_error(ArgumentError, /Canonical::Message/)
-      # rubocop:enable Lint/EmptyBlock
     end
 
     it "count_tokens rejects #{label} with a typed ArgumentError" do
@@ -121,9 +120,8 @@ RSpec.shared_examples 'B3 — operation preservation (PR #189 defect class)' do
       block&.call(CAN::Chunk.done(request_id: nil))
     end
 
-    # rubocop:disable Lint/EmptyBlock -- the block is the assertion target
+    # rubocop:disable-next Lint/EmptyBlock -- the block is the assertion target
     callable.stream_chat([CAN::Message.build(role: :user, content: 'hi')], model: 'm') { |_c| }
-    # rubocop:enable Lint/EmptyBlock
 
     expect(stream_invocations).to eq(1)
     expect(chat_invocations).to eq(0)

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

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-# rubocop:disable RSpec/DescribeClass
+# rubocop:disable-next RSpec/DescribeClass
 RSpec.describe 'LLM fleet message envelopes' do
   let(:protocol) { Legion::Extensions::Llm::Fleet::Protocol }
   let(:channel_class) do
@@ -408,4 +408,3 @@ RSpec.describe 'LLM fleet message envelopes' do
     end
   end
 end
-# rubocop:enable RSpec/DescribeClass

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

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-# rubocop:disable RSpec/DescribeClass
+# rubocop:disable-next RSpec/DescribeClass
 RSpec.describe 'lex-llm.gemspec' do
   subject(:gemspec) { Gem::Specification.load(File.expand_path('../../../../lex-llm.gemspec', __dir__)) }
 
@@ -22,4 +22,3 @@ RSpec.describe 'lex-llm.gemspec' do
     expect(gemspec.name).to eq('lex-llm')
   end
 end
-# rubocop:enable RSpec/DescribeClass

data/spec/legion/extensions/llm/provider/open_ai_compatible_spec.rb

@@ -49,6 +49,29 @@ RSpec.describe Legion::Extensions::Llm::Provider::OpenAICompatible do
     expect(payload[:messages]).to eq([{ role: 'assistant', content: "internal\n</thinking>\n\nHello" }])
   end
 
+  describe 'reasoning_effort transposition (canonical Thinking::Config -> OpenAI wire)' do
+    def payload_for(thinking)
+      provider.send(:render_payload, [], tools: {}, model: model_id, stream: false,
+                                         schema: nil, thinking: thinking, tool_prefs: nil, params: nil)
+    end
+
+    it 'passes an explicit effort through' do
+      expect(payload_for(canonical::Thinking::Config.build(effort: 'high'))[:reasoning_effort]).to eq('high')
+    end
+
+    it 'derives effort from a budget-only config so it is never dropped' do
+      expect(payload_for(canonical::Thinking::Config.build(budget: 8192))[:reasoning_effort]).to eq('medium')
+    end
+
+    it 'omits reasoning_effort when thinking is explicitly disabled' do
+      expect(payload_for(canonical::Thinking::Config.build(enabled: false))).not_to have_key(:reasoning_effort)
+    end
+
+    it 'omits reasoning_effort when there is no thinking' do
+      expect(payload_for(nil)).not_to have_key(:reasoning_effort)
+    end
+  end
+
   it 'renders content block arrays in the OpenAI wire shape' do
     message = canonical::Message.build(
       role: :user,

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

@@ -201,9 +201,8 @@ RSpec.describe Legion::Extensions::Llm::Provider do
       it 'accepts Hash<name, Canonical::ToolDefinition> through chat and stream_chat' do
         expect(provider.chat([], model: 'test-model', tools: { get_weather: tool })).to eq('ok')
         expect do
-          # rubocop:disable Lint/EmptyBlock -- the streamed chunk is consumed by the stub
+          # rubocop:disable-next Lint/EmptyBlock -- the streamed chunk is consumed by the stub
           provider.stream_chat([], model: 'test-model', tools: { get_weather: tool }) { |_c| }
-          # rubocop:enable Lint/EmptyBlock
         end.not_to raise_error
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.4
 platform: ruby
 authors:
 - LegionIO
@@ -267,6 +267,7 @@ files:
 - lib/legion/extensions/llm/canonical/response.rb
 - lib/legion/extensions/llm/canonical/strict.rb
 - lib/legion/extensions/llm/canonical/thinking.rb
+- lib/legion/extensions/llm/canonical/thinking_config.rb
 - lib/legion/extensions/llm/canonical/tool_call.rb
 - lib/legion/extensions/llm/canonical/tool_definition.rb
 - lib/legion/extensions/llm/canonical/tool_schema.rb
@@ -342,6 +343,7 @@ files:
 - spec/legion/extensions/llm/canonical/params_spec.rb
 - spec/legion/extensions/llm/canonical/request_spec.rb
 - spec/legion/extensions/llm/canonical/response_spec.rb
+- spec/legion/extensions/llm/canonical/thinking/config_spec.rb
 - spec/legion/extensions/llm/canonical/thinking_spec.rb
 - spec/legion/extensions/llm/canonical/tool_call_spec.rb
 - spec/legion/extensions/llm/canonical/tool_definition_spec.rb