geminize 0.1.0

data/lib/geminize/conversation_service.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Geminize
+  # High-level service for managing conversations
+  class ConversationService
+    # @return [Geminize::ConversationRepository] The repository for storing conversations
+    attr_reader :repository
+
+    # @return [Geminize::Client] The client instance
+    attr_reader :client
+
+    # Initialize a new conversation service
+    # @param repository [Geminize::ConversationRepository, nil] The repository to use
+    # @param client [Geminize::Client, nil] The client to use
+    # @param options [Hash] Additional options
+    def initialize(repository = nil, client = nil, options = {})
+      @repository = repository || Geminize.conversation_repository
+      @client = client || Client.new(options)
+      @options = options
+    end
+
+    # Create a new conversation
+    # @param title [String, nil] Optional title for the conversation
+    # @param system_instruction [String, nil] Optional system instruction to guide model behavior
+    # @return [Models::Conversation] The new conversation
+    def create_conversation(title = nil, system_instruction = nil)
+      # Create a conversation with the appropriate arguments
+      conversation = if system_instruction
+        Models::Conversation.new(nil, title, nil, nil, system_instruction)
+      else
+        Models::Conversation.new(nil, title)
+      end
+      @repository.save(conversation)
+      conversation
+    end
+
+    # Get a conversation by ID
+    # @param id [String] The ID of the conversation to get
+    # @return [Models::Conversation, nil] The conversation or nil if not found
+    # @raise [Geminize::GeminizeError] If the conversation cannot be loaded
+    def get_conversation(id)
+      @repository.load(id)
+    end
+
+    # Send a message in a conversation and get a response
+    # @param conversation_id [String] The ID of the conversation
+    # @param message [String] The message to send
+    # @param model_name [String, nil] The model to use
+    # @param params [Hash] Additional generation parameters
+    # @return [Hash] The response and updated conversation
+    # @raise [Geminize::GeminizeError] If the request fails
+    def send_message(conversation_id, message, model_name = nil, params = {})
+      # Load the conversation
+      conversation = get_conversation(conversation_id)
+      raise Geminize::GeminizeError.new("Conversation not found: #{conversation_id}", nil, nil) unless conversation
+
+      # Create a chat instance with the conversation
+      chat = Chat.new(conversation, @client, @options)
+
+      # Send the message
+      response = chat.send_message(message, model_name, params)
+
+      # Save the updated conversation
+      @repository.save(conversation)
+
+      {
+        response: response,
+        conversation: conversation
+      }
+    end
+
+    # List all available conversations
+    # @return [Array<Hash>] An array of conversation metadata
+    def list_conversations
+      @repository.list
+    end
+
+    # Delete a conversation
+    # @param id [String] The ID of the conversation to delete
+    # @return [Boolean] True if the deletion was successful
+    def delete_conversation(id)
+      @repository.delete(id)
+    end
+
+    # Update a conversation title
+    # @param id [String] The ID of the conversation to update
+    # @param title [String] The new title
+    # @return [Models::Conversation] The updated conversation
+    # @raise [Geminize::GeminizeError] If the conversation cannot be loaded or saved
+    def update_conversation_title(id, title)
+      conversation = get_conversation(id)
+      raise Geminize::GeminizeError.new("Conversation not found: #{id}", nil, nil) unless conversation
+
+      conversation.title = title
+      @repository.save(conversation)
+      conversation
+    end
+
+    # Clear a conversation's message history
+    # @param id [String] The ID of the conversation to clear
+    # @return [Models::Conversation] The updated conversation
+    # @raise [Geminize::GeminizeError] If the conversation cannot be loaded or saved
+    def clear_conversation(id)
+      conversation = get_conversation(id)
+      raise Geminize::GeminizeError.new("Conversation not found: #{id}", nil, nil) unless conversation
+
+      conversation.clear
+      @repository.save(conversation)
+      conversation
+    end
+
+    # Update a conversation's system instruction
+    # @param id [String] The ID of the conversation to update
+    # @param system_instruction [String] The new system instruction
+    # @return [Models::Conversation] The updated conversation
+    # @raise [Geminize::GeminizeError] If the conversation cannot be loaded or saved
+    def update_conversation_system_instruction(id, system_instruction)
+      conversation = get_conversation(id)
+      raise Geminize::GeminizeError.new("Conversation not found: #{id}", nil, nil) unless conversation
+
+      conversation.system_instruction = system_instruction
+      @repository.save(conversation)
+      conversation
+    end
+  end
+end

