geminize 1.1.0 → 1.2.0

data/lib/geminize/module_extensions.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Geminize
+  class << self
+    # Generate text with function calling capabilities
+    # @param prompt [String] The input prompt
+    # @param functions [Array<Hash>] Array of function definitions
+    # @param model_name [String, nil] The model to use, defaults to the configured default model
+    # @param params [Hash] Additional parameters for generation
+    # @option params [Float] :temperature Controls randomness (0.0-1.0)
+    # @option params [Integer] :max_tokens Maximum tokens to generate
+    # @option params [Float] :top_p Top-p value for nucleus sampling (0.0-1.0)
+    # @option params [Integer] :top_k Top-k value for sampling
+    # @option params [Array<String>] :stop_sequences Stop sequences to end generation
+    # @option params [String] :system_instruction System instruction to guide model behavior
+    # @option params [String] :tool_execution_mode Tool execution mode ("AUTO", "MANUAL", or "NONE")
+    # @param with_retries [Boolean] Whether to retry the generation if it fails
+    # @param max_retries [Integer] Maximum number of retries
+    # @param retry_delay [Float] Delay between retries in seconds
+    # @param client_options [Hash] Options for the HTTP client
+    # @return [Geminize::Models::ContentResponse] The generated response
+    # @raise [Geminize::Error] If the generation fails
+    # @example Generate text with a function call
+    #   Geminize.generate_with_functions(
+    #     "What's the weather in New York?",
+    #     [
+    #       {
+    #         name: "get_weather",
+    #         description: "Get the current weather in a location",
+    #         parameters: {
+    #           type: "object",
+    #           properties: {
+    #             location: {
+    #               type: "string",
+    #               description: "The city and state, e.g. New York, NY"
+    #             },
+    #             unit: {
+    #               type: "string",
+    #               enum: ["celsius", "fahrenheit"],
+    #               description: "The unit of temperature"
+    #             }
+    #           },
+    #           required: ["location"]
+    #         }
+    #       }
+    #     ]
+    #   )
+    def generate_with_functions(prompt, functions, model_name = nil, params = {}, with_retries: true, max_retries: 3, retry_delay: 1.0, client_options: nil)
+      validate_configuration!
+
+      # Initialize the generator
+      client = client_options ? Client.new(client_options) : Client.new
+      generator = TextGeneration.new(client)
+
+      # Parse functions
+      if functions.nil? || !functions.is_a?(Array) || functions.empty?
+        raise Geminize::ValidationError.new(
+          "Functions must be a non-empty array",
+          "INVALID_ARGUMENT"
+        )
+      end
+
+      # Set up params with defaults
+      generation_params = params.dup
+      tool_execution_mode = generation_params.delete(:tool_execution_mode) || "AUTO"
+      with_retries = generation_params.delete(:with_retries) != false if generation_params.key?(:with_retries)
+
+      # Enhance the system instruction to ensure function calling
+      generation_params[:system_instruction] ||= ""
+      generation_params[:system_instruction] = "You are a helpful assistant. When you encounter a question that you can answer by calling a function, you must always use the provided function. Always respond using the function call format, not with your own text. " + generation_params[:system_instruction]
+
+      # Create the request
+      content_request = Models::ContentRequest.new(
+        prompt,
+        model_name || configuration.default_model,
+        generation_params
+      )
+
+      # Add functions to the request
+      functions.each do |function|
+        content_request.add_function(
+          function[:name],
+          function[:description],
+          function[:parameters]
+        )
+      end
+
+      # Set the tool config
+      content_request.set_tool_config(tool_execution_mode)
+
+      # Generate the response
+      if with_retries
+        generator.generate_with_retries(content_request, max_retries, retry_delay)
+      else
+        generator.generate(content_request)
+      end
+    end
+
+    # Generate JSON output from a prompt using the Gemini API
+    # @param prompt [String] The input prompt
+    # @param model_name [String, nil] The model to use, defaults to the configured default model
+    # @param params [Hash] Additional parameters for generation
+    # @option params [Float] :temperature Controls randomness (0.0-1.0)
+    # @option params [Integer] :max_tokens Maximum tokens to generate
+    # @option params [Float] :top_p Top-p value for nucleus sampling (0.0-1.0)
+    # @option params [Integer] :top_k Top-k value for sampling
+    # @option params [Array<String>] :stop_sequences Stop sequences to end generation
+    # @option params [String] :system_instruction System instruction to guide model behavior
+    # @param with_retries [Boolean] Whether to retry the generation if it fails
+    # @param max_retries [Integer] Maximum number of retries
+    # @param retry_delay [Float] Delay between retries in seconds
+    # @param client_options [Hash] Options for the HTTP client
+    # @option params [Hash] :json_schema Schema for the JSON output (optional)
+    # @return [Geminize::Models::ContentResponse] The generated response with JSON content
+    # @raise [Geminize::Error] If the generation fails
+    # @example Generate JSON output
+    #   response = Geminize.generate_json(
+    #     "List 3 planets with their diameter",
+    #     nil,
+    #     system_instruction: "Return the information as a JSON array"
+    #   )
+    #   planets = response.json_response # Returns parsed JSON
+    def generate_json(prompt, model_name = nil, params = {}, with_retries: true, max_retries: 3, retry_delay: 1.0, client_options: nil)
+      validate_configuration!
+
+      # Initialize the generator
+      client = client_options ? Client.new(client_options) : Client.new
+      generator = TextGeneration.new(client)
+
+      # Set up params with defaults
+      generation_params = params.dup
+      with_retries = generation_params.delete(:with_retries) != false if generation_params.key?(:with_retries)
+
+      # Enhance the system instruction for JSON output
+      generation_params[:system_instruction] ||= ""
+      generation_params[:system_instruction] = "You must respond with valid JSON only, with no explanation or other text. " + generation_params[:system_instruction]
+
+      # Create the request
+      content_request = Models::ContentRequest.new(
+        prompt,
+        model_name || configuration.default_model,
+        generation_params
+      )
+
+      # Enable JSON mode
+      content_request.enable_json_mode
+
+      # Generate the response
+      if with_retries
+        generator.generate_with_retries(content_request, max_retries, retry_delay)
+      else
+        generator.generate(content_request)
+      end
+    end
+
+    # Process a function call by executing a provided block and returning the result to Gemini
+    # @param response [Geminize::Models::ContentResponse] The response containing a function call
+    # @param model_name [String, nil] The model to use for the followup, defaults to the configured default model
+    # @param with_retries [Boolean] Whether to retry the generation if it fails
+    # @param max_retries [Integer] Maximum number of retries
+    # @param retry_delay [Float] Delay between retries in seconds
+    # @param client_options [Hash] Options for the HTTP client
+    # @yield [function_name, args] Block to execute the function
+    # @yieldparam function_name [String] The name of the function to execute
+    # @yieldparam args [Hash] The arguments to pass to the function
+    # @yieldreturn [Hash, Array, String, Numeric, Boolean, nil] The result of the function
+    # @return [Geminize::Models::ContentResponse] The response after processing the function
+    # @raise [Geminize::Error] If processing fails
+    # @example Process a function call
+    #   response = Geminize.generate_with_functions("What's the weather in New York?", [...])
+    #   if response.has_function_call?
+    #     final_response = Geminize.process_function_call(response) do |function_name, args|
+    #       if function_name == "get_weather"
+    #         # Call a real weather API here
+    #         { temperature: 72, conditions: "sunny" }
+    #       end
+    #     end
+    #     puts final_response.text
+    #   end
+    def process_function_call(response, model_name = nil, with_retries: true, max_retries: 3, retry_delay: 1.0, client_options: nil)
+      validate_configuration!
+
+      # Ensure a block is provided
+      unless block_given?
+        raise Geminize::ValidationError.new(
+          "A block must be provided to process the function call",
+          "INVALID_ARGUMENT"
+        )
+      end
+
+      # Ensure the response has a function call
+      unless response.has_function_call?
+        raise Geminize::ValidationError.new(
+          "The response does not contain a function call",
+          "INVALID_ARGUMENT"
+        )
+      end
+
+      # Extract function call information
+      function_call = response.function_call
+      function_name = function_call.name
+      function_args = function_call.response
+
+      # Call the provided block with the function information
+      result = yield(function_name, function_args)
+
+      # Create a function response
+      Models::FunctionResponse.new(function_name, result)
+
+      # Initialize the generator
+      client = client_options ? Client.new(client_options) : Client.new
+      generator = TextGeneration.new(client)
+
+      # Create a request with the function result
+      content_request = Models::ContentRequest.new(
+        "Function #{function_name} returned: #{result.inspect}",
+        model_name || configuration.default_model
+      )
+
+      # Generate the response
+      if with_retries
+        generator.generate_with_retries(content_request, max_retries, retry_delay)
+      else
+        generator.generate(content_request)
+      end
+    end
+  end
+end

