lex-llm-vertex 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aea77e247a75b2b4864b832da66786008115bc64861fd1ec06a57978456508b0
-  data.tar.gz: 6082e13d0afe17cd77291494c4041a7ad0a0aae1d9fc19fb539edd398f9bea01
+  metadata.gz: 524d4e5a1420c6a145c89da553e021205e5447c462509b4397161b01d8c37ed6
+  data.tar.gz: 4b6afd972ba22dacbcfd844287ee8828bfefa05cdce2a13ec2ff052f7fdb28b0
 SHA512:
-  metadata.gz: '003679cd2e49ab95aec1664309ea6ee28ba08ddc7464ab5ea4e26618550ea19ae6c2b732df89097abe378197a17c6bacc48234a6b1f4658f514b1de6decab301'
-  data.tar.gz: 8665225fa69d9c1178a456160e1e50ba52854d42b660ebcaf92a3d3c9c1d683433f754ddcd061dcf98e7f36d4cdc353a8b9a3f0a55142027874e761cafff195f
+  metadata.gz: 6b309e1328f525cb652fb0cf9d2f4515d6092a0283d75f7240ea514e978612268613ac5c1ee06333c8fb38161cd613423c7c25b03322de3d98eb9d5f2c9c2bea
+  data.tar.gz: c78952b334fc28d106b02101585863c062d31c1069652688f0dfb93b8151d923e20efb1ac600f73ca0be98213dd92ffc368db6c992d380fbd22d6d144c40ad69

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

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/lex-llm-vertex.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-json', '>= 1.2.1'
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.3.14'
-  spec.add_dependency 'lex-llm', '>= 0.1.5'
+  spec.add_dependency 'lex-llm', '>= 0.2.0'
 end

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

@@ -56,7 +56,7 @@ module Legion
             def capabilities = Capabilities
 
             def registry_publisher
-              @registry_publisher ||= RegistryPublisher.new
+              @registry_publisher ||= Legion::Extensions::Llm::RegistryPublisher.new(provider_family: :vertex)
             end
 
             def resolve_model_id(model_id, config: nil)
@@ -112,14 +112,25 @@ module Legion
             "#{publisher_model_path(model)}:#{suffix}"
           end
 
+          def list_models
+            log.info { 'listing available Vertex models from static catalog' }
+            STATIC_MODELS.map { |entry| model_info_from_static(entry) }.tap do |models|
+              log.info { "discovered #{models.size} Vertex model(s); publishing to registry" }
+              self.class.registry_publisher.publish_models_async(models, readiness: readiness(live: false))
+            end
+          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|
-              self.class.registry_publisher.publish_offerings_async(offerings, readiness: readiness(live: false))
-            end
+            offerings = models.map { |model| offering_from_live_model(model) }
+            log.info { "discovered #{offerings.size} live offering(s) from Vertex" }
+            model_infos = offerings.map { |o| model_info_from_offering(o) }
+            self.class.registry_publisher.publish_models_async(model_infos, readiness: readiness(live: false))
+            offerings
           end
 
           def offering_for(model:, model_family: nil, instance_id: :default, **metadata)
@@ -140,6 +151,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 +166,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 +179,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 +189,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 +201,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 +218,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
@@ -227,6 +244,34 @@ module Legion
 
           private
 
+          def model_info_from_static(entry)
+            caps = default_capabilities(entry[:model], api: entry.fetch(:api, :generate_content))
+            Legion::Extensions::Llm::Model::Info.new(
+              id: entry[:model],
+              name: entry[:alias] || entry[:model],
+              provider: :vertex,
+              family: entry[:model_family].to_s,
+              capabilities: caps.map(&:to_s),
+              metadata: {
+                publisher: entry[:publisher],
+                project: project,
+                location: location,
+                api: entry.fetch(:api, :generate_content)
+              }.compact
+            )
+          end
+
+          def model_info_from_offering(offering)
+            Legion::Extensions::Llm::Model::Info.new(
+              id: offering.model,
+              name: offering.metadata[:alias] || offering.model,
+              provider: :vertex,
+              family: offering.metadata[:model_family].to_s,
+              capabilities: offering.capabilities.map(&:to_s),
+              metadata: offering.metadata
+            )
+          end
+
           def static_offerings(**filters)
             STATIC_MODELS.filter_map do |entry|
               next if filters[:model_family] && entry.fetch(:model_family) != filters[:model_family].to_sym

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Llm
       module Vertex
