geminize 0.1.0

data/lib/geminize/chat.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Geminize
+  # Class for chat functionality
+  class Chat
+    # @return [Geminize::Client] The client instance
+    attr_reader :client
+
+    # @return [Models::Conversation] The current conversation
+    attr_reader :conversation
+
+    # Initialize a new chat instance
+    # @param conversation [Geminize::Models::Conversation, nil] The conversation to use
+    # @param client [Geminize::Client, nil] The client to use (optional)
+    # @param options [Hash] Additional options
+    def initialize(conversation = nil, client = nil, options = {})
+      @conversation = conversation || Models::Conversation.new
+      @client = client || Client.new(options)
+      @options = options
+    end
+
+    # Send a user message and get a model response
+    # @param content [String] The content of the user message
+    # @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 [Models::ChatResponse] The chat response
+    # @raise [Geminize::GeminizeError] If the request fails
+    def send_message(content, model_name = nil, params = {})
+      # Add user message to conversation
+      @conversation.add_user_message(content)
+
+      # Create the chat request
+      request_params = params.dup
+
+      # Only include system_instruction in params if explicitly provided or set in conversation
+      if params[:system_instruction] || @conversation.system_instruction
+        request_params[:system_instruction] = params[:system_instruction] || @conversation.system_instruction
+      end
+
+      chat_request = Models::ChatRequest.new(
+        content,
+        model_name || Geminize.configuration.default_model,
+        nil, # user_id
+        request_params
+      )
+
+      # Generate the response using the conversation history
+      response = generate_response(chat_request)
+
+      # Extract and add the model's response to the conversation
+      if response.has_text?
+        @conversation.add_model_message(response.text)
+      end
+
+      response
+    end
+
+    # Set a system instruction for the conversation
+    # @param instruction [String] The system instruction
+    # @return [self] The chat instance
+    def set_system_instruction(instruction)
+      @conversation.system_instruction = instruction
+      self
+    end
+
+    # Generate a response based on the current conversation
+    # @param chat_request [Models::ChatRequest] The chat request
+    # @return [Models::ChatResponse] The chat response
+    # @raise [Geminize::GeminizeError] If the request fails
+    def generate_response(chat_request)
+      model_name = chat_request.model_name
+      endpoint = RequestBuilder.build_text_generation_endpoint(model_name)
+
+      # Create payload with conversation history
+      payload = RequestBuilder.build_chat_request(chat_request, @conversation.messages_as_hashes)
+
+      # Send request to API
+      response_data = @client.post(endpoint, payload)
+      Models::ChatResponse.from_hash(response_data)
+    end
+
+    # Create a new conversation
+    # @param title [String, nil] Optional title for the conversation
+    # @param system_instruction [String, nil] Optional system instruction
+    # @return [Chat] A new chat instance with a fresh conversation
+    def self.new_conversation(title = nil, system_instruction = nil)
+      # Create a conversation with explicit parameters
+      conversation = Models::Conversation.new(nil, title, nil, nil, system_instruction)
+      new(conversation)
+    end
+  end
+end

