lex-llm 0.6.4 → 0.6.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6401d7f1b284c2cee7577ff84c1ee099f5a8ae872c51e8a8410c8627c8514a16
-  data.tar.gz: 1ae7e5ff99ee54f5aae6dcc1a8cad4c65c9537d6c2ede8992cdd93d4c2933b9c
+  metadata.gz: d325676c4cc272b839d2e0ba4d678a1aab7ec05268e5e7d37ac302234d25ae4e
+  data.tar.gz: a8a2475af20b60ea5d53dc2c5da7ceb0ea2f25d8c094079df73b41cce04ea577
 SHA512:
-  metadata.gz: 7575751b784ebe46be8c03591d748fc81e62695ea3142972bc3257f72e44c1822b8d9438ed1f2958c27287f10bcb0ebe4af5081e85f08e57f6ecf10e47c6c253
-  data.tar.gz: 5a7a68f00cce655fe2912e64350c302044cbabc2bafd874d03683d40502e9edfdfc2a987bb7c591ee9d302df0e2a89cae1040c6b22f71e72f1c5700988dd57eb
+  metadata.gz: 5535f26e2755347ca1024c662eeb7e575515bfa824fe36a2f3958558d21548f393b426f0261a35f3935ccd222099ad8dedaef614af693a0b2d0a74e2353e91ae
+  data.tar.gz: 59fd2029653e72366a5384d36f34639348b12ecba38ba3e2ad19ff0a20e5ffcf6d7ea434e02fcfc8994fa0f373264efac90d532800cd3ae14f2036f10f9f64c8

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 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
+- Version bump to publish the `MeteringFlush` actor (0.6.5). Versions 0.6.5–0.6.7 tagged and created GitHub releases but never reached RubyGems: 0.6.5/0.6.6 failed `gem push` on a revoked API key, and 0.6.7 failed because the replacement API key was created with per-key MFA enabled (`gem push` prompted for an OTP a CI runner can't provide). The API key has been recreated without per-key MFA. Because the release workflow skips publishing when a version's tag/release already exists, each failed version must be superseded by a fresh one. No functional changes since 0.6.5.
+
+## 0.6.7 - 2026-07-03
+
+### Changed
+- Version bump attempting to publish the `MeteringFlush` actor. Did not reach RubyGems — the replacement API key carried a per-key MFA requirement, so `gem push` demanded an OTP (superseded by 0.6.8). No functional changes.
+
+## 0.6.6 - 2026-07-03
+
+### Changed
+- Version bump attempting to re-trigger the release pipeline. Did not publish to RubyGems — the `gem push` step failed on a revoked API key (superseded by 0.6.7). No functional changes.
+
+## 0.6.5 - 2026-07-03
+
+### Added
+- **`MeteringFlush` actor drains the LLM metering spool back into RabbitMQ.** legion-llm's `Legion::LLM::Metering` spools metering events to `~/.legionio/data/spool/metering/events.jsonl` whenever transport is down at emit time. Nothing had been draining that spool since `lex-llm-gateway` was retired, so events (chat, embeddings, skills — all funnel through `Legion::LLM::Metering.emit`) accumulated indefinitely. This `Legion::Extensions::Actors::Every` actor ticks every 60s and calls `Legion::LLM::Metering.flush_spool`, which republishes each spooled event to the `llm.metering` exchange and truncates the file. It is a no-op while transport is unavailable, so it is safe to tick continuously. Runs on every node (not a singleton) because each node owns its own spool file and must drain it locally. References legion-llm by string (`'Legion::LLM::Metering'`) so lex-llm — the lower gem — avoids a circular dependency; the constant is resolved at tick time.
+
 ## 0.6.4 - 2026-06-30
 
 ### Fixed

data/lib/legion/extensions/llm/actors/metering_flush.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Actor
+        # Periodically drains the LLM metering spool.
+        #
+        # Metering events are emitted by legion-llm's Legion::LLM::Metering. When
+        # transport is down at emit time they are appended to a durable JSONL
+        # spool (~/.legionio/data/spool/metering/events.jsonl) instead of being
+        # published to the `llm.metering` exchange. Nothing was draining that
+        # spool after lex-llm-gateway was retired, so events accumulated forever.
+        #
+        # flush_spool reads every spooled event — chat, embeddings, skills, all
+        # funnel through Legion::LLM::Metering.emit into the same file — and
+        # republishes each to the exchange, then truncates. It is a no-op when
+        # transport is unavailable, so it is safe to tick every minute.
+        #
+        # runner_class points at legion-llm (the higher gem, always loaded at
+        # full boot). lex-llm must not require legion-llm — that would be circular
+        # (legion-llm depends on lex-llm) — so we reference it by string and let
+        # the actor base resolve the constant at tick time via const_get.
+        #
+        # NOT a singleton actor: every node runs LegionIO independently and owns
+        # its own spool file, so each node must drain its own spool. Leader
+        # election would strand every non-leader node's spool.
+        class MeteringFlush < Legion::Extensions::Actors::Every
+          def runner_class
+            'Legion::LLM::Metering'
+          end
+
+          def runner_function
+            'flush_spool'
+          end
+
+          def time
+            60
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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.4'
+      VERSION = '0.6.9'
     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/actor/metering_flush_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Stub the actor base class before requiring the real actor — the concrete
+# Legion::Extensions::Actors::Every lives in LegionIO, which lex-llm does not
+# depend on (lex-llm is the lower gem).
+unless defined?(Legion::Extensions::Actors::Every)
+  module Legion
+    module Extensions
+      module Actors
+        class Every; end # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every'
+
+require_relative '../../../../../lib/legion/extensions/llm/actors/metering_flush'
+
+RSpec.describe Legion::Extensions::Llm::Actor::MeteringFlush do
+  subject(:actor) { described_class.new }
+
+  describe '#runner_class' do
+    it 'targets the legion-llm metering module that owns the spool' do
+      expect(actor.runner_class).to eq('Legion::LLM::Metering')
+    end
+  end
+
+  describe '#runner_function' do
+    it 'returns flush_spool' do
+      expect(actor.runner_function).to eq('flush_spool')
+    end
+  end
+
+  describe '#time' do
+    it 'flushes once per minute' do
+      expect(actor.time).to eq(60)
+    end
+  end
+
+  describe '#run_now?' do
+    it 'returns false so it does not fire during boot' do
+      expect(actor.run_now?).to be false
+    end
+  end
+
+  describe '#use_runner?' do
+    it 'returns false so it calls the module directly (no AMQP round-trip)' do
+      expect(actor.use_runner?).to be false
+    end
+  end
+
+  describe '#check_subtask?' do
+    it 'returns false' do
+      expect(actor.check_subtask?).to be false
+    end
+  end
+
+  describe '#generate_task?' do
+    it 'returns false' do
+      expect(actor.generate_task?).to be false
+    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.4
+  version: 0.6.9
 platform: ruby
 authors:
 - LegionIO
@@ -255,6 +255,7 @@ files:
 - README.md
 - lex-llm.gemspec
 - lib/legion/extensions/llm.rb
+- lib/legion/extensions/llm/actors/metering_flush.rb
 - lib/legion/extensions/llm/agent.rb
 - lib/legion/extensions/llm/aliases.json
 - lib/legion/extensions/llm/aliases.rb
@@ -323,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
@@ -347,6 +349,7 @@ files:
 - spec/fixtures/ruby.wav
 - spec/fixtures/ruby.xml
 - spec/fixtures/sample.pdf
+- spec/legion/extensions/llm/actor/metering_flush_spec.rb
 - spec/legion/extensions/llm/agent_spec.rb
 - spec/legion/extensions/llm/attachment_spec.rb
 - spec/legion/extensions/llm/auto_registration_spec.rb
@@ -420,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