lex-llm 0.6.8 → 0.6.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5613f655c5743be588ec5030535de96dc998cb8f03ffb8f8b2be21c95dc55b84
-  data.tar.gz: cba342c0f0662d7612b2d8647791149ddb716878e79e487e84a640dbcd3582cc
+  metadata.gz: e441fc6b1e568e1e7cde529aecb14655cfc6df845accdfbf706cade536faa25e
+  data.tar.gz: fa14725026a56fe266e5c7b4be232fc1b750bf35293830514a6ad103b1da3abc
 SHA512:
-  metadata.gz: b2eb4840e8f1f39d65690dc9226387d6fecbcc9352845cc796d2421b56b660fddae35e2373abdbb88e5c3b127a5b5a6ba621c33682762bbf2eeb271809ec2beb
-  data.tar.gz: 7cce383baa60095d03479240c16076624706d56d605200efee5943d3de290ba96c5c18c58e7ada252572966657d846107a3f55945d9f95aa278f553c31ac82a2
+  metadata.gz: f14ac394687d2059d90562529518085a4cced1732e9baa85c5847ad2fffd4ea89efeb735167ebae6533d4b335f9ddd7fcc8982c0bdac137add3d35a48010b19e
+  data.tar.gz: ed81c83224bdcbbf18b0b4fc6f8b9e2bf0886ed44d80a2dde363d4920a3a4957d4f56f34429b6ea7b7fd5ba96fd4a5b5e60fb9bc0e59cca556b1ed11e7314080

data/.rubocop.yml

@@ -51,3 +51,6 @@ RSpec/LeakyLocalVariable:
 RSpec/SpecFilePathFormat:
   Exclude:
     - 'spec/legion/extensions/llm/conformance/**/*'
+
+Style/ArrayIntersect:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.6.10 - 2026-07-09
+
+### Added
+- `ThinkingConfig#resolved_budget` and `#resolved_effort` — cross-axis derivation so provider translators get whichever thinking axis they need (Anthropic `budget_tokens` vs OpenAI `effort`) even when the client supplied only the other. A client dialect supplies only one axis (Anthropic = budget only; OpenAI = effort only), so a single `EFFORT_BUDGET` map (SSOT) drives the conversion in both directions: effort -> budget is exact (`low` = 1024, `medium` = 8192, `high` = 16384), budget -> effort maps by band boundary. Explicitly-set values always win over derivation, and both accessors return `nil` when neither axis is configured. `to_h` stays faithful to what was actually set (no fabrication). This is the foundation for fixing thinking being silently dropped on cross-provider routes (e.g. a Claude budget request routed to OpenAI effort).
+
+## 0.6.9 - 2026-07-05
+
+### Added
+- `StopReasonMapping` mixin (`legion/extensions/llm/stop_reason_mapping`) — a shared stop_reason vocabulary included by provider translators (and available to legion-llm, which depends on lex-llm). Keys are incoming provider wire strings, values are the canonical `stop_reason` symbol. Provider wire formats spell the same six canonical end-states differently (OpenAI/vLLM emit `tool_calls`, Anthropic `tool_use`; `stop`/`end_turn`/`eos` all mean the same thing), so the common vocabulary now lives in one place instead of being copy-pasted (and drifting) across provider gems.
+  - `#stop_reason_map` — the common vocabulary, inherited by all.
+  - `#stop_reason_map_additions` — returns `{}` in the base; a provider overrides it to ADD provider-specific strings (merged on top, additions win on collision). No guards needed.
+  - `#stop_reason_lookup(key)` — merges additions over the map, coerces the key via `to_s`, returns the canonical symbol or `nil` (caller decides the default). To REPLACE the whole vocabulary, a provider overrides `#stop_reason_map`.
+
 ## 0.6.8 - 2026-07-03
 
 ### Changed

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

@@ -50,6 +50,16 @@ module Legion
         # Mirrors lex-llm Thinking::Config.
         class ThinkingConfig
           INCLUDES = Thinking
