lex-llm 0.4.16 → 0.5.0

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ParameterLists -- factory methods have many params
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        # Canonical streaming chunk with full lifecycle support.
+        # Per R4: block_index/item_id/signature lifecycle, multi-tool-call deltas.
+        # Per G20d: strict on produce, ignore-unknown on consume.
+        Chunk = ::Data.define(
+          :request_id, :conversation_id, :exchange_id,
+          :index, :type, :block_index,
+          :item_id, :delta, :tool_call, :signature,
+          :usage, :stop_reason, :metadata, :timestamp
+        ) do
+          # Build a text delta chunk.
+          def self.text_delta(delta:, request_id:, conversation_id: nil, exchange_id: nil,
+                              index: 0, block_index: nil, item_id: nil)
+            new(
+              type: :text_delta, delta: delta, index: index,
+              request_id: request_id, conversation_id: conversation_id,
+              exchange_id: exchange_id, block_index: block_index,
+              item_id: item_id, tool_call: nil, signature: nil,
+              usage: nil, stop_reason: nil, metadata: {},
+              timestamp: ::Time.now
+            )
+          end
+
+          # Build a thinking delta chunk.
+          def self.thinking_delta(delta:, request_id:, conversation_id: nil, exchange_id: nil,
+                                  index: 0, block_index: nil, item_id: nil, signature: nil)
+            new(
+              type: :thinking_delta, delta: delta, index: index,
+              request_id: request_id, conversation_id: conversation_id,
+              exchange_id: exchange_id, block_index: block_index,
+              item_id: item_id, tool_call: nil, signature: signature,
+              usage: nil, stop_reason: nil, metadata: {},
+              timestamp: ::Time.now
+            )
+          end
+
+          # Build a tool_call_delta chunk (supports multiple in-flight tool calls via tool_call.id).
+          def self.tool_call_delta(tool_call:, request_id:, conversation_id: nil, exchange_id: nil,
+                                   index: 0, block_index: nil, item_id: nil)
+            new(
+              type: :tool_call_delta, index: index,
+              request_id: request_id, conversation_id: conversation_id,
+              exchange_id: exchange_id, block_index: block_index,
+              item_id: item_id, delta: nil, tool_call: tool_call, signature: nil,
+              usage: nil, stop_reason: nil, metadata: {},
+              timestamp: ::Time.now
+            )
+          end
+
+          # Build a usage chunk.
+          def self.usage_chunk(usage:, request_id:, conversation_id: nil, exchange_id: nil)
+            new(
+              type: :usage, request_id: request_id,
+              conversation_id: conversation_id, exchange_id: exchange_id,
+              index: nil, block_index: nil, item_id: nil,
+              delta: nil, tool_call: nil, signature: nil,
+              usage: usage, stop_reason: nil, metadata: {},
+              timestamp: ::Time.now
+            )
+          end
+
+          # Build a done chunk.
+          def self.done(request_id:, usage: nil, stop_reason: nil, conversation_id: nil, exchange_id: nil)
+            new(
+              type: :done, request_id: request_id,
+              conversation_id: conversation_id, exchange_id: exchange_id,
+              index: nil, block_index: nil, item_id: nil,
+              delta: nil, tool_call: nil, signature: nil,
+              usage: usage, stop_reason: stop_reason, metadata: {},
+              timestamp: ::Time.now
+            )
+          end
+
+          # Build an error chunk.
+          def self.error_chunk(error:, request_id:, conversation_id: nil, exchange_id: nil, metadata: nil)
+            new(
+              type: :error, request_id: request_id,
+              conversation_id: conversation_id, exchange_id: exchange_id,
+              index: nil, block_index: nil, item_id: nil,
+              delta: nil, tool_call: nil, signature: nil,
+              usage: nil, stop_reason: :error,
+              metadata: (metadata || {}).merge(error: error),
+              timestamp: ::Time.now
+            )
+          end
+
+          # Build from a Hash (raw provider response or deserialized wire payload).
+          # Per G20d: ignore-unknown on consume — unknown chunk types are passed through.
+          def self.from_hash(source)
+            return nil if source.nil?
+
+            h = source.transform_keys(&:to_sym)
+
+            # Normalize type
+            type_raw = h.delete(:type)
+            type_sym = type_raw&.to_sym if type_raw
+
+            # Normalize nested objects
+            tool_call_raw = h.delete(:tool_call)
+            h[:tool_call] = if tool_call_raw.is_a?(ToolCall)
+                              tool_call_raw
+                            elsif tool_call_raw.is_a?(Hash)
+                              ToolCall.from_hash(tool_call_raw)
+                            end
+
+            usage_raw = h.delete(:usage)
+            h[:usage] = if usage_raw.is_a?(Usage)
+                          usage_raw
+                        elsif usage_raw.is_a?(Hash)
+                          Usage.from_hash(usage_raw)
+                        end
+
+            # Normalize stop_reason
+            stop_reason_raw = h.delete(:stop_reason) || h.delete(:finish_reason)
+            h[:stop_reason] = stop_reason_raw&.to_sym if stop_reason_raw
+
+            # Ensure metadata is a Hash
+            h[:metadata] = h[:metadata] || {}
+
+            # Provide defaults for missing fields
+            new(
+              request_id: h[:request_id],
+              conversation_id: h[:conversation_id],
+              exchange_id: h[:exchange_id],
+              index: h[:index],
+              type: type_sym,
+              block_index: h[:block_index],
+              item_id: h[:item_id],
+              delta: h[:delta],
+              tool_call: h[:tool_call],
+              signature: h[:signature],
+              usage: h[:usage],
+              stop_reason: h[:stop_reason],
+              metadata: h[:metadata],
+              timestamp: h[:timestamp] || ::Time.now
+            )
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            {
+              request_id: request_id,
+              conversation_id: conversation_id,
+              exchange_id: exchange_id,
+              index: index,
+              type: type,
+              block_index: block_index,
+              item_id: item_id,
+              delta: delta,
+              tool_call: tool_call&.to_h,
+              signature: signature,
+              usage: usage&.to_h,
+              stop_reason: stop_reason,
+              metadata: metadata,
+              timestamp: timestamp
+            }.compact
+          end
+
+          # Type predicate helpers.
+          def text_delta? = type == :text_delta
+          def thinking_delta? = type == :thinking_delta
+          def tool_call_delta? = type == :tool_call_delta
+          def usage? = type == :usage
+          def done? = type == :done
+          def error? = type == :error
+
+          # Whether this chunk carries content (text or thinking).
+          def content?
+            %i[text_delta thinking_delta].include?(type)
+          end
+        end
+
+        Chunk::CHUNK_TYPES = %i[text_delta thinking_delta tool_call_delta usage done error].freeze
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ParameterLists

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Canonical
+        # Typed content block with media_type support per G20a.
+        # Ports field vocabulary from Legion::LLM::Types::ContentBlock.
+        ContentBlock = ::Data.define(
+          :type, :text, :data, :source_type, :media_type,
+          :detail, :name, :file_id,
+          :id, :input, :tool_use_id, :is_error,
+          :source, :start_index, :end_index,
+          :code, :message, :cache_control
+        ) do
+          # Build a text content block.
+          def self.text(content, cache_control: nil)
+            new(
+              type: :text, text: content, data: nil, source_type: nil, media_type: nil,
+              detail: nil, name: nil, file_id: nil, id: nil, input: nil,
+              tool_use_id: nil, is_error: nil, source: nil, start_index: nil,
+              end_index: nil, code: nil, message: nil, cache_control: cache_control
+            )
+          end
+
+          # Build a thinking content block.
+          def self.thinking(content)
+            new(
+              type: :thinking, text: content, data: nil, source_type: nil, media_type: nil,
+              detail: nil, name: nil, file_id: nil, id: nil, input: nil,
+              tool_use_id: nil, is_error: nil, source: nil, start_index: nil,
+              end_index: nil, code: nil, message: nil, cache_control: nil
+            )
+          end
+
+          # Build a tool_use content block.
+          def self.tool_use(id:, name:, input:)
+            new(
+              type: :tool_use, text: nil, data: nil, source_type: nil, media_type: nil,
+              detail: nil, name: name, file_id: nil, id: id, input: input,
+              tool_use_id: nil, is_error: nil, source: nil, start_index: nil,
+              end_index: nil, code: nil, message: nil, cache_control: nil
+            )
+          end
+
+          # Build a tool_result content block.
+          def self.tool_result(tool_use_id:, content:, is_error: false)
+            new(
+              type: :tool_result, text: content, data: nil, source_type: nil, media_type: nil,
+              detail: nil, name: nil, file_id: nil, id: nil, input: nil,
+              tool_use_id: tool_use_id, is_error: is_error, source: nil, start_index: nil,
+              end_index: nil, code: nil, message: nil, cache_control: nil
+            )
+          end
+
+          # Build an image content block with media_type (G20a).
+          def self.image(data:, media_type:, source_type: :base64, detail: nil)
+            new(
+              type: :image, text: nil, data: data, source_type: source_type, media_type: media_type,
+              detail: detail, name: nil, file_id: nil, id: nil, input: nil,
+              tool_use_id: nil, is_error: nil, source: nil, start_index: nil,
+              end_index: nil, code: nil, message: nil, cache_control: nil
+            )
+          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)
+            type_raw = h.delete(:type)
+            h[:type] = type_raw&.to_sym if type_raw
+
+            new(
+              type: h[:type],
+              text: h[:text],
+              data: h[:data],
+              source_type: h[:source_type],
+              media_type: h[:media_type],
+              detail: h[:detail],
+              name: h[:name],
+              file_id: h[:file_id],
+              id: h[:id],
+              input: h[:input],
+              tool_use_id: h[:tool_use_id],
+              is_error: h[:is_error],
+              source: h[:source],
+              start_index: h[:start_index],
+              end_index: h[:end_index],
+              code: h[:code],
+              message: h[:message],
+              cache_control: h[:cache_control]
+            )
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            super.compact
+          end
+
+          # Whether this block carries textual content.
+          def text?
+            type == :text
+          end
+
+          # Whether this block carries thinking/reasoning content.
+          def thinking?
+            type == :thinking
+          end
+
+          # Whether this block represents a tool use request.
+          def tool_use?
+            type == :tool_use
+          end
+
+          # Whether this block represents a tool result.
+          def tool_result?
+            type == :tool_result
+          end
+        end
+
+        ContentBlock::CONTENT_BLOCK_TYPES = %i[text thinking tool_use tool_result image audio video].freeze
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# 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 message in a conversation.
+        # Ports field vocabulary from Legion::LLM::Types::Message and lex-llm Message.
+        Message = ::Data.define(
+          :id, :parent_id, :role, :content, :tool_calls, :tool_call_id,
+          :name, :status, :version, :timestamp, :seq,
+          :provider, :model, :input_tokens, :output_tokens,
+          :conversation_id, :task_id
+        ) do
+          ROLES = %i[system user assistant tool].freeze
+
+          # Build from keyword args (primary constructor).
+          def self.build(
+            id: nil, parent_id: nil, role: :user, content: nil, tool_calls: nil,
+            tool_call_id: nil, name: nil, status: :created, version: 1,
+            timestamp: nil, seq: nil, provider: nil, model: nil,
+            input_tokens: nil, output_tokens: nil, conversation_id: nil, task_id: nil
+          )
+            role_sym = role.is_a?(String) ? role.to_sym : role
+            unless ROLES.include?(role_sym)
+              raise ArgumentError,
+                    "Invalid role: #{role_sym}. Must be one of: #{ROLES.join(', ')}"
+            end
+
+            new(
+              id: id || "msg_#{SecureRandom.hex(12)}",
+              parent_id: parent_id,
+              role: role_sym,
+              content: content,
+              tool_calls: tool_calls,
+              tool_call_id: tool_call_id,
+              name: name,
+              status: status,
+              version: version,
+              timestamp: timestamp || ::Time.now,
+              seq: seq,
+              provider: provider,
+              model: model,
+              input_tokens: input_tokens,
+              output_tokens: output_tokens,
+              conversation_id: conversation_id,
+              task_id: task_id
+            )
+          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 role to symbol
+            role_raw = h[:role]
+            h[:role] = role_raw&.to_sym if role_raw
+
+            # Parse content blocks if they're an array of hashes
+            content = h[:content]
+            if content.is_a?(Array)
+              h[:content] = content.map do |block|
+                block.is_a?(ContentBlock) ? block : ContentBlock.from_hash(block)
+              end
+            elsif content.is_a?(Hash)
+              h[:content] = ContentBlock.from_hash(content)
+            end
+
+            # Parse tool calls if they're an array of hashes
+            tool_calls = h[:tool_calls]
+            if tool_calls.is_a?(Array)
+              h[:tool_calls] = tool_calls.map do |tc|
+                tc.is_a?(ToolCall) ? tc : ToolCall.from_hash(tc)
+              end
+            end
+
+            build(**h)
+          end
+
+          # Wrap input: pass through if already a Message, parse if Hash.
+          def self.wrap(input)
+            return input if input.is_a?(Message)
+            return from_hash(input) if input.is_a?(Hash)
+
+            nil
+          end
+
+          # Extract plain text from content (String or ContentBlock array).
+          def text
+            case content
+            when String then content
+            when Array
+              content.filter_map do |block|
+                block.is_a?(ContentBlock) && block.text? ? block.text : nil
+              end.join
+            when ContentBlock then content.text if content.text?
+            else
+              content.to_s
+            end
+          end
+
+          # Serialize to a Hash for AMQP/fleet/wire transport.
+          def to_h
+            super.compact
+          end
+
+          # Minimal provider-facing hash (role + text content).
+          def to_provider_hash
+            { role: role.to_s, content: text }.compact
+          end
+        end
+
+        Message::ROLES = %i[system user assistant tool].freeze
+        # rubocop:enable Lint/ConstantDefinitionInBlock
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ParameterLists

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