geminize 1.0.0 → 1.2.0

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

data/lib/geminize/models/content_response_extensions.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Extends ContentResponse with function calling response handling
+    class ContentResponse
+      # Get the function call information from the response
+      # @return [Geminize::Models::FunctionResponse, nil] Function call information or nil if not present
+      def function_call
+        return @function_call if defined?(@function_call)
+
+        @function_call = nil
+        candidates = @raw_response["candidates"]
+
+        if candidates && !candidates.empty?
+          content = candidates.first["content"]
+          if content && content["parts"] && !content["parts"].empty?
+            function_call_part = content["parts"].find { |part| part["functionCall"] || part["function_call"] }
+
+            if function_call_part
+              # Handle both "functionCall" and "function_call" formats (API may vary)
+              function_data = function_call_part["functionCall"] || function_call_part["function_call"]
+
+              if function_data
+                # Extract name and args - handle different API response formats
+                name = function_data["name"]
+                args = function_data["args"] || function_data["arguments"]
+
+                if name
+                  @function_call = FunctionResponse.new(name, args || {})
+                end
+              end
+            end
+          end
+        end
+
+        @function_call
+      end
+
+      # Check if the response contains a function call
+      # @return [Boolean] True if the response contains a function call
+      def has_function_call?
+        !function_call.nil?
+      end
+
+      # Get structured JSON response if available
+      # @return [Hash, nil] Parsed JSON response or nil if not a JSON response
+      def json_response
+        return @json_response if defined?(@json_response)
+
+        @json_response = nil
+
+        if has_text?
+          begin
+            @json_response = JSON.parse(text)
+          rescue JSON::ParserError
+            # Try to parse any JSON-like content from the text
+            json_match = text.match(/```json\s*(.*?)\s*```/m) || text.match(/\{.*\}/m) || text.match(/\[.*\]/m)
+            if json_match
+              begin
+                @json_response = JSON.parse(json_match[1] || json_match[0])
+              rescue JSON::ParserError
+                # Still not valid JSON
+                @json_response = nil
+              end
+            end
+          end
+        end
+
+        @json_response
+      end
+
+      # Check if the response contains valid JSON
+      # @return [Boolean] True if the response contains valid JSON
+      def has_json_response?
+        !json_response.nil?
+      end
+
+      # Enhanced parse_response method to handle function calls
+      alias_method :original_parse_response, :parse_response
+
+      private
+
+      # Parse the response data and extract relevant information
+      def parse_response
+        original_parse_response
+        # Clear any cached function call before parsing again
+        remove_instance_variable(:@function_call) if defined?(@function_call)
+        parse_function_call
+      end
+
+      # Parse function call information from the response
+      def parse_function_call
+        candidates = @raw_response["candidates"]
+
+        if candidates && !candidates.empty?
+          content = candidates.first["content"]
+          if content && content["parts"] && !content["parts"].empty?
+            function_call_part = content["parts"].find { |part| part["functionCall"] || part["function_call"] }
+
+            if function_call_part
+              # Handle both "functionCall" and "function_call" formats (API may vary)
+              function_data = function_call_part["functionCall"] || function_call_part["function_call"]
+
+              if function_data
+                # Extract name and args - handle different API response formats
+                name = function_data["name"]
+                args = function_data["args"] || function_data["arguments"]
+
+                if name
+                  @function_call = FunctionResponse.new(name, args || {})
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/geminize/models/function_declaration.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Represents a function declaration for function calling in Gemini API
+    class FunctionDeclaration
+      # @return [String] Name of the function
+      attr_reader :name
+
+      # @return [String] Description of what the function does
+      attr_reader :description
+
+      # @return [Hash] JSON schema for function parameters
+      attr_reader :parameters
+
+      # Initialize a new function declaration
+      # @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
+      # @raise [Geminize::ValidationError] If the function declaration is invalid
+      def initialize(name, description, parameters)
+        @name = name
+        @description = description
+        @parameters = parameters
+        validate!
+      end
+
+      # Validate the function declaration
+      # @raise [Geminize::ValidationError] If the function declaration is invalid
+      # @return [Boolean] true if validation passes
+      def validate!
+        validate_name!
+        validate_description!
+        validate_parameters!
+        true
+      end
+
+      # Convert the function declaration to a hash for API requests
+      # @return [Hash] The function declaration as a hash
+      def to_hash
+        {
+          name: @name,
+          description: @description,
+          parameters: @parameters
+        }
+      end
+
+      # Alias for to_hash
+      # @return [Hash] The function declaration as a hash
+      def to_h
+        to_hash
+      end
+
+      private
+
+      # Validate the function name
+      # @raise [Geminize::ValidationError] If the name is invalid
+      def validate_name!
+        unless @name.is_a?(String)
+          raise Geminize::ValidationError.new(
+            "Function name must be a string, got #{@name.class}",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        if @name.empty?
+          raise Geminize::ValidationError.new(
+            "Function name cannot be empty",
+            "INVALID_ARGUMENT"
+          )
+        end
+      end
+
+      # Validate the function description
+      # @raise [Geminize::ValidationError] If the description is invalid
+      def validate_description!
+        unless @description.is_a?(String)
+          raise Geminize::ValidationError.new(
+            "Function description must be a string, got #{@description.class}",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        if @description.empty?
+          raise Geminize::ValidationError.new(
+            "Function description cannot be empty",
+            "INVALID_ARGUMENT"
+          )
+        end
+      end
+
+      # Validate the function parameters
+      # @raise [Geminize::ValidationError] If the parameters are invalid
+      def validate_parameters!
+        unless @parameters.is_a?(Hash)
+          raise Geminize::ValidationError.new(
+            "Function parameters must be a hash, got #{@parameters.class}",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        # Validate that the parameters follow JSON Schema format
+        unless @parameters.key?(:type) || @parameters.key?("type")
+          raise Geminize::ValidationError.new(
+            "Function parameters must include a 'type' field",
+            "INVALID_ARGUMENT"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/geminize/models/function_response.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Represents a function response from Gemini API
+    class FunctionResponse
+      # @return [String] The name of the function that was called
+      attr_reader :name
+
+      # @return [Hash, Array, String, Numeric, Boolean, nil] The response from the function
+      attr_reader :response
+
+      # Initialize a new function response
+      # @param name [String] The name of the function that was called
+      # @param response [Hash, Array, String, Numeric, Boolean, nil] The response from the function
+      def initialize(name, response)
+        @name = name
+        @response = response
+        validate!
+      end
+
+      # Validate the function response
+      # @raise [Geminize::ValidationError] If the function response is invalid
+      # @return [Boolean] true if validation passes
+      def validate!
+        if @name.nil? || @name.empty?
+          raise Geminize::ValidationError.new(
+            "Function name cannot be empty",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        true
+      end
+
+      # Create a FunctionResponse from a hash
+      # @param hash [Hash] The hash representation of a function response
+      # @return [Geminize::Models::FunctionResponse] The function response
+      # @raise [Geminize::ValidationError] If the hash is invalid
+      def self.from_hash(hash)
+        unless hash.is_a?(Hash)
+          raise Geminize::ValidationError.new(
+            "Expected a Hash, got #{hash.class}",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        name = hash["name"] || hash[:name]
+        response = hash["response"] || hash[:response]
+
+        new(name, response)
+      end
+
+      # Convert the function response to a hash
+      # @return [Hash] The function response as a hash
+      def to_hash
+        {
+          name: @name,
+          response: @response
+        }
+      end
+
+      # Alias for to_hash
+      # @return [Hash] The function response as a hash
+      def to_h
+        to_hash
+      end
+    end
+  end
+end