geminize 1.0.0 → 1.2.0

data/examples/function_calling.rb

@@ -0,0 +1,218 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "geminize"
+require "json"
+
+# Configure the API key
+Geminize.configure do |config|
+  config.api_key = ENV["GEMINI_API_KEY"] # Make sure to set your API key in the environment
+  config.default_model = "gemini-1.5-pro-latest" # Use the latest model that supports function calling
+end
+
+# Define a weather function that can handle a location and unit
+def get_weather(location, unit = "celsius")
+  puts "Getting weather for #{location} in #{unit}..."
+
+  # In a real implementation, this would call a weather API
+  # For this example, we'll return mock data
+  case location.downcase
+  when /new york/
+    {temperature: (unit == "celsius") ? 22 : 72, conditions: "Sunny", humidity: 45}
+  when /london/
+    {temperature: (unit == "celsius") ? 15 : 59, conditions: "Rainy", humidity: 80}
+  when /tokyo/
+    {temperature: (unit == "celsius") ? 26 : 79, conditions: "Partly Cloudy", humidity: 65}
+  else
+    {temperature: (unit == "celsius") ? 20 : 68, conditions: "Unknown", humidity: 50}
+  end
+end
+
+# Enhanced weather function that can handle a batch of locations
+def get_weather_batch(locations, unit = "celsius")
+  if locations.is_a?(Array)
+    results = {}
+    locations.each do |location|
+      results[location] = get_weather(location, unit)
+    end
+    results
+  else
+    {locations => get_weather(locations, unit)}
+  end
+end
+
+# Define a function schema for get_weather
+weather_function = {
+  name: "get_weather",
+  description: "Get the current weather in a location",
+  parameters: {
+    type: "object",
+    properties: {
+      location: {
+        type: "string",
+        description: "The city and state or country, e.g., 'New York, NY' or 'London, UK'"
+      },
+      unit: {
+        type: "string",
+        enum: ["celsius", "fahrenheit"],
+        description: "The unit of temperature"
+      }
+    },
+    required: ["location"]
+  }
+}
+
+# Define a batch weather function schema that can handle multiple locations
+batch_weather_function = {
+  name: "get_weather_batch",
+  description: "Get the current weather for multiple locations at once",
+  parameters: {
+    type: "object",
+    properties: {
+      locations: {
+        type: "array",
+        items: {
+          type: "string"
+        },
+        description: "List of cities, e.g., ['New York, NY', 'London, UK', 'Tokyo, Japan']"
+      },
+      unit: {
+        type: "string",
+        enum: ["celsius", "fahrenheit"],
+        description: "The unit of temperature"
+      }
+    },
+    required: ["locations"]
+  }
+}
+
+puts "==========================================="
+puts "= GEMINIZE FUNCTION CALLING & JSON EXAMPLES ="
+puts "==========================================="
+
+puts "\n=== FUNCTION CALLING EXAMPLE ==="
+puts "Asking Gemini about the weather in New York..."
+
+begin
+  # Generate a response with the function definition
+  response = Geminize.generate_with_functions(
+    "What's the weather like in New York?",
+    [weather_function],
+    nil,
+    {temperature: 0.2}
+  )
+
+  # Check if the model wants to call a function
+  if response.has_function_call?
+    function_call = response.function_call
+    puts "Model wants to call function: #{function_call.name}"
+    puts "With arguments: #{function_call.response.inspect}"
+
+    function_name = function_call.name
+    args = function_call.response
+
+    if function_name == "get_weather"
+      location = args["location"]
+      unit = args["unit"] || "celsius"
+
+      # Call our weather function
+      weather_data = get_weather(location, unit)
+      puts "Weather data for #{location}: #{weather_data.inspect}"
+
+      # Process the function result
+      final_response = Geminize.process_function_call(response) do |name, arguments|
+        get_weather(arguments["location"], arguments["unit"])
+      end
+
+      puts "\nFinal response from Gemini:"
+      puts final_response.text
+    else
+      puts "Unexpected function call: #{function_name}"
+    end
+  else
+    puts "Model did not request to call a function."
+    puts "Response: #{response.text}"
+  end
+rescue => e
+  puts "Error during function calling: #{e.message}"
+end
+
+# Example of using JSON mode
+puts "\n\n=== JSON MODE EXAMPLE ==="
+puts "Using JSON mode to get weather data in structured format..."
+
+begin
+  json_response = Geminize.generate_json(
+    "Get the current temperature and weather conditions for New York.",
+    nil,
+    {
+      system_instruction: "Return a JSON object with temperature in celsius and conditions."
+    }
+  )
+
+  if json_response.has_json_response?
+    puts "Structured JSON response:"
+    puts JSON.pretty_generate(json_response.json_response)
+  else
+    puts "Raw text response (not valid JSON):"
+    puts json_response.text
+  end
+rescue => e
+  puts "Error during JSON mode: #{e.message}"
+end
+
+puts "\n\n=== BATCH FUNCTION CALL EXAMPLE ==="
+puts "Using batch function to efficiently get weather for multiple cities at once..."
+
+begin
+  # Use a batch function to get all cities at once (more efficient)
+  response = Geminize.generate_with_functions(
+    "I need weather information for New York, Tokyo, and London. Please get all this information in a single function call.",
+    [batch_weather_function],
+    nil,
+    {temperature: 0.2}
+  )
+
+  # Check if the model wants to call the batch function
+  if response.has_function_call?
+    function_call = response.function_call
+    puts "Model wants to call function: #{function_call.name}"
+    puts "With arguments: #{function_call.response.inspect}"
+
+    function_name = function_call.name
+    args = function_call.response
+
+    if function_name == "get_weather_batch"
+      locations = args["locations"]
+      unit = args["unit"] || "celsius"
+
+      # Get weather for all locations at once
+      weather_data = get_weather_batch(locations, unit)
+      puts "Weather data for multiple locations: #{weather_data.inspect}"
+
+      # Process the function result with a single API call
+      final_response = Geminize.process_function_call(response) do |name, arguments|
+        get_weather_batch(arguments["locations"], arguments["unit"])
+      end
+
+      puts "\nFinal response from Gemini:"
+      puts final_response.text
+    else
+      puts "Unexpected function call: #{function_name}"
+    end
+  else
+    puts "Model did not request to call a function."
+    puts "Response: #{response.text}"
+  end
+rescue => e
+  puts "Error during batch function calling: #{e.message}"
+  puts "\nNOTE: If you hit a quota limit, try:"
+  puts "1. Using a paid API key with higher quotas"
+  puts "2. Reducing the number of examples you run"
+  puts "3. Adding delays between API calls"
+end
+
+puts "\n==========================================="
+puts "= END OF EXAMPLES ="
+puts "==========================================="