data/lib/geminize/module_safety.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Geminize
+  class << self
+    # Generate text with custom safety settings
+    # @param prompt [String] The input prompt
+    # @param safety_settings [Array<Hash>] Array of safety setting definitions
+    # @param model_name [String, nil] The model to use (optional)
+    # @param params [Hash] Additional generation parameters
+    # @option params [Float] :temperature Controls randomness (0.0-1.0)
+    # @option params [Integer] :max_tokens Maximum tokens to generate
+    # @option params [Float] :top_p Top-p value for nucleus sampling (0.0-1.0)
+    # @option params [Integer] :top_k Top-k value for sampling
+    # @option params [Array<String>] :stop_sequences Stop sequences to end generation
+    # @option params [String] :system_instruction System instruction to guide model behavior
+    # @option params [Boolean] :with_retries Enable retries for transient errors (default: true)
+    # @option params [Integer] :max_retries Maximum retry attempts (default: 3)
+    # @option params [Float] :retry_delay Initial delay between retries in seconds (default: 1.0)
+    # @option params [Hash] :client_options Options to pass to the client
+    # @return [Geminize::Models::ContentResponse] The generation response
+    # @raise [Geminize::GeminizeError] If the request fails
+    # @example Generate text with specific safety settings
+    #   Geminize.generate_with_safety_settings(
+    #     "Tell me a scary story",
+    #     [
+    #       {category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_MEDIUM_AND_ABOVE"},
+    #       {category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_LOW_AND_ABOVE"}
+    #     ]
+    #   )
+    def generate_with_safety_settings(prompt, safety_settings, model_name = nil, params = {})
+      validate_configuration!
+
+      # Extract special options
+      with_retries = params.delete(:with_retries) != false # Default to true
+      max_retries = params.delete(:max_retries) || 3
+      retry_delay = params.delete(:retry_delay) || 1.0
+      client_options = params.delete(:client_options) || {}
+
+      # Create the generator and content request
+      generator = TextGeneration.new(nil, client_options)
+      content_request = Models::ContentRequest.new(
+        prompt,
+        model_name || configuration.default_model,
+        params
+      )
+
+      # Add safety settings to the request
+      safety_settings.each do |setting|
+        content_request.add_safety_setting(
+          setting[:category],
+          setting[:threshold]
+        )
+      end
+
+      # Generate with or without retries
+      if with_retries
+        generator.generate_with_retries(content_request, max_retries, retry_delay)
+      else
+        generator.generate(content_request)
+      end
+    end
+
+    # Generate text with maximum safety (blocks most potentially harmful content)
+    # @param prompt [String] The input prompt
+    # @param model_name [String, nil] The model to use (optional)
+    # @param params [Hash] Additional generation parameters
+    # @return [Geminize::Models::ContentResponse] The generation response
+    # @raise [Geminize::GeminizeError] If the request fails
+    # @example Generate text with maximum safety
+    #   Geminize.generate_text_safe("Tell me about conflicts", nil, temperature: 0.7)
+    def generate_text_safe(prompt, model_name = nil, params = {})
+      validate_configuration!
+
+      # Extract special options
+      with_retries = params.delete(:with_retries) != false # Default to true
+      max_retries = params.delete(:max_retries) || 3
+      retry_delay = params.delete(:retry_delay) || 1.0
+      client_options = params.delete(:client_options) || {}
+
+      # Create the generator and content request
+      generator = TextGeneration.new(nil, client_options)
+      content_request = Models::ContentRequest.new(
+        prompt,
+        model_name || configuration.default_model,
+        params
+      )
+
+      # Set maximum safety (block low and above)
+      content_request.block_all_harmful_content
+
+      # Generate with or without retries
+      if with_retries
+        generator.generate_with_retries(content_request, max_retries, retry_delay)
+      else
+        generator.generate(content_request)
+      end
+    end
+
+    # Generate text with minimum safety (blocks only high-risk content)
+    # @param prompt [String] The input prompt
+    # @param model_name [String, nil] The model to use (optional)
+    # @param params [Hash] Additional generation parameters
+    # @return [Geminize::Models::ContentResponse] The generation response
+    # @raise [Geminize::GeminizeError] If the request fails
+    # @example Generate text with minimum safety
+    #   Geminize.generate_text_permissive("Tell me about conflicts", nil, temperature: 0.7)
+    def generate_text_permissive(prompt, model_name = nil, params = {})
+      validate_configuration!
+
+      # Extract special options
+      with_retries = params.delete(:with_retries) != false # Default to true
+      max_retries = params.delete(:max_retries) || 3
+      retry_delay = params.delete(:retry_delay) || 1.0
+      client_options = params.delete(:client_options) || {}
+
+      # Create the generator and content request
+      generator = TextGeneration.new(nil, client_options)
+      content_request = Models::ContentRequest.new(
+        prompt,
+        model_name || configuration.default_model,
+        params
+      )
+
+      # Set minimum safety (block only high risk)
+      content_request.block_only_high_risk_content
+
+      # Generate with or without retries
+      if with_retries
+        generator.generate_with_retries(content_request, max_retries, retry_delay)
+      else
+        generator.generate(content_request)
+      end
+    end
+  end
+end

