geminize 0.1.0

data/lib/geminize/middleware/error_handler.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "ostruct"
+
+module Geminize
+  module Middleware
+    # Faraday middleware for handling API error responses
+    class ErrorHandler < Faraday::Middleware
+      # @return [Array<Integer>] HTTP status codes that trigger error handling
+      attr_reader :error_statuses
+
+      # Initialize the middleware
+      # @param app [#call] The Faraday app
+      # @param options [Hash] Configuration options
+      # @option options [Array<Integer>] :error_statuses HTTP status codes to handle as errors (default: 400..599)
+      def initialize(app, options = {})
+        super(app)
+        @error_statuses = options.fetch(:error_statuses, 400..599).to_a
+      end
+
+      # Execute the middleware
+      # @param env [Faraday::Env] The request environment
+      def call(env)
+        @app.call(env).on_complete do |response_env|
+          on_complete(response_env) if error_statuses.include?(response_env.status)
+        end
+      rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+        # Handle network errors
+        raise Geminize::RequestError.new(
+          "Network error: #{e.message}",
+          "CONNECTION_ERROR",
+          nil
+        )
+      end
+
+      # Process the API response
+      # @param env [Faraday::Env] The response environment
+      # @raise [Geminize::GeminizeError] The appropriate exception based on the error
+      def on_complete(env)
+        # Create a simplified response object that we can pass to our parser
+        response = build_response_for_parser(env)
+
+        # Parse the error response
+        error_info = ErrorParser.parse(response)
+
+        # Map to appropriate exception and raise
+        exception = ErrorMapper.map(error_info)
+        raise exception
+      end
+
+      private
+
+      # Build a simplified response object from the Faraday environment
+      # @param env [Faraday::Env] The Faraday environment
+      # @return [OpenStruct] A simplified response-like object
+      def build_response_for_parser(env)
+        # Create a simple struct that mimics the interface expected by ErrorParser
+        OpenStruct.new(
+          status: env.status,
+          body: env.body,
+          headers: env.response_headers
+        )
+      end
+    end
+  end
+end
+
+# Register the middleware with Faraday
+Faraday::Response.register_middleware(
+  geminize_error_handler: -> { Geminize::Middleware::ErrorHandler }
+)

data/lib/geminize/model_info.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "models/model"
+require_relative "models/model_list"
+
+module Geminize
+  # Handles retrieving model information from the Gemini API
+  class ModelInfo
+    # @return [Geminize::Client] The HTTP client
+    attr_reader :client
+
+    # Initialize a new ModelInfo instance
+    # @param client [Geminize::Client, nil] The HTTP client to use
+    # @param options [Hash] Additional options for the client
+    def initialize(client = nil, options = {})
+      @client = client || Client.new(options)
+      @cache = {}
+      @cache_expiry = {}
+      @cache_ttl = options[:cache_ttl] || 3600 # Default to 1 hour
+    end
+
+    # List available models from the Gemini API
+    # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
+    # @return [Geminize::Models::ModelList] List of available models
+    # @raise [Geminize::GeminizeError] If the request fails
+    def list_models(force_refresh: false)
+      cache_key = "models_list"
+
+      # Check if we have a valid cached result
+      if !force_refresh && @cache[cache_key] && @cache_expiry[cache_key] > Time.now
+        return @cache[cache_key]
+      end
+
+      # Make the API request
+      response = client.get("models")
+
+      # Create a ModelList from the response
+      model_list = Models::ModelList.from_api_data(response)
+
+      # Cache the result
+      @cache[cache_key] = model_list
+      @cache_expiry[cache_key] = Time.now + @cache_ttl
+
+      model_list
+    end
+
+    # Get information about a specific model
+    # @param model_id [String] The model ID to retrieve
+    # @param force_refresh [Boolean] Force a refresh from the API instead of using cache
+    # @return [Geminize::Models::Model] The model information
+    # @raise [Geminize::GeminizeError] If the request fails or model is not found
+    def get_model(model_id, force_refresh: false)
+      cache_key = "model_#{model_id}"
+
+      # Check if we have a valid cached result
+      if !force_refresh && @cache[cache_key] && @cache_expiry[cache_key] > Time.now
+        return @cache[cache_key]
+      end
+
+      # Make the API request
+      begin
+        response = client.get("models/#{model_id}")
+
+        # Create a Model from the response
+        model = Models::Model.from_api_data(response)
+
+        # Cache the result
+        @cache[cache_key] = model
+        @cache_expiry[cache_key] = Time.now + @cache_ttl
+
+        model
+      rescue Geminize::NotFoundError => e
+        # Re-raise with a more descriptive message
+        raise Geminize::NotFoundError.new("Model '#{model_id}' not found", e.code, e.http_status)
+      end
+    end
+
+    # Clear all cached model information
+    # @return [void]
+    def clear_cache
+      @cache = {}
+      @cache_expiry = {}
+      nil
+    end
+
+    # Set the cache time-to-live (TTL)
+    # @param seconds [Integer] TTL in seconds
+    # @return [void]
+    attr_writer :cache_ttl
+  end
+end

data/lib/geminize/models/chat_request.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Represents a chat request to the Gemini API
+    class ChatRequest
+      # @return [String] The user's message content
+      attr_reader :content
+
+      # @return [String, nil] Optional user identifier
+      attr_reader :user_id
+
+      # @return [String] The model name to use
+      attr_reader :model_name
+
+      # @return [Time] When the message was created
+      attr_reader :timestamp
+
+      # @return [Float] Temperature (controls randomness)
+      attr_accessor :temperature
+
+      # @return [Integer] Maximum tokens to generate
+      attr_accessor :max_tokens
+
+      # @return [Float] Top-p value for nucleus sampling
+      attr_accessor :top_p
+
+      # @return [Integer] Top-k value for sampling
+      attr_accessor :top_k
+
+      # @return [Array<String>] Stop sequences to end generation
+      attr_accessor :stop_sequences
+
+      # @return [String, nil] System instruction to guide model behavior
+      attr_accessor :system_instruction
+
+      # Initialize a new chat request
+      # @param content [String] The user's message content
+      # @param model_name [String, nil] The model name to use
+      # @param user_id [String, nil] Optional user identifier
+      # @param params [Hash] Additional 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
+      def initialize(content, model_name = nil, user_id = nil, params = {})
+        @content = content
+        @model_name = model_name || Geminize.configuration.default_model
+        @user_id = user_id
+        @timestamp = Time.now
+        @temperature = params[:temperature]
+        @max_tokens = params[:max_tokens]
+        @top_p = params[:top_p]
+        @top_k = params[:top_k]
+        @stop_sequences = params[:stop_sequences]
+        @system_instruction = params[:system_instruction]
+
+        validate!
+      end
+
+      # Validate the request parameters
+      # @raise [Geminize::ValidationError] If any parameter is invalid
+      # @return [Boolean] true if all parameters are valid
+      def validate!
+        validate_content!
+        validate_temperature!
+        validate_max_tokens!
+        validate_top_p!
+        validate_top_k!
+        validate_stop_sequences!
+        validate_system_instruction!
+        true
+      end
+
+      # Convert the request to a hash for forming a single message
+      # @return [Hash] A hash representation of the user message
+      def to_message_hash
+        {
+          role: "user",
+          parts: [
+            {
+              text: @content
+            }
+          ]
+        }
+      end
+
+      # Convert the request to a hash suitable for the API
+      # @param history [Array<Hash>] Previous messages in the conversation
+      # @return [Hash] The request as a hash
+      def to_hash(history = [])
+        request = {
+          contents: history + [to_message_hash],
+          generationConfig: generation_config
+        }.compact
+
+        # Add system_instruction if provided
+        if @system_instruction
+          request[:systemInstruction] = {
+            parts: [
+              {
+                text: @system_instruction
+              }
+            ]
+          }
+        end
+
+        request
+      end
+
+      # Alias for to_hash for consistency with Ruby conventions
+      # @param history [Array<Hash>] Previous messages in the conversation
+      # @return [Hash] The request as a hash
+      def to_h(history = [])
+        to_hash(history)
+      end
+
+      private
+
+      # Build the generation configuration hash
+      # @return [Hash] The generation configuration
+      def generation_config
+        config = {}
+        config[:temperature] = @temperature if @temperature
+        config[:maxOutputTokens] = @max_tokens if @max_tokens
+        config[:topP] = @top_p if @top_p
+        config[:topK] = @top_k if @top_k
+        config[:stopSequences] = @stop_sequences if @stop_sequences && !@stop_sequences.empty?
+
+        config.empty? ? nil : config
+      end
+
+      # Validate the content parameter
+      # @raise [Geminize::ValidationError] If the content is invalid
+      def validate_content!
+        Validators.validate_not_empty!(@content, "Content")
+      end
+
+      # Validate the system_instruction parameter
+      # @raise [Geminize::ValidationError] If the system_instruction is invalid
+      def validate_system_instruction!
+        return if @system_instruction.nil?
+
+        unless @system_instruction.is_a?(String)
+          raise Geminize::ValidationError.new("System instruction must be a string", "INVALID_ARGUMENT")
+        end
+
+        if @system_instruction.empty?
+          raise Geminize::ValidationError.new("System instruction cannot be empty", "INVALID_ARGUMENT")
+        end
+      end
+
+      # Validate the temperature parameter
+      # @raise [Geminize::ValidationError] If the temperature is invalid
+      def validate_temperature!
+        Validators.validate_probability!(@temperature, "Temperature")
+      end
+
+      # Validate the max_tokens parameter
+      # @raise [Geminize::ValidationError] If the max_tokens is invalid
+      def validate_max_tokens!
+        Validators.validate_positive_integer!(@max_tokens, "Max tokens")
+      end
+
+      # Validate the top_p parameter
+      # @raise [Geminize::ValidationError] If the top_p is invalid
+      def validate_top_p!
+        Validators.validate_probability!(@top_p, "Top-p")
+      end
+
+      # Validate the top_k parameter
+      # @raise [Geminize::ValidationError] If the top_k is invalid
+      def validate_top_k!
+        Validators.validate_positive_integer!(@top_k, "Top-k")
+      end
+
+      # Validate the stop_sequences parameter
+      # @raise [Geminize::ValidationError] If the stop_sequences is invalid
+      def validate_stop_sequences!
+        Validators.validate_string_array!(@stop_sequences, "Stop sequences")
+      end
+    end
+  end
+end

data/lib/geminize/models/chat_response.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Geminize
+  module Models
+    # Represents a chat response from the Gemini API
+    class ChatResponse
+      # @return [Hash] The raw API response data
+      attr_reader :raw_response
+
+      # @return [String, nil] The reason why generation stopped (if applicable)
+      attr_reader :finish_reason
+
+      # @return [Hash, nil] Token counts for the request and response
+      attr_reader :usage
+
+      # @return [Time] When the response was created
+      attr_reader :timestamp
+
+      # Initialize a new chat response
+      # @param response_data [Hash] The raw API response
+      def initialize(response_data)
+        @raw_response = response_data
+        @timestamp = Time.now
+        parse_response
+      end
+
+      # Get the generated text from the response
+      # @return [String, nil] The generated text or nil if no text was generated
+      def text
+        return @text if defined?(@text)
+
+        @text = nil
+        candidates = @raw_response["candidates"]
+        if candidates && !candidates.empty?
+          content = candidates.first["content"]
+          if content && content["parts"] && !content["parts"].empty?
+            parts_text = content["parts"].map { |part| part["text"] }.compact
+            @text = parts_text.join(" ") unless parts_text.empty?
+          end
+        end
+        @text
+      end
+
+      # Get the response as a formatted message hash
+      # @return [Hash] Message in format suitable for conversation history
+      def to_message_hash
+        candidates = @raw_response["candidates"]
+        return nil unless candidates && !candidates.empty?
+
+        content = candidates.first["content"]
+        return nil unless content && content["parts"] && !content["parts"].empty?
+
+        {
+          role: "model",
+          parts: content["parts"]
+        }
+      end
+
+      # Check if the response has generated text
+      # @return [Boolean] True if the response has generated text
+      def has_text?
+        !text.nil? && !text.empty?
+      end
+
+      # Get the total token count
+      # @return [Integer, nil] Total token count or nil if not available
+      def total_tokens
+        return nil unless @usage
+
+        (@usage["promptTokenCount"] || 0) + (@usage["candidatesTokenCount"] || 0)
+      end
+
+      # Get the prompt token count
+      # @return [Integer, nil] Prompt token count or nil if not available
+      def prompt_tokens
+        return nil unless @usage
+
+        @usage["promptTokenCount"]
+      end
+
+      # Get the completion token count
+      # @return [Integer, nil] Completion token count or nil if not available
+      def completion_tokens
+        return nil unless @usage
+
+        @usage["candidatesTokenCount"]
+      end
+
+      # Create a ChatResponse object from a raw API response
+      # @param response_data [Hash] The raw API response
+      # @return [ChatResponse] A new ChatResponse object
+      def self.from_hash(response_data)
+        new(response_data)
+      end
+
+      private
+
+      # Parse the response data and extract relevant information
+      def parse_response
+        parse_finish_reason
+        parse_usage
+      end
+
+      # Parse the finish reason from the response
+      def parse_finish_reason
+        candidates = @raw_response["candidates"]
+        if candidates && !candidates.empty? && candidates.first["finishReason"]
+          @finish_reason = candidates.first["finishReason"]
+        end
+      end
+
+      # Parse usage information from the response
+      def parse_usage
+        @usage = @raw_response["usageMetadata"] if @raw_response["usageMetadata"]
+      end
+    end
+  end
+end