data/lib/geminize/client.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "logger"
+
+module Geminize
+  # Client for making HTTP requests to the Gemini API
+  class Client
+    # @return [Faraday::Connection] The Faraday connection
+    attr_reader :connection
+
+    # @return [Boolean] Flag indicating if a streaming operation is in progress
+    attr_reader :streaming_in_progress
+
+    # @return [Boolean] Flag indicating if a streaming operation should be cancelled
+    attr_reader :cancel_streaming
+
+    # Initialize a new client
+    # @param options [Hash] Additional options to override the defaults
+    # @option options [String] :api_key API key for Gemini API
+    # @option options [String] :api_version API version to use
+    # @option options [Integer] :timeout Request timeout in seconds
+    # @option options [Integer] :open_timeout Connection open timeout in seconds
+    # @option options [Integer] :streaming_timeout Timeout for streaming requests in seconds
+    # @option options [Logger] :logger Custom logger instance (default: nil)
+    def initialize(options = {})
+      @config = Geminize.configuration
+      @options = options
+      @connection = build_connection
+      @streaming_in_progress = false
+      @cancel_streaming = false
+    end
+
+    # Make a GET request to the specified endpoint
+    # @param endpoint [String] The API endpoint path
+    # @param params [Hash] Optional query parameters
+    # @param headers [Hash] Optional headers
+    # @return [Hash] The response body parsed as JSON
+    def get(endpoint, params = {}, headers = {})
+      response = connection.get(
+        build_url(endpoint),
+        add_api_key(params),
+        default_headers.merge(headers)
+      )
+      parse_response(response)
+    end
+
+    # Make a POST request to the specified endpoint
+    # @param endpoint [String] The API endpoint path
+    # @param payload [Hash] The request body
+    # @param params [Hash] Optional query parameters
+    # @param headers [Hash] Optional headers
+    # @return [Hash] The response body parsed as JSON
+    def post(endpoint, payload = {}, params = {}, headers = {})
+      response = connection.post(
+        build_url(endpoint),
+        payload.to_json,
+        default_headers.merge(headers).merge({"Content-Type" => "application/json"})
+      ) do |req|
+        req.params.merge!(add_api_key(params))
+      end
+      parse_response(response)
+    end
+
+    # Make a streaming POST request to the specified endpoint
+    # @param endpoint [String] The API endpoint path
+    # @param payload [Hash] The request body
+    # @param params [Hash] Optional query parameters
+    # @param headers [Hash] Optional headers
+    # @yield [chunk] Yields each chunk of the streaming response
+    # @yieldparam chunk [String, Hash] A chunk of the response (raw text or parsed JSON)
+    # @return [void]
+    # @raise [Geminize::StreamingError] If the streaming request fails
+    # @raise [Geminize::StreamingInterruptedError] If the connection is interrupted
+    # @raise [Geminize::StreamingTimeoutError] If the streaming connection times out
+    # @raise [Geminize::InvalidStreamFormatError] If the stream format is invalid
+    def post_stream(endpoint, payload = {}, params = {}, headers = {}, &block)
+      raise ArgumentError, "A block is required for streaming requests" unless block_given?
+
+      # Check if another streaming operation is in progress
+      if @streaming_in_progress
+        raise StreamingError.new("Another streaming operation is already in progress")
+      end
+
+      @streaming_in_progress = true
+      @cancel_streaming = false
+
+      # Ensure we have alt=sse parameter for the API to get server-sent events
+      params = params.merge(alt: "sse")
+
+      # Create a separate connection for streaming
+      streaming_connection = build_streaming_connection
+
+      # Initialize buffer for SSE processing
+      @buffer = ""
+
+      # Track if we've received any data
+      received_data = false
+
+      begin
+        # Make the streaming request
+        streaming_connection.post(
+          build_url(endpoint),
+          payload.to_json,
+          default_headers.merge(headers).merge({
+            "Content-Type" => "application/json",
+            "Accept" => "text/event-stream" # Request SSE format explicitly
+          })
+        ) do |req|
+          req.params.merge!(add_api_key(params))
+
+          # Configure buffer management and chunked transfer reception
+          req.options.on_data = proc do |chunk, size, env|
+            # Check if cancellation is requested
+            if @cancel_streaming
+              env[:request].http_connection.close
+              raise StreamingInterruptedError.new("Streaming was cancelled by the client")
+            end
+
+            received_data = true
+
+            # Skip empty chunks
+            next if chunk.strip.empty?
+
+            # Use a buffer for handling partial SSE messages
+            @buffer += chunk
+
+            # Process complete SSE messages in buffer
+            process_buffer(&block)
+          end
+        end
+      rescue Faraday::ConnectionFailed => e
+        # Connection was established but interrupted
+        if received_data
+          raise StreamingInterruptedError.new("Streaming connection interrupted: #{e.message}")
+        else
+          raise RequestError.new("Failed to establish streaming connection: #{e.message}", "CONNECTION_ERROR", nil)
+        end
+      rescue Faraday::TimeoutError => e
+        raise StreamingTimeoutError.new("Streaming operation timed out: #{e.message}")
+      rescue JSON::ParserError => e
+        raise InvalidStreamFormatError.new("Could not parse streaming response: #{e.message}")
+      rescue => e
+        # Generic error handler
+        error_message = "Streaming error: #{e.message}"
+        raise StreamingError.new(error_message, nil, nil)
+      ensure
+        # Always clean up resources
+        @buffer = nil
+        @streaming_in_progress = false
+        @cancel_streaming = false
+
+        # Reset the connection to free resources
+        begin
+          streaming_connection&.close if streaming_connection&.respond_to?(:close)
+        rescue => e
+          # Just log the error if there's a problem closing the connection
+          @options[:logger]&.warn("Error closing streaming connection: #{e.message}")
+        end
+      end
+    end
+
+    # Set the cancel_streaming flag to cancel an in-progress streaming operation
+    # @param value [Boolean] Value to set
+    # @return [Boolean] The new value
+    def cancel_streaming=(value)
+      # Only set if a streaming operation is in progress
+      return unless @streaming_in_progress
+
+      @cancel_streaming = value
+    end
+
+    private
+
+    # Process the buffer for complete SSE messages
+    # @yield [data] Yields each parsed SSE data chunk
+    # @return [void]
+    def process_buffer
+      # Split the buffer by double newlines, which separate SSE messages
+      messages = @buffer.split(/\r\n\r\n|\n\n|\r\r/)
+
+      # The last element might be incomplete, so keep it in the buffer
+      @buffer = messages.pop || ""
+
+      # Process each complete message
+      messages.each do |message|
+        # Skip empty messages
+        next if message.strip.empty?
+
+        # Extract data lines
+        data_lines = []
+        message.each_line do |line|
+          if line.start_with?("data: ")
+            data_lines << line[6..]
+          end
+        end
+
+        # Skip if no data lines found
+        next if data_lines.empty?
+
+        # Join data lines for multi-line data
+        data = data_lines.join("")
+
+        # Skip "[DONE]" marker
+        next if data.strip == "[DONE]"
+
+        begin
+          # Try to parse as JSON
+          parsed_data = JSON.parse(data)
+
+          # Yield parsed data regardless of type
+          yield parsed_data
+        rescue JSON::ParserError
+          # If not valid JSON, yield as raw text
+          yield data
+        end
+      end
+    end
+
+    # Build the Faraday connection with the configured URL and default headers
+    # @return [Faraday::Connection]
+    def build_connection
+      Faraday.new(url: @config.api_base_url) do |conn|
+        conn.options.timeout = @options[:timeout] || @config.timeout
+        conn.options.open_timeout = @options[:open_timeout] || @config.open_timeout
+
+        # Add JSON response parsing
+        conn.response :json, content_type: /\bjson$/
+
+        # Add our custom error handling middleware
+        conn.response :geminize_error_handler
+
+        # Add retry middleware
+        conn.request :retry, {
+          max: 3,
+          interval: 0.05,
+          interval_randomness: 0.5,
+          backoff_factor: 2,
+          retry_statuses: [429, 503]
+        }
+
+        # Add logging if enabled
+        if @config.log_requests || @options[:logger]
+          logger = @options[:logger] || Logger.new($stdout)
+          conn.response :logger, logger, bodies: true
+        end
+      end
+    end
+
+    # Build the Faraday connection optimized for streaming with the configured URL
+    # @return [Faraday::Connection]
+    def build_streaming_connection
+      Faraday.new(url: @config.api_base_url) do |conn|
+        # Set longer timeouts for streaming connections which may stay open longer
+        conn.options.timeout = (@options[:streaming_timeout] || @config.streaming_timeout || 300)
+        conn.options.open_timeout = (@options[:open_timeout] || @config.open_timeout)
+
+        # Disable response parsing middleware for raw streaming
+        conn.adapter :net_http do |http|
+          # Configure Net::HTTP for streaming
+          http.read_timeout = (@options[:streaming_timeout] || @config.streaming_timeout || 300)
+          http.keep_alive_timeout = 60
+          http.max_retries = 0 # Disable retries for streaming connections
+        end
+
+        # Error handling for streaming connections
+        conn.response :geminize_error_handler
+
+        # Add logging if enabled
+        if @config.log_requests || @options[:logger]
+          logger = @options[:logger] || Logger.new($stdout)
+          conn.response :logger, logger, bodies: false
+        end
+      end
+    end
+
+    # Build the complete URL including API version
+    # @param endpoint [String] The API endpoint path
+    # @return [String] The complete URL path
+    def build_url(endpoint)
+      version = @options[:api_version] || @config.api_version
+      "#{version}/#{endpoint}"
+    end
+
+    # Default headers for all requests
+    # @return [Hash] Default headers
+    def default_headers
+      {
+        "Accept" => "application/json"
+      }
+    end
+
+    # Add API key to request parameters
+    # @param params [Hash] Original parameters
+    # @return [Hash] Parameters with API key added
+    def add_api_key(params)
+      api_key = @options[:api_key] || @config.api_key
+      params.merge(key: api_key)
+    end
+
+    # Parse the response body as JSON
+    # @param response [Faraday::Response] The response object
+    # @return [Hash] The parsed JSON
+    def parse_response(response)
+      return {} if response.body.to_s.empty?
+
+      if response.body.is_a?(Hash)
+        response.body
+      else
+        JSON.parse(response.body)
+      end
+    rescue JSON::ParserError => e
+      raise Geminize::RequestError.new("Invalid JSON response: #{e.message}", "INVALID_JSON", nil)
+    end
+  end
+end

