lex-llm-vertex 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa2b76730bd06bc3d37af2ea20ad016bdb4015a0776601e2080d1ab8d1c09168
-  data.tar.gz: ed7bfbc8083c3ad758f240cbb14e8f9d95cf9810dcbf7f17ed8e0a2077fdc4d7
+  metadata.gz: 2a7dc0a783d3cb0961f7881a4ef0412d1842730852518f1f7ac859ad2cbb944d
+  data.tar.gz: fabd6084238f3473c1b3a75e53e1f19de820f6ce12231316c38b39a33a2a506f
 SHA512:
-  metadata.gz: 68a7cc952a88e6b155173006fe9728a30ae71f32dca491ec8726bc88f56cf70a54ed7c50929f9b9e28c6bd14d91d5401c429329af678b747ad42c7b615ef368d
-  data.tar.gz: 5d511da4251f5e5b06a21dd29b5ab2fc773af9434af7b0c211da4c584940b538c6c90938f7226281aea82778a88e8b1b2fd5e5a3470917b5fa3b70496a9167d2
+  metadata.gz: 403c6201955ec9d77611f0ade5a338b58d4164f9567bab09b927c73427a06a2214e6828dff3f3fe82ac435ed33932195454a426f1c78bbac2f74c0743db26c27
+  data.tar.gz: 91592103291579ba34d8bd61dd1e066111b7a68449585bd96d8d5ca7f38b141dfc0c9d37db532c73721eb3de88d9bdca302510366088464678156c1e978132e8

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.1.5] - 2026-04-30
+
+- Add `Legion::Logging::Helper` to all modules and classes for structured logging
+- Replace ad-hoc `log_publish_failure` with `handle_exception` in RegistryPublisher
+- Add `handle_exception` to every rescue block with correct level, handled, and operation
+- Add info-level logging for key provider actions: chat, stream, embed, count_tokens, discover_offerings, health
+- Update README to reflect current architecture, file map, and observability conventions
+
+## [0.1.4] - 2026-04-30
+
+- Add headers: parameter to complete method for base provider contract compliance
+
 ## 0.1.3 - 2026-04-28
 
 - Remove the unused runtime `legion/settings` require while preserving the gemspec dependency.

data/README.md

@@ -48,6 +48,18 @@ provider.count_tokens(messages, model: model)
 
 `discover_offerings(live: false)` returns a conservative static catalog for routing defaults and unit tests. `discover_offerings(live: true)` calls the Vertex publisher models listing endpoint and maps returned model data into `Legion::Extensions::Llm::Routing::ModelOffering` records.
 
+## Static Model Catalog
+
+| Model | Alias | Publisher | Family | API Mode |
+|-------|-------|-----------|--------|----------|
+| gemini-2.5-flash | gemini-flash | google | gemini | generateContent |
+| gemini-2.5-pro | gemini-pro | google | gemini | generateContent |
+| gemini-embedding-001 | gemini-embedding | google | gemini | predict (embedding) |
+| text-embedding-005 | text-embedding | google | gemini | predict (embedding) |
+| claude-sonnet-4-5 | claude-sonnet | anthropic | anthropic | rawPredict |
+| mistral-medium-3 | mistral-medium | mistralai | mistral | rawPredict |
+| llama-4-maverick | llama-4-maverick | meta | meta | rawPredict |
+
 ## Model Offerings
 
 Every offering uses:
@@ -60,6 +72,30 @@ Every offering uses:
 
 Known aliases are intentionally small and configurable. For example, `gemini-flash` resolves to `gemini-2.5-flash`, while the offering preserves `projects/{project}/locations/{location}/publishers/google/models/gemini-2.5-flash`.
 