data/examples/models_api.rb

@@ -0,0 +1,125 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "geminize"
+require "pp"
+
+# Configure the library with your API key
+Geminize.configure do |config|
+  # Load API key from .env file or environment variables
+  config.api_key = ENV["GEMINI_API_KEY"]
+  # Use the latest API version
+  config.api_version = "v1beta"
+end
+
+# Helper method to display model information
+def display_model(model)
+  puts "========================"
+  puts "Model: #{model.display_name} (#{model.name})"
+  puts "Base Model ID: #{model.base_model_id}"
+  puts "Version: #{model.version}"
+  puts "Description: #{model.description}"
+  puts "Input Token Limit: #{model.input_token_limit}"
+  puts "Output Token Limit: #{model.output_token_limit}"
+  puts "Temperature: #{model.temperature}"
+  puts "Max Temperature: #{model.max_temperature}"
+  puts "Top P: #{model.top_p}"
+  puts "Top K: #{model.top_k}"
+  puts "Supported Methods: #{model.supported_generation_methods.join(", ")}"
+  puts "Capabilities:"
+  puts "  - Content Generation: #{model.supports_content_generation?}"
+  puts "  - Chat: #{model.supports_message_generation?}"
+  puts "  - Embedding: #{model.supports_embedding?}"
+  puts "  - Streaming: #{model.supports_streaming?}"
+  puts "========================\n\n"
+end
+
+puts "=== MODELS API EXAMPLES ==="
+
+# Example 1: List models (first page)
+puts "\n=== Example 1: List first page of models ==="
+begin
+  model_list = Geminize.list_models(page_size: 5)
+  puts "Found #{model_list.size} models on first page"
+  puts "Has more pages: #{model_list.has_more_pages?}"
+  puts "Next page token: #{model_list.next_page_token}"
+  puts "\nFirst model details:"
+  display_model(model_list.first) if model_list.first
+rescue => e
+  puts "Error listing models: #{e.message}"
+end
+
+# Example 2: Get detailed info for a specific model
+puts "\n=== Example 2: Get specific model info ==="
+begin
+  model = Geminize.get_model("gemini-1.5-flash")
+  puts "Retrieved model details:"
+  display_model(model)
+rescue => e
+  puts "Error getting model: #{e.message}"
+end
+
+# Example 3: Get all models (handling pagination)
+puts "\n=== Example 3: Get all models (handling pagination) ==="
+begin
+  all_models = Geminize.list_all_models
+  puts "Retrieved #{all_models.size} models in total"
+rescue => e
+  puts "Error listing all models: #{e.message}"
+end
+
+# Example 4: Filter models by capability
+puts "\n=== Example 4: Filter models by capability ==="
+begin
+  # Get models that support embedding
+  embedding_models = Geminize.get_embedding_models
+  puts "Found #{embedding_models.size} models that support embeddings"
+
+  # Get models that support content generation
+  content_models = Geminize.get_content_generation_models
+  puts "Found #{content_models.size} models that support content generation"
+
+  # Get models that support chat
+  chat_models = Geminize.get_chat_models
+  puts "Found #{chat_models.size} models that support chat"
+
+  # Get models that support streaming
+  streaming_models = Geminize.get_streaming_models
+  puts "Found #{streaming_models.size} models that support streaming"
+rescue => e
+  puts "Error filtering models: #{e.message}"
+end
+
+# Example 5: Filter models by specific method
+puts "\n=== Example 5: Filter models by specific method ==="
+begin
+  method_models = Geminize.get_models_by_method("generateContent")
+  puts "Found #{method_models.size} models that support generateContent"
+
+  # Display a specific model from the filtered list
+  if method_models.size > 0
+    puts "\nExample of a model supporting generateContent:"
+    display_model(method_models.first)
+  end
+rescue => e
+  puts "Error filtering by method: #{e.message}"
+end
+
+# Example 6: Model comparison
+puts "\n=== Example 6: Compare token limits ==="
+begin
+  all_models = Geminize.list_all_models
+
+  # Filter to models with higher token limits
+  high_capacity_models = all_models.filter_by_min_input_tokens(100_000)
+
+  puts "Models with 100k+ input token limits:"
+  high_capacity_models.each do |model|
+    puts "  - #{model.display_name}: #{model.input_token_limit} input tokens"
+  end
+rescue => e
+  puts "Error comparing models: #{e.message}"
+end
+
+puts "\n=== Examples Complete ==="