data/lib/geminize/embeddings.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "models/embedding_request"
+require_relative "models/embedding_response"
+
+module Geminize
+  # Class for embedding generation functionality
+  class Embeddings
+    # Default maximum batch size
+    DEFAULT_MAX_BATCH_SIZE = 100
+
+    # @return [Geminize::Client] The client instance
+    attr_reader :client
+
+    # Initialize a new embeddings 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 embeddings based on an embedding request
+    # @param embedding_request [Geminize::Models::EmbeddingRequest] The embedding request
+    # @return [Geminize::Models::EmbeddingResponse] The embedding response
+    # @raise [Geminize::GeminizeError] If the request fails
+    def generate(embedding_request)
+      endpoint = build_embedding_endpoint(embedding_request.model_name, embedding_request.batch?)
+      payload = embedding_request.to_hash
+
+      response_data = @client.post(endpoint, payload)
+      Models::EmbeddingResponse.from_hash(response_data)
+    end
+
+    # Generate embeddings from text with optional parameters
+    # @param text [String, Array<String>] The input text or array of texts
+    # @param model_name [String, nil] The model to use (optional)
+    # @param params [Hash] Additional generation parameters
+    # @option params [Integer] :dimensions Desired dimensionality of the embeddings
+    # @option params [String] :task_type The embedding task type
+    # @option params [Integer] :batch_size Maximum number of texts to process in one batch
+    # @return [Geminize::Models::EmbeddingResponse] The embedding response
+    # @raise [Geminize::GeminizeError] If the request fails
+    def generate_embedding(text, model_name = nil, params = {})
+      model = model_name || Geminize.configuration.default_embedding_model
+
+      # Check if we need to handle batching
+      if text.is_a?(Array) && text.length > 1
+        batch_size = params.delete(:batch_size) || DEFAULT_MAX_BATCH_SIZE
+        if text.length > batch_size
+          return batch_process_embeddings(text, model, params, batch_size)
+        end
+      end
+
+      # Regular processing for a single text or a small batch
+      embedding_request = Models::EmbeddingRequest.new(
+        model_name: model,
+        text: text,
+        task_type: params[:task_type] || Geminize::Models::EmbeddingRequest::RETRIEVAL_DOCUMENT,
+        params: params
+      )
+
+      generate(embedding_request)
+    end
+
+    # Process multiple texts in batches
+    # @param texts [Array<String>] List of texts to process
+    # @param model_name [String, nil] Model name
+    # @param params [Hash] Additional parameters
+    # @param batch_size [Integer] Maximum batch size
+    # @return [Geminize::Models::EmbeddingResponse] Combined embedding response
+    def batch_process_embeddings(texts, model_name, params, batch_size)
+      batches = texts.each_slice(batch_size).to_a
+      responses = []
+
+      batches.each do |batch|
+        request = Models::EmbeddingRequest.new(
+          model_name: model_name,
+          text: batch,
+          task_type: params[:task_type] || Geminize::Models::EmbeddingRequest::RETRIEVAL_DOCUMENT,
+          params: params
+        )
+        responses << generate(request)
+      end
+
+      # Combine all responses into a single response object
+      combine_responses(responses)
+    end
+
+    private
+
+    # Combine multiple embedding responses into a single response
+    # @param responses [Array<Geminize::Models::EmbeddingResponse>] List of responses
+    # @return [Geminize::Models::EmbeddingResponse] Combined response
+    def combine_responses(responses)
+      return responses.first if responses.length == 1
+
+      # Create a synthesized response hash
+      combined_hash = {
+        "embeddings" => [],
+        "usageMetadata" => {
+          "promptTokenCount" => 0,
+          "totalTokenCount" => 0
+        }
+      }
+
+      # Merge all embeddings and usage data
+      responses.each do |response|
+        # Add embeddings
+        if response.raw_response["embeddings"]
+          combined_hash["embeddings"].concat(response.raw_response["embeddings"])
+        end
+
+        # Aggregate usage data
+        if response.usage
+          combined_hash["usageMetadata"]["promptTokenCount"] += response.prompt_tokens || 0
+          combined_hash["usageMetadata"]["totalTokenCount"] += response.total_tokens || 0
+        end
+      end
+
+      # Create a new response object
+      Models::EmbeddingResponse.from_hash(combined_hash)
+    end
+
+    # Build the endpoint for the embeddings API based on the model name
+    # @param model_name [String] The name of the model to use for embeddings
+    # @param batch [Boolean] Whether this is a batch request
+    # @return [String] The endpoint URL
+    def build_embedding_endpoint(model_name, batch = false)
+      # Clean model name - remove 'models/' prefix if present
+      clean_model_name = model_name.start_with?("models/") ? model_name[7..] : model_name
+
+      if batch
+        # For text-embedding models, use a different format
+        if clean_model_name.start_with?("text-embedding-")
+          "#{clean_model_name}:batchEmbedContents"
+        else
+          "models/#{clean_model_name}:batchEmbedContents"
+        end
+      else
+        "models/#{clean_model_name}:embedContent"
+      end
+    end
+  end
+end

