lex-llm-vllm 0.2.12 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5479735ebd9e40d7298857beba666b486ae338790ee1e9ce385f9c9150337525
-  data.tar.gz: 8867da43e8237fb5ef655e60cd37991ece45f3fd3c9174c4e3c1af0f405c784c
+  metadata.gz: 172c35debe332979f48575e43bd59c04828449a41a195f3d899bc15afa18bdb2
+  data.tar.gz: c423c24ff7a5e4b33f1b6e562b50c196d2870b347bbcad61b38cd228d54ee318
 SHA512:
-  metadata.gz: 517bd19bab906b7ef52cca5d655ff994c520ef631d6fd45c4b518e19596feba3be7668ca242247f96ad2e19d32e3a0040c7cf5de6a1b47f6cf9a295829805b36
-  data.tar.gz: d86c43300492494bb56a7883011ff0441c4f1a9fb8d4d14fbede78d358310e4ff4a895d05b58e219493c63e78d09e66a88c555310de7627d8ff84d03aa10ee9d
+  metadata.gz: dbf9166b8302c7dc786562b7e2e17381b4cf33b570825570cc153dc438bfbef4991e53b0e86811821f08b2a4a00e3b6522bac903764a6bfe3e90f04be4d556ea
+  data.tar.gz: 5ee6cda495f98e9f68c4b3ea79b1a0fa28ab833113a00c3aa9a43e9a67e94c4aa79995faf8d8745e063d7c480d77dde246940d8d6b9c3570d678c39be19b496f

data/.rubocop.yml

@@ -21,3 +21,12 @@ RSpec/ExampleLength:
   Max: 8
 RSpec/MultipleExpectations:
   Enabled: false
+
+RSpec/ExampleLength:
+  Max: 10
+
+
+Layout/LineLength:
+  Exclude:
+    - spec/**/*
+

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.0 - 2026-06-10
+
+- Add canonical provider translator (`Translator`) implementing `render_request`,
+  `parse_response`, `parse_chunk`, and `capabilities` per N×N routing design
+- Wire provider `render_payload`, `parse_completion_response`, `build_chunk` to
+  delegate to translator with legacy Message/Chunk bridge for backward compat
+- Declare vLLM quirks: `tool_calls_as_text`, `forced_tool_choice`, `thinking_tags`,
+  `streaming_token_usage`
+- G18 parameter mapping: max_tokens, temperature, top_p, top_k, stop_sequences,
+  seed, frequency_penalty, presence_penalty, response_format
+- Qwen-style </think> tag extraction and tool-call synthesis from content text
+- Adopt conformance kit (`it_behaves_like 'a canonical provider translator'`)
+- Bump lex-llm dependency floor to >= 0.5.0
+
+## 0.2.13 - 2026-06-05
+
+- Fix missing documentation comment on `DiscoveryRefresh` actor (RuboCop Style/Documentation)
+
 ## 0.2.12 - 2026-05-29
 
 - Add capabilities `[:completion, :streaming, :vision, :tools]` to `DEFAULT_INSTANCE_TIER` so routing can match vLLM instances by required capability without live discovery

data/Gemfile

@@ -3,10 +3,9 @@
 source 'https://rubygems.org'
 
 group :test do
-  llm_base_path = ENV.fetch('LEX_LLM_PATH', File.expand_path('../lex-llm', __dir__))
   transport_path = ENV.fetch('LEGION_TRANSPORT_PATH', File.expand_path('../../legion-transport', __dir__))
   gem 'legion-transport', path: transport_path if File.directory?(transport_path)
-  gem 'lex-llm', path: llm_base_path if File.directory?(llm_base_path)
+  # lex-llm >= 0.5.0 carries canonical types + conformance kit (released on rubygems.org)
 end
 
 gemspec

data/README.md

