llm_conductor 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d361f0593674c6ca79eb53b6884c200a804d104e92f59e1f6fe5a75c2138dd4
-  data.tar.gz: b8476bdaa573306af54d7f5cbb49e94357d359f357f45d14eecb4889c49e8ba0
+  metadata.gz: a132b52551949cd8cd7446e2cf9a26f1dacba997dbae0965494b4ee174cf5905
+  data.tar.gz: 89d87446edea2d31c7194f84e1c98cbb11d241a0a1cd57b2878b387c94b441a5
 SHA512:
-  metadata.gz: 80cbe8b64fa36e18a8cb117ed5d72742ceeaae3336d317a3cee90fc343c2a8cc5148b595cf8c41f35000ca9d49d396253f4e7a3922155f025a90cbdd65a32e34
-  data.tar.gz: bd7f70f9bd41889e8c481c1e4f75c0c8f8ef9c1592cfe5b5f1f8584c7c087e9a3ddaa01c0397dbad6d45af53449bdb005490d5054228434b2a27650386334f8d
+  metadata.gz: 21204a00bc9d437fa702dc67f6224c8ef325e32daa94b252421fdff430929a03ca9903634df739b72d11f4b689320d7bfb1b626e800443aa90d0393ab5d11b01
+  data.tar.gz: 490ded3cf0e013a0edaed1bb66b4c91750a6503419c37e58b8fd4e5d53db464ff0785a4de4a76c8b3b87b787684fa327d78a7c8c872dc30608a0225de829c59d

data/.rubocop.yml

@@ -30,7 +30,7 @@ Lint/ConstantDefinitionInBlock:
   Enabled: false
 
 Metrics/ClassLength:
-  Max: 120
+  Max: 125
 
 Metrics/MethodLength:
   Max: 15
@@ -38,6 +38,8 @@ Metrics/MethodLength:
     - 'lib/llm_conductor/prompts.rb'
     - 'lib/llm_conductor/clients/openrouter_client.rb'
     - 'lib/llm_conductor/clients/zai_client.rb'
+    - 'lib/llm_conductor/client_factory.rb'
+    - 'examples/*.rb'
 
 RSpec/ExampleLength:
   Enabled: false
@@ -96,6 +98,12 @@ Metrics/AbcSize:
     - 'lib/llm_conductor/prompts.rb'
     - 'lib/llm_conductor/clients/openrouter_client.rb'
     - 'lib/llm_conductor/clients/zai_client.rb'
+    - 'examples/*.rb'
+
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/llm_conductor.rb'
+    - 'lib/llm_conductor/configuration.rb'
 
 Metrics/CyclomaticComplexity:
   Exclude:
@@ -103,6 +111,7 @@ Metrics/CyclomaticComplexity:
     - 'lib/llm_conductor/prompts.rb'
     - 'lib/llm_conductor/clients/openrouter_client.rb'
     - 'lib/llm_conductor/clients/zai_client.rb'
+    - 'examples/*.rb'
 
 Metrics/PerceivedComplexity:
   Exclude:

data/docs/custom-parameters.md

@@ -29,7 +29,8 @@ params: { temperature: 0.3, top_p: 0.85 }
 | Provider | Status |
 |----------|--------|
 | Ollama | ✅ Supported |
-| OpenAI, Anthropic, Gemini, etc. | 🔜 Coming soon |
+| Gemini | ✅ Supported |
+| OpenAI, Anthropic, etc. | 🔜 Coming soon |
 
 ---
 
