lex-llm-openai 0.3.11 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 570527e7fb80e2b480eafd36844264bbb59ccfbc11fc4424213cc57cc1e539ea
-  data.tar.gz: 9ec953777f2f1b2a0c91dd63c697c5760c9264b6577ded5a50d39ae6ced7d991
+  metadata.gz: 7bb7451045c6e85e6e89657665065fe502888f49982d3dc43a53fdcb1bf4ebcd
+  data.tar.gz: 05e91bb97ec042142b126b310e9e05dcfb99fe1ae999b8595f7924102106d592
 SHA512:
-  metadata.gz: 077412edd3903af264268d9863f7ce69f522940d12abc47fb63b9f948ef607d5b39da14a8d5bf42912fd2143494577882aaf34c2656fd4df6d91ed3dadf4d09d
-  data.tar.gz: f6b2c1f473e83012b548d80763320b8d66263ade5438b13743b35b7bd4716bb72f2bf333a03679608f79dd520682b5c6d3f1778c7c4197eecde8869aa0338f57
+  metadata.gz: a7bdaf1e6de4518d02d1f0bc6af5ddcd39392f4fd8153902ce0414264ec773e2295ad14b8508984ed8140f96742081b1e76f16c2843dd4667e59d25fb558bf3a
+  data.tar.gz: d5dfe88b242d5b9ab7d3c27621c1761fd7e5a8a6958dfadcafe20be3e7a89a9f7c33f4b21bcda2574bc29e0ef7ea025b9f905f4d01d9e45c0de2aecc8f22648b

data/.rubocop.yml

@@ -13,12 +13,14 @@ Metrics/BlockLength:
     - "*.gemspec"
     - spec/**/*
 Metrics/ClassLength:
-  Max: 200
+  Max: 350
 Metrics/ModuleLength:
   Max: 110
 Metrics/MethodLength:
   Enabled: false
 RSpec/ExampleLength:
-  Max: 10
+  Max: 25
 RSpec/MultipleExpectations:
   Enabled: false
+RSpec/SubjectStub:
+  Enabled: false

data/CHANGELOG.md

@@ -1,6 +1,30 @@
 # Changelog
 
-## 0.3.11 - 2026-06-05
+## 0.4.4 - 2026-06-16
+
+- dependency updates, code quality improvements
+
+## 0.4.3 - 2026-06-15
+
+- **CapabilityPolicy integration** — CAPABILITY_MAP fed as `:provider_catalog` source. Settings overrides at provider/instance/model level supported.
+
+## 0.4.2 — 2026-06-13
+
+- **Gemfile cleanup** — Remove local path overrides; dependencies resolve from gemspec via rubygems.
+- **Capabilities** — Add canonical `:tools` to capability declarations.
+- **Bug fix** — Extract nested `cached_tokens` from usage details (G26).
+- 153 examples, 0 failures; 16 files, 0 rubocop offenses.
+
+## 0.4.1 — 2026-06-10
+
+- Canonical translator (`Translator`): `render_request`, `parse_response`, `parse_chunk`, `capabilities` — provider-boundary contract per N×N routing Amendment A
+- Conformance kit integration — loads shared `it_behaves_like 'a canonical provider translator` from `lex-llm` gem spec/ per B1b consumer pattern (54 kit scenarios passing)
+- `Provider#translator` exposes a lazy `Translator` instance; provider becomes transport + config
+- G18 parameter mapping: max_tokens, temperature, top_p, stop_sequences/stop, seed, penalties, response_format mapped 1:1; top_k dropped with debug log; max_thinking_tokens → thinking config
+- G18 stop_reason matrix: stop → end_turn, tool_calls → tool_use, length → max_tokens, content_filter → content_filter
+- Require `lex-llm >= 0.5.0` (canonical types, conformance kit, Zeitwerk removal)
+
+## 0.3.11 — 2026-06-05
 
 - Fix missing top-level documentation comment in `DiscoveryRefresh` actor (RuboCop `Style/Documentation`).
 

data/Gemfile

@@ -2,13 +2,6 @@
 
 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)
-end
-
 gemspec
 
 group :development do

data/lex-llm-openai.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/openai/actors/discovery_refresh.rb