data/lib/geminize/configuration.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module Geminize
+  # Handles configuration options for the Geminize gem
+  class Configuration
+    include Singleton
+
+    # Base URL for the Google Gemini API
+    API_BASE_URL = "https://generativelanguage.googleapis.com"
+
+    # Default API version
+    DEFAULT_API_VERSION = "v1beta"
+
+    # Default model
+    DEFAULT_MODEL = "gemini-2.0-flash"
+
+    # Default embedding model
+    DEFAULT_EMBEDDING_MODEL = "embedding-001"
+
+    # Default timeout values (in seconds)
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_STREAMING_TIMEOUT = 300
+    DEFAULT_ON_DATA_TIMEOUT = 60
+
+    # API key for accessing the Gemini API
+    # @return [String, nil]
+    attr_accessor :api_key
+
+    # API version to use
+    # @return [String]
+    attr_accessor :api_version
+
+    # Default model to use if not specified in requests
+    # @return [String]
+    attr_accessor :default_model
+
+    # Default embedding model to use if not specified in embedding requests
+    # @return [String]
+    attr_accessor :default_embedding_model
+
+    # Request timeout in seconds
+    # @return [Integer]
+    attr_accessor :timeout
+
+    # Connection open timeout in seconds
+    # @return [Integer]
+    attr_accessor :open_timeout
+
+    # Streaming request timeout in seconds
+    # @return [Integer]
+    attr_accessor :streaming_timeout
+
+    # Timeout between data chunks in streaming responses
+    # @return [Integer]
+    attr_accessor :on_data_timeout
+
+    # @return [Boolean]
+    attr_accessor :log_requests
+
+    # Initialize with default configuration values
+    def initialize
+      reset!
+    end
+
+    # Reset configuration to default values
+    # @return [void]
+    def reset!
+      @api_key = ENV["GEMINI_API_KEY"]
+      @api_version = DEFAULT_API_VERSION
+      @default_model = DEFAULT_MODEL
+      @default_embedding_model = DEFAULT_EMBEDDING_MODEL
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @streaming_timeout = DEFAULT_STREAMING_TIMEOUT
+      @on_data_timeout = DEFAULT_ON_DATA_TIMEOUT
+      @log_requests = false
+    end
+
+    # Get the base URL for the Gemini API
+    # @return [String]
+    def api_base_url
+      API_BASE_URL
+    end
+
+    # Validates the current configuration
+    # @return [Boolean]
+    # @raise [ConfigurationError] if the configuration is invalid
+    def validate!
+      raise ConfigurationError, "API key must be set" if @api_key.nil? || @api_key.empty?
+      raise ConfigurationError, "API version must be set" if @api_version.nil? || @api_version.empty?
+
+      true
+    end
+  end
+end