data/examples/safety_settings.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "geminize"
+
+# Configure the API key
+Geminize.configure do |config|
+  config.api_key = ENV["GEMINI_API_KEY"] # Make sure to set your API key in the environment
+  config.default_model = "gemini-1.5-pro-latest" # Use the latest model
+end
+
+# A prompt that might trigger safety filters
+POTENTIALLY_SENSITIVE_PROMPT = "Describe a violent conflict scene from a movie"
+
+puts "1. Generating with default safety settings:"
+begin
+  response = Geminize.generate_text(POTENTIALLY_SENSITIVE_PROMPT, nil, temperature: 0.2)
+  puts "Default response:\n#{response.text}\n\n"
+rescue Geminize::GeminizeError => e
+  puts "Error with default settings: #{e.message}\n\n"
+end
+
+puts "2. Generating with maximum safety (blocking most potentially harmful content):"
+begin
+  response = Geminize.generate_text_safe(POTENTIALLY_SENSITIVE_PROMPT, nil, temperature: 0.2)
+  puts "Maximum safety response:\n#{response.text}\n\n"
+rescue Geminize::GeminizeError => e
+  puts "Error with maximum safety: #{e.message}\n\n"
+end
+
+puts "3. Generating with minimum safety (blocking only high-risk content):"
+begin
+  response = Geminize.generate_text_permissive(POTENTIALLY_SENSITIVE_PROMPT, nil, temperature: 0.2)
+  puts "Minimum safety response:\n#{response.text}\n\n"
+rescue Geminize::GeminizeError => e
+  puts "Error with minimum safety: #{e.message}\n\n"
+end
+
+puts "4. Generating with custom safety settings:"
+begin
+  # Custom safety settings:
+  # - Block medium and above for dangerous content
+  # - Block low and above for hate speech
+  # - Block only high for sexually explicit content
+  # - No blocks for harassment
+  custom_safety_settings = [
+    {category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_MEDIUM_AND_ABOVE"},
+    {category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_LOW_AND_ABOVE"},
+    {category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold: "BLOCK_ONLY_HIGH"},
+    {category: "HARM_CATEGORY_HARASSMENT", threshold: "BLOCK_NONE"}
+  ]
+
+  response = Geminize.generate_with_safety_settings(
+    POTENTIALLY_SENSITIVE_PROMPT,
+    custom_safety_settings,
+    nil,
+    temperature: 0.2
+  )
+  puts "Custom safety response:\n#{response.text}\n\n"
+rescue Geminize::GeminizeError => e
+  puts "Error with custom safety: #{e.message}\n\n"
+end
+
+# Demonstrate direct usage of safety settings in a ContentRequest
+puts "5. Using safety settings directly in a ContentRequest:"
+begin
+  generator = Geminize::TextGeneration.new
+  content_request = Geminize::Models::ContentRequest.new(
+    POTENTIALLY_SENSITIVE_PROMPT,
+    nil,
+    temperature: 0.2
+  )
+
+  # Add specific safety settings
+  content_request.add_safety_setting("HARM_CATEGORY_DANGEROUS_CONTENT", "BLOCK_MEDIUM_AND_ABOVE")
+
+  response = generator.generate(content_request)
+  puts "ContentRequest safety response:\n#{response.text}\n\n"
+rescue Geminize::GeminizeError => e
+  puts "Error with ContentRequest safety: #{e.message}\n\n"
+end

data/lib/geminize/configuration.rb

@@ -17,7 +17,7 @@ module Geminize
     DEFAULT_MODEL = "gemini-2.0-flash"
 
     # Default embedding model
-    DEFAULT_EMBEDDING_MODEL = "embedding-001"
+    DEFAULT_EMBEDDING_MODEL = "gemini-embedding-exp-03-07"
 
     # Default timeout values (in seconds)
     DEFAULT_TIMEOUT = 30
@@ -69,9 +69,9 @@ module Geminize
     # @return [void]
     def reset!
       @api_key = ENV["GEMINI_API_KEY"]
-      @api_version = DEFAULT_API_VERSION
-      @default_model = DEFAULT_MODEL
-      @default_embedding_model = DEFAULT_EMBEDDING_MODEL
+      @api_version = ENV["GEMINI_API_VERSION"] || DEFAULT_API_VERSION
+      @default_model = ENV["GEMINI_MODEL"] || DEFAULT_MODEL
+      @default_embedding_model = ENV["GEMINI_EMBEDDING_MODEL"] || DEFAULT_EMBEDDING_MODEL
       @timeout = DEFAULT_TIMEOUT
       @open_timeout = DEFAULT_OPEN_TIMEOUT
       @streaming_timeout = DEFAULT_STREAMING_TIMEOUT

data/lib/geminize/model_info.rb

@@ -9,6 +9,9 @@ module Geminize
     # @return [Geminize::Client] The HTTP client
     attr_reader :client
 
+    # Default page size for listing models
+    DEFAULT_PAGE_SIZE = 50
+
     # Initialize a new ModelInfo instance
     # @param client [Geminize::Client, nil] The HTTP client to use
     # @param options [Hash] Additional options for the client
@@ -20,19 +23,26 @@ module Geminize
     end
 
     # List available models from the Gemini API
+    # @param page_size [Integer, nil] Number of models to return per page (max 1000)
+    # @param page_token [String, nil] Token for retrieving a specific page
     # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
     # @return [Geminize::Models::ModelList] List of available models
     # @raise [Geminize::GeminizeError] If the request fails
-    def list_models(force_refresh: false)
-      cache_key = "models_list"
+    def list_models(page_size: nil, page_token: nil, force_refresh: false)
+      cache_key = "models_list_#{page_size}_#{page_token}"
 
       # Check if we have a valid cached result
       if !force_refresh && @cache[cache_key] && @cache_expiry[cache_key] > Time.now
         return @cache[cache_key]
       end
 
+      # Prepare query parameters
+      params = {}
+      params[:pageSize] = page_size if page_size
+      params[:pageToken] = page_token
+
       # Make the API request
-      response = client.get("models")
+      response = client.get("models", params)
 
       # Create a ModelList from the response
       model_list = Models::ModelList.from_api_data(response)
@@ -44,13 +54,62 @@ module Geminize
       model_list
     end
 
+    # Get all available models, handling pagination automatically
+    # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
+    # @return [Geminize::Models::ModelList] Complete list of all available models
+    # @raise [Geminize::GeminizeError] If any request fails
+    def list_all_models(force_refresh: false)
+      cache_key = "all_models_list"
+
+      # Check if we have a valid cached result
+      if !force_refresh && @cache[cache_key] && @cache_expiry[cache_key] > Time.now
+        return @cache[cache_key]
+      end
+
+      all_models = []
+      page_token = nil
+
+      # Fetch first page
+      model_list = list_models(
+        page_size: DEFAULT_PAGE_SIZE,
+        page_token: page_token,
+        force_refresh: force_refresh
+      )
+      all_models.concat(model_list.models)
+
+      # Fetch additional pages if available
+      while model_list.has_more_pages?
+        page_token = model_list.next_page_token
+        model_list = list_models(
+          page_size: DEFAULT_PAGE_SIZE,
+          page_token: page_token,
+          force_refresh: force_refresh
+        )
+        all_models.concat(model_list.models)
+      end
+
+      # Create a consolidated model list
+      result = Models::ModelList.new(all_models)
+
+      # Cache the result
+      @cache[cache_key] = result
+      @cache_expiry[cache_key] = Time.now + @cache_ttl
+
+      result
+    end
+
     # Get information about a specific model
-    # @param model_id [String] The model ID to retrieve
+    # @param model_name [String] The model name to retrieve (models/{model})
     # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
     # @return [Geminize::Models::Model] The model information
     # @raise [Geminize::GeminizeError] If the request fails or model is not found
-    def get_model(model_id, force_refresh: false)
-      cache_key = "model_#{model_id}"
+    def get_model(model_name, force_refresh: false)
+      # Handle both formats: "models/gemini-1.5-pro" or just "gemini-1.5-pro"
+      unless model_name.start_with?("models/")
+        model_name = "models/#{model_name}"
+      end
+
+      cache_key = "model_#{model_name}"
 
       # Check if we have a valid cached result
       if !force_refresh && @cache[cache_key] && @cache_expiry[cache_key] > Time.now
@@ -59,7 +118,7 @@ module Geminize
 
       # Make the API request
       begin
-        response = client.get("models/#{model_id}")
+        response = client.get(model_name)
 
         # Create a Model from the response
         model = Models::Model.from_api_data(response)
@@ -71,10 +130,30 @@ module Geminize
         model
       rescue Geminize::NotFoundError => e
         # Re-raise with a more descriptive message
-        raise Geminize::NotFoundError.new("Model '#{model_id}' not found", e.code, e.http_status)
+        raise Geminize::NotFoundError.new("Model '#{model_name}' not found", e.code, e.http_status)
       end
     end
 
+    # Get models that support a specific generation method
+    # @param method [String] The generation method (e.g., "generateContent", "embedContent")
+    # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
+    # @return [Geminize::Models::ModelList] List of models that support the method
+    # @raise [Geminize::GeminizeError] If the request fails
+    def get_models_by_method(method, force_refresh: false)
+      all_models = list_all_models(force_refresh: force_refresh)
+      all_models.filter_by_method(method)
+    end
+
+    # Get models by base model ID
+    # @param base_model_id [String] The base model ID to filter by
+    # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
+    # @return [Geminize::Models::ModelList] List of models with the specified base model ID
+    # @raise [Geminize::GeminizeError] If the request fails
+    def get_models_by_base_id(base_model_id, force_refresh: false)
+      all_models = list_all_models(force_refresh: force_refresh)
+      all_models.filter_by_base_model_id(base_model_id)
+    end
+
     # Clear all cached model information
     # @return [void]
     def clear_cache