lex-llm-vllm 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b6bccbfd1d8e01fd38459107474d9ca3853f7d847ff3b5d71a8df3ff7a66c4b
-  data.tar.gz: f2bd935851929d113f078301a08119a425a68c35907094ee66d69d10af3e5f6f
+  metadata.gz: 3dd53d60a8e1aed0d2e1af84c39bf869b31070b927a932d18a69f79990fdd1ec
+  data.tar.gz: 739b79d90f9b6744b3eef3ff355978820692337f909cb1bb863270fd0d8114d9
 SHA512:
-  metadata.gz: 837e7ea4d14a09dd44922cb6193e4650b92aea3c4eea8cd85ed7916d766c84b7f8887961b0fb72ab8a1578d4005742f61ed44435d181235bb4f26042aa6aecf8
-  data.tar.gz: 8c73bfdd7921d1f99d788d4a311be574fc7cb9f61c7ebb6a79bdf7ea4a68622f020ace60858134288eea85186beb3d4c32b97c5ac714515a124b8110f3253679
+  metadata.gz: 3f1c76258f803a948b304fca1e887d4b2d8368057914b761033e7cde5f3f44d926209f1598de2acba905f783443a8cd1015318193dfd594a11febacc9821334a
+  data.tar.gz: af6c18324720d51fb6460b45463955a1944beff9f16edca35b271fb1168dc0a1b3598b4ee3dbce7c1724b0dcef772b83770f330003cea13fee03187761968d23

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.8 - 2026-04-30
+
+- Add `Legion::Logging::Helper` to all modules and classes for structured logging
+- Replace all bare rescue blocks with `handle_exception` calls for full observability
+- Add info-level action logging to Provider key actions (health, readiness, list_models, version)
+- Add info-level logging to RegistryPublisher publish methods
+- Remove custom `log_publish_failure` method in favor of standard `handle_exception`
+- Update README to reflect registry publishing, thinking mode, and management endpoints
+
 ## 0.1.7 - 2026-04-30
 
 - Enable stream_usage_supported? for streaming token usage reporting

data/README.md

@@ -1,6 +1,6 @@
 # lex-llm-vllm
 
