lex-llm 0.7.6 → 0.8.4

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

@@ -1,107 +1,78 @@
 # 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
+      # -- required for Data.define block scope
       module Canonical
-        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
         # Canonical response shape — the provider-boundary contract.
         # Per R2: does NOT replace Inference::Response (the pipeline envelope).
         # Per Amendment A: immutable Data.define with strict factory.
+        # Unknown keys fold into metadata — never silently dropped.
         Response = ::Data.define(
           :text, :thinking, :tool_calls, :usage,
           :stop_reason, :model, :routing, :metadata
         ) do
-          STOP_REASONS = %i[end_turn tool_use max_tokens stop_sequence content_filter error].freeze
+          # Build from keyword args (primary constructor).
+          def self.build(
+            text: '', thinking: nil, tool_calls: nil, usage: nil,
+            stop_reason: nil, model: nil, routing: nil, metadata: {}
+          )
+            new(
+              text: text.to_s,
+              thinking: normalize_thinking!(thinking, self::BUILD_SITE),
+              tool_calls: normalize_tool_calls!(tool_calls, self::BUILD_SITE),
+              usage: normalize_usage!(usage, self::BUILD_SITE),
+              stop_reason: normalize_stop_reason!(stop_reason, self::BUILD_SITE),
+              model: model,
+              routing: routing || {},
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE)
+            )
+          end
 
           # Build from a Hash (raw provider response or deserialized wire payload).
-          # Unknown keys go to metadata, never silently dropped.
+          # Canonical keys only (O03a): edges pass `stop_reason`, not `finish_reason`.
           def self.from_hash(source)
-            return nil if source.nil?
-
-            h = source.transform_keys(&:to_sym)
-
-            # Extract known fields
-            text = h.delete(:text) || h.delete(:content) || ''
-            text = text.to_s if text
-
-            thinking_raw = h.delete(:thinking)
-            thinking = thinking_raw.is_a?(Thinking) ? thinking_raw : Thinking.from_hash(thinking_raw)
-
-            tool_calls_raw = h.delete(:tool_calls)
-            tool_calls = Array(tool_calls_raw).filter_map do |tc|
-              tc.is_a?(ToolCall) ? tc : ToolCall.from_hash(tc)
-            end
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(**hash, metadata:)
+          end
 
-            usage_raw = h.delete(:usage)
-            usage = usage_raw.is_a?(Usage) ? usage_raw : Usage.from_hash(usage_raw)
+          # L6: stop_reason validated at construction, in both factories.
+          def self.normalize_stop_reason!(stop_reason, site)
+            stop_reason_sym = stop_reason&.to_sym
+            Strict.enum!(stop_reason_sym, self::STOP_REASONS, site, :stop_reason)
+          end
 
-            # Normalize stop_reason
-            stop_reason_raw = h.delete(:stop_reason) || h.delete(:finish_reason)
-            stop_reason = stop_reason_raw&.to_sym if stop_reason_raw
-            unless stop_reason.nil? || STOP_REASONS.include?(stop_reason)
-              raise ArgumentError,
-                    "Invalid stop_reason: #{stop_reason.inspect}. Must be one of: #{STOP_REASONS.join(', ')}"
-            end
+          # L2: one normalizer per member, shared by build and from_hash.
+          def self.normalize_thinking!(thinking, site)
+            return nil if thinking.nil?
+            return thinking if thinking.is_a?(Thinking)
 
-            model = h.delete(:model)
-            routing = h.delete(:routing) || {}
+            Strict.expect_type!(thinking, [::Hash], site, :thinking)
+            Thinking.from_hash(thinking)
+          end
 
-            # Remaining keys become metadata
-            existing_metadata = h.delete(:metadata) || {}
-            metadata = existing_metadata.merge(h).compact
+          def self.normalize_tool_calls!(tool_calls, site)
+            return [] if tool_calls.nil?
 
-            new(
-              text: text,
-              thinking: thinking,
-              tool_calls: tool_calls,
-              usage: usage,
-              stop_reason: stop_reason,
-              model: model,
-              routing: routing,
-              metadata: metadata
-            )
+            Strict.expect_type!(tool_calls, [::Array], site, :tool_calls)
+            tool_calls.map { |tc| tc.is_a?(ToolCall) ? tc : ToolCall.from_hash(tc) }
           end
 
-          # Build from keyword args (primary constructor).
-          def self.build(
-            text: '', thinking: nil, tool_calls: nil, usage: nil,
-            stop_reason: nil, model: nil, routing: nil, metadata: nil
-          )
-            stop_reason_sym = stop_reason&.to_sym
-            unless stop_reason_sym.nil? || STOP_REASONS.include?(stop_reason_sym)
-              raise ArgumentError,
-                    "Invalid stop_reason: #{stop_reason_sym.inspect}. Must be one of: #{STOP_REASONS.join(', ')}"
-            end
+          def self.normalize_usage!(usage, site)
+            return nil if usage.nil?
+            return usage if usage.is_a?(Usage)
 