-        VERSION = '0.1.4'
+        VERSION = '0.1.6'
       end
     end
   end

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

@@ -2,8 +2,6 @@
 
 require 'legion/extensions/llm'
 require 'legion/extensions/llm/vertex/provider'
-require 'legion/extensions/llm/vertex/registry_event_builder'
-require 'legion/extensions/llm/vertex/registry_publisher'
 require 'legion/extensions/llm/vertex/version'
 
 module Legion
@@ -11,29 +9,23 @@ 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
 
         def self.default_settings
-          ::Legion::Extensions::Llm.provider_settings(
-            family: PROVIDER_FAMILY,
-            discovery: { enabled: true, live: false, locations: %w[us-central1 us-east5 europe-west4] },
-            instance: {
-              endpoint: 'https://us-central1-aiplatform.googleapis.com/v1',
-              project: 'env://GOOGLE_CLOUD_PROJECT',
-              location: 'us-central1',
-              tier: :frontier,
-              transport: :http,
-              credentials: {
-                provider: 'google-application-default-credentials',
-                access_token: 'env://VERTEX_ACCESS_TOKEN',
-                credentials_file: 'env://GOOGLE_APPLICATION_CREDENTIALS'
-              },
-              usage: { inference: true, embedding: true, token_counting: true },
-              limits: { concurrency: 4 }
-            }
-          )
+          {
+            enabled: false,
+            default_model: nil,
+            project: nil,
+            location: 'us-central1',
+            model_whitelist: [],
+            model_blacklist: [],
+            model_cache_ttl: 3600,
+            tls: { enabled: false, verify: :peer },
+            instances: {}
+          }
         end
 
         def self.provider_class
@@ -44,5 +36,6 @@ module Legion
   end
 end
 
-Legion::Extensions::Llm::Provider.register(Legion::Extensions::Llm::Vertex::PROVIDER_FAMILY,
-                                           Legion::Extensions::Llm::Vertex::Provider)
+Legion::Extensions::Llm::Configuration.register_provider_options(
+  Legion::Extensions::Llm::Vertex::Provider.configuration_options
+)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm-vertex
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - LegionIO
@@ -57,14 +57,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
 description: Google Cloud Vertex AI provider integration for the LegionIO LLM routing
   framework.
 email:
@@ -85,10 +85,6 @@ files:
 - lex-llm-vertex.gemspec
 - lib/legion/extensions/llm/vertex.rb
 - lib/legion/extensions/llm/vertex/provider.rb
-- lib/legion/extensions/llm/vertex/registry_event_builder.rb
-- lib/legion/extensions/llm/vertex/registry_publisher.rb
-- lib/legion/extensions/llm/vertex/transport/exchanges/llm_registry.rb
-- lib/legion/extensions/llm/vertex/transport/messages/registry_event.rb
 - lib/legion/extensions/llm/vertex/version.rb
 homepage: https://github.com/LegionIO/lex-llm-vertex
 licenses:

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