@@ -133,6 +134,42 @@ response = LlmConductor.generate(
 )
 ```
 
+## Gemini Parameters Reference
+
+Below are common parameters supported by Google Gemini via `generationConfig`. For a complete list, see the [Gemini API docs](https://ai.google.dev/gemini-api/docs/text-generation).
+
+### Supported Parameters
+
+| Ruby Key | Gemini API Key | Type | Description |
+|----------|---------------|------|-------------|
+| `temperature` | `temperature` | Float | Controls randomness (0.0-2.0) |
+| `top_p` | `topP` | Float | Nucleus sampling threshold (0.0-1.0) |
+| `top_k` | `topK` | Integer | Top-k sampling limit |
+| `max_tokens` | `maxOutputTokens` | Integer | Maximum tokens to generate |
+| `max_output_tokens` | `maxOutputTokens` | Integer | Alias for max_tokens |
+| `candidate_count` | `candidateCount` | Integer | Number of candidates to return |
+| `stop_sequences` | `stopSequences` | Array | Stop sequences that end generation |
+
+### Gemini Usage Examples
+
+```ruby
+# Low temperature for focused output
+response = LlmConductor.generate(
+  model: 'gemini-2.5-flash',
+  prompt: 'Summarize this article.',
+  vendor: :gemini,
+  params: { temperature: 0.3, max_tokens: 500 }
+)
+
+# Creative writing with Gemini
+response = LlmConductor.generate(
+  model: 'gemini-2.5-flash',
+  prompt: 'Write a poem about the ocean.',
+  vendor: :gemini,
+  params: { temperature: 0.9, top_p: 0.95, top_k: 40 }
+)
+```
+
 ## Ollama Parameters Reference
 
 Below are common parameters supported by Ollama. For a complete list, see the [Ollama documentation](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
@@ -311,11 +348,11 @@ Always refer to your provider's documentation for supported parameters.
 
 Currently, custom parameters are fully supported for:
 - ✅ **Ollama**
+- ✅ **Google (Gemini)** — maps snake_case Ruby keys to camelCase `generationConfig`
 
 Coming soon:
 - 🔜 OpenAI (GPT)
 - 🔜 Anthropic (Claude)
-- 🔜 Google (Gemini)
 - 🔜 Groq
 - 🔜 OpenRouter
 - 🔜 Z.ai

data/examples/gemini_usage.rb

@@ -1,18 +1,90 @@
+#!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# Connectivity test for all Gemini auth methods.
+# Omit SCENARIO to run all scenarios that have the required env vars set.
+#
+#   Scenario A — Generative Language API (api_key)
+#     SCENARIO=api_key GEMINI_API_KEY=... ruby examples/gemini_usage.rb
+#
+#   Scenario B — Vertex AI with account-bound API key
+#     SCENARIO=vertex_api_key GEMINI_API_KEY=... GOOGLE_VERTEX_PROJECT_ID=... ruby examples/gemini_usage.rb
+#
+#   Scenario C — Vertex AI via Application Default Credentials
+#     SCENARIO=adc \
+#     GOOGLE_VERTEX_PROJECT_ID=... \
+#     GOOGLE_APPLICATION_CREDENTIALS=/path/to/sa.json \
+#     ruby examples/gemini_usage.rb
+#
+#   Scenario C — Vertex AI via credentials file contents
+#     SCENARIO=file_contents \
+#     GOOGLE_VERTEX_PROJECT_ID=... \
+#     GOOGLE_CREDENTIALS_FILE_CONTENTS=$(cat /path/to/sa.json) \
+#     ruby examples/gemini_usage.rb
+
 require_relative '../lib/llm_conductor'
 
-# Configure Gemini API key
-LlmConductor.configure do |config|
-  config.gemini(api_key: ENV['GEMINI_API_KEY'] || 'your_gemini_api_key_here')
+MODEL  = 'gemini-2.5-flash'
+PROMPT = 'Say hello.'
+
+SCENARIOS = {
+  'api_key' => -> { ENV['GEMINI_API_KEY'] && !ENV['GOOGLE_VERTEX_PROJECT_ID'] },
+  'vertex_api_key' => -> { ENV['GEMINI_API_KEY'] && ENV['GOOGLE_VERTEX_PROJECT_ID'] },
+  'adc' => -> { ENV['GOOGLE_VERTEX_PROJECT_ID'] && ENV['GOOGLE_APPLICATION_CREDENTIALS'] },
+  'file_contents' => -> { ENV['GOOGLE_VERTEX_PROJECT_ID'] && ENV['GOOGLE_CREDENTIALS_FILE_CONTENTS'] }
+}.freeze
+
+def run_scenario(name)
+  case name
+  when 'api_key'
+    LlmConductor.configure { |c| c.gemini(api_key: ENV.fetch('GEMINI_API_KEY')) }
+    label = 'api_key'
+
+  when 'vertex_api_key'
+    LlmConductor.configure do |c|
+      c.gemini(api_key: ENV.fetch('GEMINI_API_KEY'),
+               project_id: ENV.fetch('GOOGLE_VERTEX_PROJECT_ID'),
+               region: ENV['GOOGLE_VERTEX_REGION'])
+    end
+    label = 'vertex_ai/api_key'
+
+  when 'adc'
+    LlmConductor.configure do |c|
+      c.gemini(project_id: ENV.fetch('GOOGLE_VERTEX_PROJECT_ID'),
+               region: ENV['GOOGLE_VERTEX_REGION'])
+    end
+    label = 'vertex_ai/adc'
+
+  when 'file_contents'
+    LlmConductor.configure do |c|
+      c.gemini(project_id: ENV.fetch('GOOGLE_VERTEX_PROJECT_ID'),
+               region: ENV['GOOGLE_VERTEX_REGION'],
+               file_contents: ENV.fetch('GOOGLE_CREDENTIALS_FILE_CONTENTS'))
+    end
+    label = 'vertex_ai/file_contents'
+  end
+
+  response = LlmConductor.generate(model: MODEL, prompt: PROMPT)
+  raise 'Empty response' if response.output.nil? || response.output.strip.empty?
+
+  puts "[#{label}] OK — #{response.output.strip}"
+rescue StandardError => e
+  puts "[#{label}] FAILED — #{e.message}"
+  false
 end
 
-# Example usage
-response = LlmConductor.generate(
-  model: 'gemini-2.5-flash',
-  prompt: 'Explain how AI works in a few words'
-)
+scenario = ENV['SCENARIO']
 
-puts "Model: #{response.model}"
-puts "Output: #{response.output}"
-puts "Vendor: #{response.metadata[:vendor]}"
+if scenario
+  abort "Unknown SCENARIO=#{scenario}. Use: api_key | vertex_api_key | adc | file_contents" unless SCENARIOS.key?(scenario)
+  run_scenario(scenario)
+else
+  ran = 0
+  SCENARIOS.each do |name, available|
+    next unless available.call
+
+    run_scenario(name)
+    ran += 1
+  end
+  puts '(no scenarios ran — set the required env vars)' if ran.zero?
+end

data/lib/llm_conductor/client_factory.rb

@@ -19,6 +19,8 @@ module LlmConductor
         ollama: Clients::OllamaClient,
         gemini: Clients::GeminiClient,
         google: Clients::GeminiClient,
+        vertex_ai: Clients::GeminiClient,
+        vertex: Clients::GeminiClient,
         groq: Clients::GroqClient,
         zai: Clients::ZaiClient
       }

data/lib/llm_conductor/clients/gemini_client.rb

@@ -5,6 +5,7 @@ require 'base64'
 require 'net/http'
 require 'uri'
 require_relative 'concerns/vision_support'
+require_relative '../patches/gemini_vertex_api_key'
 
 module LlmConductor
   module Clients
@@ -15,20 +16,49 @@ module LlmConductor
 
       private
 
+      # Gemini REST API uses camelCase keys in generationConfig.
+      PARAM_KEY_MAP = {
+        temperature: :temperature,
+        top_p: :topP,
+        top_k: :topK,
+        max_tokens: :maxOutputTokens,
+        max_output_tokens: :maxOutputTokens,
+        candidate_count: :candidateCount,
+        stop_sequences: :stopSequences
+      }.freeze
+
       def generate_content(prompt)
         content = format_content(prompt)
         parts = build_parts_for_gemini(content)
 
         payload = {
           contents: [
-            { parts: }
+            { role: 'user', parts: }
           ]
         }
 
+        # Inject generationConfig from params when present
+        generation_config = build_generation_config
+        payload[:generationConfig] = generation_config if generation_config
+
         response = client.generate_content(payload)
         response.dig('candidates', 0, 'content', 'parts', 0, 'text')
       end
 
+      # Build Gemini generationConfig from params hash.
+      # Maps snake_case Ruby keys to camelCase Gemini API keys.
+      # @return [Hash, nil] generationConfig hash or nil if no mapped params
+      def build_generation_config
+        return unless params.is_a?(Hash) && params.any?
+
+        gen_cfg = {}
+        params.each do |key, value|
+          mapped = PARAM_KEY_MAP[key.to_sym]
+          gen_cfg[mapped] = value if mapped
+        end
+        gen_cfg.any? ? gen_cfg : nil
+      end
+
       # Build parts array for Gemini API from formatted content
       # Converts VisionSupport format to Gemini's specific format
       # @param content [String, Array] Formatted content from VisionSupport
@@ -127,14 +157,33 @@ module LlmConductor
         @client ||= begin
           config = LlmConductor.configuration.provider_config(:gemini)
           Gemini.new(
-            credentials: {
-              service: 'generative-language-api',
-              api_key: config[:api_key]
-            },
+            credentials: build_credentials(config),
             options: { model: }
           )
         end
       end
+
+      def build_credentials(config)
+        if config[:project_id] && config[:api_key]
+          { service: 'vertex-ai-api', region: config[:region], project_id: config[:project_id],
+            api_key: config[:api_key] }
+        elsif config[:project_id]
+          vertex_ai_credentials(config)
+        else
+          { service: 'generative-language-api', api_key: config[:api_key] }
+        end
+      end
+
+      def vertex_ai_credentials(config)
+        creds = {
+          service: 'vertex-ai-api',
+          region: config[:region],
+          project_id: config[:project_id]
+        }
+        creds[:file_path] = config[:file_path] if config[:file_path]
+        creds[:file_contents] = config[:file_contents] if config[:file_contents]
+        creds
+      end
     end
   end
 end

data/lib/llm_conductor/configuration.rb

@@ -56,12 +56,23 @@ module LlmConductor
       }
     end
 
-    # Configure Google Gemini provider
-    def gemini(api_key: nil, **options)
+    # Configure Google Gemini provider (Generative Language API or Vertex AI)
+    #
+    # For the standard Generative Language API, provide api_key.
+    # For Vertex AI, provide project_id and optionally region (defaults to 'global').
+    # Authentication falls back to Application Default Credentials
+    # (ADC / GOOGLE_APPLICATION_CREDENTIALS) when neither file_path nor file_contents is supplied.
+    # Env vars (GEMINI_API_KEY, GOOGLE_VERTEX_PROJECT_ID, etc.) are only applied automatically
+    # on boot via setup_defaults_from_env — explicit calls use only what is passed.
+    def gemini(api_key: nil, project_id: nil, region: nil, file_path: nil, file_contents: nil, **options)
       @providers[:gemini] = {
-        api_key: api_key || ENV['GEMINI_API_KEY'],
+        api_key:,
+        project_id:,
+        region: region || 'global',
+        file_path:,
+        file_contents:,
         **options
-      }
+      }.compact
     end
 
     # Configure Groq provider
@@ -149,11 +160,22 @@ module LlmConductor
       anthropic if ENV['ANTHROPIC_API_KEY']
       openai if ENV['OPENAI_API_KEY']
       openrouter if ENV['OPENROUTER_API_KEY']
-      gemini if ENV['GEMINI_API_KEY']
+      setup_gemini_from_env
       groq if ENV['GROQ_API_KEY']
       zai if ENV['ZAI_API_KEY']
       ollama # Always configure Ollama with default URL
     end
+
+    def setup_gemini_from_env
+      return unless ENV.values_at('GEMINI_API_KEY', 'GOOGLE_VERTEX_PROJECT_ID').any?
+
+      gemini(
+        api_key: ENV['GEMINI_API_KEY'],
+        project_id: ENV['GOOGLE_VERTEX_PROJECT_ID'],
+        region: ENV['GOOGLE_VERTEX_REGION'],
+        file_contents: ENV['GOOGLE_CREDENTIALS_FILE_CONTENTS']
+      )
+    end
   end
 
   def self.configuration

data/lib/llm_conductor/patches/gemini_vertex_api_key.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Patches the gemini-ai gem for two Vertex AI issues:
+#
+# 1. api_key + Vertex AI: the gem natively supports api_key only for
+#    generative-language-api. When both project_id and api_key are present,
+#    this patch rebuilds @base_address so the key is appended as ?key=... to
+#    the correct Vertex AI endpoint.
+#
+# 2. ADC (Application Default Credentials): the gem calls
+#    Google::Auth.get_application_default without a scope, which causes
+#    `invalid_scope` when exchanging service-account credentials for a token.
+#    This patch re-fetches the authorizer with the required cloud-platform scope.
+module Gemini
+  module Controllers
+    class Client
+      module VertexAiPatch
+        CLOUD_PLATFORM_SCOPE = 'https://www.googleapis.com/auth/cloud-platform'
+
+        def initialize(config)
+          super
+          fix_vertex_api_key_base_address(config) if @authentication == :api_key && @service == 'vertex-ai-api'
+          fix_adc_scope if @authentication == :default_credentials
+        end
+
+        private
+
+        def fix_vertex_api_key_base_address(config)
+          project_id = config.dig(:credentials, :project_id)
+
+          if project_id.nil?
+            raise Errors::MissingProjectIdError,
+                  'project_id is required for vertex-ai-api with api_key'
+          end
+
+          region = config.dig(:credentials, :region) || 'global'
+          @base_address = if region == 'global'
+                            "https://aiplatform.googleapis.com/#{@service_version}/projects/#{project_id}/locations/#{region}"
+                          else
+                            "https://#{region}-aiplatform.googleapis.com/#{@service_version}/projects/#{project_id}/locations/#{region}"
+                          end
+        end
+
+        def fix_adc_scope
+          @authorizer = ::Google::Auth.get_application_default(CLOUD_PLATFORM_SCOPE)
+        end
+      end
+
+      prepend VertexAiPatch
+    end
+  end
+end

data/lib/llm_conductor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmConductor
-  VERSION = '1.5.0'
+  VERSION = '1.7.0'
 end

data/lib/llm_conductor.rb

@@ -29,7 +29,6 @@ module LlmConductor
   end
 
   # Unified generate method supporting both simple prompts and legacy template-based generation
-  # rubocop:disable Metrics/ParameterLists
   def self.generate(model: nil, prompt: nil, type: nil, data: nil, vendor: nil, params: {})
     if prompt && !type && !data
       generate_simple_prompt(model:, prompt:, vendor:, params:)
@@ -40,7 +39,6 @@ module LlmConductor
             "Invalid arguments. Use either: generate(prompt: 'text') or generate(type: :custom, data: {...})"
     end
   end
-  # rubocop:enable Metrics/ParameterLists
 
   class << self
     private

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: llm_conductor
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Ben Zheng
 bindir: exe
 cert_chain: []
-date: 2025-12-12 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -181,6 +181,7 @@ files:
 - lib/llm_conductor/clients/zai_client.rb
 - lib/llm_conductor/configuration.rb
 - lib/llm_conductor/data_builder.rb
+- lib/llm_conductor/patches/gemini_vertex_api_key.rb
 - lib/llm_conductor/prompt_manager.rb
 - lib/llm_conductor/prompts.rb
 - lib/llm_conductor/prompts/base_prompt.rb