@@ -2,24 +2,138 @@
 
 LegionIO LLM provider extension for [vLLM](https://docs.vllm.ai/).
 
-This gem lives under `Legion::Extensions::Llm::Vllm` and depends on `lex-llm >= 0.4.3` for shared provider-neutral routing, response normalization, fleet envelopes, responder-side fleet execution, and schema primitives.
+This gem provides a complete vLLM adapter for the LegionIO LLM routing layer. It speaks the OpenAI-compatible API, discovers models at runtime, publishes availability events, and supports vLLM-specific features like thinking mode and server lifecycle management.
 
-Load it with `require 'legion/extensions/llm/vllm'`.
+**Namespace:** `Legion::Extensions::Llm::Vllm`
+**Provider slug:** `:vllm`
+**Dependency:** `lex-llm >= 0.4.3`
 
-## What It Provides
+Load with:
 
-- `Legion::Extensions::Llm::Provider` registration as `:vllm`
-- Shared `Legion::Extensions::Llm::Provider::OpenAICompatible` request and response handling
-- Chat requests through `POST /v1/chat/completions`
-- Streaming chat with `stream_usage_supported?` for token usage reporting
-- Model discovery through `GET /v1/models`
-- Embeddings through `POST /v1/embeddings`
-- vLLM thinking mode via `chat_template_kwargs` (configurable through `Legion::Settings`)
-- Best-effort `llm.registry` readiness and model availability event publishing when transport is loaded
-- vLLM management helpers: `/health`, `/version`, `/reset_prefix_cache`, `/reset_mm_cache`, `/sleep`, `/wake_up`
-- Normalized OpenAI-compatible capability and modality metadata for discovered models
-- Shared fleet/default settings via `Legion::Extensions::Llm.provider_settings`
-- Structured `Legion::Logging::Helper` handling for provider discovery and fallback paths
+```ruby
+require 'legion/extensions/llm/vllm'
+```
+
+---
+
+## Architecture at a Glance
+
+```
+Legion::Extensions::Llm::Vllm          # Root module (namespace, discovery, defaults)
+  |-- Provider                          # Per-instance provider (chat, models, management)
+  |     |-- OpenAICompatible (mixin)    # Shared request/response handling
+  |     |-- Capabilities (module)       # Capability predicates for offerings
+  |
+  |-- Actor::DiscoveryRefresh           # Periodic actor: refreshes discovered model list
+  |-- Actor::FleetWorker                # Subscription actor: consumes fleet requests
+  |
+  |-- Runners::FleetWorker              # Runner: delegates to Fleet::ProviderResponder
+```
+
+### File Map
+
+| File | What |
+|------|------|
+| `lib/legion/extensions/llm/vllm.rb` | Root module, `discover_instances`, `default_settings`, alias normalization |
+| `lib/legion/extensions/llm/vllm/version.rb` | `VERSION` constant |
+| `lib/legion/extensions/llm/vllm/provider.rb` | Provider class, chat/embeddings/model discovery, management endpoints |
+| `lib/legion/extensions/llm/vllm/actors/discovery_refresh.rb` | Periodic actor to refresh model discovery cache |
+| `lib/legion/extensions/llm/vllm/actors/fleet_worker.rb` | Subscription actor for fleet request consumption |
+| `lib/legion/extensions/llm/vllm/runners/fleet_worker.rb` | Runner entrypoint that delegates to `Fleet::ProviderResponder` |
+
+---
+
+## Key Classes
+
+### `Legion::Extensions::Llm::Vllm` (Root Module)
+
+The top-level module. It handles auto-registration via `Legion::Extensions::Llm::AutoRegistration`, instance discovery, and configuration normalization.
+
+**Constants:**
+- `PROVIDER_FAMILY` — `:vllm`
+- `DEFAULT_INSTANCE_TIER` — `{ tier: :direct, capabilities: [:completion, :streaming, :vision, :tools] }`
+
+**Class methods:**
+
+| Method | Description |
+|--------|-------------|
+| `default_settings` | Returns the full default settings hash (endpoint, fleet, thinking, etc.) |
+| `provider_class` | Returns `Provider` |
+| `registry_publisher` | Memoized `Legion::Extensions::Llm::RegistryPublisher` instance |
+| `discover_instances` | Probes `localhost:8000` health endpoint, merges configured instances from `Legion::Settings` |
+| `normalize_instance_config(config)` | Normalizes config keys (`base_url`/`api_base`/`endpoint` -> `vllm_api_base`), infers tier |
+| `normalize_api_base(url)` | Strips trailing `/v1` from URLs |
+| `infer_tier_from_endpoint(url)` | Returns `:local` for localhost addresses, `:direct` otherwise |
+
+**Instance discovery sources:**
+1. HTTP health probe against `http://localhost:8000` (0.1s timeout) -> `:local` tier
+2. Configured instances under `Legion::Settings[:extensions][:llm][:vllm][:instances]`
+
+### `Legion::Extensions::Llm::Vllm::Provider`
+
+The per-instance provider class. Inherits from `Legion::Extensions::Llm::Provider` and mixes in `OpenAICompatible` for shared HTTP request/response handling.
+
+**Class methods:**
+
+| Method | Returns |
+|--------|---------|
+| `slug` | `'vllm'` |
+| `local?` | `false` |
+| `default_transport` | `:http` |
+| `default_tier` | `:direct` |
+| `configuration_options` | `[:vllm_api_base, :vllm_api_key]` |
+| `configuration_requirements` | `[]` (no required fields) |
+| `capabilities` | `Capabilities` module |
+| `registry_publisher` | Delegates to `Vllm.registry_publisher` |
+
+**Instance methods:**
+
+| Method | Description |
+|--------|-------------|
+| `api_base` | Normalized API root from config, settings, or `http://localhost:8000` |
+| `headers` | Identity headers + optional Bearer token |
+| `settings` | Returns `Vllm.default_settings` |
+| `health(live:)` | `GET /health` |
+| `readiness(live:)` | Checks readiness, publishes async readiness event when `live: true` |
+| `list_models` | `GET /v1/models`, publishes async model availability events |
+| `discover_offerings(live:, **)` | Builds `ModelOffering` instances from discovered models (uses cache when not live) |
+| `version` | `GET /version` |
+| `fetch_model_detail(model_name)` | Re-fetches `/v1/models` to resolve `context_window` on cache miss |
+| `stream_usage_supported?` | Always `true` for vLLM |
+| `reset_prefix_cache(reset_running_requests:, reset_external:)` | `POST /reset_prefix_cache` |
+| `reset_mm_cache` | `POST /reset_mm_cache` |
+| `sleep(level:)` | `POST /sleep` |
+| `wake_up(tags:)` | `POST /wake_up` |
+
+**Payload rendering:** Overrides `render_payload` to support vLLM thinking mode via `chat_template_kwargs` and strips `reasoning_effort`.
+
+### `Provider::Capabilities` (Module)
+
+Predicate methods for model capability detection. All return `true` for vLLM by default:
+
+- `chat?(model)`, `streaming?(model)`, `vision?(model)`, `functions?(model)`, `embeddings?(model)`
+- `critical_capabilities_for(model)` — returns array of active capability names
+
+### `Actor::DiscoveryRefresh`
+
+Periodic actor (extends `Legion::Extensions::Actors::Every`) that refreshes the vLLM discovered model list.
+
+- **Default interval:** 1800 seconds (30 minutes)
+- **Configurable via:** `Legion::Settings[:extensions][:llm][:vllm][:discovery_interval]`
+- **Action:** Calls `Legion::LLM::Discovery.refresh_discovered_models!(provider: :vllm)`
+
+### `Actor::FleetWorker`
+
+Subscription actor (extends `Legion::Extensions::Actors::Subscription`) that consumes LLM fleet requests routed to vLLM.
+
+- Only activates when `Fleet::ProviderResponder.enabled_for?` returns true for discovered instances
+- Delegates execution to `Runners::FleetWorker.handle_fleet_request`
+
+### `Runners::FleetWorker`
+
+Runner module that dispatches fleet requests to `Legion::Extensions::Llm::Fleet::ProviderResponder` with vLLM-specific context (provider family, class, instance discovery callback).
+
+---
 
 ## Defaults
 
@@ -49,8 +163,12 @@ Legion::Extensions::Llm::Vllm.default_settings
 # }
 ```
 
+---
+
 ## Configuration
 
+### Per-instance via Legion::Extensions::Llm.configure
+
 ```ruby
 Legion::Extensions::Llm.configure do |config|
   config.vllm_api_base = "http://localhost:8000"
@@ -60,9 +178,36 @@ Legion::Extensions::Llm.configure do |config|
 end
 ```
 
+### Multi-instance via Legion::Settings
+
+```yaml
+extensions:
+  llm:
+    vllm:
+      discovery_interval: 1800  # seconds between model list refreshes
+      instances:
+        production:
+          vllm_api_base: "https://vllm.example.com"
+          tier: :direct
+        local:
+          vllm_api_base: "http://localhost:8000"
+          tier: :local
+```
+
+### Endpoint alias normalization
+
+The following keys are all resolved to `vllm_api_base` during instance config normalization:
+- `base_url`
+- `api_base`
+- `endpoint`
+
+Trailing `/v1` is stripped automatically.
+
+---
+
 ## Fleet Responder
 
-Provider instances can opt in to consuming Legion LLM fleet requests. The provider-owned fleet actor only starts when at least one configured instance enables `respond_to_requests`, and request execution delegates to `Legion::Extensions::Llm::Fleet::ProviderResponder`.
+Provider instances can opt in to consuming Legion LLM fleet requests. The fleet actor only starts when at least one configured instance enables `respond_to_requests`.
 
 ```yaml
 extensions:
@@ -79,29 +224,51 @@ extensions:
               - embed
 ```
 
-### Thinking Mode
+Execution flows: `Actor::FleetWorker` (receives message) -> `Runners::FleetWorker.handle_fleet_request` -> `Fleet::ProviderResponder.call`.
+
+---
+
+## Thinking Mode
 
-Enable vLLM thinking mode globally via settings:
+vLLM supports a "thinking" mode that enables extended reasoning. Enable via:
 
+**Instance-level:**
+```yaml
+extensions:
+  llm:
+    vllm:
+      instances:
+        default:
+          enable_thinking: true
+```
+
+**Global:**
 ```ruby
-# In Legion::Settings or settings JSON
+# Legion::Settings or settings JSON
 { llm: { providers: { vllm: { enable_thinking: true } } } }
 ```
 
-Or pass `thinking: { enabled: true }` per-request. When enabled, the provider adds `chat_template_kwargs: { enable_thinking: true }` to the payload and strips `reasoning_effort`.
+**Per-request:**
+```ruby
+# Pass thinking: { enabled: true } in the chat kwargs
+```
+
+When enabled, the provider adds `chat_template_kwargs: { enable_thinking: true }` to the chat payload and strips the OpenAI-specific `reasoning_effort` key.
+
+---
 
 ## Management Endpoints
 
-The provider exposes helpers for vLLM server management:
+| Method | Endpoint | Kwargs | Description |
+|--------|----------|--------|-------------|
+| `health(live:)` | `GET /health` | `live:` | Server health check |
+| `version` | `GET /version` | none | Server version info |
+| `reset_prefix_cache` | `POST /reset_prefix_cache` | `reset_running_requests:`, `reset_external:` | Clear prefix cache |
+| `reset_mm_cache` | `POST /reset_mm_cache` | none | Clear multimodal cache |
+| `sleep(level:)` | `POST /sleep` | `level:` (default: 1) | Put worker to sleep |
+| `wake_up(tags:)` | `POST /wake_up` | `tags:` | Wake worker up |
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `health` | `GET /health` | Server health check |
-| `version` | `GET /version` | Server version info |
-| `reset_prefix_cache` | `POST /reset_prefix_cache` | Clear prefix cache |
-| `reset_mm_cache` | `POST /reset_mm_cache` | Clear multimodal cache |
-| `sleep(level:)` | `POST /sleep` | Put server to sleep |
-| `wake_up(tags:)` | `POST /wake_up` | Wake server up |
+---
 
 ## Registry Publishing
 
@@ -110,16 +277,31 @@ When `lex-llm` routing and Legion transport are available, the provider publishe
 - **Readiness events** on `readiness(live: true)` calls
 - **Model availability events** on `list_models` discovery
 
-Publishing is async (background threads) and never blocks the caller. All failures are handled gracefully via `handle_exception`.
+All publishing is async (background threads) and never blocks the caller. Failures are logged via `handle_exception`.
+
+---
+
+## Model Discovery & Offerings
+
+On `list_models`, vLLM returns `max_model_len` which is mapped to `context_length`. This value is:
+1. Attached to `Model::Info` objects
+2. Cached via `cache_set` with 86400s TTL keyed by `model_detail_cache_key`
+3. Available in routing offerings via `limits: { context_window: ctx }`
+
+`discover_offerings(live: false)` serves from the cached model list without hitting the network.
+
+---
 
 ## Development
 
 ```bash
 bundle install
-bundle exec rspec --format json --out tmp/rspec_results.json --format progress --out tmp/rspec_progress.txt
+bundle exec rspec
 bundle exec rubocop -A
 ```
 
+---
+
 ## License
 
 MIT

data/lex-llm-vllm.gemspec

@@ -27,5 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.3.14'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
-  spec.add_dependency 'lex-llm', '>= 0.4.3'
+  spec.add_dependency 'lex-llm', '>= 0.5.0'
 end

data/lib/legion/extensions/llm/vllm/actors/discovery_refresh.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+begin
+  require 'legion/extensions/actors/every'
+rescue LoadError => e
+  warn(e.message) if $VERBOSE
+end
+
+return unless defined?(Legion::Extensions::Actors::Every)
+
+module Legion
+  module Extensions
+    module Llm
+      module Vllm
+        module Actor
+          # Periodic actor that refreshes the vLLM discovered model list.
+          class DiscoveryRefresh < Legion::Extensions::Actors::Every
+            include Legion::Logging::Helper
+
+            REFRESH_INTERVAL = 1800
+
+            def runner_class    = self.class
+            def runner_function = 'manual'
+            def run_now?        = true
+            def use_runner?     = false
+            def check_subtask?  = false
+            def generate_task?  = false
+
+            def time
+              return REFRESH_INTERVAL unless defined?(Legion::Settings)
+
+              Legion::Settings.dig(:extensions, :llm, :vllm, :discovery_interval) || REFRESH_INTERVAL
+            end
+
+            def manual
+              log.debug('[vllm][discovery_refresh] refreshing model list')
+              return unless defined?(Legion::LLM::Discovery)
+
+              Legion::LLM::Discovery.refresh_discovered_models!(provider: :vllm)
+            rescue StandardError => e
+              handle_exception(e, level: :warn, handled: true, operation: 'vllm.actor.discovery_refresh')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/vllm/provider.rb

@@ -53,6 +53,11 @@ module Legion
             Vllm.default_settings
           end
 
+          # Canonical translator instance — renders requests, parses responses/chunks.
+          def translator
+            @translator ||= Translator.new(config: config)
+          end
+
           def api_base
             normalize_url(config.vllm_api_base || settings[:endpoint] || 'http://localhost:8000')
           end
@@ -173,15 +178,159 @@ module Legion
             )
           end
 
+          # ── Canonical bridge: legacy provider API → Canonical::Request ──
+
+          # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- bridge method can be complex
+          def build_canonical_request(
+            messages:, tools:, temperature:, model:, stream:, schema:, thinking:, tool_prefs:
+          )
+            model_id = model.respond_to?(:id) ? model.id : model.to_s
+
+            canonical_messages = messages.filter_map do |msg|
+              Canonical::Message.from_hash(msg.to_h) if msg.respond_to?(:to_h)
+            end
+
+            canonical_tools = tools.to_h.transform_values do |tool|
+              if tool.is_a?(Canonical::ToolDefinition)
+                tool
+              else
+                Canonical::ToolDefinition.from_hash(tool.respond_to?(:to_h) ? tool.to_h : tool)
+              end
+            end
+
+            params_hash = { temperature: temperature }
+            params_hash[:response_format] = schema if schema
+            canonical_params = Canonical::Params.from_hash(params_hash)
+
+            canonical_thinking = if thinking.respond_to?(:enabled?) && thinking.enabled?
+                                   Canonical::Thinking::Config.new(
+                                     effort: thinking.respond_to?(:effort) ? thinking.effort : nil
+                                   )
+                                 elsif thinking.is_a?(Hash)
+                                   Canonical::Thinking::Config.new(
+                                     effort: thinking[:effort] || thinking['effort'],
+                                     budget: thinking[:budget] || thinking['budget']
+                                   )
+                                 end
+
+            # Tool choice from tool_prefs
+            tool_choice = format_tool_choice_from_prefs(tool_prefs)
+
+            Canonical::Request.build(
+              messages: canonical_messages,
+              system: extract_system_prompt(messages),
+              tools: canonical_tools,
+              tool_choice: tool_choice,
+              params: canonical_params,
+              thinking: canonical_thinking,
+              stream: stream,
+              metadata: { model: model_id }
+            )
+          end
+          # rubocop:enable Metrics/ParameterLists, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+          # ── Canonical bridge: Canonical→legacy Message/Chunk ──
+
+          # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- verbose bridge
+          def to_legacy_message(canonical, raw_body, _raw_response)
+            thinking = nil
+            if canonical.thinking
+              thinking = Thinking.build(
+                text: canonical.thinking.content,
+                signature: canonical.thinking.signature
+              )
+            end
+
+            tool_calls = {}
+            canonical.tool_calls.each do |tc|
+              key = (tc.name || tc.id).to_s.to_sym
+              tool_calls[key] = Legion::Extensions::Llm::ToolCall.new(
+                id: tc.id,
+                name: tc.name,
+                arguments: tc.arguments
+              )
+            end
+
+            usage = canonical.usage || {}
+
+            Legion::Extensions::Llm::Message.new(
+              role: :assistant,
+              content: canonical.text,
+              model_id: canonical.model,
+              tool_calls: tool_calls.empty? ? nil : tool_calls,
+              thinking: thinking,
+              input_tokens: usage.respond_to?(:input_tokens) ? usage.input_tokens : nil,
+              output_tokens: usage.respond_to?(:output_tokens) ? usage.output_tokens : nil,
+              reasoning_tokens: usage.respond_to?(:thinking_tokens) ? usage.thinking_tokens : nil,
+              raw: raw_body
+            )
+          end
+          # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+          def to_legacy_chunk(canonical, raw_data)
+            usage = canonical&.usage || {}
+
+            content = canonical.delta
+            thinking = nil
+            if canonical.type == :thinking_delta
+              thinking = Thinking.build(text: canonical.delta)
+              content = nil
+            end
+
+            Legion::Extensions::Llm::Chunk.new(
+              role: :assistant,
+              content: content,
+              model_id: raw_data['model'],
+              tool_calls: nil,
+              thinking: thinking,
+              input_tokens: usage.respond_to?(:input_tokens) ? usage.input_tokens : nil,
+              output_tokens: usage.respond_to?(:output_tokens) ? usage.output_tokens : nil,
+              raw: raw_data
+            )
+          end
+
+          # ── Tool choice helpers ──
+
+          def format_tool_choice_from_prefs(tool_prefs)
+            return nil unless tool_prefs
+
+            choice = tool_prefs[:choice] || tool_prefs['choice']
+            return nil unless choice
+            return choice.to_sym if %w[auto none required].include?(choice.to_s)
+
+            { name: choice.to_s }
+          end
+
+          # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- multibranch guard chain for system parsing
+          def extract_system_prompt(messages)
+            return nil unless messages.is_a?(Array)
+            return nil if messages.empty?
+
+            first = messages.first
+            return nil unless first
+
+            role = first.respond_to?(:role) ? first.role.to_sym : (first[:role] || first['role'])
+            return nil unless [:system, 'system'].include?(role)
+
+            content = first.respond_to?(:content) ? first.content : (first[:content] || first['content'])
+            content.is_a?(String) ? content : nil
+          end
+          # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
           def render_payload(messages, tools:, temperature:, model:, stream:, schema:, thinking:, tool_prefs:) # rubocop:disable Metrics/ParameterLists
-            payload = super
-            payload.delete(:reasoning_effort)
-            payload[:chat_template_kwargs] = { enable_thinking: true } if thinking_enabled?(thinking)
+            # Build a canonical request from provider call parameters,
+            # then delegate to the translator for wire-format rendering.
+            canonical_req = build_canonical_request(
+              messages:, tools:, temperature:, model:, stream:,
+              schema:, thinking:, tool_prefs:
+            )
+            wire = translator.render_request(canonical_req)
+
             log.debug do
-              "rendered vLLM payload model=#{model.respond_to?(:id) ? model.id : model} stream=#{stream} " \
-                "tools=#{tools.respond_to?(:size) ? tools.size : 0} thinking=#{payload.key?(:chat_template_kwargs)}"
+              "vLLM provider rendered wire payload model=#{wire[:model]} stream=#{wire[:stream]} " \
+                "messages=#{(wire[:messages] || []).size} keys=#{wire.keys.join(', ')}"
             end
-            payload
+            wire
           end
 
           def thinking_enabled?(thinking)
@@ -214,6 +363,24 @@ module Legion
             vllm[:enable_thinking] == true || vllm['enable_thinking'] == true
           end
 
+          # Override: delegate completion response parsing to the canonical translator.
+          def parse_completion_response(response)
+            body = response.body
+            canonical = translator.parse_response(body)
+
+            # Convert Canonical::Response back to the legacy Message/Chunk shape
+            # that the Provider base class expects (backward compat with existing callers).
+            to_legacy_message(canonical, body, response)
+          end
+
+          # Override: delegate SSE chunk parsing to the canonical translator.
+          def build_chunk(data)
+            canonical_chunk = translator.parse_chunk(data)
+            return nil if canonical_chunk.nil?
+
+            to_legacy_chunk(canonical_chunk, data)
+          end
+
           def parse_list_models_response(response, provider, capabilities)
             response.body.fetch('data', []).map do |model|
               critical_capabilities = critical_capabilities_for(capabilities, model)