geminize 1.1.0 → 1.3.0

data/lib/geminize/models/content_request_extensions.rb

@@ -0,0 +1,227 @@
+# 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
+
+      # Enable code execution for the request
+      # @return [self] The request object for chaining
+      def enable_code_execution
+        @tools ||= []
+        @tools << Tool.new(nil, true)
+        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,129 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Extends ContentResponse with function calling capabilities
+    class ContentResponse
+      # @return [Geminize::Models::FunctionResponse, nil] The function call in the response, if any
+      attr_reader :function_call
+
+      # @return [String, nil] The raw JSON response content, if this is a JSON response
+      attr_reader :json_response
+
+      # @return [Geminize::Models::CodeExecution::ExecutableCode, nil] The executable code in the response, if any
+      attr_reader :executable_code
+
+      # @return [Geminize::Models::CodeExecution::CodeExecutionResult, nil] The code execution result in the response, if any
+      attr_reader :code_execution_result
+
+      # Store the response data for extensions
+      alias_method :original_initialize, :initialize
+      def initialize(response_data)
+        @response_data = response_data
+        original_initialize(response_data)
+        parse_function_call
+        parse_json_response
+        parse_code_execution
+      end
+
+      # Determine 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
+
+      # Determine if the response contains a JSON response
+      # @return [Boolean] true if the response contains a JSON response
+      def has_json_response?
+        !@json_response.nil?
+      end
+
+      # Determine if the response contains executable code
+      # @return [Boolean] true if the response contains executable code
+      def has_executable_code?
+        !@executable_code.nil?
+      end
+
+      # Determine if the response contains a code execution result
+      # @return [Boolean] true if the response contains a code execution result
+      def has_code_execution_result?
+        !@code_execution_result.nil?
+      end
+
+      private
+
+      # Parse the function call from the response
+      def parse_function_call
+        candidates = @response_data.dig("candidates") || []
+        return if candidates.empty?
+
+        content = candidates[0].dig("content") || {}
+        parts = content.dig("parts") || []
+        function_call_part = parts.find { |part| part.dig("functionCall") }
+
+        if function_call_part
+          function_call_data = function_call_part["functionCall"]
+          function_name = function_call_data["name"]
+          function_args = function_call_data["args"] || {}
+
+          @function_call = FunctionResponse.new(function_name, function_args)
+        end
+      end
+
+      # Parse JSON response if available
+      def parse_json_response
+        # First try to check if it's explicitly returned as JSON
+        if @response_data.dig("candidates", 0, "content", "parts", 0, "text")
+          text = @response_data.dig("candidates", 0, "content", "parts", 0, "text")
+          begin
+            @json_response = JSON.parse(text)
+            return
+          rescue JSON::ParserError
+            # Not valid JSON, continue checking other methods
+          end
+        end
+
+        # Next check if it's returned in structured format
+        candidates = @response_data.dig("candidates") || []
+        return if candidates.empty?
+
+        content = candidates[0].dig("content") || {}
+        parts = content.dig("parts") || []
+        json_part = parts.find { |part| part.key?("structuredValue") }
+
+        if json_part && json_part["structuredValue"]
+          @json_response = json_part["structuredValue"]
+        end
+      end
+
+      # Parse code execution data from the response
+      def parse_code_execution
+        candidates = @response_data.dig("candidates") || []
+        return if candidates.empty?
+
+        content = candidates[0].dig("content") || {}
+        parts = content.dig("parts") || []
+
+        # Find executable code
+        executable_code_part = parts.find { |part| part.dig("executableCode") }
+        if executable_code_part && executable_code_part["executableCode"]
+          code_data = executable_code_part["executableCode"]
+          language = code_data["language"] || "PYTHON"
+          code = code_data["code"] || ""
+
+          @executable_code = Geminize::Models::CodeExecution::ExecutableCode.new(language, code)
+        end
+
+        # Find code execution result
+        result_part = parts.find { |part| part.dig("codeExecutionResult") }
+        if result_part && result_part["codeExecutionResult"]
+          result_data = result_part["codeExecutionResult"]
+          outcome = result_data["outcome"] || "OUTCOME_OK"
+          output = result_data["output"] || ""
+
+          @code_execution_result = Geminize::Models::CodeExecution::CodeExecutionResult.new(outcome, output)
+        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