RubyGems - lex-llm-openai - Versions diffs - 0.3.10 → 0.4.1 - Mend

lex-llm-openai 0.3.10 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

checksums.yaml +4 -4
data/.rubocop.yml +4 -2
data/CHANGELOG.md +13 -0
data/Gemfile +1 -2
data/README.md +214 -59
data/lex-llm-openai.gemspec +1 -1
data/lib/legion/extensions/llm/openai/actors/discovery_refresh.rb +48 -0
data/lib/legion/extensions/llm/openai/provider.rb +7 -1
data/lib/legion/extensions/llm/openai/translator.rb +437 -0
data/lib/legion/extensions/llm/openai/version.rb +1 -1
data/lib/legion/extensions/llm/openai.rb +1 -0
metadata +5 -3

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35f7b923651392686a2c504e6ec30249ee8efa6c3f51c7171e18a11d124bc1d8
-  data.tar.gz: 7bc891da29aee08bb0bfa4600cd7cea7f0562703b210774d67b543682715143a
+  metadata.gz: 1e0bcb314dd98bb72b108f3f92a05ceb40dd8fc125e3972712674537e5baa2a9
+  data.tar.gz: b9fd92e6d25f2e9949fa5b5e1a7d79f8d9ed04a197b873a0b754d309dc30aef6
 SHA512:
-  metadata.gz: 2efc2485c6e46d476c654cab015262030455c366546a649011e16be3fc4e0613d1d46d45ff5122d68a7335612bda14c9cebee0cff37012bfce7ee2df1a35687f
-  data.tar.gz: 72c4c111bf0c447e0e8646067508382e52524de22f66381824f143f8717edbadf17d424ff12c4935c773e670d8a46aa8e0a2a2c5307f648fbc33ebeaf2b230d8
+  metadata.gz: 4e3886489304539fda6fe6566aa7f596682bcd480944822eebf473ff638a0c3f47b8f88243444afaf3e2ccd58a6b1699c4918b627eb859fcef7a409884536294
+  data.tar.gz: efaaea62fada60fe7f598426c59028d6461ad6afb5c935d9e3a77b43b22a6d9ae0e76577ae75a9b5e96b40f6f9bff8cc1dbf881a082fab3a88c93f00516bfd67

data/.rubocop.yml CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,5 +1,18 @@
 # Changelog
+## 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`).
 ## 0.3.10 - 2026-05-21
 - api_base reads from settings[:endpoint] fallback

data/Gemfile CHANGED Viewed

@@ -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 resolved from rubygems (>= 0.5.0) via gemspec - no local path dep
 end
 gemspec

data/README.md CHANGED Viewed

@@ -2,53 +2,138 @@
 LegionIO LLM provider extension for OpenAI.
-This gem lives under `Legion::Extensions::Llm::Openai` and depends on `lex-llm >= 0.4.3` for shared provider-neutral routing, response normalization, fleet envelopes, fleet responder execution, and schema primitives.
+This gem provides the `:openai` provider family implementation, enabling LegionIO to route chat, streaming, embedding, moderation, image, and audio requests to OpenAI-compatible APIs through the shared `lex-llm` provider contract.
-Load it with `require 'legion/extensions/llm/openai'`.
+**Namespace:** `Legion::Extensions::Llm::Openai`
+**Version:** 0.3.11
+**Load:** `require 'legion/extensions/llm/openai'`
+## Quick Start
+```ruby
+require 'legion/extensions/llm/openai'
+# Configure via the shared LLM configuration API
+Legion::Extensions::Llm.configure do |config|
+  config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
+  config.default_model = "gpt-5.5"
+end
+# Use through the standard provider interface
+provider = Legion::Extensions::Llm::Openai::Provider.new
+provider.chat(model: "gpt-5.5", messages: [{ role: "user", content: "Hello" }])
+```
 ## What It Provides
