geminize 0.1.0

data/lib/geminize/text_generation.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Geminize
+  # Class for text generation functionality
+  class TextGeneration
+    # @return [Geminize::Client] The client instance
+    attr_reader :client
+
+    # Initialize a new text generation instance
+    # @param client [Geminize::Client, nil] The client to use (optional)
+    # @param options [Hash] Additional options
+    def initialize(client = nil, options = {})
+      @client = client || Client.new(options)
+      @options = options
+    end
+
+    # Generate text based on a content request
+    # @param content_request [Geminize::Models::ContentRequest] The content request
+    # @return [Geminize::Models::ContentResponse] The generation response
+    # @raise [Geminize::GeminizeError] If the request fails
+    def generate(content_request)
+      model_name = content_request.model_name
+      endpoint = RequestBuilder.build_text_generation_endpoint(model_name)
+      payload = RequestBuilder.build_text_generation_request(content_request)
+
+      response_data = @client.post(endpoint, payload)
+      Models::ContentResponse.from_hash(response_data)
+    end
+
+    # Generate text from a prompt string with optional parameters
+    # @param prompt [String] The input prompt
+    # @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
+    # @return [Geminize::Models::ContentResponse] The generation response
+    # @raise [Geminize::GeminizeError] If the request fails
+    def generate_text(prompt, model_name = nil, params = {})
+      model = model_name || Geminize.configuration.default_model
+
+      content_request = Models::ContentRequest.new(
+        prompt,
+        model,
+        params
+      )
+
+      generate(content_request)
+    end
+
+    # Generate a streaming text response from a prompt string with optional parameters
+    # @param prompt [String] The input prompt
+    # @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 [Symbol] :stream_mode Mode for processing stream chunks (:raw, :incremental, or :delta)
+    # @option params [String] :system_instruction System instruction to guide model behavior
+    # @yield [chunk] Yields each chunk of the streaming response
+    # @yieldparam chunk [String, Hash, StreamResponse] A chunk of the response
+    # @return [void]
+    # @raise [Geminize::GeminizeError] If the request fails
+    # @example Generate text with streaming, yielding each chunk
+    #   text_generation.generate_text_stream("Tell me a story") do |chunk|
+    #     puts chunk
+    #   end
+    # @example Generate text with incremental mode
+    #   accumulated_text = ""
+    #   text_generation.generate_text_stream("Tell me a story", nil, stream_mode: :incremental) do |text|
+    #     # text contains the full response so far
+    #     print "\r#{text}"
+    #   end
+    # @example Generate text with delta mode (only new content)
+    #   text_generation.generate_text_stream("Tell me a story", nil, stream_mode: :delta) do |new_text|
+    #     # new_text contains only the new content in this chunk
+    #     print new_text
+    #   end
+    def generate_text_stream(prompt, model_name = nil, params = {}, &block)
+      raise ArgumentError, "A block is required for streaming" unless block_given?
+
+      # Extract stream processing mode
+      stream_mode = params.delete(:stream_mode) || :incremental
+      unless [:raw, :incremental, :delta].include?(stream_mode)
+        raise ArgumentError, "Invalid stream_mode. Must be :raw, :incremental, or :delta"
+      end
+
+      # Create the content request
+      content_request = Models::ContentRequest.new(
+        prompt,
+        model_name || Geminize.configuration.default_model,
+        params
+      )
+
+      # Generate with streaming
+      generate_stream(content_request, stream_mode, &block)
+    end
+
+    # Generate content with both text and images
+    # @param prompt [String] The input prompt text
+    # @param images [Array<Hash>] Array of image data hashes
+    # @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 images [Hash] :source_type Source type for image ('file', 'bytes', or 'url')
+    # @option images [String] :data File path, raw bytes, or URL depending on source_type
+    # @option images [String] :mime_type MIME type for the image (optional for file and url)
+    # @return [Geminize::Models::ContentResponse] The generation response
+    # @raise [Geminize::GeminizeError] If the request fails
+    # @example Generate with an image file
+    #   generate_text_multimodal("Describe this image", [{source_type: 'file', data: 'path/to/image.jpg'}])
+    # @example Generate with multiple images
+    #   generate_text_multimodal("Compare these images", [
+    #     {source_type: 'file', data: 'path/to/image1.jpg'},
+    #     {source_type: 'url', data: 'https://example.com/image2.jpg'}
+    #   ])
+    def generate_text_multimodal(prompt, images, model_name = nil, params = {})
+      # Create a new content request with the prompt text
+      content_request = Models::ContentRequest.new(
+        prompt,
+        model_name || Geminize.configuration.default_model,
+        params
+      )
+
+      # Add each image to the request based on its source type
+      images.each do |image|
+        case image[:source_type]
+        when "file"
+          content_request.add_image_from_file(image[:data])
+        when "bytes"
+          content_request.add_image_from_bytes(image[:data], image[:mime_type])
+        when "url"
+          content_request.add_image_from_url(image[:data])
+        else
+          raise Geminize::ValidationError.new(
+            "Invalid image source type: #{image[:source_type]}. Must be 'file', 'bytes', or 'url'",
+            "INVALID_ARGUMENT"
+          )
+        end
+      end
+
+      # Generate content with the constructed multimodal request
+      generate(content_request)
+    end
+
+    # Generate text with retries for transient errors
+    # @param content_request [Geminize::Models::ContentRequest] The content request
+    # @param max_retries [Integer] Maximum number of retry attempts
+    # @param retry_delay [Float] Delay between retries in seconds
+    # @return [Geminize::Models::ContentResponse] The generation response
+    # @raise [Geminize::GeminizeError] If all retry attempts fail
+    def generate_with_retries(content_request, max_retries = 3, retry_delay = 1.0)
+      retries = 0
+
+      begin
+        generate(content_request)
+      rescue Geminize::RateLimitError, Geminize::ServerError => e
+        if retries < max_retries
+          retries += 1
+          sleep retry_delay * retries # Exponential backoff
+          retry
+        else
+          raise e
+        end
+      end
+    end
+
+    # Cancel the current streaming operation, if any
+    # @return [Boolean] true if a streaming operation was cancelled, false if none was in progress
+    def cancel_streaming
+      return false unless @client
+
+      # Set the cancel_streaming flag to true on the client
+      @client.cancel_streaming = true
+    end
+
+    private
+
+    # Generate text with streaming from a content request
+    # @param content_request [Geminize::Models::ContentRequest] The content request
+    # @param stream_mode [Symbol] The stream processing mode (:raw, :incremental, or :delta)
+    # @yield [chunk] Yields each chunk of the streaming response
+    # @yieldparam chunk [String, Hash, StreamResponse] A chunk of the response
+    # @return [void]
+    # @raise [Geminize::GeminizeError] If the request fails
+    def generate_stream(content_request, stream_mode = :incremental, &block)
+      model_name = content_request.model_name
+      endpoint = RequestBuilder.build_streaming_endpoint(model_name)
+      payload = RequestBuilder.build_text_generation_request(content_request)
+
+      # For incremental mode, we'll accumulate the response
+      accumulated_text = "" if [:incremental, :delta].include?(stream_mode)
+
+      # Track if we received any non-error chunks
+      received_successful_chunks = false
+
+      begin
+        @client.post_stream(endpoint, payload) do |chunk|
+          received_successful_chunks = true
+
+          case stream_mode
+          when :raw
+            # Raw mode - yield the chunk as-is
+            yield chunk
+          when :incremental
+            # Incremental mode - extract and accumulate text
+            stream_response = Models::StreamResponse.from_hash(chunk)
+
+            # Only process and yield if there's text content in this chunk
+            if stream_response.text
+              accumulated_text += stream_response.text
+              yield accumulated_text
+            end
+
+            # If this is the final chunk with a finish reason or usage metrics, yield them
+            if stream_response.final_chunk? && stream_response.has_usage_metrics?
+              # Yield a hash with usage metrics and the final text
+              yield({
+                text: accumulated_text,
+                finish_reason: stream_response.finish_reason,
+                usage: {
+                  prompt_tokens: stream_response.prompt_tokens,
+                  completion_tokens: stream_response.completion_tokens,
+                  total_tokens: stream_response.total_tokens
+                }
+              })
+            end
+          when :delta
+            # Delta mode - extract and yield only the new text
+            stream_response = Models::StreamResponse.from_hash(chunk)
+
+            # Only process and yield if there's text content in this chunk
+            if stream_response.text
+              previous_length = accumulated_text.length
+              accumulated_text += stream_response.text
+
+              # Extract only the new content and yield it
+              new_content = accumulated_text[previous_length..]
+              yield new_content unless new_content.empty?
+            end
+
+            # If this is the final chunk with a finish reason or usage metrics, yield them
+            if stream_response.final_chunk? && stream_response.has_usage_metrics?
+              # Yield a hash with usage metrics and the final text
+              yield({
+                text: accumulated_text,
+                finish_reason: stream_response.finish_reason,
+                usage: {
+                  prompt_tokens: stream_response.prompt_tokens,
+                  completion_tokens: stream_response.completion_tokens,
+                  total_tokens: stream_response.total_tokens
+                }
+              })
+            end
+          end
+        end
+      rescue StreamingError, StreamingInterruptedError, StreamingTimeoutError, InvalidStreamFormatError => e
+        # For specialized streaming errors, add context and re-raise
+        error_message = "Streaming error: #{e.message}"
+
+        # If we had already received some chunks, add the partial response to the error information
+        if received_successful_chunks && accumulated_text && !accumulated_text.empty?
+          error_message += " (Partial response received: #{accumulated_text.length} characters)"
+          raise e.class.new(error_message, e.code, e.http_status)
+        else
+          # No chunks received, just re-raise the original error
+          raise
+        end
+      rescue => e
+        # For other errors, wrap in a GeminizeError
+        error_message = "Error during text generation streaming: #{e.message}"
+        raise GeminizeError.new(error_message)
+      end
+    end
+  end
+end

