lex-llm 0.4.18 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 251e67e07340b260806c156849759a36717aa0edded8d487e4781bc18dd6a796
-  data.tar.gz: 91cc4357b30623f8d05c26781838daaca04cc610bd0e9437f1dd8e3c7333d965
+  metadata.gz: 9ab0a51687719efbd7f048be70ff4ba57b6d81fafddfcaefb2f0d78f5f3721ae
+  data.tar.gz: 49e57ce1c99330d956cc92b6c6a75a283f078f5e0b8fb036ae7aad9579caccd0
 SHA512:
-  metadata.gz: a221259bedc60837bab73ef1e497799d2b7712c3c0e9a74f782ba69e361878fc56d5bb3dc63fc0ffffd731d89ea10233a5e015b86033122550ff571cef667030
-  data.tar.gz: '0709a98c1239c7e053b8d333d19150e4153c4c1ace084520d92221ceb532cb3fdc01cece4734eda9f0ef37f351f36c4a8aa50d78a500b74af7558ad25ac82c86'
+  metadata.gz: 8d8fcea6f732dd4c5dfcd713024796a640941d18c8ef90f3c5b5ca0b3fcbc0094942f2cadabbdd78669ecabce8cd76f893488a92f15ec70c21ebec865fb0a531
+  data.tar.gz: 4a062635e491cb84b60117b1c28520a8fc5bb4d0775609ed1104639e549114c2a373e68461833008a234e33d7ac14a5fe1292cc2f37fe37b0f00818387cc4851

data/.rubocop.yml

@@ -13,12 +13,18 @@ AllCops:
     - lib/generators/**/templates/**/*
   SuggestExtensions: false
 
+Layout/LineLength:
+  Max: 190
 Metrics/ClassLength:
   Enabled: false
 Metrics/AbcSize:
-  Enabled: false
+  Enabled: true
+  Max: 50
+Metrics/PerceivedComplexity:
+  Max: 50
 Metrics/CyclomaticComplexity:
-  Enabled: false
+  Enabled: true
+  Max: 50
 Metrics/MethodLength:
   Enabled: false
 Metrics/ModuleLength:
@@ -40,3 +46,8 @@ RSpec/MultipleExpectations:
   Enabled: false
 RSpec/LeakyLocalVariable:
   Enabled: false
+# Conformance kit specs live under spec/legion/extensions/llm/conformance/
+# but the test classes use Canonical::Conformance:: namespace — path can't match.
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/legion/extensions/llm/conformance/**/*'

data/B1b-conformance-kit.md