-- OpenAI provider discovery under the `:openai` provider family
-- Chat completions via `POST /v1/chat/completions`
-- Streaming chat completions (same endpoint, `stream: true`)
-- Model discovery via `GET /v1/models`
-- Model retrieval via `GET /v1/models/{model}`
-- Embeddings via `POST /v1/embeddings`
-- Moderation via `POST /v1/moderations`
-- Image generation via `POST /v1/images/generations`
-- Image editing via `POST /v1/images/edits`
-- Image variation via `POST /v1/images/variations`
-- Audio transcription via `POST /v1/audio/transcriptions`
-- Streaming token usage reporting (`stream_usage_supported?`)
-- Shared OpenAI-compatible request/response mapping via `Legion::Extensions::Llm::Provider::OpenAICompatible`
-- Normalized chat, embedding, moderation, image, and audio capability mapping for discovered models
-- Shared fleet/default settings via `Legion::Extensions::Llm.provider_settings`
-- Best-effort `llm.registry` availability event publishing for discovered models
-- Provider-owned fleet request handling through `Legion::Extensions::Llm::Fleet::ProviderResponder`
+| Capability | Endpoint | Notes |
+|---|---|---|
+| Chat completions | `POST /v1/chat/completions` | Includes function calling, vision, structured output |
+| Streaming chat | Same endpoint, `stream: true` | Token usage reported via `stream_usage_supported?` |
+| Model listing | `GET /v1/models` | Enriched with static capability map; publishes registry events |
+| Model retrieval | `GET /v1/models/{model}` | |
+| Embeddings | `POST /v1/embeddings` | |
+| Moderation | `POST /v1/moderations` | |
+| Image generation | `POST /v1/images/generations` | |
+| Image editing | `POST /v1/images/edits` | |
+| Image variation | `POST /v1/images/variations` | |
+| Audio transcription | `POST /v1/audio/transcriptions` | Whisper, gpt-4o-transcribe |
 ## Architecture
 ```
 Legion::Extensions::Llm::Openai
-|-- Provider                              # OpenAI provider implementation (chat, models, embeddings, etc.)
-|   `-- Capabilities                      # Model family capability predicates
-|-- Actor::FleetWorker                    # Subscription actor gate for provider-owned fleet requests
-`-- Runners::FleetWorker                  # Delegates request execution to lex-llm ProviderResponder
+|-- Openai                              # Root module — settings, discovery, auto-registration
+|   |-- default_settings                # Provider family defaults (endpoint, models, fleet)
+|   |-- discover_instances              # Credential scanning across env, Codex, Claude, settings
+|   |-- normalize_instance_config       # Normalizes generic keys to canonical OpenAI keys
+|   `-- sanitize_instance_config        # Strips temporary credential fields
+|
+|-- Provider                            # OpenAI provider implementation
+|   |-- Capabilities                    # Model family predicates (chat?, streaming?, vision?, etc.)
+|   |-- CAPABILITY_MAP                  # Static capability matrix for 14 known model families
+|   |-- list_models                     # Enriches raw API response with capability metadata
+|   |-- retrieve_model                  # Fetches single model detail
+|   |-- chat_url, models_url, etc.      # Endpoint builders
+|   `-- maybe_normalize_temperature     # Adjusts temperature for o*/gpt-5 reasoning models
+|
+|-- Actor::FleetWorker                  # Subscription actor for fleet request consumption
+|   |-- enabled?                        # Checks if any instance has respond_to_requests: true
+|   `-- Delegates to lex-llm ProviderResponder
+|
+|-- Actor::DiscoveryRefresh             # Periodic actor that refreshes the model discovery cache
+|   |-- time                            # Reads discovery_interval from settings (default 1800s)
+|   `-- Calls Legion::LLM::Discovery.refresh_discovered_models!
+|
+`-- Runners::FleetWorker                # Execution entrypoint for fleet requests
+    `-- handle_fleet_request            # Routes to lex-llm ProviderResponder.call
 ```