-LegionIO LLM provider extension for vLLM.
+LegionIO LLM provider extension for [vLLM](https://docs.vllm.ai/).
 
 This gem lives under `Legion::Extensions::Llm::Vllm` and depends on `lex-llm` for shared provider-neutral routing, fleet, and schema primitives.
 
@@ -9,14 +9,17 @@ Load it with `require 'legion/extensions/llm/vllm'`.
 ## What It Provides
 
 - `Legion::Extensions::Llm::Provider` registration as `:vllm`
-- shared `Legion::Extensions::Llm::Provider::OpenAICompatible` request and response handling
-- chat requests through `POST /v1/chat/completions`
-- streaming chat support
-- model discovery through `GET /v1/models`
-- embeddings through `POST /v1/embeddings`
-- vLLM management helpers for `/health`, `/version`, `/reset_prefix_cache`, `/reset_mm_cache`, `/sleep`, and `/wake_up`
-- normalized OpenAI-compatible capability and modality metadata for discovered models
-- shared fleet/default settings via `Legion::Extensions::Llm.provider_settings`
+- Shared `Legion::Extensions::Llm::Provider::OpenAICompatible` request and response handling
+- Chat requests through `POST /v1/chat/completions`
+- Streaming chat with `stream_usage_supported?` for token usage reporting
+- Model discovery through `GET /v1/models`
+- Embeddings through `POST /v1/embeddings`
+- vLLM thinking mode via `chat_template_kwargs` (configurable through `Legion::Settings`)
+- Best-effort `llm.registry` readiness and model availability event publishing when transport is loaded
+- vLLM management helpers: `/health`, `/version`, `/reset_prefix_cache`, `/reset_mm_cache`, `/sleep`, `/wake_up`
+- Normalized OpenAI-compatible capability and modality metadata for discovered models
+- Shared fleet/default settings via `Legion::Extensions::Llm.provider_settings`
+- Full `Legion::Logging::Helper` integration with structured `handle_exception` across all classes
 
 ## Defaults
 
@@ -47,4 +50,47 @@ Legion::Extensions::Llm.configure do |config|
 end
 ```
 
-vLLM's OpenAI-compatible server supports the chat completions, models, and embeddings APIs when the served model and task support them. Chat requests require a model with a chat template; embedding requests require an embedding-capable served model.
+### Thinking Mode
+
+Enable vLLM thinking mode globally via settings:
+
+```ruby
+# In Legion::Settings or settings JSON
+{ llm: { providers: { vllm: { enable_thinking: true } } } }
+```
+
+Or pass `thinking: { enabled: true }` per-request. When enabled, the provider adds `chat_template_kwargs: { enable_thinking: true }` to the payload and strips `reasoning_effort`.
+
+## Management Endpoints
+
+The provider exposes helpers for vLLM server management:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `health` | `GET /health` | Server health check |
+| `version` | `GET /version` | Server version info |
+| `reset_prefix_cache` | `POST /reset_prefix_cache` | Clear prefix cache |
+| `reset_mm_cache` | `POST /reset_mm_cache` | Clear multimodal cache |
+| `sleep(level:)` | `POST /sleep` | Put server to sleep |
+| `wake_up(tags:)` | `POST /wake_up` | Wake server up |
+
+## Registry Publishing
+
+When `lex-llm` routing and Legion transport are available, the provider publishes best-effort availability events to the `llm.registry` exchange:
+
+- **Readiness events** on `readiness(live: true)` calls
+- **Model availability events** on `list_models` discovery
+
+Publishing is async (background threads) and never blocks the caller. All failures are handled gracefully via `handle_exception`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

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

@@ -10,6 +10,7 @@ module Legion
         # vLLM provider implementation for the Legion::Extensions::Llm base provider contract.
         class Provider < Legion::Extensions::Llm::Provider
           include Legion::Extensions::Llm::Provider::OpenAICompatible
+          include Legion::Logging::Helper
 
           class << self
             attr_writer :registry_publisher
@@ -66,22 +67,27 @@ module Legion
           def wake_up_url = '/wake_up'
 
           def health
+            log.info { "checking health at #{api_base}#{health_url}" }
             connection.get(health_url).body
           end
 
           def readiness(live: false)
+            log.info { "checking readiness live=#{live} at #{api_base}" }
             super.tap do |metadata|
               self.class.registry_publisher.publish_readiness_async(metadata) if live
             end
           end
 
           def list_models
+            log.info { "discovering models from #{api_base}#{models_url}" }
             super.tap do |models|
+              log.info { "discovered #{models.size} model(s) from vLLM" }
               self.class.registry_publisher.publish_models_async(models, readiness: readiness(live: false))
             end
           end
 
           def version
+            log.info { "fetching version from #{api_base}#{version_url}" }
             connection.get(version_url).body
           end
 
@@ -124,7 +130,8 @@ module Legion
 
             vllm = Legion::Settings.dig(:llm, :providers, :vllm)
             vllm.is_a?(Hash) && (vllm[:enable_thinking] == true || vllm['enable_thinking'] == true)
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'vllm.thinking_setting')
             false
           end
 

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

@@ -6,6 +6,8 @@ module Legion
       module Vllm
         # Builds sanitized lex-llm registry envelopes for vLLM provider state.
         class RegistryEventBuilder
+          include Legion::Logging::Helper
+
           def readiness(readiness)
             registry_event_class.public_send(
               readiness[:ready] ? :available : :unavailable,
@@ -108,7 +110,8 @@ module Legion
             configured_node = (::Legion::Settings.dig(:node, :canonical_name) if defined?(::Legion::Settings))
             value = configured_node.to_s.strip
             value.empty? ? :vllm : value.to_sym
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'vllm.registry.provider_instance')
             :vllm
           end
 

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

@@ -6,6 +6,8 @@ module Legion
       module Vllm
         # Best-effort publisher for vLLM provider availability events.
         class RegistryPublisher
+          include Legion::Logging::Helper
+
           APP_ID = 'lex-llm-vllm'
 
           def initialize(builder: RegistryEventBuilder.new)
@@ -13,10 +15,12 @@ module Legion
           end
 
           def publish_readiness_async(readiness)
+            log.info { 'publishing readiness event to llm.registry' }
             schedule { publish_event(@builder.readiness(readiness)) }
           end
 
           def publish_models_async(models, readiness:)
+            log.info { "publishing #{Array(models).size} model event(s) to llm.registry" }
             schedule do
               Array(models).each do |model|
                 publish_event(@builder.model_available(model, readiness:))
@@ -33,10 +37,10 @@ module Legion
               Thread.current.abort_on_exception = false
               yield
             rescue StandardError => e
-              log_publish_failure(e, level: :debug)
+              handle_exception(e, level: :debug, handled: true, operation: 'vllm.registry.schedule_thread')
             end
           rescue StandardError => e
-            log_publish_failure(e, level: :debug)
+            handle_exception(e, level: :debug, handled: true, operation: 'vllm.registry.schedule')
             false
           end
 
@@ -45,7 +49,7 @@ module Legion
 
             message_class.new(event:, app_id: APP_ID).publish(spool: false)
           rescue StandardError => e
-            log_publish_failure(e)
+            handle_exception(e, level: :warn, handled: true, operation: 'vllm.registry.publish_event')
             false
           end
 
@@ -56,7 +60,8 @@ module Legion
             return true unless ::Legion::Transport::Connection.respond_to?(:session_open?)
 
             ::Legion::Transport::Connection.session_open?
-          rescue StandardError
+          rescue StandardError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'vllm.registry.publishing_available?')
             false
           end
 
@@ -70,7 +75,8 @@ module Legion
 
             require 'legion/extensions/llm/vllm/transport/messages/registry_event'
             message_class_defined?
-          rescue LoadError
+          rescue LoadError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'vllm.registry.transport_load')
             false
           end
 
@@ -81,18 +87,6 @@ module Legion
           def message_class
             ::Legion::Extensions::Llm::Vllm::Transport::Messages::RegistryEvent
           end
-
-          def log_publish_failure(error, level: :warn)
-            message = "[lex-llm-vllm] llm.registry publish failed: #{error.class}: #{error.message}"
-            logger = ::Legion::Extensions::Llm.logger if defined?(::Legion::Extensions::Llm)
-            if logger.respond_to?(level)
-              logger.public_send(level, message)
-            elsif logger.respond_to?(:debug)
-              logger.debug(message)
-            end
-          rescue StandardError
-            nil
-          end
         end
       end
     end

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Vllm
-        VERSION = '0.1.7'
+        VERSION = '0.1.8'
       end
     end
   end

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

@@ -12,6 +12,7 @@ module Legion
       # Vllm provider extension namespace.
       module Vllm
         extend ::Legion::Extensions::Core if ::Legion::Extensions.const_defined?(:Core, false)
+        extend Legion::Logging::Helper
 
         PROVIDER_FAMILY = :vllm
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-vllm
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - LegionIO