data/lib/geminize/error_mapper.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Geminize
+  # Maps API error responses to appropriate exception classes
+  class ErrorMapper
+    # Maps an error response to the appropriate exception
+    # @param error_info [Hash] Hash containing error information (http_status, code, message)
+    # @return [Geminize::GeminizeError] An instance of the appropriate exception class
+    def self.map(error_info)
+      new(error_info).map
+    end
+
+    # @return [Hash] The error information hash
+    attr_reader :error_info
+
+    # Initialize a new mapper
+    # @param error_info [Hash] Hash containing error information (http_status, code, message)
+    def initialize(error_info)
+      @error_info = error_info
+    end
+
+    # Map the error to an appropriate exception
+    # @return [Geminize::GeminizeError] An instance of the appropriate exception class
+    def map
+      error_class = determine_error_class
+      error_class.new(
+        error_info[:message],
+        error_info[:code],
+        error_info[:http_status]
+      )
+    end
+
+    private
+
+    # Determine the appropriate error class based on status code and error type
+    # @return [Class] The exception class to instantiate
+    def determine_error_class
+      # First check for specific error codes from the API
+      api_error_class = map_api_error_code
+      return api_error_class if api_error_class
+
+      # Then fall back to HTTP status code mapping
+      http_status_class = map_http_status
+      return http_status_class if http_status_class
+
+      # Default to generic error
+      GeminizeError
+    end
+
+    # Map error based on API-specific error codes
+    # @return [Class, nil] The error class or nil if no mapping is found
+    def map_api_error_code
+      return nil unless error_info[:code]
+
+      code = error_info[:code].to_s.downcase
+      message = error_info[:message].to_s.downcase
+
+      if code.include?("permission") || code.include?("unauthorized") || code.include?("unauthenticated")
+        AuthenticationError
+      elsif code.include?("quota") || code.include?("rate") || code.include?("limit")
+        RateLimitError
+      elsif code.include?("not_found") || code.include?("notfound")
+        ResourceNotFoundError
+      elsif code.include?("invalid") && (code.include?("model") || message.include?("model"))
+        InvalidModelError
+      elsif code.include?("invalid") || code.include?("validation")
+        ValidationError
+      elsif code.include?("blocked") || message.include?("blocked") || message.include?("safety")
+        ContentBlockedError
+      elsif code.include?("server") || code.include?("internal")
+        ServerError
+      elsif code.include?("config")
+        ConfigurationError
+      end
+    end
+
+    # Map error based on HTTP status code
+    # @return [Class] The error class
+    def map_http_status
+      status = error_info[:http_status]
+
+      case status
+      when 400
+        BadRequestError
+      when 401, 403
+        AuthenticationError
+      when 404
+        ResourceNotFoundError
+      when 429
+        RateLimitError
+      when 500..599
+        ServerError
+      end
+    end
+  end
+end