-Registry publishing, event envelope construction, fleet protocol handling, and fleet response/error transport live in `lex-llm`. This provider intentionally does not depend on `legion-llm` at runtime.
+### Design Boundaries
-## Observability
+- **Response normalization, request payload mapping** lives in `Lex-llm::Provider::OpenAICompatible` (mixed in)
+- **Fleet responder logic** (ack/reject, response publication) lives in `Lex-llm::Fleet::ProviderResponder`
+- **Registry event publishing** is delegated to `Lex-llm::RegistryPublisher`
+- This extension depends **only** on `lex-llm` at runtime; it does not depend on `legion-llm`
-The provider and root extension namespace use `Legion::Logging::Helper` for:
+## Instance Discovery
-- Structured `handle_exception` calls on every rescue block
-- Info-level action logging for model listing, model retrieval, and registry publishing
-- Automatic log segment derivation and component type tagging
+`Openai.discover_instances` scans 7 credential sources, deduplicates by key, and injects `default_model`:
-Fleet actor and runner code stays thin and delegates execution, ack/reject handling, and response publication to the shared `lex-llm` responder helper.
+| Priority | Source | Key |
+|---|---|---|
+| 1 | `OPENAI_API_KEY` environment variable | `:env` |
+| 2 | `CODEX_API_KEY` environment variable | `:codex_env` |
+| 3 | Codex bearer token (`~/.codex/auth.json`) | `:codex` |
+| 4 | Codex OpenAI key (`~/.codex/auth.json`) | `:codex_key` |
+| 5 | Claude config (`openaiApiKey`) | `:claude` |
+| 6 | Extension settings (`extensions.llm.openai`) | `:settings` |
+| 7 | Named instances in extension settings | Named keys |
+## Configuration
+### Via Legion Settings (YAML)
+```yaml
+extensions:
+  llm:
+    openai:
+      api_key: "sk-..."
+      default_model: "gpt-5.5"
+      endpoint: "https://api.openai.com"
+      discovery_interval: 1800    # Seconds between model list refresh (used by DiscoveryRefresh actor)
+      instances:
+        primary:
+          openai_api_key: "sk-..."
+          openai_api_base: "https://api.openai.com"
+          fleet:
+            enabled: true
+            respond_to_requests: true
+            capabilities:
+              - chat
+              - stream_chat
+              - embed
+              - image
+```
-## Defaults
+### Via Ruby Configuration API
+```ruby
+Legion::Extensions::Llm.configure do |config|
+  config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
+  config.openai_api_base = nil                     # defaults to https://api.openai.com
+  config.openai_organization_id = nil              # optional OpenAI-Organization header
+  config.openai_project_id = nil                   # optional OpenAI-Project header
+  config.openai_use_system_role = true             # include system messages in requests
+  config.default_model = "gpt-5.5"
+  config.default_embedding_model = "text-embedding-3-small"
+  config.default_moderation_model = "omni-moderation-latest"
+  config.default_image_model = "gpt-image-1"
+  config.default_transcription_model = "gpt-4o-transcribe"
+end
+```
+### Default Settings
 ```ruby
 Legion::Extensions::Llm::Openai.default_settings
@@ -57,45 +142,78 @@ Legion::Extensions::Llm::Openai.default_settings
 #   instances: {
 #     default: {
 #       endpoint: "https://api.openai.com",
+#       default_model: "gpt-5.5",
 #       tier: :frontier,
 #       transport: :http,
-#       credentials: { api_key: "env://OPENAI_API_KEY" },
-#       usage: { inference: true, embedding: true, moderation: true, image: true, audio: true },
-#       limits: { concurrency: 4 }
+#       credentials: {
+#         api_key: "env://OPENAI_API_KEY",
+#         organization_id: nil,
+#         project_id: nil
+#       },
+#       usage: {
+#         inference: true,
+#         embedding: true,
+#         moderation: true,
+#         image: true,
+#         audio: true
+#       },
+#       limits: { concurrency: 4 },
+#       fleet: {
+#         enabled: false,
+#         respond_to_requests: false,
+#         capabilities: [:chat, :stream_chat, :embed, :image],
+#         lanes: [],
+#         concurrency: 4,
+#         queue_suffix: nil
+#       }
 #     }
 #   }
 # }
 ```