+
+          # SSOT for the effort<->budget conversion. A client dialect supplies only
+          # ONE axis (Anthropic = budget_tokens only; OpenAI = effort only), but a
+          # provider translator may need the OTHER. This single map lets every
+          # provider ask for whichever axis it needs and always get a usable value,
+          # so thinking survives any client x provider pair (best-effort, never
+          # silently dropped). effort -> budget is exact; budget -> effort uses the
+          # band boundaries below.
+          EFFORT_BUDGET = { 'low' => 1024, 'medium' => 8192, 'high' => 16_384 }.freeze
+
           attr_reader :effort, :budget
 
           def initialize(effort: nil, budget: nil)
@@ -70,7 +80,8 @@ module Legion
             build(effort: h[:effort], budget: h[:budget])
           end
 
-          # Serialize to a Hash for AMQP/fleet/wire transport.
+          # Serialize to a Hash for AMQP/fleet/wire transport. Faithful to what was
+          # SET — never fabricates the missing axis (use resolved_* for that).
           def to_h
             { effort: effort, budget: budget }.compact
           end
@@ -79,6 +90,30 @@ module Legion
           def enabled?
             !effort.nil? || !budget.nil?
           end
+
+          # Budget for a provider that needs a token budget (e.g. Anthropic),
+          # derived from effort when budget was not explicitly set. nil only when
+          # neither axis is configured.
+          def resolved_budget
+            return budget unless budget.nil?
+            return nil if effort.nil?
+
+            EFFORT_BUDGET[effort.to_s.downcase] || EFFORT_BUDGET['medium']
+          end
+
+          # Effort for a provider that needs an effort level (e.g. OpenAI),
+          # derived from budget when effort was not explicitly set. nil only when
+          # neither axis is configured.
+          def resolved_effort
+            return effort unless effort.nil?
+            return nil if budget.nil?
+
+            b = budget.to_i
+            if b < EFFORT_BUDGET['medium'] then 'low'
+            elsif b < EFFORT_BUDGET['high'] then 'medium'
+            else 'high'
+            end
+          end
         end
 
         # Alias for convenience: Canonical::Thinking::Config

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Shared stop_reason vocabulary, included by every provider translator (and
+      # available to legion-llm, which depends on lex-llm). Provider wire formats
+      # spell the same canonical end-states differently — OpenAI/vLLM emit
+      # "tool_calls", Anthropic "tool_use", and "stop"/"end_turn"/"eos" all mean
+      # the same thing. This puts the common vocabulary in one place so it is not
+      # copy-pasted (and drifting) across five provider gems.
+      #
+      # Keys are the incoming provider strings; values are the canonical
+      # stop_reason (see Canonical::Response::STOP_REASONS).
+      #
+      # Provider overrides, all by plain method definition — no guards:
+      #   * ADD provider-specific strings  → override #stop_reason_map_additions
+      #   * REPLACE the whole vocabulary   → override #stop_reason_map
+      module StopReasonMapping
+        # The common vocabulary every provider inherits for free.
+        def stop_reason_map
+          {
+            'stop' => :end_turn,
+            'end_turn' => :end_turn,
+            'eos' => :end_turn,
+            'complete' => :end_turn,
+            'tool_calls' => :tool_use,
+            'tool_call' => :tool_use,
+            'tool_use' => :tool_use,
+            'function_call' => :tool_use,
+            'length' => :max_tokens,
+            'max_tokens' => :max_tokens,
+            'stop_sequence' => :stop_sequence,
+            'stop_sequences' => :stop_sequence,
+            'content_filter' => :content_filter,
+            'error' => :error
+          }
+        end
+
+        # Provider-specific additions, merged on top of the common map. Base
+        # returns {} so callers never need an "if defined?" guard. Additions win
+        # over the common map on key collision.
+        def stop_reason_map_additions
+          {}
+        end
+
+        # Resolve a provider wire stop_reason string to its canonical symbol, or
+        # nil when unmapped (the caller decides the default — usually :end_turn).
+        def stop_reason_lookup(key)
+          stop_reason_map.merge(stop_reason_map_additions).fetch(key.to_s, nil)
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.6.8'
+      VERSION = '0.6.10'
     end
   end
 end

data/lib/legion/extensions/llm.rb

@@ -82,6 +82,7 @@ module Legion
 
       # --- Provider base & allied modules ---
       require_relative 'llm/provider_contract'
+      require_relative 'llm/stop_reason_mapping'
       require_relative 'llm/provider_settings'
       require_relative 'llm/provider'
 

data/spec/legion/extensions/llm/canonical/thinking_spec.rb

@@ -147,5 +147,43 @@ RSpec.describe Legion::Extensions::Llm::Canonical::Thinking do
         expect(config.to_h).to eq(effort: 'low')
       end
     end
+
+    # SSOT / one-oracle for cross-provider thinking (NxN best-effort): a client
+    # dialect supplies only ONE axis (Anthropic = budget_tokens only, OpenAI =
+    # effort only). Every provider translator must still get a usable value for
+    # whichever axis IT needs, so thinking survives ANY client×provider pair
+    # instead of being silently dropped. The conversion lives HERE (the canonical
+    # config), not scattered/one-directional in each translator. Derived accessors
+    # do NOT mutate stored state or #to_h — they only fill the gap on read.
+    describe 'derived cross-axis accessors' do
+      it 'derives budget from effort when only effort was set' do
+        expect(config_class.build(effort: 'low').resolved_budget).to eq(1024)
+        expect(config_class.build(effort: 'medium').resolved_budget).to eq(8192)
+        expect(config_class.build(effort: 'high').resolved_budget).to eq(16_384)
+      end
+
+      it 'derives effort from budget by band (< medium=low, < high=medium, else high)' do
+        expect(config_class.build(budget: 500).resolved_effort).to eq('low') # < 8192
+        expect(config_class.build(budget: 10_000).resolved_effort).to eq('medium') # 8192..16383
+        expect(config_class.build(budget: 20_000).resolved_effort).to eq('high') # >= 16384
+      end
+
+      it 'prefers the explicitly-set value over derivation' do
+        c = config_class.build(effort: 'high', budget: 2048)
+        expect(c.resolved_budget).to eq(2048)
+        expect(c.resolved_effort).to eq('high')
+      end
+
+      it 'returns nil derivations when neither axis is set' do
+        c = config_class.build
+        expect(c.resolved_budget).to be_nil
+        expect(c.resolved_effort).to be_nil
+      end
+
+      it 'does not fabricate the missing axis in to_h (stored state stays faithful)' do
+        expect(config_class.build(effort: 'high').to_h).to eq(effort: 'high')
+        expect(config_class.build(budget: 2048).to_h).to eq(budget: 2048)
+      end
+    end
   end
 end

data/spec/legion/extensions/llm/stop_reason_mapping_spec.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+# Shared stop_reason vocabulary. Provider wire formats spell the same six
+# canonical end-states differently (OpenAI/vLLM: "tool_calls"; Anthropic:
+# "tool_use"; "stop" vs "end_turn" vs "eos"). Before this module, every
+# provider translator carried its own copy-pasted *_STOP_REASON_MAP, which
+# drifted — vllm/ollama mapped only "tool_use" and silently fell back to
+# :end_turn on the "tool_calls" that OpenAI-compatible backends actually send.
+#
+# StopReasonMapping puts the common vocabulary in one place (inherited by all)
+# with a provider-overridable additions hook and a full-replace hook.
+RSpec.describe Legion::Extensions::Llm::StopReasonMapping do
+  let(:host_class) do
+    Class.new { include Legion::Extensions::Llm::StopReasonMapping }
+  end
+  let(:host) { host_class.new }
+
+  describe 'the common vocabulary (#stop_reason_lookup)' do
+    it 'maps OpenAI/vLLM "tool_calls" to :tool_use' do
+      expect(host.stop_reason_lookup('tool_calls')).to eq(:tool_use)
+    end
+
+    it 'maps Anthropic "tool_use" to :tool_use' do
+      expect(host.stop_reason_lookup('tool_use')).to eq(:tool_use)
+    end
+
+    it 'maps "stop"/"end_turn"/"eos" to :end_turn' do
+      expect(host.stop_reason_lookup('stop')).to eq(:end_turn)
+      expect(host.stop_reason_lookup('end_turn')).to eq(:end_turn)
+      expect(host.stop_reason_lookup('eos')).to eq(:end_turn)
+    end
+
+    it 'maps "length"/"max_tokens" to :max_tokens' do
+      expect(host.stop_reason_lookup('length')).to eq(:max_tokens)
+      expect(host.stop_reason_lookup('max_tokens')).to eq(:max_tokens)
+    end
+
+    it 'coerces non-string keys via to_s' do
+      expect(host.stop_reason_lookup(:tool_calls)).to eq(:tool_use)
+    end
+
+    it 'returns nil for an unmapped key (caller decides the default)' do
+      expect(host.stop_reason_lookup('totally_unknown')).to be_nil
+    end
+  end
+
+  describe 'provider additions (#stop_reason_map_additions)' do
+    it 'base returns {} so no guard is ever needed' do
+      expect(host.stop_reason_map_additions).to eq({})
+    end
+
+    it 'a provider adds provider-specific strings on top of the common map' do
+      bedrock_like = Class.new do
+        include Legion::Extensions::Llm::StopReasonMapping
+
+        def stop_reason_map_additions
+          { 'guardrail_intervened' => :content_filter }
+        end
+      end.new
+
+      # addition resolves
+      expect(bedrock_like.stop_reason_lookup('guardrail_intervened')).to eq(:content_filter)
+      # common vocabulary still inherited
+      expect(bedrock_like.stop_reason_lookup('tool_calls')).to eq(:tool_use)
+    end
+
+    it 'additions win over the common map on key collision' do
+      override = Class.new do
+        include Legion::Extensions::Llm::StopReasonMapping
+
+        def stop_reason_map_additions
+          { 'stop' => :stop_sequence }
+        end
+      end.new
+
+      expect(override.stop_reason_lookup('stop')).to eq(:stop_sequence)
+    end
+  end
+
+  describe 'full replacement (#stop_reason_map)' do
+    it 'a provider can replace the whole map, dropping the defaults' do
+      replaced = Class.new do
+        include Legion::Extensions::Llm::StopReasonMapping
+
+        def stop_reason_map
+          { 'weird_only' => :end_turn }
+        end
+      end.new
+
+      expect(replaced.stop_reason_lookup('weird_only')).to eq(:end_turn)
+      expect(replaced.stop_reason_lookup('tool_calls')).to be_nil
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.6.8
+  version: 0.6.10
 platform: ruby
 authors:
 - LegionIO
@@ -324,6 +324,7 @@ files:
 - lib/legion/extensions/llm/routing/model_offering.rb
 - lib/legion/extensions/llm/routing/offering_registry.rb
 - lib/legion/extensions/llm/routing/registry_event.rb
+- lib/legion/extensions/llm/stop_reason_mapping.rb
 - lib/legion/extensions/llm/stream_accumulator.rb
 - lib/legion/extensions/llm/streaming.rb
 - lib/legion/extensions/llm/taxonomies.rb
@@ -422,6 +423,7 @@ files:
 - spec/legion/extensions/llm/routing/model_offering_spec.rb
 - spec/legion/extensions/llm/routing/offering_registry_spec.rb
 - spec/legion/extensions/llm/routing/registry_event_spec.rb
+- spec/legion/extensions/llm/stop_reason_mapping_spec.rb
 - spec/legion/extensions/llm/stream_accumulator_spec.rb
 - spec/legion/extensions/llm/streaming_spec.rb
 - spec/legion/extensions/llm/taxonomies_spec.rb