@@ -37,6 +37,13 @@ module Legion
               return unless defined?(Legion::LLM::Discovery)
 
               Legion::LLM::Discovery.refresh_discovered_models!(provider: :openai)
+
+              if defined?(Legion::LLM::Router) && Legion::LLM::Router.respond_to?(:populate_auto_rules)
+                Legion::LLM::Router.populate_auto_rules(Legion::LLM::Discovery.discovered_instances)
+              end
+              if defined?(Legion::LLM::Inventory) && Legion::LLM::Inventory.respond_to?(:invalidate_offerings_cache!)
+                Legion::LLM::Inventory.invalidate_offerings_cache!
+              end
             rescue StandardError => e
               handle_exception(e, level: :warn, handled: true, operation: 'openai.actor.discovery_refresh')
             end

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

@@ -17,43 +17,43 @@ module Legion
           # the raw /v1/models response.
           CAPABILITY_MAP = {
             'gpt-4o' => {
-              capabilities: %i[completion streaming function_calling vision structured_output],
+              capabilities: %i[completion streaming function_calling tools vision structured_output],
               modalities_input: %w[text image audio],
               modalities_output: %w[text],
               context_window: 128_000
             },
             'gpt-4.1' => {
-              capabilities: %i[completion streaming function_calling vision structured_output],
+              capabilities: %i[completion streaming function_calling tools vision structured_output],
               modalities_input: %w[text image],
               modalities_output: %w[text],
               context_window: 1_047_576
             },
             'gpt-4' => {
-              capabilities: %i[completion streaming function_calling vision],
+              capabilities: %i[completion streaming function_calling tools vision],
               modalities_input: %w[text image],
               modalities_output: %w[text],
               context_window: 128_000
             },
             'gpt-5' => {
-              capabilities: %i[completion streaming function_calling vision structured_output reasoning],
+              capabilities: %i[completion streaming function_calling tools vision structured_output reasoning],
               modalities_input: %w[text image],
               modalities_output: %w[text],
               context_window: 1_047_576
             },
             'o4' => {
-              capabilities: %i[completion streaming function_calling vision reasoning],
+              capabilities: %i[completion streaming function_calling tools vision reasoning],
               modalities_input: %w[text image],
               modalities_output: %w[text],
               context_window: 200_000
             },
             'o3' => {
-              capabilities: %i[completion streaming function_calling vision reasoning],
+              capabilities: %i[completion streaming function_calling tools vision reasoning],
               modalities_input: %w[text image],
               modalities_output: %w[text],
               context_window: 200_000
             },
             'o1' => {
-              capabilities: %i[completion streaming function_calling vision reasoning],
+              capabilities: %i[completion streaming function_calling tools vision reasoning],
               modalities_input: %w[text image],
               modalities_output: %w[text],
               context_window: 200_000
@@ -166,7 +166,13 @@ module Legion
           end
 
           def api_base
-            config.openai_api_base || settings[:endpoint] || 'https://api.openai.com'
+            config.openai_api_base || settings.dig(:instances, :default, :endpoint) || 'https://api.openai.com'
+          end
+
+          # Canonical translator instance - the provider boundary contract.
+          # Created lazily; delegate translation to the Translator class.
+          def translator
+            @translator ||= Translator.new(api_base: api_base, headers: headers)
           end
 
           def headers
@@ -205,6 +211,36 @@ module Legion
             raise
           end
 
+          def discover_offerings(live: false, **)
+            models = if live
+                       @cached_models = list_models
+                     else
+                       Array(@cached_models)
+                     end
+            offerings = models.filter_map { |model_info| offering_from_model(model_info) }
+            log.debug { "built #{offerings.size} OpenAI offering(s) live=#{live}" }
+            offerings
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'openai.discover_offerings')
+            []
+          end
+
+          # ── CapabilityPolicy integration ─────────────────────────────────
+          # Maps raw CAPABILITY_MAP symbol arrays to the boolean hash format
+          # that CapabilityPolicy.resolve expects as :provider_catalog.
+          CATALOG_CAPABILITY_MAPPING = {
+            streaming: :streaming,
+            function_calling: :tools,
+            tools: :tools,
+            vision: :vision,
+            structured_output: :structured_output,
+            reasoning: :thinking,
+            embedding: :embeddings,
+            image_generation: :image,
+            audio_transcription: :audio_transcription,
+            audio_generation: :audio_speech
+          }.freeze
+
           private
 
           def build_model_infos(body)
@@ -242,6 +278,115 @@ module Legion
             }
           end
 