@@ -0,0 +1,79 @@
+# B1b — Conformance Kit (lex-llm spec support)
+
+> **Status:** Complete (self-test green: 54 examples, 0 failures)
+> **Date:** 2026-06-10
+> **Repo:** lex-llm (conformance kit only)
+> **Branch:** feat/canonical-types
+> **Design doc:** 2026-06-09-nxn-canonical-routing-design.md Amendment B
+> **Implementation plan:** Phase 2 (conformance kit in lex-llm)
+> **Dependency:** B1a canonical types (coordinator commit e1cbf820)
+> **Self-test green:** `bundle exec rspec spec/legion/extensions/llm/conformance` → 54 examples, 0 failures
+
+---
+
+## What was delivered
+
+### Shared example groups
+
+**provider_translator_examples.rb** (~390 lines)
+`it_behaves_like 'a canonical provider translator'` — 54 scenarios across render_request,
+parse_response, parse_chunk, stop_reason, round-trip.
+
+**client_translator_examples.rb** (~270 lines)
+Mirror group for client translators: `it_behaves_like 'a canonical client translator'` —
+parse_request/format_request round-trip, format_response, format_chunk, format_error.
+
+### Fixture corpus (19 JSON files)
+
+All under `spec/legion/extensions/llm/conformance/fixtures/`:
+- simple_text request/response, system_prompt, params_mapping (all 10 G18 fields),
+  tools_request, tool_use_response, tool_results_continuation_request (enhanced: mixed client + registry tool calls per G4)
+- canonical_thinking_request.json
+- canonical_thinking_response.json (thinking content + signature, thinking_tokens)
+- canonical_empty_response.json
+- canonical_error_response.json
+- canonical_stop_reason_matrix.json (6 canonical enums + 5 provider mappings)
+- canonical_streaming_text_chunks.json
+- canonical_streaming_thinking_chunks.json (thinking + text + signature + done)
+- canonical_streaming_tool_call_chunks.json (multi-chunk tool-call identity per A7)
+- canonical_streaming_error_chunks.json (**new**: mid-stream error per G5/G6)
+- canonical_streaming_accumulated_response.json (**new**: expected assembled response from tool-call chunks)
+- canonical_fleet_round_trip.json (per R6)
+- canonical_metering_audit_events.json (per G15e: schemas + example events)
+
+### Self-test echo translator
+
+Echo translator + spec that passes both provider and client translator groups, proving the shared examples work correctly.
+
+### Infrastructure fixes
+
+1. **lex-llm.gemspec** — spec.files now includes spec/ (was excluded); spec.require_paths adds 'spec' — enables cross-gem conformance kit loading per the amended Phase 2 spec.
+2. .rubocop.yml — excluded conformance directory from RSpec/SpecFilePathFormat.
+3. **provider_translator_examples.rb** — parse_response now tests translator.parse_response(wire) instead of canonical::Response.from_hash(fixture).
+
+### Issues found & fixed during this session
+
+1. **parse_response tests didn't exercise the translator** — Fixed by using `fixture_symbolized` + calling `translator.parse_response(wire).
+2. **Malformed rubocop directives in canonical lib files** — 5 files had `# rubocop:disable Metrics/ParameterLists, Metrics/PerceivedComplexity -- factory` where the trailing `, --` triggered `Lint/CopDirectiveSyntax`. Fixed & committed.
+3. **RSpec/SpecFilePathFormat rubocop violation** — `echo_translator_spec.rb` in `spec/legion/extensions/llm/conformance/` triggered the cop. Excluded conformance directory.
+4. **Symbolized vs string-keyed fixtures** — Fixed by using `fixture_symbolized` for self-test.
+
+---
+
+## Test results
+
+Conformance kit: 54 examples, 0 failures
+Full test suite: 630 examples, 0 failures
+Line coverage: 79.01% (3569 / 4517)
+Branch coverage: 52.76% (908 / 1721)
+RuboCop: clean (136 files, 0 offenses)
+
+---
+
+## Next steps
+
+1. **Phase 3** — Provider gems adopt the kit (anthropic first, then openai, vllm, ollama, bedrock). Each runs `it_behaves_like 'a canonical provider translator'`.
+2. **Phase 5** — Client translators in legion-llm adopt the client shared examples.
+3. **Bug fix** — Resolve ToolCall.from_hash JSON::ParserError constant resolution in lib/canonical (feat/canonical-types branch). The coordinator commit e1cbf820 fixed this with `Legion::JSON`.
+4. **Provider-specific fixtures** — Real provider gems will supply their own wire-format fixtures; the canonical fixtures serve as the round-trip anchor. A future step would add anthropic/openai wire-format reference fixtures (sanitized from `legionio-e2e/results/`) for direct cross-verification.
+5. **Streaming tool-call incremental fragments** — The `canonical_streaming_tool_call_chunks.json` fixture carries complete (canonical-form) tool call args per chunk due to the ParserError bug. The fix in #3 allows incremental fragments if desired.

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.5.0 - 2026-06-10
+
+### Added
+- **Canonical types module** — `Legion::Extensions::Llm::Canonical` provides immutable `Data.define` value objects (Thinking, Usage, Params, ContentBlock, ToolDefinition, ToolCall, Message, Request, Response, Chunk) forming the single N×N client↔provider routing contract. Includes `from_hash`/`to_h` for serialization, `CONTRACT_VERSION` for provider gem compatibility checks, and explicit factory validation per Amendment A.
+- **Conformance kit** — Shared RSpec example groups shipped under `spec/legion/extensions/llm/conformance/` (provider_translator_examples, client_translator_examples) with JSON fixtures for canonical↔provider translation contract testing. Packaged via gemspec `spec.files`; `gemspec.require_paths` remains `['lib']` only — conformance specs are consumed by provider gems at test time via `Gem.loaded_specs['lex-llm'].full_gem_path`.
+- **Conformance kit coordinator** — Fixtures read with explicit UTF-8 encoding so locale-less CI shells do not fail on JSON.parse.
+
+### Changed
+- **Zeitwerk autoloading removed** — Replaced lazy Zeitwerk::Loader with deterministic explicit `require_relative` for every file in `lib/`. Contract constants now exist at `require` time so provider gems can subclass against them during phased extension loading (core → lex-identity → lex-llm → lex-llm-*). Removed undeclared `zeitwerk ~> 2` runtime dependency from gemspec. Load order: canonical types and base classes first, then components referencing them. Transport exchange/message modules remain as Ruby `autoload` to avoid forcing `legion-transport` at boot time.
+
+## 0.4.19 - 2026-06-10
+
+### Fixed
+- **Connection logging bodies** — `setup_logging` now enables request body logging when the logger is at DEBUG level OR when `fleet.request.logger.request_payload` is explicitly true. Previously relied solely on log-level check; the new `request_payload` setting provides explicit control for fleet worker scenarios.
+- **OpenAI-compatible tool formatting** — `format_openai_tools` now handles both `ToolDefinition` objects and plain Hashes (from `native_dispatch`) by checking `respond_to?` for method access and falling back to symbol/string key access. Prevents `NoMethodError` when tools arrive as hash-backed definitions.
+
+### Added
+- **Fleet request_payload setting** — Added `fleet.request.logger.request_payload` (default: `false`) to `default_settings` for explicit control over request body logging in Faraday middleware.
+
 ## 0.4.18 - 2026-06-05
 
 ### Fixed

data/lex-llm.gemspec

@@ -24,8 +24,8 @@ Gem::Specification.new do |spec|
 
   spec.metadata['rubygems_mfa_required'] = 'true'
 
-  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec|test|features|tmp|coverage)/}) }
-  spec.require_paths = ['lib']
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|features|tmp|coverage)/}) }
+  spec.require_paths = %w[lib]
 
   # Runtime dependencies
   spec.add_dependency 'base64'
@@ -44,5 +44,4 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-transport', '>= 1.4.14'
   spec.add_dependency 'marcel', '~> 1'
   spec.add_dependency 'ruby_llm-schema', '~> 0'
-  spec.add_dependency 'zeitwerk', '~> 2'
 end

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

@@ -196,7 +196,7 @@ module Legion
           end
         end
 
-        def extract_filename_from_active_storage # rubocop:disable Metrics/PerceivedComplexity
+        def extract_filename_from_active_storage
           return 'attachment' unless defined?(ActiveStorage)
 
           case @source

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