data/lib/geminize/conversation_repository.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Geminize
+  # Interface for conversation repositories
+  class ConversationRepository
+    # Save a conversation
+    # @param conversation [Models::Conversation] The conversation to save
+    # @return [Boolean] True if the save was successful
+    def save(conversation)
+      raise NotImplementedError, "Subclasses must implement #save"
+    end
+
+    # Load a conversation by ID
+    # @param id [String] The ID of the conversation to load
+    # @return [Models::Conversation, nil] The loaded conversation or nil if not found
+    def load(id)
+      raise NotImplementedError, "Subclasses must implement #load"
+    end
+
+    # Delete a conversation by ID
+    # @param id [String] The ID of the conversation to delete
+    # @return [Boolean] True if the deletion was successful
+    def delete(id)
+      raise NotImplementedError, "Subclasses must implement #delete"
+    end
+
+    # List all available conversations
+    # @return [Array<Hash>] An array of conversation metadata
+    def list
+      raise NotImplementedError, "Subclasses must implement #list"
+    end
+  end
+
+  # File-based implementation of the ConversationRepository
+  class FileConversationRepository < ConversationRepository
+    # @return [String] The directory where conversations are stored
+    attr_reader :storage_dir
+
+    # Initialize a new file-based repository
+    # @param directory [String] The directory to store conversations in
+    def initialize(directory = nil)
+      @storage_dir = directory || File.join(Dir.home, ".geminize", "conversations")
+      FileUtils.mkdir_p(@storage_dir) unless Dir.exist?(@storage_dir)
+    end
+
+    # Save a conversation to disk
+    # @param conversation [Models::Conversation] The conversation to save
+    # @return [Boolean] True if the save was successful
+    def save(conversation)
+      return false unless conversation
+
+      begin
+        file_path = file_path_for(conversation.id)
+        File.write(file_path, conversation.to_json)
+        true
+      rescue
+        false
+      end
+    end
+
+    # Load a conversation from disk by ID
+    # @param id [String] The ID of the conversation to load
+    # @return [Models::Conversation, nil] The loaded conversation or nil if not found
+    def load(id)
+      file_path = file_path_for(id)
+      return nil unless File.exist?(file_path)
+
+      begin
+        json = File.read(file_path)
+        Models::Conversation.from_json(json)
+      rescue
+        nil
+      end
+    end
+
+    # Delete a conversation from disk by ID
+    # @param id [String] The ID of the conversation to delete
+    # @return [Boolean] True if the deletion was successful
+    def delete(id)
+      file_path = file_path_for(id)
+      return false unless File.exist?(file_path)
+
+      begin
+        File.delete(file_path)
+        true
+      rescue
+        false
+      end
+    end
+
+    # List all available conversations
+    # @return [Array<Models::Conversation>] An array of conversations
+    def list
+      Dir.glob(File.join(@storage_dir, "*.json")).map do |file_path|
+        json = File.read(file_path)
+        Models::Conversation.from_json(json)
+      rescue
+        nil # Skip files that can't be parsed
+      end.compact.sort_by { |conversation| conversation.updated_at }.reverse
+    rescue
+      []
+    end
+
+    private
+
+    # Get the file path for a conversation ID
+    # @param id [String] The conversation ID
+    # @return [String] The file path
+    def file_path_for(id)
+      # Ensure the ID is safe for a filename
+      safe_id = id.to_s.gsub(/[^a-zA-Z0-9_-]/, "_")
+      File.join(@storage_dir, "#{safe_id}.json")
+    end
+  end
+
+  # In-memory implementation of the ConversationRepository (for testing)
+  class MemoryConversationRepository < ConversationRepository
+    # Initialize a new memory repository
+    def initialize
+      @conversations = {}
+    end
+
+    # Save a conversation to memory
+    # @param conversation [Models::Conversation] The conversation to save
+    # @return [Boolean] True if the save was successful
+    def save(conversation)
+      return false unless conversation
+
+      @conversations[conversation.id] = conversation
+      true
+    end
+
+    # Load a conversation from memory by ID
+    # @param id [String] The ID of the conversation to load
+    # @return [Models::Conversation, nil] The loaded conversation or nil if not found
+    def load(id)
+      @conversations[id]
+    end
+
+    # Delete a conversation from memory by ID
+    # @param id [String] The ID of the conversation to delete
+    # @return [Boolean] True if the deletion was successful
+    def delete(id)
+      if @conversations.key?(id)
+        @conversations.delete(id)
+        true
+      else
+        false
+      end
+    end
+
+    # List all available conversations
+    # @return [Array<Models::Conversation>] An array of conversations
+    def list
+      @conversations.values.sort_by(&:updated_at).reverse
+    end
+  end
+end