+          def offering_from_model(model_info)
+            policy = resolve_model_policy(model_info)
+
+            Legion::Extensions::Llm::Routing::ModelOffering.new(
+              offering_attrs_for(model_info, policy)
+            )
+          end
+
+          def resolve_model_policy(model_info)
+            catalog = capabilities_to_boolean_hash(capability_entry_for(model_info.id)[:capabilities])
+
+            Legion::Extensions::Llm::CapabilityPolicy.resolve(
+              real: {},
+              provider_catalog: catalog,
+              probe: {},
+              provider_envelope: {},
+              provider_config: provider_capability_config,
+              instance_config: instance_capability_config,
+              model_config: model_capability_config(model_info.id)
+            )
+          end
+
+          def offering_attrs_for(model_info, policy)
+            {
+              provider_family: :openai,
+              instance_id: config.respond_to?(:instance_id) ? config.instance_id : :default,
+              transport: :http,
+              tier: :frontier,
+              model: model_info.id,
+              canonical_model_alias: model_info.respond_to?(:name) ? model_info.name : nil,
+              model_family: infer_model_family(model_info.id),
+              usage_type: infer_usage_type(model_info),
+              capabilities: policy[:capabilities],
+              capability_sources: policy[:sources],
+              limits: { context_window: model_info.context_length }.compact,
+              metadata: { capability_sources: policy[:sources] }
+            }
+          end
+
+          def capabilities_to_boolean_hash(capability_symbols)
+            return {} unless capability_symbols.is_a?(Array)
+
+            result = {}
+            capability_symbols.each do |sym|
+              mapped = CATALOG_CAPABILITY_MAPPING[sym]
+              result[mapped] = true if mapped
+            end
+            result
+          end
+
+          def provider_capability_config
+            return {} unless defined?(Legion::Extensions::Llm::CredentialSources)
+
+            conf = Legion::Extensions::Llm::CredentialSources.setting(:extensions, :llm, :openai)
+            conf.is_a?(Hash) ? conf.to_h.except(:instances, 'instances') : {}
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'openai.provider_capability_config')
+            {}
+          end
+
+          def instance_capability_config
+            cfg = config
+            result = {}
+            %i[capabilities enable_thinking enable_tools enable_streaming enable_vision enable_embeddings
+               thinking_flag tools_flag streaming_flag vision_flag embedding_flag embeddings_flag
+               tool_flag images_flag image_flag].each do |key|
+              next unless cfg.respond_to?(key)
+
+              val = cfg.send(key)
+              result[key] = val unless val.nil?
+            rescue StandardError
+              next
+            end
+            result
+          end
+
+          def model_capability_config(model_id)
+            models_conf = fetch_models_config
+            return {} unless models_conf.respond_to?(:to_h)
+
+            models_conf.to_h[model_id.to_s] || models_conf.to_h[model_id.to_sym] || {}
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'openai.model_capability_config')
+            {}
+          end
+
+          def fetch_models_config
+            return config.models if config.respond_to?(:models)
+            return config[:models] if config.respond_to?(:[])
+
+            nil
+          end
+
+          def infer_model_family(model_id)
+            CAPABILITY_MAP.each_key do |prefix|
+              return prefix.tr('-', '_').to_sym if model_id.start_with?(prefix)
+            end
+            :unknown
+          end
+
+          def infer_usage_type(model_info)
+            caps = model_info.respond_to?(:capabilities) ? Array(model_info.capabilities) : []
+            return :embedding if caps.include?(:embedding)
+            return :moderation if caps.include?(:moderation)
+            return :image if caps.include?(:image_generation)
+
+            :inference
+          end
+
           def fetch_model_detail(model_name)
             entry = capability_entry_for(model_name)
             ctx = entry[:context_window]

data/lib/legion/extensions/llm/openai/translator.rb