-            new(
-              text: text.to_s,
-              thinking: thinking,
-              tool_calls: tool_calls || [],
-              usage: usage,
-              stop_reason: stop_reason_sym,
-              model: model,
-              routing: routing || {},
-              metadata: metadata || {}
-            )
+            Strict.expect_type!(usage, [::Hash], site, :usage)
+            Usage.from_hash(usage)
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
           def to_h
-            {
-              text: text,
-              thinking: thinking&.to_h,
-              tool_calls: tool_calls&.map { |tc| tc.is_a?(ToolCall) ? tc.to_h : tc },
-              usage: usage&.to_h,
-              stop_reason: stop_reason,
-              model: model,
-              routing: routing,
-              metadata: metadata
-            }.compact.reject do |k, v|
-              %i[tool_calls routing
-                 metadata].include?(k) && v.is_a?(Enumerable) && v.empty?
-            end
+            super.compact
           end
 
           # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
@@ -122,12 +93,25 @@ module Legion
           def error?
             stop_reason == :error
           end
+
+          # H1: the single strict constructor — .new runs the same member
+          # contract as the factories; the factories fill their defaults and
+          # delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:thinking] = normalize_thinking!(values[:thinking], site)
+            values[:tool_calls] = normalize_tool_calls!(values[:tool_calls], site)
+            values[:usage] = normalize_usage!(values[:usage], site)
+            values[:stop_reason] = normalize_stop_reason!(values[:stop_reason], site)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
 
         Response::STOP_REASONS = %i[end_turn tool_use max_tokens stop_sequence content_filter error].freeze
-        # rubocop:enable Lint/ConstantDefinitionInBlock
+        Response::BUILD_SITE = 'Canonical::Response.build'
+        Response::FROM_HASH_SITE = 'Canonical::Response.from_hash'
+        Response::NEW_SITE = 'Canonical::Response.new'
       end
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# -- module doc is in canonical.rb entry point
+module Legion
+  module Extensions
+    module Llm
+      # -- required for Data.define block scope
+      module Canonical
+        # Shared strict-factory guards (04 L1/L3/L5/L6) — one implementation for
+        # every type. Nil or wrong-class input raises ArgumentError naming the
+        # site, member, and offending class. No factory returns nil; unknown
+        # keys fold into the metadata member (no drops, no raises).
+        #
+        # H1: every type installs a validated `.new` (a single strict
+        # constructor). `.new`, `.build`, and `.from_hash` all run the same
+        # member contract — a `.new`-minted object cannot carry poison past
+        # the class-membership boundaries (enforce_canonical_messages!,
+        # fleet W4 rehydration, the conformance kit).
+        module Strict
+          module_function
+
+          # H1: install the strict `.new` on a Data type. The C-level
+          # constructor is preserved as the PRIVATE `data_define_new` (used
+          # only by the strict `.new` itself); the public `.new` maps the
+          # call shape (member_values!), runs the type's member contract
+          # (validate, a ->(values, site) block returning the normalized
+          # values), and delegates. Every construction path — .new, .build,
+          # .from_hash — funnels through the same contract.
+          def install_strict_new!(type_class, &validate)
+            singleton = type_class.singleton_class
+            singleton.alias_method(:data_define_new, :new)
+            singleton.send(:private, :data_define_new)
+
+            singleton.define_method(:new) do |*args, **kwargs|
+              values = Strict.member_values!(self, self::NEW_SITE, args, kwargs)
+              values = validate.call(values, self::NEW_SITE)
+              data_define_new(**values)
+            end
+          end
+
+          # Map raw `.new` arguments (positional or keyword form) onto a
+          # member => value Hash. Wrong call shapes raise a typed
+          # ArgumentError naming the site: mixing both forms, a positional
+          # count mismatch, or an unknown member. Members absent from the
+          # call map to nil and follow each member's own contract.
+          def member_values!(type_class, site, args, kwargs)
+            members = type_class.members
+            raise ArgumentError, "#{site}: pass either positional or keyword members, not both" if args.any? && kwargs.any?
+
+            if args.any?
+              raise ArgumentError, "#{site}: expected #{members.size} positional members, got #{args.size}" unless args.size == members.size
+
+              return members.zip(args).to_h
+            end
+
+            unknown = kwargs.keys - members.map(&:to_sym)
+            raise ArgumentError, "#{site}: unknown member(s) #{unknown.sort.join(', ')}" unless unknown.empty?
+
+            members.to_h { |member| [member, kwargs[member]] }
+          end
+
+          def require_hash!(source, site)
+            return source if source.is_a?(::Hash)
+
+            raise ArgumentError, "#{site}: expected Hash, got #{source.class}"
+          end
+
+          def symbolize_keys(hash)
+            hash.transform_keys { |key| key.respond_to?(:to_sym) ? key.to_sym : key }
+          end
+
+          # 04 L5: unknown keys fold into the metadata member.
+          def fold_unknowns!(type_class, site, hash)
+            metadata = metadata!(hash.delete(:metadata), site)
+            known = type_class.members.map(&:to_sym)
+            (hash.keys - known).each { |key| metadata[key] = hash.delete(key) }
+            metadata
+          end
+
+          def metadata!(value, site, member: :metadata)
+            return {} if value.nil?
+
+            raise ArgumentError, "#{site}: #{member} expected Hash, got #{value.class}" unless value.is_a?(::Hash)
+
+            value
+          end
+
+          def enum!(value, allowed, site, member)
+            return value if value.nil? || allowed.include?(value)
+
+            raise ArgumentError,
+                  "#{site}: Invalid #{member}: #{value.inspect}. Must be one of: #{allowed.join(', ')}"
+          end
+
+          def expect_type!(value, allowed, site, member)
+            return value if value.nil? || allowed.any? { |klass| value.is_a?(klass) }
+
+            raise ArgumentError,
+                  "#{site}: #{member} expected #{allowed.map(&:name).join(' | ')}, got #{value.class}"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,27 +3,37 @@
 # -- from_hash normalization is intentional
 module Legion
   module Extensions
