lex-llm 0.4.18 → 0.5.0

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

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        # Canonical request shape — the single contract between client translators
+        # and the inference executor. Per R3 and G18.
+        Request = ::Data.define(
+          :id, :messages, :system, :tools, :tool_choice,
+          :params, :thinking, :stream,
+          :conversation_id, :caller, :routing, :metadata
+        ) do
+          # Build from keyword args (primary constructor).
+          def self.build(
+            id: nil, messages: nil, system: nil, tools: nil, tool_choice: nil,
+            params: nil, thinking: nil, stream: false,
+            conversation_id: nil, caller: nil, routing: nil, metadata: nil
+          )
+            # Normalize messages to Canonical::Message array
+            msg_array = Array(messages).filter_map do |msg|
+              msg.is_a?(Message) ? msg : Message.from_hash(msg)
+            end
+
+            # Normalize tools to Hash<name, ToolDefinition>
+            tool_hash = normalize_tools(tools)
+
+            # Normalize params
+            params_obj = case params
+                         when Params then params
+                         when Hash then Params.from_hash(params)
+                         end
+
+            # Normalize thinking config
+            thinking_obj = case thinking
+                           when Thinking::Config then thinking
+                           when Hash then Thinking::Config.new(**thinking.transform_keys(&:to_sym))
+                           end
+
+            new(
+              id: id || "req_#{SecureRandom.hex(12)}",
+              messages: msg_array,
+              system: system,
+              tools: tool_hash,
+              tool_choice: tool_choice.is_a?(String) ? tool_choice.to_sym : tool_choice,
+              params: params_obj,
+              thinking: thinking_obj,
+              stream: stream,
+              conversation_id: conversation_id,
+              caller: caller,
+              routing: routing || {},
+              metadata: metadata || {}
+            )
+          end
+
+          # Build from a Hash (raw client request or deserialized wire payload).
+          def self.from_hash(source)
+            return nil if source.nil?
+
+            h = source.transform_keys(&:to_sym)
+
+            # Extract metadata from unknown keys
+            metadata = h[:metadata] || {}
+            known_keys = %i[id messages system tools tool_choice params thinking
+                            stream conversation_id caller routing metadata]
+            (h.keys - known_keys).each do |key|
+              metadata[key] = h.delete(key)
+            end
+            h[:metadata] = metadata
+
+            build(**h)
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            {
+              id: id,
+              messages: messages&.map { |m| m.is_a?(Message) ? m.to_h : m },
+              system: system,
+              tools: tools&.transform_values { |t| t.is_a?(ToolDefinition) ? t.to_h : t },
+              tool_choice: tool_choice,
+              params: params&.to_h,
+              thinking: thinking&.to_h,
+              stream: stream,
+              conversation_id: conversation_id,
+              caller: caller,
+              routing: routing,
+              metadata: metadata
+            }.compact
+          end
+
+          def self.normalize_tools(tools)
+            return {} if tools.nil? || tools.empty?
+
+            case tools
+            when Hash
+              tools.transform_values do |tool|
+                tool.is_a?(ToolDefinition) ? tool : ToolDefinition.from_hash(tool)
+              end
+            when Array
+              tools.each_with_object({}) do |tool, hash|
+                td = tool.is_a?(ToolDefinition) ? tool : ToolDefinition.from_hash(tool)
+                hash[td.name] = td
+              end
+            else
+              {}
+            end
+          end
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ParameterLists

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+module Legion
+  module Extensions
+    module Llm
+      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.
+        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 a Hash (raw provider response or deserialized wire payload).
+          # Unknown keys go to metadata, never silently dropped.
+          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
+
+            usage_raw = h.delete(:usage)
+            usage = usage_raw.is_a?(Usage) ? usage_raw : Usage.from_hash(usage_raw)
+
+            # 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
+
+            model = h.delete(:model)
+            routing = h.delete(:routing) || {}
+
+            # Remaining keys become metadata
+            existing_metadata = h.delete(:metadata) || {}
+            metadata = existing_metadata.merge(h).compact
+
+            new(
+              text: text,
+              thinking: thinking,
+              tool_calls: tool_calls,
+              usage: usage,
+              stop_reason: stop_reason,
+              model: model,
+              routing: routing,
+              metadata: metadata
+            )
+          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
+
+            new(
+              text: text.to_s,
+              thinking: thinking,
+              tool_calls: tool_calls || [],
+              usage: usage,
+              stop_reason: stop_reason_sym,
+              model: model,
+              routing: routing || {},
+              metadata: metadata || {}
+            )
+          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
+          end
+
+          # Whether the response includes tool calls.
+          def tool_call?
+            !tool_calls.nil? && !tool_calls.empty?
+          end
+
+          # Whether the response ended due to an error.
+          def error?
+            stop_reason == :error
+          end
+        end
+
+        Response::STOP_REASONS = %i[end_turn tool_use max_tokens stop_sequence content_filter error].freeze
+        # rubocop:enable Lint/ConstantDefinitionInBlock
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ParameterLists

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# -- from_hash normalization is intentional
+module Legion
+  module Extensions
+    module Llm
+      # rubocop:disable Style/Documentation -- module doc is in canonical.rb entry point
+      module Canonical
+        # Canonical thinking/reasoning block.
+        # Ports field vocabulary from Legion::LLM::Types and lex-llm Thinking.
+        Thinking = ::Data.define(:content, :signature) do
+          # 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?
+
+            return nil if content.nil? && signature.nil?
+
+            new(content: content, signature: signature)
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            super.compact
+          end
+
+          # Whether this thinking block has any content.
+          def empty?
+            content.nil? && signature.nil?
+          end
+        end
+
+        # Normalized config for thinking across providers.
+        # Mirrors lex-llm Thinking::Config.
+        class ThinkingConfig
+          INCLUDES = Thinking
+          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.
+          def to_h
+            { effort: effort, budget: budget }.compact
+          end
+
+          # Whether thinking is configured.
+          def enabled?
+            !effort.nil? || !budget.nil?
+          end
+        end
+
+        # Alias for convenience: Canonical::Thinking::Config
+        Thinking.const_set(:Config, ThinkingConfig)
+      end
+      # rubocop:enable Style/Documentation
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
+        # Canonical tool call with source enum and compliance fields.
+        # Ports field vocabulary from Legion::LLM::Types::ToolCall.
+        # Source enum per R7: :client | :registry | :special | :extension | :mcp
+        # Compliance fields per R8: data_handling_classification, policy_decision
+        ToolCall = ::Data.define(
+          :id, :exchange_id, :name, :arguments, :source,
+          :status, :duration_ms, :result, :error,
+          :started_at, :finished_at, :category,
+          :data_handling_classification, :policy_decision
+        ) do
+          SOURCE_VALUES = %i[client registry special extension mcp].freeze
+          STATUS_VALUES = %i[pending running success error].freeze
+
+          # Build from keyword args (primary constructor).
+          def self.build(
+            name:, id: nil, exchange_id: nil, arguments: nil, source: nil,
+            status: nil, duration_ms: nil, result: nil, error: nil,
+            started_at: nil, finished_at: nil, category: nil,
+            data_handling_classification: nil, policy_decision: nil
+          )
+            new(
+              id: id || "call_#{SecureRandom.hex(12)}",
+              exchange_id: exchange_id,
+              name: name,
+              arguments: arguments || {},
+              source: source,
+              status: status,
+              duration_ms: duration_ms,
+              result: result,
+              error: error,
+              started_at: started_at,
+              finished_at: finished_at,
+              category: category,
+              data_handling_classification: data_handling_classification,
+              policy_decision: policy_decision
+            )
+          end
+
+          # Build from a Hash (raw provider response or deserialized wire payload).
+          def self.from_hash(hash)
+            return nil if hash.nil?
+
+            h = hash.transform_keys(&:to_sym)
+
+            # Normalize source to symbol
+            source_raw = h[:source]
+            h[:source] = source_raw&.to_sym if source_raw.is_a?(String)
+
+            # Normalize status to symbol
+            status_raw = h[:status]
+            h[:status] = status_raw&.to_sym if status_raw.is_a?(String)
+
+            # Parse arguments if they're a JSON string
+            args = h[:arguments]
+            if args.is_a?(String) && !args.empty?
+              begin
+                h[:arguments] = Legion::JSON.load(args)
+              rescue Legion::JSON::ParseError => e
+                Legion::Logging.debug("[lex-llm][canonical][tool_call] arguments not parseable as JSON, leaving as string: #{e.message}")
+              end
+            end
+
+            build(**h)
+          end
+
+          # Return a new ToolCall with execution result attached.
+          def with_result(result:, status:, duration_ms: nil, finished_at: nil)
+            self.class.new(
+              id: id,
+              exchange_id: exchange_id,
+              name: name,
+              arguments: arguments,
+              source: source,
+              status: status,
+              duration_ms: duration_ms,
+              result: result,
+              error: status == :error ? result : error,
+              started_at: started_at,
+              finished_at: finished_at || ::Time.now,
+              category: category,
+              data_handling_classification: data_handling_classification,
+              policy_decision: policy_decision
+            )
+          end
+
+          def success?
+            status == :success
+          end
+
+          def error?
+            status == :error
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            super.compact
+          end
+
+          # Subset for audit/ledger emission.
+          def to_audit_hash
+            {
+              id: id,
+              name: name,
+              arguments: arguments,
+              status: status,
+              duration_ms: duration_ms,
+              error: error,
+              exchange_id: exchange_id,
+              source: source,
+              category: category,
+              data_handling_classification: data_handling_classification,
+              policy_decision: policy_decision
+            }.compact
+          end
+        end
+
+        ToolCall::SOURCE_VALUES = %i[client registry special extension mcp].freeze
+        ToolCall::STATUS_VALUES = %i[pending running success error].freeze
+        # rubocop:enable Lint/ConstantDefinitionInBlock
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ParameterLists

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        TOOL_NAME_MAX_LENGTH = 64
+
+        # Canonical tool definition.
+        # Ports field vocabulary from Legion::LLM::Types::ToolDefinition.
+        ToolDefinition = ::Data.define(:name, :description, :parameters, :source) do
+          # Build from keyword args (primary constructor).
+          def self.build(name:, description: '', parameters: nil, source: nil)
+            new(
+              sanitize_tool_name(name),
+              description.to_s,
+              parameters || {},
+              source || { type: :builtin }
+            )
+          end
+
+          # Build from a Hash (raw provider response or deserialized wire payload).
+          def self.from_hash(hash, source: nil)
+            return nil if hash.nil?
+
+            normalized = hash.respond_to?(:transform_keys) ? hash.transform_keys(&:to_sym) : {}
+            build(
+              name: normalized[:name],
+              description: normalized[:description],
+              parameters: normalized[:parameters] || normalized[:input_schema],
+              source: source || normalized[:source]
+            )
+          end
+
+          # Build from a registry entry (extension/registry tool metadata).
+          def self.from_registry_entry(entry)
+            source = {
+              type: entry[:tool_class] ? :registry : :extension,
+              tool_class: entry[:tool_class],
+              extension: entry[:extension],
+              runner: entry[:runner],
+              function: entry[:function]
+            }.compact
+
+            build(
+              name: entry[:name],
+              description: entry[:description],
+              parameters: entry[:input_schema] || entry[:parameters],
+              source: source.compact
+            )
+          end
+
+          # Sanitize a tool name to be safe for all wire formats.
+          def self.sanitize_tool_name(raw)
+            name = raw.to_s.tr('.', '_')
+            name = name.gsub(/[^a-zA-Z0-9_-]/, '')
+            name = name[0, TOOL_NAME_MAX_LENGTH] if name.length > TOOL_NAME_MAX_LENGTH
+            name.empty? ? 'tool' : name
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            {
+              name: name,
+              description: description,
+              parameters: parameters
+            }.compact.reject { |k, v| k == :description && v == '' }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# -- from_hash normalization is intentional
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
+        # Canonical usage/metering data for a response.
+        # Ports field vocabulary from lex-llm Tokens and legion-llm Types.
+        # Includes non-token units extension point per G20b.
+        Usage = ::Data.define(
+          :input_tokens, :output_tokens, :cache_read_tokens, :cache_write_tokens,
+          :thinking_tokens, :units
+        ) do
+          USAGE_KNOWN_KEYS = %i[input_tokens output_tokens cache_read_tokens cache_write_tokens
+                                thinking_tokens units].freeze
+
+          # Build from a Hash (raw provider response or deserialized wire payload).
+          # Accepts both canonical key names and legacy provider spellings.
+          def self.from_hash(source)
+            return nil if source.nil? || source.empty?
+
+            h = source.transform_keys(&:to_sym)
+
+            # Normalize legacy key names
+            h[:input_tokens] ||= h.delete(:input) || h.delete(:prompt_tokens)
+            h[:output_tokens] ||= h.delete(:output) || h.delete(:completion_tokens)
+            h[:cache_read_tokens] ||= h.delete(:cached) || h.delete(:cache_read)
+            h[:cache_write_tokens] ||= h.delete(:cache_creation) || h.delete(:cache_write)
+            h[:thinking_tokens] ||= h.delete(:thinking) || h.delete(:reasoning)
+
+            # Extract units (non-token extension point — G20b)
+            units = h.delete(:units) || {}
+
+            new(
+              input_tokens: h[:input_tokens],
+              output_tokens: h[:output_tokens],
+              cache_read_tokens: h[:cache_read_tokens],
+              cache_write_tokens: h[:cache_write_tokens],
+              thinking_tokens: h[:thinking_tokens],
+              units: units
+            )
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            super.compact
+          end
+
+          # Total tokens across all categories.
+          def total_tokens
+            [input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+             thinking_tokens].compact.sum
+          end
+        end
+        # rubocop:enable Lint/ConstantDefinitionInBlock
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'canonical/thinking'
+require_relative 'canonical/usage'
+require_relative 'canonical/params'
+require_relative 'canonical/content_block'
+require_relative 'canonical/tool_definition'
+require_relative 'canonical/tool_call'
+require_relative 'canonical/message'
+require_relative 'canonical/request'
+require_relative 'canonical/response'
+require_relative 'canonical/chunk'
+
+module Legion
+  module Extensions
+    module Llm
+      # Canonical types for the N×N client→provider routing architecture.
+      #
+      # These Data.define structs form the single contract between client translators
+      # and provider translators. Per Amendment A: immutable, strict factories,
+      # enum validation, unknown keys → metadata.
+      #
+      # Contract version: incremented on any breaking change to the canonical shape.
+      # Provider registration refuses gems built against a mismatched version (G7).
+      module Canonical
+        CONTRACT_VERSION = '1.0.0'
+
+        # Available canonical types.
+        TYPES = %i[
+          Thinking Usage Params ContentBlock
+          ToolDefinition ToolCall Message
+          Request Response Chunk
+        ].freeze
+
+        class << self
+          # List all canonical type classes.
+          def types
+            TYPES.map { |name| const_get(name) }
+          end
+
+          # Check if a given constant name is a registered canonical type.
+          def type?(name)
+            TYPES.include?(name.to_sym)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -11,9 +11,7 @@ module Legion
         attr_reader :model, :messages, :tools, :tool_prefs, :params, :headers, :schema
 
         def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil)