@@ -0,0 +1,455 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Openai
+        # Canonical <-> OpenAI wire-format translator.
+        #
+        # Implements the provider-boundary contract (Amendment A) so that
+        # canonical requests/responses/chunks cross exactly one translation
+        # layer per provider. Extracted from OpenAICompatible mixin methods;
+        # semantics preserved, not rewritten.
+        #
+        # Capabilities (declarative, per the design doc):
+        #   - reasoning_effort: true            (gpt-5.x / o-series)
+        #   - responses_api: true               (chat/completions wire format)
+        #   - thinking_metadata_keys: [...]     (metadata keys for thinking)
+        #   - stop_reason_map: { openai -> canonical }
+        # -- translator complexity is inherent to multi-field mapping (B1a pattern)
+        # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        class Translator
+          include Legion::Logging::Helper
+
+          # OpenAI finish_reason -> canonical stop_reason (G18 stop-reason matrix)
+          STOP_REASON_MAP = {
+            'stop' => :end_turn,
+            'tool_calls' => :tool_use,
+            'function_call' => :tool_use,
+            'length' => :max_tokens,
+            'content_filter' => :content_filter
+          }.freeze
+
+          # Metadata keys carrying thinking/reasoning in OpenAI responses
+          THINKING_METADATA_KEYS = %i[
+            reasoning_content reasoning thinking thinking_text
+            thinking_signature reasoning_signature
+          ].freeze
+
+          def initialize(api_base: nil, headers: nil)
+            @api_base = api_base
+            @headers = headers || {}
+          end
+
+          # @return [Hash] declarative capabilities consumed by routing/dispatch
+          def capabilities
+            {
+              provider: 'openai',
+              reasoning_effort: true,
+              responses_api: true,
+              thinking_metadata_keys: THINKING_METADATA_KEYS,
+              stop_reason_map: STOP_REASON_MAP
+            }
+          end
+
+          # @param canonical_request [Canonical::Request]
+          # @return [Hash] OpenAI wire-format payload for /v1/chat/completions
+          def render_request(canonical_request)
+            wire = {
+              model: resolve_model(canonical_request),
+              messages: render_messages(canonical_request),
+              stream: canonical_request.stream
+            }.compact
+
+            apply_params(wire, canonical_request.params) if canonical_request.params
+            apply_tools(wire, canonical_request) if canonical_request.tools&.any?
+            apply_tool_choice(wire, canonical_request.tool_choice) if canonical_request.tool_choice
+            apply_thinking(wire, canonical_request)
+            use_stream_usage(wire) if canonical_request.stream
+
+            wire
+          end
+
+          # @param wire [Hash] OpenAI API response body (string-keyed)
+          # @return [Canonical::Response]
+          def parse_response(wire)
+            return Canonical::Response.from_hash(wire) if canonical_form?(wire)
+
+            body = wire.to_h
+            choice = Array(body['choices']).first || {}
+            message = choice['message'] || {}
+            usage_raw = body['usage'] || {}
+
+            text, thinking = extract_thinking_from_message(message)
+            tool_calls = parse_tool_calls(message['tool_calls'])
+            usage = parse_usage(usage_raw)
+            stop_reason = map_stop_reason(choice['finish_reason'])
+            metadata = extract_response_metadata(message)
+
+            Canonical::Response.build(
+              text: text,
+              thinking: thinking,
+              tool_calls: tool_calls,
+              usage: usage,
+              stop_reason: stop_reason,
+              model: body['model'],
+              metadata: metadata
+            )
+          rescue StandardError => e
+            handle_exception(e, level: :error, handled: true, operation: 'openai.translator.parse_response')
+            Canonical::Response.build(
+              text: '',
+              stop_reason: :error,
+              metadata: { error: e.message }
+            )
+          end
+
+          # @param raw [Hash] single SSE data payload or canonical chunk
+          # @return [Canonical::Chunk, nil]
+          def parse_chunk(raw)
+            return nil if raw.nil? || raw.to_h.empty?
+            return Canonical::Chunk.from_hash(raw) if canonical_chunk_form?(raw)
+
+            data = raw.to_h
+            choice = Array(data['choices']).first || {}
+            delta = choice['delta'] || {}
+            finish_reason = choice['finish_reason']
+            usage_raw = data['usage']
+
+            return build_done_chunk(data, finish_reason, usage_raw) if finish_reason
+            return parse_error_chunk(data) if data['error']
+
+            reasoning = delta['reasoning_content'] || delta['reasoning']
+            content = delta['content']
+
+            return build_thinking_chunk(reasoning, data['id']) if reasoning
+            return build_text_chunk(content, data['id']) if content
+
+            parse_tool_call_delta(delta, data)
+          rescue StandardError => e
+            handle_exception(e, level: :error, handled: true, operation: 'openai.translator.parse_chunk')
+            Canonical::Chunk.error_chunk(
+              error: e.message,
+              request_id: raw.to_h['id']
+            )
+          end
+
+          private
+
+          # G18: OpenAI param mapping - unsupported drop with debug log
+          def apply_params(wire, params)
+            wire[:max_tokens] = params.max_tokens if params.max_tokens
+            wire[:temperature] = params.temperature if params.temperature
+            wire[:top_p] = params.top_p if params.top_p
+
+            log.debug('[openai.translator] dropping unsupported param: top_k') if params.top_k
+
+            wire[:stop] = Array(params.stop_sequences) if params.stop_sequences
+            wire[:seed] = params.seed if params.seed
+            wire[:frequency_penalty] = params.frequency_penalty if params.frequency_penalty
+            wire[:presence_penalty] = params.presence_penalty if params.presence_penalty
+
+            wire[:response_format] = render_response_format(params.response_format) if params.response_format
+
+            return unless params.max_thinking_tokens
+
+            log.debug('[openai.translator] mapped to reasoning_effort via thinking config')
+          end
+
+          def render_response_format(fmt)
+            return fmt if fmt.is_a?(Hash)
+
+            type_val = fmt.to_s
+            type_val == 'json_object' ? { type: 'json_object' } : { type: type_val }
+          rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'openai.translator.render_response_format')
+            { type: 'text' }
+          end
+
+          def apply_tools(wire, canonical_request)
+            wire[:tools] = canonical_request.tools.values.map do |tool_def|
+              {
+                type: 'function',
+                function: {
+                  name: tool_def.name,
+                  description: tool_def.description,
+                  parameters: tool_def.parameters || { type: 'object', properties: {} }
+                }
+              }
+            end
+          end
+
+          def apply_tool_choice(wire, tool_choice)
+            wire[:tool_choice] = case tool_choice
+                                 when :auto then 'auto'
+                                 when :none then 'none'
+                                 when :required then 'required'
+                                 when Hash
+                                   {
+                                     type: 'function',
+                                     function: { name: tool_choice[:name] || tool_choice['name'] }
+                                   }
+                                 else
+                                   tool_choice.to_s
+                                 end
+          end
+
+          def apply_thinking(wire, canonical_request)
+            thinking = canonical_request.thinking
+            return unless thinking
+
+            effort = if thinking.respond_to?(:effort)
+                       thinking.effort
+                     else
+                       thinking[:effort] || thinking['effort']
+                     end
+            return unless effort
+
+            wire[:reasoning_effort] = effort.to_s.downcase
+          end
+
+          def use_stream_usage(wire)
+            wire[:stream_options] = { include_usage: true }
+          end
+
+          def resolve_model(canonical_request)
+            return canonical_request.routing[:model] if canonical_request.routing&.dig(:model)
+            return canonical_request.caller[:model] if canonical_request.caller&.dig(:model)
+
+            canonical_request.metadata[:model] || 'gpt-4o'
+          end
+
+          def render_messages(canonical_request)
+            messages = []
+
+            messages << { role: 'system', content: canonical_request.system } if canonical_request.system
+
+            Array(canonical_request.messages).each do |msg|
+              messages << render_message(msg)
+            end
+
+            messages
+          end
+
+          def render_message(msg)
+            openai_msg = { role: msg.role.to_s }
+
+            # rubocop:disable Lint/DuplicateBranch -- explicit per-role clarity for :tool vs unknown
+            case msg.role
+            when :user
+              openai_msg[:content] = extract_text_from_content(msg.content)
+            when :assistant
+              content_parts = []
+
+              openai_msg[:tool_calls] = render_openai_tool_calls(msg.tool_calls) if msg.tool_calls&.any?
+
+              text = extract_text_from_content(msg.content)
+              content_parts << { type: 'text', text: text } if text
+
+              if msg.content.is_a?(Array)
+                msg.content.each do |block|
+                  next unless block.is_a?(Canonical::ContentBlock) && block.tool_use?
+
+                  content_parts << {
+                    type: 'tool_use',
+                    id: block.id,
+                    name: block.name,
+                    input: block.input || {}
+                  }
+                end
+              end
+
+              openai_msg[:content] = content_parts.empty? ? '' : content_parts
+            when :tool
+              openai_msg[:tool_call_id] = msg.tool_call_id if msg.tool_call_id
+              openai_msg[:content] = extract_text_from_content(msg.content)
+            else
+              openai_msg[:content] = extract_text_from_content(msg.content)
+            end
+            # rubocop:enable Lint/DuplicateBranch
+
+            openai_msg
+          end
+
+          def extract_text_from_content(content)
+            return content if content.is_a?(String)
+            return '' unless content
+
+            case content
+            when Array then content.filter_map { |block| extract_block_text(block) }.join
+            when Canonical::ContentBlock then content.text.to_s
+            else content.to_s
+            end
+          end
+
+          def extract_block_text(block)
+            block.is_a?(Canonical::ContentBlock) ? block.text.to_s : (block[:text] || block['text'] || block.to_s)
+          end
+
+          def render_openai_tool_calls(tool_calls)
+            tc_array = tool_calls.is_a?(Hash) ? tool_calls.values : Array(tool_calls)
+            tc_array.map do |tc|
+              args = tc.arguments.is_a?(String) ? tc.arguments : Legion::JSON.generate(tc.arguments || {})
+
+              {
+                id: tc.id,
+                type: 'function',
+                function: { name: tc.name, arguments: args }
+              }
+            end
+          end
+
+          # Extracted from OpenAICompatible mixin response parsing
+
+          def extract_thinking_from_message(message)
+            metadata = {
+              reasoning_content: message['reasoning_content'],
+              reasoning: message['reasoning'],
+              thinking: message['thinking'],
+              thinking_text: message['thinking_text'],
+              thinking_signature: message['thinking_signature'],
+              reasoning_signature: message['reasoning_signature']
+            }.compact
+
+            extraction = Llm::Responses::ThinkingExtractor.extract(
+              message['content'],
+              metadata: metadata
+            )
+
+            [
+              extraction.content || '',
+              Canonical::Thinking.from_hash(
+                content: extraction.thinking,
+                signature: extraction.signature
+              )
+            ]
+          end
+
+          def parse_tool_calls(raw)
+            return [] unless raw&.any?
+
+            Array(raw).flat_map do |call|
+              function = call.fetch('function', {})
+              args = parse_tool_arguments(function['arguments'])
+
+              Canonical::ToolCall.build(
+                id: call['id'],
+                name: function['name'],
+                arguments: args,
+                source: :client
+              )
+            end.compact
+          end
+
+          def parse_tool_arguments(arguments)
+            return {} if arguments.nil? || arguments == ''
+            return arguments if arguments.is_a?(Hash)
+
+            Legion::JSON.load(arguments)
+          rescue Legion::JSON::ParseError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'openai.translator.parse_tool_arguments')
+            {}
+          end
+
+          def parse_usage(raw)
+            return nil unless raw&.any?
+
+            normalized = raw.dup
+            normalized[:cache_read_tokens] ||= extract_nested_cached_tokens(raw)
+            normalized[:thinking_tokens] ||= extract_nested_reasoning_tokens(raw)
+            Canonical::Usage.from_hash(normalized)
+          end
+
+          def extract_nested_cached_tokens(raw)
+            raw.dig(:prompt_tokens_details, :cached_tokens) ||
+              raw.dig('prompt_tokens_details', 'cached_tokens') ||
+              raw.dig(:input_tokens_details, :cached_tokens) ||
+              raw.dig('input_tokens_details', 'cached_tokens')
+          end
+
+          def extract_nested_reasoning_tokens(raw)
+            raw.dig(:completion_tokens_details, :reasoning_tokens) ||
+              raw.dig('completion_tokens_details', 'reasoning_tokens') ||
+              raw.dig(:output_tokens_details, :reasoning_tokens) ||
+              raw.dig('output_tokens_details', 'reasoning_tokens')
+          end
+
+          def map_stop_reason(raw)
+            return nil unless raw
+
+            mapped = STOP_REASON_MAP.fetch(raw.to_s, nil)
+            mapped || raw.to_sym
+          end
+
+          def extract_response_metadata(message)
+            {
+              reasoning: message['reasoning'],
+              reasoning_content: message['reasoning_content']
+            }.compact
+          end
+
+          def parse_error_chunk(data)
+            Canonical::Chunk.error_chunk(
+              error: data['error'].to_s,
+              request_id: data['id']
+            )
+          end
+
+          def build_done_chunk(data, finish_reason, usage_raw)
+            Canonical::Chunk.done(
+              request_id: data['id'],
+              stop_reason: map_stop_reason(finish_reason),
+              usage: parse_usage(usage_raw)
+            )
+          end
+
+          def build_thinking_chunk(reasoning, request_id)
+            Canonical::Chunk.thinking_delta(
+              delta: reasoning,
+              request_id: request_id
+            )
+          end
+
+          def build_text_chunk(content, request_id)
+            Canonical::Chunk.text_delta(
+              delta: content,
+              request_id: request_id
+            )
+          end
+
+          def parse_tool_call_delta(delta, data)
+            raw_tc = delta['tool_calls']
+            return nil unless raw_tc&.any?
+
+            tc = Array(raw_tc).first || {}
+            func = tc['function'] || {}
+
+            tool_call = Canonical::ToolCall.build(
+              id: tc['id'],
+              name: func['name'],
+              arguments: parse_tool_arguments(func['arguments'])
+            )
+
+            Canonical::Chunk.tool_call_delta(
+              tool_call: tool_call,
+              request_id: data['id']
+            )
+          end
+
+          # Format detection - conformance kit passes canonical-form fixtures;
+          # real usage sends OpenAI wire format. Detect and handle both.
+          def canonical_form?(hash)
+            h = hash.is_a?(Hash) ? hash.transform_keys(&:to_sym) : {}
+            !h[:text].nil? || !h[:stop_reason].nil? || !h[:tool_calls].nil? || !h[:thinking].nil?
+          end
+
+          def canonical_chunk_form?(hash)
+            h = hash.is_a?(Hash) ? hash.transform_keys(&:to_sym) : {}
+            !h[:type].nil?
+          end
+        end
+        # rubocop:enable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/openai/version.rb

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Openai
-        VERSION = '0.3.11'
+        VERSION = '0.4.4'
       end
     end
   end

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

@@ -2,7 +2,9 @@
 
 require 'legion/extensions/llm'
 require 'legion/extensions/llm/openai/provider'
+require 'legion/extensions/llm/openai/translator'
 require 'legion/extensions/llm/openai/version'
+require_relative 'openai/actors/discovery_refresh'
 
 module Legion
   module Extensions
@@ -39,10 +41,7 @@ module Legion
               fleet: {
                 enabled: false,
                 respond_to_requests: false,
-                capabilities: %i[chat stream_chat embed image],
-                lanes: [],
-                concurrency: 4,
-                queue_suffix: nil
+                capabilities: %i[chat stream_chat embed image]
               }
             }
           )
@@ -134,8 +133,7 @@ module Legion
           config.except(:api_key, :organization_id, :project_id)
         end
 
-        Legion::Extensions::Llm::Configuration.register_provider_options(Provider.configuration_options) if
-          Legion::Extensions::Llm::Configuration.respond_to?(:register_provider_options)
+        Legion::Extensions::Llm::Configuration.register_provider_options(Provider.configuration_options)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-openai
 version: !ruby/object:Gem::Version
-  version: 0.3.11
+  version: 0.4.4
 platform: ruby
 authors:
 - LegionIO
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.3
+        version: 0.5.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.4.3
+        version: 0.5.0
 description: OpenAI provider integration for the LegionIO LLM routing framework.
 email:
 - matthewdiverson@gmail.com
@@ -101,6 +101,7 @@ files:
 - lib/legion/extensions/llm/openai/actors/fleet_worker.rb
 - lib/legion/extensions/llm/openai/provider.rb
 - lib/legion/extensions/llm/openai/runners/fleet_worker.rb
+- lib/legion/extensions/llm/openai/translator.rb
 - lib/legion/extensions/llm/openai/version.rb
 homepage: https://github.com/LegionIO/lex-llm-openai
 licenses: