llm_conductor 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bce592da24b8bb09f9702361a8d2de5051092290dd3b263f0026ddb877a8717b
-  data.tar.gz: 364a233ac3b1490010d949e15f83a3c45a5750ed117674ae2498508884cc365a
+  metadata.gz: 8e5bb3310ea1328acac93c59e7bc227e63de52397e51402eee0eb921eb92acc8
+  data.tar.gz: cacb73f7d04e46a100581df3b77781a98d0d4277fc726a0b32c266443999f66a
 SHA512:
-  metadata.gz: 3ea0a7fc5d5fe1f729e6eb76b9b81eb5b24aaad96ba59ef954637e00184eded4f6fd44c591ee3921f86dd3131403fc496a77b355bd59e60158849c2e3af44511
-  data.tar.gz: 322cfca7d9e8917761af1b5de1033d9c11f58fceaa8d79aa18feee6b65050c4ab123c340479d44adeafa42f85b25c9e406e17ffda0af0ed6f871cb3d4d7d682f
+  metadata.gz: 97d9c89718834420532c391c207790b416048b65958f3b6d7feac008f099cc533c644c614a014bc437b1631cf9fa60c2d0e340b8bea8316217e950af5449764b
+  data.tar.gz: 4fb3301001cebc258485568ebfa0078b3773b3563dd5149c8cd7527cc9a306ae41785fea6a73f09d1dca19a09f1af92b88611efa283e80efed317ef876f59330

data/VISION_USAGE.md

@@ -1,6 +1,6 @@
 # Vision/Multimodal Usage Guide
 
-This guide explains how to use vision/multimodal capabilities with LLM Conductor. Vision support is available for Claude (Anthropic), GPT (OpenAI), OpenRouter, and Z.ai clients.
+This guide explains how to use vision/multimodal capabilities with LLM Conductor. Vision support is available for Claude (Anthropic), GPT (OpenAI), Gemini (Google), OpenRouter, and Z.ai clients.
 
 ## Quick Start
 
@@ -73,6 +73,29 @@ response = LlmConductor.generate(
 puts response.output
 ```
 
+### Using Gemini (Google)
+
+```ruby
+require 'llm_conductor'
+
+# Configure
+LlmConductor.configure do |config|
+  config.gemini(api_key: ENV['GEMINI_API_KEY'])
+end
+
+# Analyze an image
+response = LlmConductor.generate(
+  model: 'gemini-2.5-flash',
+  vendor: :gemini,
+  prompt: {
+    text: 'What is in this image?',
+    images: 'https://cdn.autonomous.ai/production/ecm/230930/10-Comfortable-Office-Chairs-for-Gaming-A-Comprehensive-Review00002.webp'
+  }
+)
+
+puts response.output
+```
+
 ### Using Z.ai (Zhipu AI)
 
 ```ruby
@@ -124,6 +147,17 @@ For vision tasks via OpenRouter, these models work reliably:
 - **`anthropic/claude-3.5-sonnet`** - High quality analysis
 - **`openai/gpt-4o`** - Best quality (higher cost)
 
+### Gemini Models (Google)
+
+For vision tasks via Google Gemini API:
+
+- **`gemini-2.0-flash`** - Gemini 2.0 Flash (fast, efficient, multimodal) ✅
+- **`gemini-2.5-flash`** - Gemini 2.5 Flash (latest fast model)
+- **`gemini-1.5-pro`** - Gemini 1.5 Pro (high quality, large context window)
+- **`gemini-1.5-flash`** - Gemini 1.5 Flash (previous generation fast model)
+
+**Note:** Gemini client automatically fetches images from URLs and encodes them as base64, as required by the Gemini API.
+
 ### Z.ai Models (Zhipu AI)
 
 For vision tasks via Z.ai, these GLM models are recommended:
@@ -186,7 +220,7 @@ Detail levels (GPT and OpenRouter only):
 - `'low'` - Faster, cheaper (default if not specified)
 - `'auto'` - Let the model decide
 
-**Note:** Claude (Anthropic) and Z.ai don't support the `detail` parameter.
+**Note:** Claude (Anthropic), Gemini (Google), and Z.ai don't support the `detail` parameter.
 
 ### 4. Raw Format (Advanced)
 
@@ -217,6 +251,18 @@ response = LlmConductor.generate(
 )
 ```
 
+**Gemini Format:**
+```ruby
+response = LlmConductor.generate(
+  model: 'gemini-2.0-flash',
+  vendor: :gemini,
+  prompt: [
+    { type: 'text', text: 'What is in this image? Describe it in detail.' },
+    { type: 'image_url', image_url: { url: 'https://example.com/image.jpg' } }
+  ]
+)
+```
+
 ## Text-Only Requests (Backward Compatible)
 
 The client still supports regular text-only requests:
@@ -236,6 +282,10 @@ response = LlmConductor.generate(
 - Maximum file size depends on the model
 - Use HTTPS URLs when possible
 
+**Provider-Specific Notes:**
+- **Gemini**: URLs are automatically fetched and base64-encoded by the client before sending to the API
+- **Claude, GPT, OpenRouter, Z.ai**: URLs are sent directly to the API (no preprocessing required)
+
 ## Error Handling
 
 ```ruby
@@ -300,6 +350,12 @@ export OPENROUTER_API_KEY='your-key'
 ruby examples/openrouter_vision_usage.rb
 ```
 
+For Gemini:
+```bash
+export GEMINI_API_KEY='your-key'
+ruby examples/gemini_vision_usage.rb
+```
+
 For Z.ai:
 ```bash
 export ZAI_API_KEY='your-key'
@@ -357,6 +413,7 @@ For production:
 
 - `examples/claude_vision_usage.rb` - Complete Claude vision examples with Claude Sonnet 4
 - `examples/gpt_vision_usage.rb` - Complete GPT vision examples with GPT-4o
+- `examples/gemini_vision_usage.rb` - Complete Gemini vision examples with Gemini 2.0 Flash
 - `examples/openrouter_vision_usage.rb` - Complete OpenRouter vision examples
 - `examples/zai_usage.rb` - Complete Z.ai GLM-4.5V examples including vision and text
 
@@ -365,6 +422,7 @@ For production:
 - [OpenRouter Documentation](https://openrouter.ai/docs)
 - [OpenAI Vision API Reference](https://platform.openai.com/docs/guides/vision)
 - [Anthropic Claude Vision](https://docs.anthropic.com/claude/docs/vision)
+- [Google Gemini API Documentation](https://ai.google.dev/docs)
 - [Z.ai API Platform](https://api.z.ai/)
 - [GLM-4.5V Documentation](https://bigmodel.cn/)
 

data/examples/gemini_usage.rb

@@ -4,7 +4,7 @@ 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'
+  config.gemini(api_key: ENV['GEMINI_API_KEY'] || 'your_gemini_api_key_here')
 end
 
 # Example usage

data/examples/gemini_vision_usage.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+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')
+end
+
+puts '=' * 80
+puts 'Google Gemini Vision Examples'
+puts '=' * 80
+puts
+
+# Example 1: Single image analysis (simple format)
+puts 'Example 1: Single Image Analysis'
+puts '-' * 40
+
+response = LlmConductor.generate(
+  model: 'gemini-2.0-flash',
+  vendor: :gemini,
+  prompt: {
+    text: 'What is in this image? Describe it in detail.',
+    images: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg'
+  }
+)
+
+puts "Model: #{response.model}"
+puts "Vendor: #{response.metadata[:vendor]}"
+puts "Input tokens: #{response.input_tokens}"
+puts "Output tokens: #{response.output_tokens}"
+puts "\nResponse:"
+puts response.output
+puts
+
+# Example 2: Multiple images comparison
+puts '=' * 80
+puts 'Example 2: Multiple Images Comparison'
+puts '-' * 40
+
+response = LlmConductor.generate(
+  model: 'gemini-2.0-flash',
+  vendor: :gemini,
+  prompt: {
+    text: 'Compare these images. What are the main differences?',
+    images: [
+      'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg',
+      'https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Placeholder_view_vector.svg/681px-Placeholder_view_vector.svg.png'
+    ]
+  }
+)
+
+puts "Model: #{response.model}"
+puts "Input tokens: #{response.input_tokens}"
+puts "Output tokens: #{response.output_tokens}"
+puts "\nResponse:"
+puts response.output
+puts
+
+# Example 3: Raw format with Gemini-specific structure
+puts '=' * 80
+puts 'Example 3: Raw Format (Gemini-specific)'
+puts '-' * 40
+
+response = LlmConductor.generate(
+  model: 'gemini-2.0-flash',
+  vendor: :gemini,
+  prompt: [
+    { type: 'text', text: 'Analyze this nature scene:' },
+    { type: 'image_url', image_url: { url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg' } },
+    { type: 'text', text: 'What time of day do you think this photo was taken?' }
+  ]
+)
+
+puts "Model: #{response.model}"
+puts "Input tokens: #{response.input_tokens}"
+puts "Output tokens: #{response.output_tokens}"
+puts "\nResponse:"
+puts response.output
+puts
+
+# Example 4: Image with specific analysis request
+puts '=' * 80
+puts 'Example 4: Specific Analysis Request'
+puts '-' * 40
+
+response = LlmConductor.generate(
+  model: 'gemini-2.0-flash',
+  vendor: :gemini,
+  prompt: {
+    text: 'Count the number of distinct colors visible in this image and list them.',
+    images: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg'
+  }
+)
+
+puts "Model: #{response.model}"
+puts "\nResponse:"
+puts response.output
+puts
+
+# Example 5: Error handling
+puts '=' * 80
+puts 'Example 5: Error Handling'
+puts '-' * 40
+
+begin
+  response = LlmConductor.generate(
+    model: 'gemini-2.0-flash',
+    vendor: :gemini,
+    prompt: {
+      text: 'What is in this image?',
+      images: 'https://example.com/nonexistent-image.jpg'
+    }
+  )
+
+  if response.success?
+    puts 'Success! Response:'
+    puts response.output
+  else
+    puts "Request failed: #{response.metadata[:error]}"
+  end
+rescue StandardError => e
+  puts "Error occurred: #{e.message}"
+end
+puts
+
+# Example 6: Text-only request (backward compatibility)
+puts '=' * 80
+puts 'Example 6: Text-Only Request (No Images)'
+puts '-' * 40
+
+response = LlmConductor.generate(
+  model: 'gemini-2.0-flash',
+  vendor: :gemini,
+  prompt: 'Explain how neural networks work in 3 sentences.'
+)
+
+puts "Model: #{response.model}"
+puts "Input tokens: #{response.input_tokens}"
+puts "Output tokens: #{response.output_tokens}"
+puts "\nResponse:"
+puts response.output
+puts
+
+# Example 7: Image with hash format (URL specified explicitly)
+puts '=' * 80
+puts 'Example 7: Image Hash Format'
+puts '-' * 40
+
+response = LlmConductor.generate(
+  model: 'gemini-2.0-flash',
+  vendor: :gemini,
+  prompt: {
+    text: 'Describe the mood and atmosphere of this image.',
+    images: [
+      { url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg' }
+    ]
+  }
+)
+
+puts "Model: #{response.model}"
+puts "\nResponse:"
+puts response.output
+puts
+
+puts '=' * 80
+puts 'Examples completed!'
+puts '=' * 80

data/lib/llm_conductor/clients/gemini_client.rb

@@ -1,17 +1,27 @@
 # frozen_string_literal: true
 
 require 'gemini-ai'
+require 'base64'
+require 'net/http'
+require 'uri'
+require_relative 'concerns/vision_support'
 
 module LlmConductor
   module Clients
     # Google Gemini client implementation for accessing Gemini models via Google AI API
+    # Supports both text-only and multimodal (vision) requests
     class GeminiClient < BaseClient
+      include Concerns::VisionSupport
+
       private
 
       def generate_content(prompt)
+        content = format_content(prompt)
+        parts = build_parts_for_gemini(content)
+
         payload = {
           contents: [
-            { parts: [{ text: prompt }] }
+            { parts: }
           ]
         }
 
@@ -19,6 +29,100 @@ module LlmConductor
         response.dig('candidates', 0, 'content', 'parts', 0, 'text')
       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
+      # @return [Array] Array of parts in Gemini format
+      def build_parts_for_gemini(content)
+        case content
+        when String
+          [{ text: content }]
+        when Array
+          content.map { |part| convert_to_gemini_part(part) }
+        else
+          [{ text: content.to_s }]
+        end
+      end
+
+      # Convert a VisionSupport formatted part to Gemini format
+      # @param part [Hash] Content part with type and data
+      # @return [Hash] Gemini-formatted part
+      def convert_to_gemini_part(part)
+        case part[:type]
+        when 'text'
+          { text: part[:text] }
+        when 'image_url'
+          convert_image_url_to_inline_data(part)
+        when 'inline_data'
+          part # Already in Gemini format
+        else
+          part
+        end
+      end
+
+      # Convert image_url part to Gemini's inline_data format
+      # @param part [Hash] Part with image_url
+      # @return [Hash] Gemini inline_data format
+      def convert_image_url_to_inline_data(part)
+        url = part.dig(:image_url, :url)
+        {
+          inline_data: {
+            mime_type: detect_mime_type(url),
+            data: fetch_and_encode_image(url)
+          }
+        }
+      end
+
+      # Fetch image from URL and encode as base64
+      # Gemini API requires images to be base64-encoded
+      # @param url [String] Image URL
+      # @return [String] Base64-encoded image data
+      def fetch_and_encode_image(url)
+        uri = URI.parse(url)
+        response = fetch_image_from_uri(uri)
+
+        raise StandardError, "HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        Base64.strict_encode64(response.body)
+      rescue StandardError => e
+        raise StandardError, "Error fetching image from #{url}: #{e.message}"
+      end
+
+      # Fetch image from URI using Net::HTTP
+      # @param uri [URI] Parsed URI
+      # @return [Net::HTTPResponse] HTTP response
+      def fetch_image_from_uri(uri)
+        http = create_http_client(uri)
+        request = Net::HTTP::Get.new(uri.request_uri)
+        http.request(request)
+      end
+
+      # Create HTTP client with SSL configuration
+      # @param uri [URI] Parsed URI
+      # @return [Net::HTTP] Configured HTTP client
+      def create_http_client(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        return http unless uri.scheme == 'https'
+
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        http
+      end
+
+      # Detect MIME type from URL file extension
+      # @param url [String] Image URL
+      # @return [String] MIME type (e.g., 'image/jpeg', 'image/png')
+      def detect_mime_type(url)
+        extension = File.extname(URI.parse(url).path).downcase
+        case extension
+        when '.jpg', '.jpeg' then 'image/jpeg'
+        when '.png' then 'image/png'
+        when '.gif' then 'image/gif'
+        when '.webp' then 'image/webp'
+        else 'image/jpeg' # Default to jpeg
+        end
+      end
+
       def client
         @client ||= begin
           config = LlmConductor.configuration.provider_config(:gemini)

data/lib/llm_conductor/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: llm_conductor
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Ben Zheng
 bindir: exe
 cert_chain: []
-date: 2025-11-04 00:00:00.000000000 Z
+date: 2025-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -157,6 +157,7 @@ files:
 - examples/claude_vision_usage.rb
 - examples/data_builder_usage.rb
 - examples/gemini_usage.rb
+- examples/gemini_vision_usage.rb
 - examples/gpt_vision_usage.rb
 - examples/groq_usage.rb
 - examples/openrouter_vision_usage.rb