lex-llm-vertex 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b1ff87c604774c449138054bd3675a26da6696eaa43993c86b6f567e8861b628
+  data.tar.gz: f87648ca25d8317bbacbe84597b6c3abc495ea5f5ede11b2d363b74db04cfdd0
+SHA512:
+  metadata.gz: df0217a1da4c3cea8adf36a0bf3fe27fa6932b672b8053f7aab01e5b360a6e6601548244e6f804817a5319c210e9ec05913b39023a260d06ba66f6b9dd9104cd
+  data.tar.gz: 2f17a80cdb3e2553ec857ad68d359c9669a93203c9b0b116c6dd547bc22350ad7229b5b201bc3509aba1e747ff20d8bb982d0899a36fdfac9323706d89cc9155

data/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @LegionIO/maintainers

data/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: bundler
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/coverage/
+/pkg/
+/tmp/
+Gemfile.lock
+*.gem
+
+.rspec_status*
+.env
+.claude
+AGENTS.md
+CLAUDE.md

data/.rubocop.yml

@@ -0,0 +1,32 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "*.gemspec"
+    - spec/**/*
+Metrics/MethodLength:
+  Enabled: false
+Metrics/ParameterLists:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/LeakyConstantDeclaration:
+  Enabled: false
+RSpec/InstanceVariable:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-04-28
+
+- Initial Legion::Extensions::Llm Vertex AI provider extension scaffold.
+- Add offline provider defaults, project/location-aware model offering mapping, Vertex publisher model endpoint construction, chat, streaming, embeddings, token-counting metadata, health, and live discovery entrypoints.
+- Add README, gemspec, CI, and stubbed unit specs for Vertex AI routing behavior.

data/Gemfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+group :test do
+  llm_base_path = ENV.fetch('LEX_LLM_PATH', File.expand_path('../lex-llm', __dir__))
+  gem 'lex-llm', path: llm_base_path if File.directory?(llm_base_path)
+end
+
+gemspec
+
+group :development do
+  gem 'bundler', '>= 2.0'
+  gem 'rake', '>= 13.0'
+  gem 'rspec', '~> 3.12'
+  gem 'rubocop', '>= 1.0'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake', '>= 0.6'
+  gem 'rubocop-rspec'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LegionIO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,79 @@
+# lex-llm-vertex
+
+Google Cloud Vertex AI provider extension for `Legion::Extensions::Llm`.
+
+This gem adds a hosted Vertex AI provider surface for Legion LLM routing without depending on the old `legion-llm` gem. It keeps discovery offline by default, preserves full Vertex publisher model resource names for routing, and exposes project/location instance metadata for multi-region provider fleets.
+
+## Install
+
+```ruby
+gem 'lex-llm-vertex'
+```
+
+## Configuration
+
+The provider registers the `:vertex` provider family with `Legion::Extensions::Llm::Provider`.
+
+```ruby
+require 'legion/extensions/llm/vertex'
+
+Legion::Extensions::Llm.configure do |config|
+  config.vertex_project = ENV['GOOGLE_CLOUD_PROJECT']
+  config.vertex_location = ENV.fetch('VERTEX_LOCATION', 'us-central1')
+  config.vertex_access_token = ENV['VERTEX_ACCESS_TOKEN']
+end
+```
+
+`vertex_access_token` is optional for local routing metadata and tests. For live calls, provide a Google Cloud access token through configuration or use Application Default Credentials in the process that owns HTTP authentication.
+
+Default settings expose `env://` references and keep live discovery disabled:
+
+```ruby
+Legion::Extensions::Llm::Vertex.default_settings
+```
+
+## Provider Surface
+
+```ruby
+provider = Legion::Extensions::Llm::Vertex::Provider.new(Legion::Extensions::Llm.config)
+
+provider.discover_offerings(live: false)
+provider.offering_for(model: 'gemini-2.5-flash')
+provider.health(live: false)
+provider.chat(messages, model: model)
+provider.stream(messages, model: model) { |chunk| chunk.content }
+provider.embed('hello', model: 'gemini-embedding-001')
+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.
+
+## Model Offerings
+
+Every offering uses:
+
+- `provider_family: :vertex`
+- `transport: :http`
+- the full Vertex publisher model resource name as `model`
+- `metadata[:model_family]` inferred from the publisher/model or accepted from the caller
+- `metadata[:project]` and `metadata[:location]` copied from the provider instance
+
+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`.
+
+## API Contract
+
+The implementation is intentionally limited to Vertex AI REST surfaces documented by Google Cloud:
+
+- `generateContent` and `streamGenerateContent` for Gemini publisher models
+- `countTokens` for Gemini-style publisher models
+- `predict` for documented text embedding models
+- `rawPredict` and `streamRawPredict` endpoint builders for partner publisher models such as Mistral, Anthropic, and Meta
+
+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:
+
+- [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)
+- [Text embeddings API](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api)
+- [Mistral AI models on Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/mistral)

data/lex-llm-vertex.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/llm/vertex/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-llm-vertex'
+  spec.version       = Legion::Extensions::Llm::Vertex::VERSION
+  spec.authors       = ['LegionIO']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'LegionIO LLM Google Cloud Vertex AI provider extension'
+  spec.description   = 'Google Cloud Vertex AI provider integration for the LegionIO LLM routing framework.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-llm-vertex'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['documentation_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |file| file.match(%r{^(spec|test|features|tmp|coverage)/}) }
+  spec.require_paths = ['lib']
+
+  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.3'
+end

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

@@ -0,0 +1,609 @@
+# frozen_string_literal: true
+
+require 'legion/json'
+require 'legion/logging'
+require 'legion/settings'
+require 'legion/extensions/llm'
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Llm
+      module Vertex
+        # Google Cloud Vertex AI provider implementation for the Legion::Extensions::Llm contract.
+        class Provider < Legion::Extensions::Llm::Provider # rubocop:disable Metrics/ClassLength
+          DEFAULT_LOCATION = 'us-central1'
+          DEFAULT_PROJECT = 'env://GOOGLE_CLOUD_PROJECT'
+          DEFAULT_PUBLISHER = 'google'
+
+          STATIC_MODELS = [
+            { model: 'gemini-2.5-flash', alias: 'gemini-flash', publisher: 'google', model_family: :gemini },
+            { model: 'gemini-2.5-pro', alias: 'gemini-pro', publisher: 'google', model_family: :gemini },
+            { model: 'gemini-embedding-001', alias: 'gemini-embedding', publisher: 'google',
+              model_family: :gemini, usage_type: :embedding },
+            { model: 'text-embedding-005', alias: 'text-embedding', publisher: 'google',
+              model_family: :gemini, usage_type: :embedding },
+            { model: 'claude-sonnet-4-5', alias: 'claude-sonnet', publisher: 'anthropic',
+              model_family: :anthropic, api: :raw_predict },
+            { model: 'mistral-medium-3', alias: 'mistral-medium', publisher: 'mistralai',
+              model_family: :mistral, api: :raw_predict },
+            { model: 'llama-4-maverick', alias: 'llama-4-maverick', publisher: 'meta',
+              model_family: :meta, api: :raw_predict }
+          ].freeze
+
+          ALIASES = STATIC_MODELS.to_h { |entry| [entry.fetch(:alias), entry.fetch(:model)] }.freeze
+          PUBLISHERS = STATIC_MODELS.to_h { |entry| [entry.fetch(:model), entry.fetch(:publisher)] }.freeze
+          API_MODES = STATIC_MODELS.to_h { |entry| [entry.fetch(:model), entry.fetch(:api, :generate_content)] }.freeze
+          MODEL_FAMILIES = STATIC_MODELS.to_h { |entry| [entry.fetch(:model), entry.fetch(:model_family)] }.freeze
+
+          class << self
+            def slug = 'vertex'
+
+            def configuration_options
+              %i[
+                vertex_project
+                vertex_location
+                vertex_api_base
+                vertex_access_token
+                vertex_credentials
+                vertex_model_aliases
+                vertex_discovery_live
+              ]
+            end
+
+            def configuration_requirements = []
+            def capabilities = Capabilities
+
+            def resolve_model_id(model_id, config: nil)
+              configured_aliases = config.respond_to?(:vertex_model_aliases) ? config.vertex_model_aliases : nil
+              aliases = ALIASES.merge((configured_aliases || {}).transform_keys(&:to_s))
+              aliases.fetch(model_id.to_s, model_id.to_s)
+            end
+          end
+
+          # Capability predicates inferred from Vertex publisher model IDs and API modality.
+          module Capabilities
+            module_function
+
+            def chat?(model) = !embeddings?(model)
+            def streaming?(model) = chat?(model)
+            def vision?(model) = model_id(model).match?(/gemini|claude|mistral|llama/)
+            def functions?(model) = chat?(model)
+            def embeddings?(model) = model_id(model).match?(/embedding|embed/)
+
+            def model_id(model)
+              return model.fetch('model', model.fetch('id', '')) if model.is_a?(Hash)
+
+              model.respond_to?(:id) ? model.id.to_s : model.to_s
+            end
+          end
+
+          def api_base
+            config.vertex_api_base || "https://#{location}-aiplatform.googleapis.com/v1"
+          end
+
+          def headers
+            { 'Authorization' => bearer_token, 'Content-Type' => 'application/json; charset=utf-8' }.compact
+          end
+
+          def project = config.vertex_project || ENV.fetch('GOOGLE_CLOUD_PROJECT', DEFAULT_PROJECT)
+          def location = config.vertex_location || DEFAULT_LOCATION
+          def models_url = publisher_parent
+          def completion_url = generate_content_url(model: @model || STATIC_MODELS.first.fetch(:model))
+          def stream_url = stream_generate_content_url(model: @model || STATIC_MODELS.first.fetch(:model))
+          def count_tokens_url(model:) = "#{publisher_model_path(model)}:countTokens"
+          def embedding_url(model:) = "#{publisher_model_path(model)}:predict"
+
+          def generate_content_url(model:)
+            "#{publisher_model_path(model)}:generateContent"
+          end
+
+          def stream_generate_content_url(model:)
+            "#{publisher_model_path(model)}:streamGenerateContent?alt=sse"
+          end
+
+          def raw_predict_url(model:, stream: false)
+            suffix = stream ? 'streamRawPredict' : 'rawPredict'
+            "#{publisher_model_path(model)}:#{suffix}"
+          end
+
+          def discover_offerings(live: false, **filters)
+            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) }
+          end
+
+          def offering_for(model:, model_family: nil, instance_id: :default, **metadata)
+            model_id = model_id(model)
+            publisher = metadata.delete(:publisher) || publisher_for(model_id)
+            family = model_family || metadata.delete(:model_family) || model_family_for(model_id, publisher)
+
+            build_offering(
+              model: resource_name(model_id, publisher:),
+              alias_name: alias_for(model_id),
+              model_family: family,
+              instance_id: instance_id,
+              publisher: publisher,
+              usage_type: metadata.delete(:usage_type) || usage_type_for(model_id),
+              api: metadata.delete(:api) || api_for(model_id),
+              metadata: metadata
+            )
+          end
+
+          def health(live: false)
+            baseline = {
+              provider: :vertex,
+              project: project,
+              location: location,
+              configured: configured?,
+              ready: configured?,
+              live: live,
+              credentials: credential_source
+            }
+            return baseline.merge(checked: false) unless live
+
+            connection.get(models_url)
+            baseline.merge(checked: true)
+          rescue StandardError => e
+            baseline.merge(checked: true, ready: false, error: e.class.name, message: e.message)
+          end
+
+          def readiness(live: false)
+            health(live:).merge(local: false, remote: true, api_base: api_base, endpoints: endpoint_manifest)
+          end
+
+          def chat(messages, model:, temperature: nil, max_tokens: nil, tools: {}, tool_prefs: nil, params: {})
+            model_id = model_id(model)
+            @model = model_id
+            payload = Utils.deep_merge(chat_payload(messages, model: model_id, temperature:, max_tokens:, tools:,
+                                                              tool_prefs:, stream: false), params)
+            response = connection.post(chat_url(model_id, stream: false), payload)
+            parse_chat_response(response, model: model_id)
+          end
+
+          def stream(messages, model:, temperature: nil, max_tokens: nil, tools: {}, tool_prefs: nil, params: {})
+            model_id = model_id(model)
+            @model = model_id
+            payload = Utils.deep_merge(chat_payload(messages, model: model_id, temperature:, max_tokens:, tools:,
+                                                              tool_prefs:, stream: true), params)
+            response = connection.post(chat_url(model_id, stream: true), payload)
+            chunk = build_chunk(response.body, model: model_id)
+            yield chunk if block_given? && chunk.content
+            parse_chat_response(response, model: model_id)
+          end
+
+          def count_tokens(messages, model:, params: {})
+            model_id = model_id(model)
+            unless generate_content_model?(model_id)
+              return {
+                supported: false,
+                provider: :vertex,
+                model: resource_name(model_id),
+                reason: 'Vertex countTokens is standardized for generateContent publisher models'
+              }
+            end
+
+            payload = Utils.deep_merge({ contents: format_messages(messages) }, params)
+            response = connection.post(count_tokens_url(model: model_id), payload)
+            { input_tokens: response.body['totalTokens'], raw: response.body }
+          end
+
+          def embed(text, model:, dimensions: nil, task_type: nil, title: nil, params: {})
+            model_id = model_id(model)
+            unless Capabilities.embeddings?(model_id)
+              raise NotImplementedError, "Vertex embedding payload for #{model_id} is not standardized"
+            end
+
+            instances = Array(text).map { |item| embedding_instance(item, task_type:, title:) }
+            parameters = { outputDimensionality: dimensions }.compact
+            payload = Utils.deep_merge({ instances: instances, parameters: parameters }, params)
+            response = connection.post(embedding_url(model: model_id), payload)
+            parse_embedding_response(response, model: model_id)
+          end
+
+          def complete(messages, tools:, temperature:, model:, params: {}, schema: nil, thinking: nil, tool_prefs: nil,
+                       &)
+            payload = params.dup
+            payload[:generationConfig] = Utils.deep_merge(payload[:generationConfig] || {},
+                                                          generation_config(temperature, schema, thinking))
+            if block_given?
+              stream(messages, model:, temperature:, tools:, tool_prefs:, params: payload, &)
+            else
+              chat(messages, model:, temperature:, tools:, tool_prefs:, params: payload)
+            end
+          end
+
+          private
+
+          def static_offerings(**filters)
+            STATIC_MODELS.filter_map do |entry|
+              next if filters[:model_family] && entry.fetch(:model_family) != filters[:model_family].to_sym
+              next if filters[:publisher] && entry.fetch(:publisher) != filters[:publisher].to_s
+
+              offering_for(**entry.slice(:model, :model_family, :publisher, :usage_type, :api))
+            end
+          end
+
+          def offering_from_live_model(model)
+            name = model['name'] || model['publisherModelName'] || model['model'] || model['id']
+            publisher = publisher_from_resource(name) || model['publisher'] || DEFAULT_PUBLISHER
+            id = name.to_s.split('/').last
+            offering_for(model: id, publisher:, metadata: model)
+          end
+
+          def build_offering(model:, model_family:, usage_type:, publisher:, api:, instance_id: :default,
+                             alias_name: nil, metadata: {})
+            Legion::Extensions::Llm::Routing::ModelOffering.new(
+              provider_family: :vertex,
+              instance_id: instance_id,
+              transport: :http,
+              tier: :frontier,
+              model: model,
+              usage_type: usage_type,
+              capabilities: default_capabilities(model, api:),
+              limits: metadata.delete(:limits) || {},
+              metadata: metadata.merge(
+                model_family: model_family,
+                alias: alias_name,
+                publisher: publisher,
+                project: project,
+                location: location,
+                api: api
+              ).compact
+            )
+          end
+
+          def publisher_parent
+            "projects/#{project}/locations/#{location}/publishers/#{DEFAULT_PUBLISHER}/models"
+          end
+
+          def publisher_model_path(model)
+            id = model_id(model)
+            return id.delete_prefix("#{api_base}/") if id.start_with?('projects/')
+
+            "projects/#{project}/locations/#{location}/publishers/#{publisher_for(id)}/models/#{id}"
+          end
+
+          def resource_name(model, publisher: nil)
+            id = model_id(model)
+            return id if id.start_with?('projects/')
+
+            "projects/#{project}/locations/#{location}/publishers/#{publisher || publisher_for(id)}/models/#{id}"
+          end
+
+          def chat_url(model, stream:)
+            return raw_predict_url(model:, stream:) unless generate_content_model?(model)
+
+            stream ? stream_generate_content_url(model:) : generate_content_url(model:)
+          end
+
+          def chat_payload(messages, model:, temperature:, max_tokens:, tools:, tool_prefs:, stream:)
+            if generate_content_model?(model)
+              generate_content_payload(messages, temperature:, max_tokens:, tools:, tool_prefs:)
+            else
+              raw_predict_payload(messages, model:, temperature:, max_tokens:, stream:)
+            end
+          end
+
+          def generate_content_payload(messages, temperature:, max_tokens:, tools:, tool_prefs:)
+            {
+              contents: format_messages(messages.reject { |message| message.role == :system }),
+              systemInstruction: system_instruction(messages),
+              generationConfig: generation_config(temperature, nil, nil, max_tokens:),
+              tools: format_tools(tools),
+              toolConfig: tool_config(tool_prefs)
+            }.compact
+          end
+
+          def raw_predict_payload(messages, model:, temperature:, max_tokens:, stream:)
+            {
+              model: model,
+              messages: messages.reject { |message| message.role == :system }.map do |message|
+                { role: raw_role(message.role), content: content_text(message.content) }
+              end,
+              temperature: temperature,
+              max_tokens: max_tokens,
+              stream: stream
+            }.compact
+          end
+
+          def generation_config(temperature, schema, thinking, max_tokens: nil)
+            {
+              temperature: temperature,
+              maxOutputTokens: max_tokens,
+              responseMimeType: ('application/json' if schema),
+              responseSchema: schema_hash(schema),
+              thinkingConfig: thinking_config(thinking)
+            }.compact
+          end
+
+          def schema_hash(schema)
+            return unless schema
+
+            schema.respond_to?(:to_h) ? schema.to_h.fetch(:schema, schema.to_h) : schema
+          end
+
+          def thinking_config(thinking)
+            return nil unless thinking
+
+            budget = thinking.respond_to?(:budget) ? thinking.budget : nil
+            budget ||= thinking[:budget] || thinking['budget'] if thinking.is_a?(Hash)
+            { thinkingBudget: budget }.compact
+          end
+
+          def system_instruction(messages)
+            parts = messages.select { |message| message.role == :system }
+                            .flat_map { |message| content_parts(message.content) }
+            return nil if parts.empty?
+
+            { parts: parts }
+          end
+
+          def format_messages(messages)
+            messages.map { |message| { role: vertex_role(message.role), parts: message_parts(message) } }
+          end
+
+          def vertex_role(role)
+            role == :assistant ? 'model' : 'user'
+          end
+
+          def raw_role(role)
+            role == :assistant ? 'assistant' : 'user'
+          end
+
+          def message_parts(message)
+            return tool_call_parts(message) if message.tool_call?
+            return tool_result_parts(message) if message.tool_result?
+
+            content_parts(message.content)
+          end
+
+          def content_parts(content)
+            return Array(content.value) if content.is_a?(Legion::Extensions::Llm::Content::Raw)
+            return [{ text: Legion::JSON.generate(content) }] if content.is_a?(Hash) || content.is_a?(Array)
+            return [{ text: content.to_s }] unless content.is_a?(Legion::Extensions::Llm::Content)
+
+            parts = []
+            parts << { text: content.text } if content.text
+            content.attachments.each { |attachment| parts << attachment_part(attachment) }
+            parts
+          end
+
+          def attachment_part(attachment)
+            if attachment.text?
+              { text: attachment.for_llm }
+            else
+              { inlineData: { mimeType: attachment.mime_type, data: attachment.encoded } }
+            end
+          end
+
+          def content_text(content)
+            return content.text if content.respond_to?(:text)
+
+            content.to_s
+          end
+
+          def tool_call_parts(message)
+            message.tool_calls.values.map do |tool_call|
+              { functionCall: { name: tool_call.name, args: tool_call.arguments } }
+            end
+          end
+
+          def tool_result_parts(message)
+            [{
+              functionResponse: {
+                name: message.tool_call_id,
+                response: { name: message.tool_call_id, content: content_parts(message.content) }
+              }
+            }]
+          end
+
+          def format_tools(tools)
+            return nil if tools.empty?
+
+            [{
+              functionDeclarations: tools.values.map do |tool|
+                declaration = { name: tool.name, description: tool.description }
+                declaration[:parameters] = tool.params_schema if tool.respond_to?(:params_schema) && tool.params_schema
+                declaration
+              end
+            }]
+          end
+
+          def tool_config(tool_prefs)
+            return nil unless tool_prefs
+
+            choice = tool_prefs[:choice] || tool_prefs['choice']
+            return nil unless choice
+
+            { functionCallingConfig: { mode: choice.to_s } }
+          end
+
+          def parse_chat_response(response, model:)
+            body = response.body
+            if generate_content_model?(model)
+              parse_generate_content_response(body, model:)
+            else
+              parse_raw_predict_response(body, model:)
+            end
+          end
+
+          def parse_generate_content_response(body, model:)
+            parts = response_parts(body)
+            usage = body['usageMetadata'] || {}
+
+            Legion::Extensions::Llm::Message.new(
+              role: :assistant,
+              content: text_content(parts),
+              tool_calls: parse_tool_calls(parts),
+              input_tokens: usage['promptTokenCount'],
+              output_tokens: output_tokens(usage),
+              cached_tokens: usage['cachedContentTokenCount'],
+              thinking_tokens: usage['thoughtsTokenCount'],
+              model_id: body['modelVersion'] || model,
+              raw: body
+            )
+          end
+
+          def parse_raw_predict_response(body, model:)
+            choice = Array(body['choices']).first || {}
+            message = choice['message'] || {}
+            usage = body['usage'] || {}
+
+            Legion::Extensions::Llm::Message.new(
+              role: :assistant,
+              content: message['content'] || choice['text'],
+              input_tokens: usage['prompt_tokens'],
+              output_tokens: usage['completion_tokens'],
+              model_id: body['model'] || model,
+              raw: body
+            )
+          end
+
+          def build_chunk(body, model:)
+            parts = response_parts(body)
+            return raw_chunk(body, model:) if parts.empty?
+
+            usage = body['usageMetadata'] || {}
+            Legion::Extensions::Llm::Chunk.new(
+              role: :assistant,
+              content: text_content(parts),
+              input_tokens: usage['promptTokenCount'],
+              output_tokens: output_tokens(usage),
+              model_id: body['modelVersion'] || model,
+              raw: body
+            )
+          end
+
+          def raw_chunk(body, model:)
+            delta = Array(body['choices']).first&.dig('delta') || Array(body['choices']).first&.dig('message') || {}
+            Legion::Extensions::Llm::Chunk.new(role: :assistant, content: delta['content'],
+                                               model_id: body['model'] || model, raw: body)
+          end
+
+          def response_parts(body)
+            body.dig('candidates', 0, 'content', 'parts') || []
+          end
+
+          def text_content(parts)
+            text = parts.reject { |part| part['thought'] }.filter_map { |part| part['text'] }.join
+            text.empty? ? nil : text
+          end
+
+          def output_tokens(usage)
+            candidates = usage['candidatesTokenCount'] || 0
+            thoughts = usage['thoughtsTokenCount'] || 0
+            total = candidates + thoughts
+            total.positive? ? total : nil
+          end
+
+          def parse_tool_calls(parts)
+            calls = parts.each_with_object({}) do |part, result|
+              function_call = part['functionCall']
+              next unless function_call
+
+              id = SecureRandom.uuid
+              result[id] = Legion::Extensions::Llm::ToolCall.new(
+                id: id,
+                name: function_call['name'],
+                arguments: function_call['args'] || {}
+              )
+            end
+            calls.empty? ? nil : calls
+          end
+
+          def parse_embedding_response(response, model:)
+            predictions = response.body['predictions'] || []
+            vectors = predictions.map do |prediction|
+              prediction['embeddings']&.fetch('values', nil) || prediction['values']
+            end
+            vectors = vectors.first if vectors.length == 1
+            statistics = predictions.first&.dig('embeddings', 'statistics') || {}
+            Legion::Extensions::Llm::Embedding.new(vectors: vectors, model: model,
+                                                   input_tokens: statistics['token_count'] || 0)
+          end
+
+          def embedding_instance(text, task_type:, title:)
+            { content: text, task_type: task_type, title: title }.compact
+          end
+
+          def default_capabilities(model, api:)
+            return %i[embedding] if Capabilities.embeddings?(model)
+
+            capabilities = %i[chat]
+            capabilities << :streaming if %i[generate_content raw_predict].include?(api)
+            capabilities << :vision if Capabilities.vision?(model)
+            capabilities << :functions if generate_content_model?(model)
+            capabilities
+          end
+
+          def bearer_token
+            token = config.vertex_access_token
+            token ? "Bearer #{token}" : nil
+          end
+
+          def credential_source
+            return :access_token if config.vertex_access_token
+            return :credentials_file if config.vertex_credentials
+
+            :google_application_default_credentials
+          end
+
+          def model_id(model)
+            value = model.respond_to?(:id) ? model.id : model
+            self.class.resolve_model_id(value, config:)
+          end
+
+          def publisher_for(model)
+            id = model_id(model)
+            return publisher_from_resource(id) if id.start_with?('projects/')
+
+            PUBLISHERS.fetch(id, DEFAULT_PUBLISHER)
+          end
+
+          def publisher_from_resource(resource)
+            match = resource.to_s.match(%r{/publishers/([^/]+)/models/})
+            match&.[](1)
+          end
+
+          def api_for(model)
+            id = model_id(model)
+            return API_MODES[id] if API_MODES.key?(id)
+            return :raw_predict if publisher_for(id) != DEFAULT_PUBLISHER && !Capabilities.embeddings?(id)
+
+            :generate_content
+          end
+
+          def generate_content_model?(model)
+            api_for(model) == :generate_content
+          end
+
+          def usage_type_for(model)
+            Capabilities.embeddings?(model) ? :embedding : :inference
+          end
+
+          def model_family_for(model, publisher = nil)
+            id = model_id(model)
+            return MODEL_FAMILIES[id] if MODEL_FAMILIES.key?(id)
+
+            normalized_family(publisher || publisher_for(id))
+          end
+
+          def normalized_family(provider)
+            value = provider.to_s.downcase.tr('-', '_')
+            return :gemini if value == 'google'
+            return :mistral if value == 'mistralai'
+
+            value.to_sym
+          end
+
+          def alias_for(model)
+            ALIASES.key(model_id(model))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      module Vertex
+        VERSION = '0.1.0'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm'
+require 'legion/extensions/llm/vertex/provider'
+require 'legion/extensions/llm/vertex/version'
+
+module Legion
+  module Extensions
+    module Llm
+      # Google Cloud Vertex AI provider extension namespace.
+      module Vertex
+        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 }
+            }
+          )
+        end
+
+        def self.provider_class
+          Provider
+        end
+      end
+    end
+  end
+end
+
+Legion::Extensions::Llm::Provider.register(Legion::Extensions::Llm::Vertex::PROVIDER_FAMILY,
+                                           Legion::Extensions::Llm::Vertex::Provider)

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: lex-llm-vertex
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- LegionIO
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: legion-logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+- !ruby/object:Gem::Dependency
+  name: legion-settings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+- !ruby/object:Gem::Dependency
+  name: lex-llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+description: Google Cloud Vertex AI provider integration for the LegionIO LLM routing
+  framework.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/CODEOWNERS"
+- ".github/dependabot.yml"
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- lex-llm-vertex.gemspec
+- lib/legion/extensions/llm/vertex.rb
+- lib/legion/extensions/llm/vertex/provider.rb
+- lib/legion/extensions/llm/vertex/version.rb
+homepage: https://github.com/LegionIO/lex-llm-vertex
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-llm-vertex
+  source_code_uri: https://github.com/LegionIO/lex-llm-vertex
+  documentation_uri: https://github.com/LegionIO/lex-llm-vertex
+  changelog_uri: https://github.com/LegionIO/lex-llm-vertex/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-llm-vertex/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LegionIO LLM Google Cloud Vertex AI provider extension
+test_files: []