lex-llm 0.4.18 → 0.5.1

data/lib/legion/extensions/llm/canonical/params.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 sampling and limit parameters for a request.
+        # Per G18: all standard/useful params are first-class, mapped per provider by translators.
+        Params = ::Data.define(
+          :max_tokens, :max_thinking_tokens, :temperature, :top_p, :top_k,
+          :stop_sequences, :seed, :frequency_penalty, :presence_penalty,
+          :response_format
+        ) do
+          PARAMS_KNOWN_KEYS = %i[max_tokens max_thinking_tokens temperature top_p top_k
+                                 stop_sequences seed frequency_penalty presence_penalty
+                                 response_format].freeze
+
+          # Build from a Hash (raw client request or deserialized wire payload).
+          # Accepts both canonical key names and common provider spellings.
+          def self.from_hash(source)
+            return nil if source.nil? || source.empty?
+
+            h = source.transform_keys(&:to_sym)
+
+            # Normalize common provider key variations
+            h[:max_tokens] ||= h.delete(:max_output_tokens) || h.delete(:num_predict)
+            h[:max_thinking_tokens] ||= h.delete(:budget_tokens) || h.delete(:thinking_budget)
+            h[:stop_sequences] ||= h.delete(:stop)
+
+            # Filter to known keys only
+            filtered = h.slice(*PARAMS_KNOWN_KEYS)
+
+            # Return nil if all known values are nil
+            return nil if filtered.all? { |_, v| v.nil? }
+
+            new(
+              max_tokens: filtered[:max_tokens],
+              max_thinking_tokens: filtered[:max_thinking_tokens],
+              temperature: filtered[:temperature],
+              top_p: filtered[:top_p],
+              top_k: filtered[:top_k],
+              stop_sequences: filtered[:stop_sequences],
+              seed: filtered[:seed],
+              frequency_penalty: filtered[:frequency_penalty],
+              presence_penalty: filtered[:presence_penalty],
+              response_format: filtered[:response_format]
+            )
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            super.compact
+          end
+        end
+        # rubocop:enable Lint/ConstantDefinitionInBlock
+      end
+    end
+  end
+end

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,98 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        TOOL_NAME_MAX_LENGTH = 64
+        OBJECT_SCHEMA_KEYWORDS    = %i[properties required additionalProperties].freeze
+        COMPOSITE_SCHEMA_KEYWORDS = %i[oneOf anyOf allOf enum $ref $defs definitions].freeze
+
+        # Canonical tool definition.
+        # Ports field vocabulary from Legion::LLM::Types::ToolDefinition.
+        ToolDefinition = ::Data.define(:name, :description, :parameters, :source) do
+          def self.normalize_parameters(parameters)
+            empty = { type: 'object', properties: {} }
+            return empty if parameters.nil?
+
+            schema = if parameters.respond_to?(:transform_keys)
+                       parameters.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
+                     end
+            return empty if schema.nil? || schema.empty?
+            return schema if schema.key?(:type)
+            return schema.merge(type: 'object') if OBJECT_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
+            return schema if COMPOSITE_SCHEMA_KEYWORDS.any? { |k| schema.key?(k) }
+
+            { type: 'object', properties: schema }
+          end
+
+          # Build from keyword args (primary constructor).
+          def self.build(name:, description: '', parameters: nil, source: nil)
+            new(
+              sanitize_tool_name(name),
+              description.to_s,
+              normalize_parameters(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
+
+          def params_schema
+            parameters
+          end
+
+          def input_schema
+            parameters
+          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/tool_schema.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        # Extracts and normalizes tool schemas from heterogeneous sources.
+        module ToolSchema
+          EMPTY_OBJECT = { type: 'object', properties: {} }.freeze
+
+          module_function
+
+          def extract(tool)
+            raw = raw_schema(tool)
+            ToolDefinition.normalize_parameters(raw)
+          end
+
+          def raw_schema(tool)
+            return nil if tool.nil?
+            return tool.params_schema if tool.respond_to?(:params_schema) && tool.params_schema
+            return tool.parameters if tool.respond_to?(:parameters) && tool.parameters
+
+            return unless tool.respond_to?(:[])
+
+            tool[:parameters] || tool['parameters'] || tool[:input_schema] || tool['input_schema'] ||
+              tool[:params_schema] || tool['params_schema']
+          end
+
+          def tool_name(tool)
+            return tool.name if tool.respond_to?(:name) && !tool.is_a?(Hash)
+            return tool[:name] || tool['name'] if tool.respond_to?(:[])
+
+            'unknown'
+          end
+
+          def tool_description(tool)
+            return tool.description if tool.respond_to?(:description) && !tool.is_a?(Hash)
+            return (tool[:description] || tool['description'] || '').to_s if tool.respond_to?(:[])
+
+            ''
+          end
+        end
+      end
+    end
+  end
+end