data/lib/geminize/error_parser.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Geminize
+  # Utility class for parsing error responses from the Gemini API
+  class ErrorParser
+    # Parse an error response and extract relevant information
+    # @param response [Faraday::Response] The response object
+    # @return [Hash] Hash containing extracted error information
+    def self.parse(response)
+      new(response).parse
+    end
+
+    # @return [Faraday::Response] The response object
+    attr_reader :response
+
+    # Initialize a new parser
+    # @param response [Faraday::Response] The response object
+    def initialize(response)
+      @response = response
+    end
+
+    # Parse the response and extract error information
+    # @return [Hash] Hash containing error code, message, and status
+    def parse
+      {
+        http_status: response.status,
+        code: extract_error_code,
+        message: extract_error_message
+      }
+    end
+
+    private
+
+    # Extract the error code from the response
+    # @return [String, nil] The error code or nil if not present
+    def extract_error_code
+      return nil unless parsed_body && parsed_body["error"]
+
+      if parsed_body["error"].is_a?(Hash)
+        code = parsed_body["error"]["code"] || parsed_body["error"]["status"]
+        code&.to_s # Use safe navigation operator
+      elsif parsed_body["error"].is_a?(String)
+        # Extract error code from string if possible
+        parsed_body["error"].scan(/code[:\s]+([A-Z_]+)/i).flatten.first
+      end
+    end
+
+    # Extract the error message from the response
+    # @return [String] The error message
+    def extract_error_message
+      return default_error_message unless parsed_body
+
+      if parsed_body["error"].is_a?(Hash)
+        if parsed_body["error"]["message"]
+          parsed_body["error"]["message"]
+        else
+          detailed_message = extract_detailed_error_message
+          detailed_message || default_error_message
+        end
+      elsif parsed_body["error"].is_a?(String)
+        parsed_body["error"]
+      else
+        default_error_message
+      end
+    end
+
+    # Extract a detailed error message from nested error structures
+    # @return [String, nil] Detailed error message if present
+    def extract_detailed_error_message
+      return nil unless parsed_body["error"].is_a?(Hash)
+
+      details = parsed_body["error"]["details"]
+      return nil unless details.is_a?(Array) && !details.empty?
+
+      # Try to extract messages from details
+      messages = details.map do |detail|
+        if detail.is_a?(Hash) && detail["@type"] && detail["@type"].include?("type.googleapis.com")
+          detail["detail"] || detail["description"] || detail["message"]
+        end
+      end.compact
+
+      messages.join(". ") unless messages.empty?
+    end
+
+    # Parses the JSON response body
+    # @return [Hash, nil] The parsed JSON or nil if parsing fails
+    def parsed_body
+      @parsed_body ||= begin
+        return nil if response.body.to_s.empty?
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    # Generate a default error message based on HTTP status
+    # @return [String] A default error message
+    def default_error_message
+      case response.status
+      when 400
+        "Bad Request: The server could not process the request"
+      when 401
+        "Unauthorized: Authentication is required or has failed"
+      when 403
+        "Forbidden: You don't have permission to access this resource"
+      when 404
+        "Not Found: The requested resource could not be found"
+      when 429
+        "Too Many Requests: Rate limit exceeded"
+      when 500..599
+        "Server Error: The server encountered an error (#{response.status})"
+      else
+        "Error: An unexpected error occurred (HTTP #{response.status})"
+      end
+    end
+  end
+end

data/lib/geminize/errors.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Geminize
+  # Base error class for all Geminize errors
+  class GeminizeError < StandardError
+    # @return [String] The error message
+    attr_reader :message
+
+    # @return [String, nil] The error code from the API response
+    attr_reader :code
+
+    # @return [Integer, nil] The HTTP status code
+    attr_reader :http_status
+
+    # Initialize a new error
+    # @param message [String] The error message
+    # @param code [String, nil] The error code from the API response
+    # @param http_status [Integer, nil] The HTTP status code
+    def initialize(message = nil, code = nil, http_status = nil)
+      @message = message || "An error occurred with the Geminize API"
+      @code = code
+      @http_status = http_status
+      super(@message)
+    end
+  end
+
+  # Error raised when there's an authentication issue
+  class AuthenticationError < GeminizeError
+    def initialize(message = nil, code = nil, http_status = 401)
+      super(
+        message || "Authentication failed. Please check your API key.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised when rate limits are exceeded
+  class RateLimitError < GeminizeError
+    def initialize(message = nil, code = nil, http_status = 429)
+      super(
+        message || "Rate limit exceeded. Please retry after some time.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised for client-side errors (4xx)
+  class BadRequestError < GeminizeError
+    def initialize(message = nil, code = nil, http_status = 400)
+      super(
+        message || "Invalid request. Please check your parameters.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised for server-side errors (5xx)
+  class ServerError < GeminizeError
+    def initialize(message = nil, code = nil, http_status = 500)
+      super(
+        message || "The Gemini API encountered a server error.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised for network/request issues
+  class RequestError < GeminizeError
+    def initialize(message = nil, code = nil, http_status = nil)
+      super(
+        message || "There was an error making the request to the Gemini API.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised when a resource is not found
+  class ResourceNotFoundError < BadRequestError
+    def initialize(message = nil, code = nil, http_status = 404)
+      super(
+        message || "The requested resource was not found.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised when a requested model is invalid or not available
+  class InvalidModelError < BadRequestError
+    def initialize(message = nil, code = nil, http_status = 400)
+      super(
+        message || "The specified model is invalid or not available.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised for validation errors
+  class ValidationError < BadRequestError
+    def initialize(message = nil, code = nil, http_status = 400)
+      super(
+        message || "Validation failed. Please check your input parameters.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised when the content is blocked by the safety filters
+  class ContentBlockedError < BadRequestError
+    def initialize(message = nil, code = nil, http_status = 400)
+      super(
+        message || "Content blocked by safety filters.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error raised when there are configuration issues
+  class ConfigurationError < GeminizeError
+    def initialize(message = nil, code = nil, http_status = nil)
+      super(
+        message || "Configuration error. Please check your Geminize configuration.",
+        code,
+        http_status
+      )
+    end
+  end
+
+  # Error specific to streaming operations
+  class StreamingError < GeminizeError
+    def initialize(message = nil, code = nil, http_status = nil)
+      super(
+        message || "Streaming operation failed",
+        code || "STREAMING_ERROR",
+        http_status
+      )
+    end
+  end
+
+  # Error during connection interrupted during streaming
+  class StreamingInterruptedError < StreamingError
+    def initialize(message = nil, code = nil, http_status = nil)
+      super(
+        message || "Streaming connection was interrupted",
+        code || "STREAMING_INTERRUPTED",
+        http_status
+      )
+    end
+  end
+
+  # Error when the stream format is invalid
+  class InvalidStreamFormatError < StreamingError
+    def initialize(message = nil, code = nil, http_status = 400)
+      super(
+        message || "Invalid stream format or response structure",
+        code || "INVALID_STREAM_FORMAT",
+        http_status
+      )
+    end
+  end
+
+  # Error for timeout during streaming
+  class StreamingTimeoutError < StreamingError
+    def initialize(message = nil, code = nil, http_status = 408)
+      super(
+        message || "Streaming operation timed out",
+        code || "STREAMING_TIMEOUT",
+        http_status
+      )
+    end
+  end
+
+  # Error raised when a requested resource is not found (alias for ResourceNotFoundError)
+  class NotFoundError < ResourceNotFoundError
+    # Uses the same implementation as ResourceNotFoundError
+  end
+end