+## Registry Events
+
+When transport is available, the `RegistryPublisher` publishes best-effort readiness and offering availability events to the `llm.registry` topic exchange using `lex-llm` registry envelopes. Events are published asynchronously in background threads and never block the caller.
+
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/extensions/llm/vertex.rb` | Namespace module, default settings, provider registration |
+| `lib/legion/extensions/llm/vertex/provider.rb` | Vertex AI provider: chat, stream, embed, count_tokens, health, discovery |
+| `lib/legion/extensions/llm/vertex/registry_publisher.rb` | Async best-effort llm.registry event publisher |
+| `lib/legion/extensions/llm/vertex/registry_event_builder.rb` | Builds sanitized registry event envelopes |
+| `lib/legion/extensions/llm/vertex/version.rb` | `VERSION` constant |
+| `lib/legion/extensions/llm/vertex/transport/exchanges/llm_registry.rb` | `llm.registry` topic exchange definition |
+| `lib/legion/extensions/llm/vertex/transport/messages/registry_event.rb` | Transport message for registry events |
+
+## Observability
+
+All modules and classes use `Legion::Logging::Helper` for structured logging:
+
+- **Info-level logging** on key provider actions: `chat`, `stream`, `embed`, `count_tokens`, `discover_offerings`, `health`, and registry publish operations
+- **Every rescue block** calls `handle_exception(e, level:, handled:, operation:)` with dot-separated operation names (e.g. `vertex.provider.health`, `vertex.registry.publish_event`)
+- **Level conventions**: `:warn` for recoverable failures, `:error` for unexpected errors, `:debug` for expected/best-effort failures (transport unavailable, etc.)
+
 ## API Contract
 
 The implementation is intentionally limited to Vertex AI REST surfaces documented by Google Cloud:
@@ -71,7 +107,20 @@ The implementation is intentionally limited to Vertex AI REST surfaces documente
 
 Provider-specific request bodies are not guessed. Partner raw-predict chat requests use the message shape documented for those partner model endpoints; embeddings are only implemented for documented Vertex text embedding models.
 
-Google Cloud references:
+## Development
+
+```bash
+bundle install
+bundle exec rspec       # 0 failures
+bundle exec rubocop -A  # auto-fix
+bundle exec rubocop     # lint check
+```
+
+## License
+
+Apache-2.0
+
+## References
 
 - [Vertex AI GenAI REST API](https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest)
 - [Generate content with the Gemini API in Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference)

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

@@ -113,11 +113,13 @@ module Legion
           end
 
           def discover_offerings(live: false, **filters)
+            log.info { "discovering offerings live=#{live} project=#{project} location=#{location}" }
             return static_offerings(**filters) unless live
 
             response = connection.get(models_url)
             models = response.body['publisherModels'] || response.body['models'] || []
             models.map { |model| offering_from_live_model(model) }.tap do |offerings|
+              log.info { "discovered #{offerings.size} live offering(s) from Vertex" }
               self.class.registry_publisher.publish_offerings_async(offerings, readiness: readiness(live: false))
             end
           end
@@ -140,6 +142,7 @@ module Legion
           end
 
           def health(live: false)
+            log.info { "checking health live=#{live} project=#{project} location=#{location}" }
             baseline = {
               provider: :vertex,
               project: project,
@@ -154,6 +157,7 @@ module Legion
             connection.get(models_url)
             baseline.merge(checked: true)
           rescue StandardError => e
+            handle_exception(e, level: :warn, handled: true, operation: 'vertex.provider.health')
             baseline.merge(checked: true, ready: false, error: e.class.name, message: e.message)
           end
 
@@ -166,6 +170,7 @@ module Legion
 
           def chat(messages, model:, temperature: nil, max_tokens: nil, tools: {}, tool_prefs: nil, params: {})
             model_id = model_id(model)
+            log.info { "chat model=#{model_id} messages=#{messages.size}" }
             @model = model_id
             payload = Utils.deep_merge(chat_payload(messages, model: model_id, temperature:, max_tokens:, tools:,
                                                               tool_prefs:, stream: false), params)
@@ -175,6 +180,7 @@ module Legion
 
           def stream(messages, model:, temperature: nil, max_tokens: nil, tools: {}, tool_prefs: nil, params: {})
             model_id = model_id(model)
+            log.info { "stream model=#{model_id} messages=#{messages.size}" }
             @model = model_id
             payload = Utils.deep_merge(chat_payload(messages, model: model_id, temperature:, max_tokens:, tools:,
                                                               tool_prefs:, stream: true), params)
@@ -186,6 +192,7 @@ module Legion
 
           def count_tokens(messages, model:, params: {})
             model_id = model_id(model)
+            log.info { "count_tokens model=#{model_id}" }
             unless generate_content_model?(model_id)
               return {
                 supported: false,
@@ -202,6 +209,7 @@ module Legion
 
           def embed(text, model:, dimensions: nil, task_type: nil, title: nil, params: {})
             model_id = model_id(model)
+            log.info { "embed model=#{model_id} inputs=#{Array(text).size}" }
             unless Capabilities.embeddings?(model_id)
               raise NotImplementedError, "Vertex embedding payload for #{model_id} is not standardized"
             end
@@ -213,8 +221,8 @@ module Legion
             parse_embedding_response(response, model: model_id)
           end
 
-          def complete(messages, tools:, temperature:, model:, params: {}, schema: nil, thinking: nil, tool_prefs: nil,
-                       &)
+          def complete(messages, tools:, temperature:, model:, params: {}, headers: {}, schema: nil, thinking: nil, # rubocop:disable Lint/UnusedMethodArgument
+                       tool_prefs: nil, &)
             payload = params.dup
             payload[:generationConfig] = Utils.deep_merge(payload[:generationConfig] || {},
                                                           generation_config(temperature, schema, thinking))

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

@@ -6,6 +6,8 @@ module Legion
       module Vertex
         # Builds sanitized lex-llm registry envelopes for Vertex provider state.
         class RegistryEventBuilder
+          include Legion::Logging::Helper
+
           def readiness(readiness)
             registry_event_class.public_send(
               readiness[:ready] ? :available : :unavailable,

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

@@ -6,6 +6,8 @@ module Legion
       module Vertex
         # Best-effort publisher for Vertex provider availability events.
         class RegistryPublisher
+          include Legion::Logging::Helper
+
           APP_ID = 'lex-llm-vertex'
 
           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_offerings_async(offerings, readiness:)
+            log.info { "publishing #{Array(offerings).size} offering event(s) to llm.registry" }
             schedule do
               Array(offerings).each do |offering|
                 publish_event(@builder.offering_available(offering, 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: 'vertex.registry.schedule_thread')
             end
           rescue StandardError => e
-            log_publish_failure(e, level: :debug)
+            handle_exception(e, level: :debug, handled: true, operation: 'vertex.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: 'vertex.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: 'vertex.registry.publishing_available?')
             false
           end
 
@@ -70,7 +75,8 @@ module Legion
 
             require 'legion/extensions/llm/vertex/transport/messages/registry_event'
             message_class_defined?
-          rescue LoadError
+          rescue LoadError => e
+            handle_exception(e, level: :debug, handled: true, operation: 'vertex.registry.transport_load')
             false
           end
 
@@ -81,18 +87,6 @@ module Legion
           def message_class
             ::Legion::Extensions::Llm::Vertex::Transport::Messages::RegistryEvent
           end
-
-          def log_publish_failure(error, level: :warn)
-            message = "[lex-llm-vertex] 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/vertex/transport/exchanges/llm_registry.rb

@@ -8,6 +8,8 @@ module Legion
           module Exchanges
             # Topic exchange for Vertex provider availability events.
             class LlmRegistry < ::Legion::Transport::Exchange
+              include Legion::Logging::Helper
+
               def exchange_name
                 'llm.registry'
               end

data/lib/legion/extensions/llm/vertex/transport/messages/registry_event.rb

@@ -10,6 +10,8 @@ module Legion
           module Messages
             # Publishes lex-llm RegistryEvent envelopes to the llm.registry exchange.
             class RegistryEvent < ::Legion::Transport::Message
+              include Legion::Logging::Helper
+
               def initialize(event:, **options)
                 super(**event.to_h.merge(options))
               end

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Vertex
-        VERSION = '0.1.3'
+        VERSION = '0.1.5'
       end
     end
   end

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

@@ -11,6 +11,7 @@ module Legion
     module Llm
       # Google Cloud Vertex AI provider extension namespace.
       module Vertex
+        extend Legion::Logging::Helper
         extend ::Legion::Extensions::Core if ::Legion::Extensions.const_defined?(:Core, false)
 
         PROVIDER_FAMILY = :vertex

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-vertex
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - LegionIO