@@ -1,93 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Vertex
-        # Builds sanitized lex-llm registry envelopes for Vertex provider state.
-        class RegistryEventBuilder
-          def readiness(readiness)
-            registry_event_class.public_send(
-              readiness[:ready] ? :available : :unavailable,
-              provider_offering(readiness),
-              runtime: runtime_metadata,
-              health: readiness_health(readiness),
-              metadata: readiness_metadata(readiness)
-            )
-          end
-
-          def offering_available(offering, readiness:)
-            registry_event_class.available(
-              offering,
-              runtime: runtime_metadata,
-              health: offering_health(readiness),
-              metadata: offering_metadata
-            )
-          end
-
-          private
-
-          def provider_offering(readiness)
-            {
-              provider_family: :vertex,
-              provider_instance: provider_instance,
-              transport: :http,
-              model: 'provider-readiness',
-              usage_type: :inference,
-              capabilities: [],
-              health: readiness_health(readiness),
-              metadata: { lex: :llm_vertex, provider_readiness: true }
-            }
-          end
-
-          def readiness_health(readiness)
-            health = {
-              ready: readiness[:ready] == true,
-              status: readiness[:ready] ? :available : :unavailable,
-              checked: readiness[:checked] != false
-            }
-            add_readiness_error(health, readiness)
-          end
-
-          def add_readiness_error(health, source)
-            error_class = source[:error] || source['error']
-            error_message = source[:message] || source['message']
-            health[:error_class] = error_class if error_class
-            health[:error] = error_message if error_message
-            health
-          end
-
-          def offering_health(readiness)
-            ready = readiness.fetch(:ready, true) == true
-            { ready:, status: ready ? :available : :degraded, checked: readiness[:checked] != false }
-          end
-
-          def readiness_metadata(readiness)
-            {
-              extension: :lex_llm_vertex,
-              provider: :vertex,
-              configured: readiness[:configured] == true,
-              live: readiness[:live] == true
-            }
-          end
-
-          def offering_metadata
-            { extension: :lex_llm_vertex, provider: :vertex }
-          end
-
-          def runtime_metadata
-            { node: provider_instance }
-          end
-
-          def provider_instance
-            :vertex
-          end
-
-          def registry_event_class
-            ::Legion::Extensions::Llm::Routing::RegistryEvent
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,100 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Vertex
-        # Best-effort publisher for Vertex provider availability events.
-        class RegistryPublisher
-          APP_ID = 'lex-llm-vertex'
-
-          def initialize(builder: RegistryEventBuilder.new)
-            @builder = builder
-          end
-
-          def publish_readiness_async(readiness)
-            schedule { publish_event(@builder.readiness(readiness)) }
-          end
-
-          def publish_offerings_async(offerings, readiness:)
-            schedule do
-              Array(offerings).each do |offering|
-                publish_event(@builder.offering_available(offering, readiness:))
-              end
-            end
-          end
-
-          private
-
-          def schedule(&)
-            return false unless publishing_available?
-
-            Thread.new do
-              Thread.current.abort_on_exception = false
-              yield
-            rescue StandardError => e
-              log_publish_failure(e, level: :debug)
-            end
-          rescue StandardError => e
-            log_publish_failure(e, level: :debug)
-            false
-          end
-
-          def publish_event(event)
-            return false unless publishing_available?
-
-            message_class.new(event:, app_id: APP_ID).publish(spool: false)
-          rescue StandardError => e
-            log_publish_failure(e)
-            false
-          end
-
-          def publishing_available?
-            return false unless registry_event_available?
-            return false unless transport_message_available?
-            return true unless defined?(::Legion::Transport::Connection)
-            return true unless ::Legion::Transport::Connection.respond_to?(:session_open?)
-
-            ::Legion::Transport::Connection.session_open?
-          rescue StandardError
-            false
-          end
-
-          def registry_event_available?
-            defined?(::Legion::Extensions::Llm::Routing::RegistryEvent)
-          end
-
-          def transport_message_available?
-            return true if message_class_defined?
-            return false unless defined?(::Legion::Transport::Message) && defined?(::Legion::Transport::Exchange)
-
-            require 'legion/extensions/llm/vertex/transport/messages/registry_event'
-            message_class_defined?
-          rescue LoadError
-            false
-          end
-
-          def message_class_defined?
-            defined?(::Legion::Extensions::Llm::Vertex::Transport::Messages::RegistryEvent)
-          end
-
-          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
-  end
-end

data/lib/legion/extensions/llm/vertex/transport/exchanges/llm_registry.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Llm
-      module Vertex
-        module Transport
-          module Exchanges
-            # Topic exchange for Vertex provider availability events.
-            class LlmRegistry < ::Legion::Transport::Exchange
-              def exchange_name
-                'llm.registry'
-              end
-
-              def default_type
-                'topic'
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-require 'legion/extensions/llm/vertex/transport/exchanges/llm_registry'
-
-module Legion
-  module Extensions
-    module Llm
-      module Vertex
-        module Transport
-          module Messages
-            # Publishes lex-llm RegistryEvent envelopes to the llm.registry exchange.
-            class RegistryEvent < ::Legion::Transport::Message
-              def initialize(event:, **options)
-                super(**event.to_h.merge(options))
-              end
-
-              def exchange
-                Transport::Exchanges::LlmRegistry
-              end
-
-              def routing_key
-                @options[:routing_key] || "llm.registry.#{@options.fetch(:event_type)}"
-              end
-
-              def type
-                'llm.registry.event'
-              end
-
-              def app_id
-                @options[:app_id] || RegistryPublisher::APP_ID
-              end
-
-              def persistent # rubocop:disable Naming/PredicateMethod
-                false
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end