+    # -- module doc is in canonical.rb entry point
     module Llm
-      # rubocop:disable Style/Documentation -- module doc is in canonical.rb entry point
+      # -- required for Data.define block scope
       module Canonical
         # Canonical thinking/reasoning block.
         # Ports field vocabulary from Legion::LLM::Types and lex-llm Thinking.
-        Thinking = ::Data.define(:content, :signature) do
+        # Empty-string values normalize to nil (absence, not data — 04 §8).
+        Thinking = ::Data.define(:content, :signature, :metadata) do
+          # Build from keyword args (primary constructor).
+          def self.build(content: nil, signature: nil, metadata: {})
+            new(
+              content: absence!(content, self::BUILD_SITE, :content),
+              signature: absence!(signature, self::BUILD_SITE, :signature),
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE)
+            )
+          end
+
           # Build from a Hash (raw provider response or deserialized wire payload).
           def self.from_hash(source)
-            return nil if source.nil?
-
-            h = source.transform_keys(&:to_sym)
-
-            # Treat empty strings as nil
-            content = h[:content]
-            content = nil if content.is_a?(String) && content.empty?
-            signature = h[:signature]
-            signature = nil if signature.is_a?(String) && signature.empty?
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            build(content: hash[:content], signature: hash[:signature], metadata:)
+          end
 
-            return nil if content.nil? && signature.nil?
+          # Empty-string is absence, not data (04 §8).
+          def self.absence!(value, site, member)
+            return nil if value.nil?
 
-            new(content: content, signature: signature)
+            Strict.expect_type!(value, [::String], site, member)
+            value.empty? ? nil : value
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -44,82 +54,24 @@ module Legion
           def empty?
             content.nil? && signature.nil?
           end
-        end
-
-        # Normalized config for thinking across providers.
-        # Mirrors lex-llm Thinking::Config.
-        class ThinkingConfig
-          INCLUDES = Thinking
-
-          # 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 below.
-          EFFORT_BUDGET = { 'low' => 1024, 'medium' => 8192, 'high' => 16_384 }.freeze
-
-          attr_reader :effort, :budget
-
-          def initialize(effort: nil, budget: nil)
-            @effort = effort.is_a?(Symbol) ? effort.to_s : effort
-            @budget = budget
-          end
 
-          # Build from keyword args.
-          def self.build(effort: nil, budget: nil)
-            new(effort: effort, budget: budget)
-          end
-
-          # Build from a Hash.
-          def self.from_hash(source)
-            return nil if source.nil? || source.empty?
-
-            h = source.transform_keys(&:to_sym)
-            build(effort: h[:effort], budget: h[:budget])
-          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
-            { effort: effort, budget: budget }.compact
-          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.
-          def resolved_budget
-            return budget unless budget.nil?
-            return nil if effort.nil?
-
-            EFFORT_BUDGET[effort.to_s.downcase] || EFFORT_BUDGET['medium']
-          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?
-
-            b = budget.to_i
-            if b < EFFORT_BUDGET['medium'] then 'low'
-            elsif b < EFFORT_BUDGET['high'] then 'medium'
-            else 'high'
-            end
+          # H1: the single strict constructor — .new runs the same member
+          # contract as the factories; the factories fill their defaults and
+          # delegate here.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:content] = absence!(values[:content], site, :content)
+            values[:signature] = absence!(values[:signature], site, :signature)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
           end
         end
 
-        # Alias for convenience: Canonical::Thinking::Config
-        Thinking.const_set(:Config, ThinkingConfig)
+        Thinking::BUILD_SITE = 'Canonical::Thinking.build'
+        Thinking::FROM_HASH_SITE = 'Canonical::Thinking.from_hash'
+        Thinking::NEW_SITE = 'Canonical::Thinking.new'
       end
-      # rubocop:enable Style/Documentation
     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