-## Configuration
+## Model Capability Map
-```ruby
-Legion::Extensions::Llm.configure do |config|
-  config.openai_api_key = ENV.fetch("OPENAI_API_KEY")
-  config.openai_api_base = nil                          # defaults to https://api.openai.com
-  config.openai_organization_id = nil                   # optional OpenAI-Organization header
-  config.openai_project_id = nil                        # optional OpenAI-Project header
-  config.default_model = "gpt-5.2"
-  config.default_embedding_model = "text-embedding-3-small"
-  config.default_moderation_model = "omni-moderation-latest"
-  config.default_image_model = "gpt-image-1"
-  config.default_transcription_model = "gpt-4o-transcribe"
-end
-```
+The provider maintains a static `CAPABILITY_MAP` covering 14 OpenAI model families. Each entry declares capabilities, input/output modalities, and context window size.
-## Dependencies
+| Prefix | Capabilities | Input | Output | Context |
+|---|---|---|---|---|
+| `gpt-4o` | completion, streaming, function_calling, vision, structured_output | text, image, audio | text | 128K |
+| `gpt-4.1` | completion, streaming, function_calling, vision, structured_output | text, image | text | 1M |
+| `gpt-4` | completion, streaming, function_calling, vision | text, image | text | 128K |
+| `gpt-5` | completion, streaming, function_calling, vision, structured_output, reasoning | text, image | text | 1M |
+| `o4` | completion, streaming, function_calling, vision, reasoning | text, image | text | 200K |
+| `o3` | completion, streaming, function_calling, vision, reasoning | text, image | text | 200K |
+| `o1` | completion, streaming, function_calling, vision, reasoning | text, image | text | 200K |
+| `text-embedding-*` | embedding | text | embeddings | 8K |
+| `omni-moderation` | moderation | text, image | moderation | - |
+| `text-moderation` | moderation | text | moderation | - |
+| `gpt-image` | image_generation | text, image | image | - |
+| `dall-e` | image_generation | text | image | - |
+| `whisper` | audio_transcription | audio | text | - |
+| `tts` | audio_generation | text | audio | - |
-| Gem | Purpose |
-|-----|---------|
-| `lex-llm` (>= 0.4.3) | Shared provider contract, response normalization, fleet settings, routing, and fleet responder execution |
-| `legion-transport` (>= 1.4.14) | AMQP subscriptions and replies |
-| `legion-json` (>= 1.2.1) | JSON serialization |
-| `legion-logging` (>= 1.3.2) | Structured logging via Helper |
-| `legion-settings` (>= 1.3.14) | Configuration management |
+Unknown models default to `{ capabilities: [:completion, :streaming], modalities: { input: ["text"], output: ["text"] } }`.
+## Capability Predicates
+`Provider::Capabilities` provides module functions for model routing decisions:
+| Method | Matches |
+|---|---|
+| `chat?(model)` | Any model that is not embedding, moderation, image, audio, tts, realtime, or sora |
+| `streaming?(model)` | Same as `chat?` |
+| `functions?(model)` | Models starting with `gpt` or `o\d` |
+| `vision?(model)` | Models starting with `gpt`, `o\d`, or `omni-moderation` |
+| `embeddings?(model)` | Models starting with `text-embedding-` |
+| `moderation?(model)` | Models containing `moderation` |
+| `images?(model)` | Models starting with `gpt-image` or `dall-e` |
+| `audio_transcription?(model)` | Models matching `gpt-4o.*transcribe` or `whisper` |
 ## 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 the runner delegates execution to `Legion::Extensions::Llm::Fleet::ProviderResponder` from `lex-llm`.