data/lib/geminize/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Geminize
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/geminize.rb

@@ -28,6 +28,11 @@ require_relative "geminize/models/memory"
 require_relative "geminize/models/conversation"
 require_relative "geminize/models/embedding_request"
 require_relative "geminize/models/embedding_response"
+require_relative "geminize/models/function_declaration"
+require_relative "geminize/models/tool"
+require_relative "geminize/models/tool_config"
+require_relative "geminize/models/function_response"
+require_relative "geminize/models/safety_setting"
 require_relative "geminize/request_builder"
 require_relative "geminize/vector_utils"
 require_relative "geminize/text_generation"
@@ -37,6 +42,13 @@ require_relative "geminize/conversation_repository"
 require_relative "geminize/conversation_service"
 require_relative "geminize/model_info"
 
+# Load extensions
+require_relative "geminize/models/content_request_extensions"
+require_relative "geminize/models/content_response_extensions"
+require_relative "geminize/models/content_request_safety"
+require_relative "geminize/module_extensions"
+require_relative "geminize/module_safety"
+
 # Main module for the Geminize gem
 module Geminize
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: geminize
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Nhat Long Nguyen
@@ -184,9 +184,11 @@ files:
 - examples/README.md
 - examples/configuration.rb
 - examples/embeddings.rb
