geminize 1.1.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/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/models/content_request_extensions.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Extends ContentRequest with function calling and JSON mode support
+    class ContentRequest
+      # Additional attributes for function calling and JSON mode
+
+      # @return [Array<Geminize::Models::Tool>] The tools for this request
+      attr_reader :tools
+
+      # @return [Geminize::Models::ToolConfig, nil] The tool configuration
+      attr_reader :tool_config
+
+      # @return [String, nil] The MIME type for the response format
+      attr_accessor :response_mime_type
+
+      # Add a function to the request
+      # @param name [String] The name of the function
+      # @param description [String] A description of what the function does
+      # @param parameters [Hash] JSON schema for function parameters
+      # @return [self] The request object for chaining
+      # @raise [Geminize::ValidationError] If the function is invalid
+      def add_function(name, description, parameters)
+        @tools ||= []
+
+        function_declaration = FunctionDeclaration.new(name, description, parameters)
+        tool = Tool.new(function_declaration)
+
+        @tools << tool
+        self
+      end
+
+      # Set the tool config for function execution
+      # @param execution_mode [String] The execution mode for functions ("AUTO", "MANUAL", or "NONE")
+      # @return [self] The request object for chaining
+      # @raise [Geminize::ValidationError] If the tool config is invalid
+      def set_tool_config(execution_mode = "AUTO")
+        @tool_config = ToolConfig.new(execution_mode)
+        self
+      end
+
+      # Enable JSON mode for structured output
+      # @return [self] The request object for chaining
+      def enable_json_mode
+        @response_mime_type = "application/json"
+        self
+      end
+
+      # Disable JSON mode and return to regular text output
+      # @return [self] The request object for chaining
+      def disable_json_mode
+        @response_mime_type = nil
+        self
+      end
+
+      # Override the to_hash method to include additional function calling features
+      # @return [Hash] The request as a hash
+      def to_hash
+        # First get the base implementation's hash by calling the standard method
+        # Use the implementation from ContentRequest directly
+        request = {
+          contents: [
+            {
+              parts: @content_parts.map do |part|
+                if part[:type] == "text"
+                  {text: part[:text]}
+                elsif part[:type] == "image"
+                  {
+                    inlineData: {
+                      mimeType: part[:mime_type],
+                      data: part[:data]
+                    }
+                  }
+                end
+              end.compact
+            }
+          ]
+        }
+
+        # Add generation config
+        if @temperature || @max_tokens || @top_p || @top_k || @stop_sequences
+          request[:generationConfig] = {}
+          request[:generationConfig][:temperature] = @temperature if @temperature
+          request[:generationConfig][:maxOutputTokens] = @max_tokens if @max_tokens
+          request[:generationConfig][:topP] = @top_p if @top_p
+          request[:generationConfig][:topK] = @top_k if @top_k
+          request[:generationConfig][:stopSequences] = @stop_sequences if @stop_sequences
+        end
+
+        # Add system instruction
+        if @system_instruction
+          request[:systemInstruction] = {
+            parts: [
+              {
+                text: @system_instruction
+              }
+            ]
+          }
+        end
+
+        # Add tools if present
+        if @tools && !@tools.empty?
+          request[:tools] = @tools.map(&:to_hash)
+        end
+
+        # Add tool config if present
+        if @tool_config
+          request[:toolConfig] = @tool_config.to_hash
+        end
+
+        # Add response format if JSON mode is enabled
+        if @response_mime_type
+          request[:generationConfig] ||= {}
+          request[:generationConfig][:responseSchema] = {
+            type: "object",
+            properties: {
+              # Add a sample property to satisfy the API requirement
+              # This is a generic structure that will be overridden by the model's understanding
+              # of what properties to include based on the prompt
+              result: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: {type: "string"},
+                    value: {type: "string"}
+                  }
+                }
+              }
+            }
+          }
+          request[:generationConfig][:responseMimeType] = @response_mime_type
+        end
+
+        request
+      end
+
+      # Original validate! method includes validation for tools and JSON mode
+      alias_method :original_validate!, :validate!
+
+      def validate!
+        # Don't call super, instead call the original specific validations directly
+        validate_prompt!
+        validate_system_instruction! if @system_instruction
+        validate_temperature! if @temperature
+        validate_max_tokens! if @max_tokens
+        validate_top_p! if @top_p
+        validate_top_k! if @top_k
+        validate_stop_sequences! if @stop_sequences
+        validate_content_parts!
+
+        # Then validate our extensions
+        validate_tools!
+        validate_tool_config!
+        validate_response_mime_type!
+        true
+      end
+
+      private
+
+      # Validate the tools
+      # @raise [Geminize::ValidationError] If the tools are invalid
+      def validate_tools!
+        return if @tools.nil? || @tools.empty?
+
+        unless @tools.is_a?(Array)
+          raise Geminize::ValidationError.new(
+            "Tools must be an array, got #{@tools.class}",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        @tools.each_with_index do |tool, index|
+          unless tool.is_a?(Tool)
+            raise Geminize::ValidationError.new(
+              "Tool at index #{index} must be a Tool, got #{tool.class}",
+              "INVALID_ARGUMENT"
+            )
+          end
+        end
+      end
+
+      # Validate the tool config
+      # @raise [Geminize::ValidationError] If the tool config is invalid
+      def validate_tool_config!
+        return if @tool_config.nil?
+
+        unless @tool_config.is_a?(ToolConfig)
+          raise Geminize::ValidationError.new(
+            "Tool config must be a ToolConfig, got #{@tool_config.class}",
+            "INVALID_ARGUMENT"
+          )
+        end
+      end
+
+      # Validate the response MIME type
+      # @raise [Geminize::ValidationError] If the response MIME type is invalid
+      def validate_response_mime_type!
+        return if @response_mime_type.nil?
+
+        unless @response_mime_type.is_a?(String)
+          raise Geminize::ValidationError.new(
+            "Response MIME type must be a string, got #{@response_mime_type.class}",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        # For now, only allow JSON
+        unless @response_mime_type == "application/json"
+          raise Geminize::ValidationError.new(
+            "Response MIME type must be 'application/json', got #{@response_mime_type}",
+            "INVALID_ARGUMENT"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/geminize/models/content_request_safety.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Extends ContentRequest with safety settings support
+    class ContentRequest
+      # @return [Array<Geminize::Models::SafetySetting>] The safety settings for this request
+      attr_reader :safety_settings
+
+      # Add a safety setting to the request
+      # @param category [String] The harm category this setting applies to
+      # @param threshold [String] The threshold level for filtering
+      # @return [self] The request object for chaining
+      # @raise [Geminize::ValidationError] If the safety setting is invalid
+      def add_safety_setting(category, threshold)
+        @safety_settings ||= []
+
+        safety_setting = SafetySetting.new(category, threshold)
+        @safety_settings << safety_setting
+
+        self
+      end
+
+      # Set default safety settings for all harm categories
+      # @param threshold [String] The threshold level to apply to all categories
+      # @return [self] The request object for chaining
+      # @raise [Geminize::ValidationError] If the threshold is invalid
+      def set_default_safety_settings(threshold)
+        @safety_settings = []
+
+        SafetySetting::HARM_CATEGORIES.each do |category|
+          add_safety_setting(category, threshold)
+        end
+
+        self
+      end
+
+      # Block all harmful content (most conservative setting)
+      # @return [self] The request object for chaining
+      def block_all_harmful_content
+        set_default_safety_settings("BLOCK_LOW_AND_ABOVE")
+      end
+
+      # Block only high-risk content (least conservative setting)
+      # @return [self] The request object for chaining
+      def block_only_high_risk_content
+        set_default_safety_settings("BLOCK_ONLY_HIGH")
+      end
+
+      # Remove all safety settings (use with caution)
+      # @return [self] The request object for chaining
+      def remove_safety_settings
+        @safety_settings = []
+        self
+      end
+
+      # Get the base to_hash method - this will use the one defined in content_request_extensions.rb if available
+      alias_method :safety_original_to_hash, :to_hash unless method_defined?(:safety_original_to_hash)
+
+      # Override the to_hash method to include safety settings
+      # @return [Hash] The request as a hash
+      def to_hash
+        # Get the base hash (will include tools if that extension is loaded)
+        request = defined?(original_to_hash) ? original_to_hash : safety_original_to_hash
+
+        # Add safety settings if present
+        if @safety_settings && !@safety_settings.empty?
+          request[:safetySettings] = @safety_settings.map(&:to_hash)
+        end
+
+        request
+      end
+
+      # Validate method for safety settings - should only be called if not overridden by content_request_extensions.rb
+      # If that file's validate! is called, it should also call validate_safety_settings!
+      def validate!
+        # Don't call super, instead call the necessary validations directly
+        # Check if original_validate! is defined from the extensions
+        if defined?(original_validate!)
+          original_validate!
+        else
+          # Call the original internal validation methods
+          validate_prompt!
+          validate_system_instruction! if @system_instruction
+          validate_temperature! if @temperature
+          validate_max_tokens! if @max_tokens
+          validate_top_p! if @top_p
+          validate_top_k! if @top_k
+          validate_stop_sequences! if @stop_sequences
+          validate_content_parts!
+        end
+
+        # Add our safety validation
+        validate_safety_settings!
+        true
+      end
+
+      private
+
+      # Validate the safety settings
+      # @raise [Geminize::ValidationError] If the safety settings are invalid
+      def validate_safety_settings!
+        return if @safety_settings.nil? || @safety_settings.empty?
+
+        unless @safety_settings.is_a?(Array)
+          raise Geminize::ValidationError.new(
+            "Safety settings must be an array, got #{@safety_settings.class}",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        @safety_settings.each_with_index do |setting, index|
+          unless setting.is_a?(SafetySetting)
+            raise Geminize::ValidationError.new(
+              "Safety setting at index #{index} must be a SafetySetting, got #{setting.class}",
+              "INVALID_ARGUMENT"
+            )
+          end
+        end
+      end
+    end
+  end
+end