+Provider instances can opt in to consuming Legion LLM fleet requests via the shared `ProviderResponder`. The fleet actor starts automatically when any instance has `respond_to_requests: true`.
+### Fleet YAML Configuration
 ```yaml
 extensions:
@@ -113,12 +231,49 @@ extensions:
               - image
 ```
+### Fleet Components
+| Class | Role |
+|---|---|
+| `Actor::FleetWorker` | Subscription actor; checks `enabled?` against discovered instances |
+| `Runners::FleetWorker.handle_fleet_request` | Execution entrypoint; delegates to `ProviderResponder.call` |
+## Observability
+All classes include `Legion::Logging::Helper`:
+- **Structured error handling:** Every `rescue` calls `handle_exception` with operation context
+- **Debug-level request telemetry:** Model listing, retrieval, fleet dispatch, discovery refresh
+- **Info-level action logging:** Registry publishing, instance discovery results
+- **Automatic segment derivation:** Log lines tagged with provider family and component type
+## Dependencies
+| Gem | Purpose |
+|-----|---------|
+| `lex-llm` (>= 0.4.3) | Provider contract, OpenAICompatible mixin, fleet responder, registry publisher |
+| `legion-transport` (>= 1.4.14) | AMQP subscriptions and replies |
+| `legion-json` (>= 1.2.1) | JSON serialization |
+| `legion-logging` (>= 1.3.2) | Structured logging |
+| `legion-settings` (>= 1.3.14) | Configuration management |
+## Key Files
+| File | Purpose |
+|------|---------|
+| `lib/legion/extensions/llm/openai.rb` | Root module, settings, instance discovery, auto-registration |
+| `lib/legion/extensions/llm/openai/provider.rb` | Provider implementation, capability map, API methods |
+| `lib/legion/extensions/llm/openai/actors/discovery_refresh.rb` | Periodic model cache refresh actor |
+| `lib/legion/extensions/llm/openai/actors/fleet_worker.rb` | Fleet request subscription actor |
+| `lib/legion/extensions/llm/openai/runners/fleet_worker.rb` | Fleet request execution runner |
+| `lib/legion/extensions/llm/openai/version.rb` | Version constant |
 ## Development
 ```bash
 bundle install
-bundle exec rspec --format json --out tmp/rspec_results.json --format progress --out tmp/rspec_progress.txt
-bundle exec rubocop -A
+bundle exec rspec
+bundle exec rubocop
 ```
 ## License

data/lex-llm-openai.gemspec CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 Openai
+        module Actor
+          # Periodically refreshes the OpenAI model discovery cache.
+          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, :openai, :discovery_interval) || REFRESH_INTERVAL
+            end
+            def manual
+              log.debug('[openai][discovery_refresh] refreshing model list')
+              return unless defined?(Legion::LLM::Discovery)
+              Legion::LLM::Discovery.refresh_discovered_models!(provider: :openai)
+            rescue StandardError => e
+              handle_exception(e, level: :warn, handled: true, operation: 'openai.actor.discovery_refresh')
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -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

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

@@ -0,0 +1,437 @@
+# 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)
+            Array(tool_calls).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?
+            Canonical::Usage.from_hash(raw)
+          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 CHANGED Viewed

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Openai
-        VERSION = '0.3.10'
+        VERSION = '0.4.1'
       end
     end
   end

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

@@ -2,6 +2,7 @@
 require 'legion/extensions/llm'
 require 'legion/extensions/llm/openai/provider'
+require 'legion/extensions/llm/openai/translator'
 require 'legion/extensions/llm/openai/version'
 module Legion

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-openai
 version: !ruby/object:Gem::Version
-  version: 0.3.10
+  version: 0.4.1
 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
@@ -97,9 +97,11 @@ files:
 - README.md
 - lex-llm-openai.gemspec
 - lib/legion/extensions/llm/openai.rb
+- lib/legion/extensions/llm/openai/actors/discovery_refresh.rb
 - 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: