gemini_craft 0.1.3 → 0.2.0

data/lib/gemini_craft/cache.rb

@@ -3,7 +3,7 @@
 require "digest"
 
 module GeminiCraft
-  # Simple in-memory cache for API responses
+  # Enhanced in-memory cache for API responses with automatic cleanup
   class Cache
     # Initialize the cache
     # @param config [GeminiCraft::Configuration] Configuration object
@@ -11,45 +11,129 @@ module GeminiCraft
       @config = config
       @store = {}
       @timestamps = {}
+      @access_times = {}
+      @mutex = Mutex.new
+      @cleanup_thread = nil
+
+      start_cleanup_thread if @config.cache_enabled
     end
 
     # Get a value from the cache
     # @param key [String] Cache key
     # @return [String, nil] Cached value or nil if not found/expired
     def get(key)
-      return nil unless @store.key?(key)
+      @mutex.synchronize do
+        return nil unless @store.key?(key)
 
-      # Check if the entry has expired
-      if Time.now.to_i - @timestamps[key] > @config.cache_ttl
-        @store.delete(key)
-        @timestamps.delete(key)
-        return nil
-      end
+        # Check if the entry has expired
+        if expired?(key)
+          remove_entry(key)
+          return nil
+        end
 
-      @store[key]
+        # Update access time for LRU
+        @access_times[key] = Time.now.to_i
+        @store[key]
+      end
     end
 
     # Set a value in the cache
     # @param key [String] Cache key
     # @param value [String] Value to cache
     def set(key, value)
-      @store[key] = value
-      @timestamps[key] = Time.now.to_i
+      @mutex.synchronize do
+        @store[key] = value
+        current_time = Time.now.to_i
+        @timestamps[key] = current_time
+        @access_times[key] = current_time
+
+        # Perform cleanup if cache is getting large
+        cleanup_if_needed
+      end
     end
 
     # Clear the entire cache
     def clear
-      @store.clear
-      @timestamps.clear
+      @mutex.synchronize do
+        @store.clear
+        @timestamps.clear
+        @access_times.clear
+      end
+    end
+
+    # Get cache statistics
+    # @return [Hash] Cache statistics
+    def stats
+      @mutex.synchronize do
+        {
+          size: @store.size,
+          oldest_entry: @timestamps.values.min,
+          newest_entry: @timestamps.values.max,
+          total_keys: @timestamps.keys
+        }
+      end
     end
 
     # Remove expired entries from the cache
     def cleanup
-      current_time = Time.now.to_i
-      @timestamps.each do |key, timestamp|
-        if current_time - timestamp > @config.cache_ttl
-          @store.delete(key)
-          @timestamps.delete(key)
+      @mutex.synchronize do
+        current_time = Time.now.to_i
+        expired_keys = []
+
+        @timestamps.each do |key, timestamp|
+          expired_keys << key if current_time - timestamp > @config.cache_ttl
+        end
+
+        expired_keys.each { |key| remove_entry(key) }
+        expired_keys.size
+      end
+    end
+
+    # Stop the cleanup thread (for testing)
+    def stop_cleanup_thread
+      return unless @cleanup_thread
+
+      @cleanup_thread.kill
+      @cleanup_thread = nil
+    end
+
+    private
+
+    def expired?(key)
+      return false unless @timestamps[key]
+
+      Time.now.to_i - @timestamps[key] > @config.cache_ttl
+    end
+
+    def remove_entry(key)
+      @store.delete(key)
+      @timestamps.delete(key)
+      @access_times.delete(key)
+    end
+
+    def cleanup_if_needed
+      return if @store.size < 100 # Lower threshold for testing
+
+      # Remove expired entries first
+      cleanup
+
+      # If still too large, remove least recently used entries
+      return if @store.size < 100
+
+      # Remove 50% of entries (LRU)
+      lru_count = @store.size / 2
+      lru_keys = @access_times.sort_by { |_, time| time }.first(lru_count).map(&:first)
+      lru_keys.each { |key| remove_entry(key) }
+    end
+
+    def start_cleanup_thread
+      @cleanup_thread = Thread.new do
+        loop do
+          sleep(@config.cache_ttl / 2) # Cleanup every half TTL period
+          cleanup
+        rescue StandardError => e
+          # Log error if logger is available, otherwise silently continue
+          Rails.logger.warn "[GeminiCraft::Cache] Cleanup error: #{e.message}" if defined?(Rails) && Rails.logger
         end
       end
     end

data/lib/gemini_craft/client.rb

@@ -1,3 +1,5 @@
+# lib/gemini_craft/client.rb - FIXED STREAMING
+
 # frozen_string_literal: true
 
 require "faraday"
@@ -5,54 +7,165 @@ require "faraday/retry"
 require "json"
 
 module GeminiCraft
-  # Client for interacting with the Gemini API
   class Client
-    attr_reader :config, :cache
+    attr_reader :config, :cache, :logger
 
-    # Initialize a new client
     def initialize
       @config = GeminiCraft.configuration
       @config.validate!
       @cache = Cache.new(@config)
+      @logger = setup_logger
     end
 
-    # Generate content using Gemini
-    # @param text [String] The text prompt to send to Gemini
-    # @param system_instruction [String, nil] Optional system instruction to guide the model
-    # @param options [Hash] Additional options for the request
-    # @return [String] The generated content
-    def generate_content(text, system_instruction = nil, options = {})
-      # Create cache key from the request parameters
-      cache_key = generate_cache_key(text, system_instruction, options)
+    def generate_content(text, system_instruction = nil, options = {}, stream: false)
+      log(:info, "Generating content", { model: @config.model, stream: stream })
+
+      cache_key = generate_cache_key(text, system_instruction, options) unless stream
 
-      # Check cache if enabled
-      if @config.cache_enabled && (cached_response = @cache.get(cache_key))
+      if !stream && @config.cache_enabled && (cached_response = @cache.get(cache_key))
+        log(:debug, "Cache hit", { cache_key: cache_key })
         return cached_response
       end
 
-      # Prepare request payload
+      payload = build_payload(text, system_instruction, options, stream: stream)
+
+      if stream
+        generate_streaming_content(payload)
+      else
+        generate_standard_content(payload, cache_key)
+      end
+    rescue StandardError => e
+      log(:error, "Content generation failed", { error: e.message })
+      raise
+    end
+
+    def generate_with_functions(text, functions, system_instruction = nil, options = {})
+      log(:info, "Generating content with functions", { function_count: functions.size })
+
       payload = build_payload(text, system_instruction, options)
+      payload[:tools] = [{ function_declarations: functions }]
 
-      # Send request to API
       response = make_request("models/#{@config.model}:generateContent", payload)
+      process_function_response(response)
+    end
+
+    private
 
-      # Process response
+    def setup_logger
+      return @config.logger if @config.logger
+      return Logger.new(IO::NULL) unless defined?(Rails)
+
+      Rails.logger
+    rescue StandardError
+      Logger.new(IO::NULL)
+    end
+
+    def log(level, message, metadata = {})
+      return unless @logger.respond_to?(level)
+
+      log_message = "[GeminiCraft] #{message}"
+      log_message += " #{metadata.inspect}" unless metadata.empty?
+
+      @logger.send(level, log_message)
+    end
+
+    def generate_standard_content(payload, cache_key)
+      response = make_request("models/#{@config.model}:generateContent", payload)
       content = extract_content(response)
 
-      # Cache response if enabled
-      @cache.set(cache_key, content) if @config.cache_enabled
+      if @config.cache_enabled && cache_key
+        @cache.set(cache_key, content)
+        log(:debug, "Response cached", { cache_key: cache_key })
+      end
 
       content
     end
 
-    private
+    def generate_streaming_content(payload)
+      Enumerator.new do |yielder|
+        # Remove stream flag from payload
+        streaming_payload = payload.dup
+        streaming_payload.delete(:stream)
+
+        # Use streamGenerateContent endpoint with alt=sse
+        streaming_connection.post("models/#{@config.model}:streamGenerateContent") do |req|
+          req.params["key"] = @config.api_key
+          req.params["alt"] = "sse"
+          req.headers["Content-Type"] = "application/json"
+          req.headers["Accept"] = "text/event-stream"
+          req.body = JSON.generate(streaming_payload)
+
+          # Process each chunk as it arrives
+          req.options.on_data = proc do |chunk, _overall_received_bytes, _env|
+            process_streaming_chunk(chunk, yielder)
+          end
+        end
+      end
+    end
+
+    def process_streaming_chunk(chunk, yielder)
+      StreamingProcessor.new(self).process_chunk(chunk) { |content| yielder << content }
+    rescue StandardError => e
+      log(:error, "Streaming error", { error: e.message })
+      raise StreamingError, "Streaming failed: #{e.message}"
+    end
+
+    def handle_streaming_response(response)
+      # Handle final streaming response if there are any errors
+      return if [200, 204].include?(response.status)
+
+      error_body = response.body.empty? ? "Unknown streaming error" : response.body
+      raise APIError, "Streaming request failed (#{response.status}): #{error_body}"
+    end
+
+    def process_function_response(response)
+      FunctionResponseProcessor.new.process(response)
+    end
 
-    # Build the API request payload
-    # @param text [String] The text prompt
-    # @param system_instruction [String, nil] Optional system instruction
-    # @param options [Hash] Additional options
-    # @return [Hash] The request payload
-    def build_payload(text, system_instruction, options)
+    def build_payload(text, system_instruction, options, stream: false)
+      PayloadBuilder.new.build(text, system_instruction, options, stream: stream)
+    end
+
+    def make_request(endpoint, payload)
+      log(:debug, "Making API request", { endpoint: endpoint })
+
+      response = connection.post(endpoint) do |req|
+        req.params["key"] = @config.api_key
+        req.headers["Content-Type"] = "application/json"
+        req.body = JSON.generate(payload)
+      end
+
+      ResponseHandler.new(self).handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Request timed out: #{e.message}"
+    rescue Faraday::ConnectionFailed => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    rescue Faraday::Error => e
+      raise APIError, "API request failed: #{e.message}"
+    end
+
+    def connection
+      @connection ||= ConnectionBuilder.new(@config).build_connection
+    end
+
+    # FIXED: Separate connection for streaming to handle SSE properly
+    def streaming_connection
+      @streaming_connection ||= StreamingConnectionBuilder.new(@config).build_connection
+    end
+
+    def extract_content(response)
+      ContentExtractor.new.extract(response)
+    rescue StandardError => e
+      raise ResponseError, "Failed to extract content from response: #{e.message}"
+    end
+
+    def generate_cache_key(text, system_instruction, options)
+      CacheKeyGenerator.new(@config.model).generate(text, system_instruction, options)
+    end
+  end
+
+  class PayloadBuilder
+    def build(text, system_instruction, options, stream: false)
       payload = {
         contents: [
           {
@@ -65,7 +178,6 @@ module GeminiCraft
         ]
       }
 
-      # Add system instruction if provided
       if system_instruction
         payload[:system_instruction] = {
           parts: [
@@ -76,68 +188,161 @@ module GeminiCraft
         }
       end
 
-      # Merge additional options if provided
-      payload.merge!(options) if options && !options.empty?
+      # Don't include stream flag in payload for SSE streaming
+      # payload[:stream] = true if stream
 
+      payload.merge!(options) if options && !options.empty?
       payload
     end
+  end
 
-    # Make a request to the Gemini API
-    # @param endpoint [String] API endpoint
-    # @param payload [Hash] Request payload
-    # @return [Hash] Parsed response
-    # @raise [GeminiCraft::APIError] If the API returns an error
-    def make_request(endpoint, payload)
-      response = connection.post(endpoint) do |req|
-        req.params["key"] = @config.api_key
-        req.headers["Content-Type"] = "application/json"
-        req.body = JSON.generate(payload)
+  class StreamingProcessor
+    def initialize(client)
+      @client = client
+    end
+
+    def process_chunk(chunk)
+      lines = chunk.split(/\r?\n/)
+
+      lines.each do |line|
+        next unless line.start_with?("data: ")
+
+        json_data = line[6..].strip
+        next if json_data.empty? || json_data == "[DONE]"
+
+        begin
+          data = JSON.parse(json_data)
+          content = extract_streaming_content(data)
+          yield(content) unless content.empty?
+        rescue JSON::ParserError
+          @client.send(:log, :debug, "Skipping invalid JSON chunk", { chunk: json_data[0..50] })
+        end
       end
+    end
 
-      handle_response(response)
-    rescue Faraday::Error => e
-      raise APIError, "API request failed: #{e.message}"
+    private
+
+    def extract_streaming_content(data)
+      candidates = data["candidates"]
+      return "" if candidates.nil? || candidates.empty?
+
+      candidate = candidates.first
+      content = candidate["content"]
+      return "" if content.nil?
+
+      parts = content["parts"]
+      return "" if parts.nil? || parts.empty?
+
+      parts.first["text"] || ""
+    rescue StandardError
+      ""
     end
+  end
 
-    # Set up a Faraday connection with retry logic
-    # @return [Faraday::Connection] Configured connection
-    def connection
-      Faraday.new(url: @config.api_base_url) do |faraday|
-        faraday.options.timeout = @config.timeout
-        faraday.request :retry, max: @config.max_retries, interval: 0.5,
-                                interval_randomness: 0.5, backoff_factor: 2,
-                                exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
-        faraday.adapter Faraday.default_adapter
+  class FunctionResponseProcessor
+    def process(response)
+      candidates = response["candidates"]
+      return { content: "", function_calls: [] } if candidates.nil? || candidates.empty?
+
+      candidate = candidates.first
+      content_parts = candidate.dig("content", "parts") || []
+
+      text_parts = []
+      function_calls = []
+
+      content_parts.each do |part|
+        if part["text"]
+          text_parts << part["text"]
+        elsif part["functionCall"]
+          function_calls << {
+            name: part["functionCall"]["name"],
+            args: part["functionCall"]["args"] || {}
+          }
+        end
       end
+
+      {
+        content: text_parts.join(" "),
+        function_calls: function_calls
+      }
+    end
+  end
+
+  class ResponseHandler
+    def initialize(client)
+      @client = client
     end
 
-    # Handle and parse the API response
-    # @param response [Faraday::Response] The API response
-    # @return [Hash] Parsed response body
-    # @raise [GeminiCraft::APIError] If the API returns an error
     def handle_response(response)
       case response.status
       when 200
         JSON.parse(response.body)
-      when 400..499
-        error_body = begin
-          JSON.parse(response.body)
-        rescue StandardError
-          { "error" => response.body }
-        end
-        raise APIError, "API client error (#{response.status}): #{error_body["error"]["message"] || "Unknown error"}"
+      when 400
+        handle_client_error(response, "Bad Request")
+      when 401
+        raise AuthenticationError, "Invalid API key or authentication failed"
+      when 403
+        raise AuthorizationError, "Access forbidden - check your API permissions"
+      when 404
+        raise NotFoundError, "Model or endpoint not found"
+      when 429
+        raise RateLimitError, "Rate limit exceeded - please slow down your requests"
       when 500..599
-        raise APIError, "API server error (#{response.status}): The server encountered an error"
+        raise ServerError, "API server error (#{response.status}): The server encountered an error"
       else
         raise APIError, "Unknown API error (#{response.status})"
       end
     end
 
-    # Extract content from the response
-    # @param response [Hash] Parsed API response
-    # @return [String] The extracted content
-    # @raise [GeminiCraft::ResponseError] If the response format is unexpected
-    def extract_content(response)
+    private
+
+    def handle_client_error(response, error_type)
+      error_body = begin
+        JSON.parse(response.body)
+      rescue StandardError
+        { "error" => { "message" => response.body } }
+      end
+
+      message = error_body.dig("error", "message") || "Unknown error"
+      raise ClientError, "#{error_type} (#{response.status}): #{message}"
+    end
+  end
+
+  class ConnectionBuilder
+    def initialize(config)
+      @config = config
+    end
+
+    def build_connection
+      Faraday.new(url: @config.api_base_url) do |faraday|
+        faraday.options.timeout = @config.timeout
+        faraday.options.open_timeout = 10
+        faraday.adapter Faraday.default_adapter
+        faraday.request :retry, max: @config.max_retries, interval: 0.5
+      end
+    end
+  end
+
+  # FIXED: Separate connection builder for streaming
+  class StreamingConnectionBuilder
+    def initialize(config)
+      @config = config
+    end
+
+    def build_connection
+      Faraday.new(url: @config.api_base_url) do |faraday|
+        faraday.options.timeout = @config.timeout * 3 # Longer timeout for streaming
+        faraday.options.open_timeout = 15
+        faraday.adapter Faraday.default_adapter
+
+        # No retry for streaming connections
+        # Streaming should handle failures gracefully
+      end
+    end
+  end
+
+  class ContentExtractor
+    def extract(response)
       candidates = response["candidates"]
       return "" if candidates.nil? || candidates.empty?
 
@@ -152,21 +357,21 @@ module GeminiCraft
     rescue StandardError => e
       raise ResponseError, "Failed to extract content from response: #{e.message}"
     end
+  end
 
-    # Generate a cache key from request parameters
-    # @param text [String] The text prompt
-    # @param system_instruction [String, nil] Optional system instruction
-    # @param options [Hash] Additional options
-    # @return [String] A unique cache key
-    def generate_cache_key(text, system_instruction, options)
+  class CacheKeyGenerator
+    def initialize(model)
+      @model = model
+    end
+
+    def generate(text, system_instruction, options)
       key_parts = [
-        @config.model,
+        @model,
         text,
         system_instruction,
         options.to_s
       ]
 
-      # Create a deterministic string from the key parts
       Digest::SHA256.hexdigest(key_parts.join("--"))
     end
   end

data/lib/gemini_craft/configuration.rb

@@ -3,7 +3,8 @@
 module GeminiCraft
   # Configuration for the GeminiCraft gem
   class Configuration
-    attr_accessor :api_key, :api_base_url, :model, :timeout, :cache_enabled, :cache_ttl, :max_retries
+    attr_accessor :api_key, :api_base_url, :model, :timeout, :cache_enabled, :cache_ttl, :max_retries,
+                  :logger, :log_level, :streaming_enabled, :connection_pool_size, :keep_alive_timeout
 
     # Initialize a new configuration with default values
     def initialize
@@ -14,6 +15,11 @@ module GeminiCraft
       @cache_enabled = false
       @cache_ttl = 3600 # 1 hour in seconds
       @max_retries = 3
+      @logger = nil
+      @log_level = :info
+      @streaming_enabled = false
+      @connection_pool_size = 5
+      @keep_alive_timeout = 30
     end
 
     # Validate that the configuration has required parameters
@@ -21,6 +27,23 @@ module GeminiCraft
     def validate!
       raise ConfigurationError, "API key must be configured" unless api_key
       raise ConfigurationError, "Model must be configured" unless model
+
+      validate_log_level!
+      validate_timeouts!
+    end
+
+    private
+
+    def validate_log_level!
+      valid_levels = %i[debug info warn error fatal]
+      return if valid_levels.include?(log_level)
+
+      raise ConfigurationError, "Invalid log level: #{log_level}. Must be one of: #{valid_levels.join(", ")}"
+    end
+
+    def validate_timeouts!
+      raise ConfigurationError, "Timeout must be positive" if timeout <= 0
+      raise ConfigurationError, "Cache TTL must be positive" if cache_ttl <= 0
     end
   end
 

data/lib/gemini_craft/error.rb

@@ -9,4 +9,31 @@ module GeminiCraft
 
   # Error raised when the response cannot be processed
   class ResponseError < Error; end
+
+  # Error raised when authentication fails
+  class AuthenticationError < APIError; end
+
+  # Error raised when authorization fails
+  class AuthorizationError < APIError; end
+
+  # Error raised when the requested resource is not found
+  class NotFoundError < APIError; end
+
+  # Error raised when rate limits are exceeded
+  class RateLimitError < APIError; end
+
+  # Error raised for client-side errors (4xx)
+  class ClientError < APIError; end
+
+  # Error raised for server-side errors (5xx)
+  class ServerError < APIError; end
+
+  # Error raised when requests timeout
+  class TimeoutError < APIError; end
+
+  # Error raised when connection fails
+  class ConnectionError < APIError; end
+
+  # Error raised when streaming fails
+  class StreamingError < APIError; end
 end

data/lib/gemini_craft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GeminiCraft
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end