data/lib/geminize/validators.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Geminize
+  # Utility module for validating parameters
+  module Validators
+    class << self
+      # Validate that a value is a string and not empty
+      # @param value [Object] The value to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_string!(value, param_name)
+        if value.nil?
+          raise Geminize::ValidationError.new("#{param_name} cannot be nil", "INVALID_ARGUMENT")
+        end
+
+        unless value.is_a?(String)
+          raise Geminize::ValidationError.new("#{param_name} must be a string", "INVALID_ARGUMENT")
+        end
+      end
+
+      # Validate that a string is not empty
+      # @param value [String] The string to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_not_empty!(value, param_name)
+        validate_string!(value, param_name)
+
+        if value.empty?
+          raise Geminize::ValidationError.new("#{param_name} cannot be empty", "INVALID_ARGUMENT")
+        end
+      end
+
+      # Validate that a value is a number in the specified range
+      # @param value [Object] The value to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @param min [Numeric, nil] The minimum allowed value (inclusive)
+      # @param max [Numeric, nil] The maximum allowed value (inclusive)
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_numeric!(value, param_name, min: nil, max: nil)
+        return if value.nil?
+
+        unless value.is_a?(Numeric)
+          raise Geminize::ValidationError.new("#{param_name} must be a number", "INVALID_ARGUMENT")
+        end
+
+        if min && value < min
+          raise Geminize::ValidationError.new("#{param_name} must be at least #{min}", "INVALID_ARGUMENT")
+        end
+
+        if max && value > max
+          raise Geminize::ValidationError.new("#{param_name} must be at most #{max}", "INVALID_ARGUMENT")
+        end
+      end
+
+      # Validate that a value is an integer in the specified range
+      # @param value [Object] The value to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @param min [Integer, nil] The minimum allowed value (inclusive)
+      # @param max [Integer, nil] The maximum allowed value (inclusive)
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_integer!(value, param_name, min: nil, max: nil)
+        return if value.nil?
+
+        unless value.is_a?(Integer)
+          raise Geminize::ValidationError.new("#{param_name} must be an integer", "INVALID_ARGUMENT")
+        end
+
+        validate_numeric!(value, param_name, min: min, max: max)
+      end
+
+      # Validate that a value is a positive integer
+      # @param value [Object] The value to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_positive_integer!(value, param_name)
+        return if value.nil?
+
+        validate_integer!(value, param_name)
+
+        if value <= 0
+          raise Geminize::ValidationError.new("#{param_name} must be positive", "INVALID_ARGUMENT")
+        end
+      end
+
+      # Validate that a value is a float between 0 and 1
+      # @param value [Object] The value to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_probability!(value, param_name)
+        return if value.nil?
+
+        validate_numeric!(value, param_name, min: 0.0, max: 1.0)
+      end
+
+      # Validate that a value is an array
+      # @param value [Object] The value to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_array!(value, param_name)
+        return if value.nil?
+
+        unless value.is_a?(Array)
+          raise Geminize::ValidationError.new("#{param_name} must be an array", "INVALID_ARGUMENT")
+        end
+      end
+
+      # Validate that all elements of an array are strings
+      # @param value [Array] The array to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_string_array!(value, param_name)
+        return if value.nil?
+
+        validate_array!(value, param_name)
+
+        value.each_with_index do |item, index|
+          unless item.is_a?(String)
+            raise Geminize::ValidationError.new("#{param_name}[#{index}] must be a string", "INVALID_ARGUMENT")
+          end
+        end
+      end
+
+      # Validate that a value is one of an allowed set of values
+      # @param value [Object] The value to validate
+      # @param param_name [String] The name of the parameter (for error messages)
+      # @param allowed_values [Array] The allowed values
+      # @raise [Geminize::ValidationError] If validation fails
+      # @return [void]
+      def validate_allowed_values!(value, param_name, allowed_values)
+        return if value.nil?
+
+        unless allowed_values.include?(value)
+          allowed_str = allowed_values.map(&:inspect).join(", ")
+          raise Geminize::ValidationError.new(
+            "#{param_name} must be one of: #{allowed_str}",
+            "INVALID_ARGUMENT"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/geminize/vector_utils.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Geminize
+  # Utility module for vector operations used with embeddings
+  module VectorUtils
+    class << self
+      # Calculate the cosine similarity between two vectors
+      # @param vec1 [Array<Float>] First vector
+      # @param vec2 [Array<Float>] Second vector
+      # @return [Float] Cosine similarity (-1 to 1)
+      # @raise [Geminize::ValidationError] If vectors have different dimensions
+      def cosine_similarity(vec1, vec2)
+        unless vec1.length == vec2.length
+          raise Geminize::ValidationError.new(
+            "Vectors must have the same dimensions (#{vec1.length} vs #{vec2.length})",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        dot_product = 0.0
+        magnitude1 = 0.0
+        magnitude2 = 0.0
+
+        vec1.zip(vec2).each do |v1, v2|
+          dot_product += v1 * v2
+          magnitude1 += v1 * v1
+          magnitude2 += v2 * v2
+        end
+
+        magnitude1 = Math.sqrt(magnitude1)
+        magnitude2 = Math.sqrt(magnitude2)
+
+        # Guard against division by zero
+        return 0.0 if magnitude1.zero? || magnitude2.zero?
+
+        dot_product / (magnitude1 * magnitude2)
+      end
+
+      # Calculate the Euclidean distance between two vectors
+      # @param vec1 [Array<Float>] First vector
+      # @param vec2 [Array<Float>] Second vector
+      # @return [Float] Euclidean distance
+      # @raise [Geminize::ValidationError] If vectors have different dimensions
+      def euclidean_distance(vec1, vec2)
+        unless vec1.length == vec2.length
+          raise Geminize::ValidationError.new(
+            "Vectors must have the same dimensions (#{vec1.length} vs #{vec2.length})",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        sum_square_diff = 0.0
+        vec1.zip(vec2).each do |v1, v2|
+          diff = v1 - v2
+          sum_square_diff += diff * diff
+        end
+
+        Math.sqrt(sum_square_diff)
+      end
+
+      # Calculate the dot product of two vectors
+      # @param vec1 [Array<Float>] First vector
+      # @param vec2 [Array<Float>] Second vector
+      # @return [Float] Dot product
+      # @raise [Geminize::ValidationError] If vectors have different dimensions
+      def dot_product(vec1, vec2)
+        unless vec1.length == vec2.length
+          raise Geminize::ValidationError.new(
+            "Vectors must have the same dimensions (#{vec1.length} vs #{vec2.length})",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        product = 0.0
+        vec1.zip(vec2).each do |v1, v2|
+          product += v1 * v2
+        end
+
+        product
+      end
+
+      # Normalize a vector to unit length
+      # @param vec [Array<Float>] Vector to normalize
+      # @return [Array<Float>] Normalized vector
+      def normalize(vec)
+        magnitude = 0.0
+        vec.each do |v|
+          magnitude += v * v
+        end
+        magnitude = Math.sqrt(magnitude)
+
+        # Handle zero magnitude vector
+        return vec.map { 0.0 } if magnitude.zero?
+
+        vec.map { |v| v / magnitude }
+      end
+
+      # Average multiple vectors
+      # @param vectors [Array<Array<Float>>] Array of vectors
+      # @return [Array<Float>] Average vector
+      # @raise [Geminize::ValidationError] If vectors have different dimensions or no vectors provided
+      def average_vectors(vectors)
+        if vectors.empty?
+          raise Geminize::ValidationError.new(
+            "Cannot average an empty array of vectors",
+            "INVALID_ARGUMENT"
+          )
+        end
+
+        # Check all vectors have same dimensionality
+        dim = vectors.first.length
+        vectors.each_with_index do |vec, i|
+          unless vec.length == dim
+            raise Geminize::ValidationError.new(
+              "All vectors must have the same dimensions (expected #{dim}, got #{vec.length} at index #{i})",
+              "INVALID_ARGUMENT"
+            )
+          end
+        end
+
+        # Calculate average
+        avg = Array.new(dim, 0.0)
+        vectors.each do |vec|
+          vec.each_with_index do |v, i|
+            avg[i] += v
+          end
+        end
+
+        avg.map { |sum| sum / vectors.length }
+      end
+
+      # Find the most similar vectors to a target vector
+      # @param target [Array<Float>] Target vector
+      # @param vectors [Array<Array<Float>>] Vectors to compare against
+      # @param top_k [Integer, nil] Number of most similar vectors to return
+      # @param metric [Symbol] Distance metric to use (:cosine or :euclidean)
+      # @return [Array<Hash>] Array of {index:, similarity:} hashes sorted by similarity
+      def most_similar(target, vectors, top_k = nil, metric = :cosine)
+        similarities = []
+
+        vectors.each_with_index do |vec, i|
+          similarity = case metric
+          when :cosine
+            cosine_similarity(target, vec)
+          when :euclidean
+            # Convert to similarity (higher is more similar)
+            1.0 / (1.0 + euclidean_distance(target, vec))
+          else
+            raise Geminize::ValidationError.new(
+              "Unknown metric: #{metric}. Supported metrics: :cosine, :euclidean",
+              "INVALID_ARGUMENT"
+            )
+          end
+
+          similarities << {index: i, similarity: similarity}
+        end
+
+        # Sort by similarity (descending)
+        sorted = similarities.sort_by { |s| -s[:similarity] }
+        top_k ? sorted.take(top_k) : sorted
+      end
+    end
+  end
+end

data/lib/geminize/version.rb

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