+- examples/function_calling.rb
 - examples/models_api.rb
 - examples/multimodal.rb
 - examples/ruby.png
+- examples/safety_settings.rb
 - examples/system_instructions.rb
 - lib/geminize.rb
 - lib/geminize/chat.rb
@@ -203,15 +205,25 @@ files:
 - lib/geminize/models/chat_request.rb
 - lib/geminize/models/chat_response.rb
 - lib/geminize/models/content_request.rb
+- lib/geminize/models/content_request_extensions.rb
+- lib/geminize/models/content_request_safety.rb
 - lib/geminize/models/content_response.rb
+- lib/geminize/models/content_response_extensions.rb
 - lib/geminize/models/conversation.rb
 - lib/geminize/models/embedding_request.rb
 - lib/geminize/models/embedding_response.rb
+- lib/geminize/models/function_declaration.rb
+- lib/geminize/models/function_response.rb
 - lib/geminize/models/memory.rb
 - lib/geminize/models/message.rb
 - lib/geminize/models/model.rb
 - lib/geminize/models/model_list.rb
+- lib/geminize/models/safety_setting.rb
 - lib/geminize/models/stream_response.rb
+- lib/geminize/models/tool.rb
+- lib/geminize/models/tool_config.rb
+- lib/geminize/module_extensions.rb
+- lib/geminize/module_safety.rb
 - lib/geminize/request_builder.rb
 - lib/geminize/text_generation.rb
 - lib/geminize/validators.rb