-          if assume_model_exists && !provider
-            raise ArgumentError, 'Provider must be specified if assume_model_exists is true'
-          end
+          raise ArgumentError, 'Provider must be specified if assume_model_exists is true' if assume_model_exists && !provider
 
           @context = context
           @config = context&.config || Legion::Extensions::Llm.config
@@ -139,7 +137,7 @@ module Legion
           messages.each(&)
         end
 
-        def complete(&) # rubocop:disable Metrics/PerceivedComplexity
+        def complete(&)
           response = @provider.complete(
             messages,
             tools: @tools,
@@ -234,7 +232,7 @@ module Legion
           end
         end
 
-        def handle_tool_calls(response, &) # rubocop:disable Metrics/PerceivedComplexity
+        def handle_tool_calls(response, &)
           halt_result = nil
 
           response.tool_calls.each_value do |tool_call|

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

@@ -77,9 +77,13 @@ module Legion
 
         def setup_logging(faraday)
           logger = faraday_logger
+          # Enable request body logging when the logger is at DEBUG level,
+          # or when explicitly enabled via fleet request_payload setting.
+          request_payload = Legion::Extensions::Llm.default_settings.dig(:fleet, :request, :logger, :request_payload)
+          bodies_enabled = request_payload == true || debug_logger?(logger)
           faraday.response :logger,
                            logger,
-                           bodies: debug_logger?(logger),
+                           bodies: bodies_enabled,
                            errors: false,
                            headers: false,
                            log_level: :debug do |logger|