aigen-google 0.1.0

data/lib/aigen/google/chat.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Aigen
+  module Google
+    # Chat manages stateful multi-turn conversations with the Gemini API.
+    # It maintains conversation history and automatically includes context
+    # in each API request for coherent, context-aware responses.
+    #
+    # @example Starting a new chat session
+    #   client = Aigen::Google::Client.new(api_key: "your-api-key")
+    #   chat = client.start_chat
+    #   response = chat.send_message("Hello!")
+    #   puts response["candidates"][0]["content"]["parts"][0]["text"]
+    #
+    # @example Multi-turn conversation with context
+    #   chat = client.start_chat
+    #   chat.send_message("What is Ruby?")
+    #   chat.send_message("What are its main features?") # Uses context from first message
+    #   puts chat.history # View full conversation
+    #
+    # @example Starting chat with existing history
+    #   history = [
+    #     {role: "user", parts: [{text: "Hello"}]},
+    #     {role: "model", parts: [{text: "Hi there!"}]}
+    #   ]
+    #   chat = client.start_chat(history: history)
+    #   chat.send_message("How are you?") # Continues from existing context
+    class Chat
+      # Returns the conversation history as an array of message hashes.
+      # Each message has a role ("user" or "model") and parts array.
+      #
+      # @return [Array<Hash>] a frozen copy of the conversation history
+      # @note The returned array is frozen to prevent external modification.
+      #   The history is managed internally by the Chat instance.
+      def history
+        @history.dup.freeze
+      end
+
+      # Initializes a new Chat instance.
+      #
+      # @param client [Aigen::Google::Client] the client instance for API requests
+      # @param model [String, nil] the model to use (defaults to client's default_model)
+      # @param history [Array<Hash>] initial conversation history (defaults to empty array)
+      #
+      # @example Create a new chat
+      #   chat = Chat.new(client: client, model: "gemini-pro")
+      #
+      # @example Create chat with existing history
+      #   history = [{role: "user", parts: [{text: "Hello"}]}]
+      #   chat = Chat.new(client: client, history: history)
+      def initialize(client:, model: nil, history: [])
+        @client = client
+        @model = model || @client.config.default_model
+        @history = history.dup
+      end
+
+      # Sends a message in the chat context and returns the model's response.
+      # Automatically includes conversation history for context and updates
+      # history with both the user message and model response.
+      #
+      # Accepts both simple String messages and Content objects for multimodal support.
+      #
+      # @param message [String, Content] the message text or Content object to send
+      # @param options [Hash] additional options to pass to the API (e.g., generationConfig)
+      #
+      # @return [Hash] the API response containing the model's reply
+      #
+      # @raise [Aigen::Google::AuthenticationError] if API key is invalid
+      # @raise [Aigen::Google::InvalidRequestError] if the request is malformed
+      # @raise [Aigen::Google::RateLimitError] if rate limit is exceeded
+      # @raise [Aigen::Google::ServerError] if the API returns a server error
+      # @raise [Aigen::Google::TimeoutError] if the request times out
+      # @raise [ArgumentError] if message is nil or empty
+      #
+      # @example Send a simple text message
+      #   response = chat.send_message("What is the weather today?")
+      #   text = response["candidates"][0]["content"]["parts"][0]["text"]
+      #
+      # @example Send multimodal content (text + image)
+      #   content = Aigen::Google::Content.new([
+      #     {text: "What is in this image?"},
+      #     {inline_data: {mime_type: "image/jpeg", data: base64_data}}
+      #   ])
+      #   response = chat.send_message(content)
+      #
+      # @example Send message with generation config
+      #   response = chat.send_message(
+      #     "Tell me a story",
+      #     generationConfig: {temperature: 0.9, maxOutputTokens: 1024}
+      #   )
+      def send_message(message, **options)
+        # Validate message parameter
+        raise ArgumentError, "message cannot be nil" if message.nil?
+        raise ArgumentError, "message cannot be empty" if message.respond_to?(:empty?) && message.empty?
+
+        # Build user message part
+        # Handle both String (simple text) and Content objects (multimodal)
+        user_message = if message.is_a?(Content)
+          # Content object - use its to_h serialization and add role
+          message.to_h.merge(role: "user")
+        else
+          # String - wrap in standard format
+          {
+            role: "user",
+            parts: [{text: message}]
+          }
+        end
+
+        # Build payload with full history + new message
+        payload = {
+          contents: @history + [user_message]
+        }
+
+        # Merge any additional generation config options
+        payload.merge!(options) if options.any?
+
+        # Make API request
+        endpoint = "models/#{@model}:generateContent"
+        response = @client.http_client.post(endpoint, payload)
+
+        # Extract model response
+        model_response = extract_model_message(response)
+
+        # Update history with both user message and model response
+        @history << user_message
+        @history << model_response
+
+        response
+      end
+
+      # Sends a message in the chat context with streaming response delivery.
+      # Automatically includes conversation history for context and updates history
+      # with the full accumulated response after streaming completes.
+      #
+      # @param message [String] the message text to send
+      # @param options [Hash] additional options to pass to the API (e.g., generationConfig)
+      # @yieldparam chunk [Hash] parsed JSON chunk from the streaming response (if block given)
+      #
+      # @return [nil] if block is given, returns nil after streaming completes
+      # @return [Enumerator] if no block given, returns lazy Enumerator for progressive iteration
+      #
+      # @raise [Aigen::Google::AuthenticationError] if API key is invalid
+      # @raise [Aigen::Google::InvalidRequestError] if the request is malformed
+      # @raise [Aigen::Google::RateLimitError] if rate limit is exceeded
+      # @raise [Aigen::Google::ServerError] if the API returns a server error
+      # @raise [Aigen::Google::TimeoutError] if the request times out
+      # @raise [ArgumentError] if message is nil or empty
+      #
+      # @note The conversation history is NOT updated until the entire stream completes.
+      #   This ensures the history remains consistent even if streaming is interrupted.
+      #
+      # @example Stream chat response with block
+      #   chat = client.start_chat
+      #   chat.send_message_stream("Tell me a joke") do |chunk|
+      #     text = chunk["candidates"][0]["content"]["parts"][0]["text"]
+      #     print text
+      #   end
+      #   # History now contains both user message and full accumulated response
+      #
+      # @example Stream with Enumerator for lazy processing
+      #   chat = client.start_chat
+      #   stream = chat.send_message_stream("Count to 5")
+      #   stream.each { |chunk| puts chunk["candidates"][0]["content"]["parts"][0]["text"] }
+      #   puts chat.history.length # => 2 (user + model)
+      def send_message_stream(message, **options, &block)
+        # Validate message parameter
+        raise ArgumentError, "message cannot be nil" if message.nil?
+        raise ArgumentError, "message cannot be empty" if message.respond_to?(:empty?) && message.empty?
+
+        # Build user message part
+        user_message = {
+          role: "user",
+          parts: [{text: message}]
+        }
+
+        # Build payload with full history + new message
+        payload = {
+          contents: @history + [user_message]
+        }
+
+        # Merge any additional generation config options
+        payload.merge!(options) if options.any?
+
+        # Make API request
+        endpoint = "models/#{@model}:streamGenerateContent"
+
+        # Accumulate full response text while streaming
+        accumulated_text = ""
+
+        # If block given, stream with block and accumulate
+        if block_given?
+          @client.http_client.post_stream(endpoint, payload) do |chunk|
+            # Extract text from chunk
+            text = extract_chunk_text(chunk)
+            accumulated_text += text if text
+
+            # Yield chunk to user's block
+            block.call(chunk)
+          end
+
+          # After streaming completes, update history with full response
+          update_history_after_stream(user_message, accumulated_text)
+          nil
+        else
+          # Return Enumerator that accumulates and updates history when consumed
+          Enumerator.new do |yielder|
+            @client.http_client.post_stream(endpoint, payload) do |chunk|
+              text = extract_chunk_text(chunk)
+              accumulated_text += text if text
+              yielder << chunk
+            end
+
+            # Update history after enumeration completes
+            update_history_after_stream(user_message, accumulated_text)
+          end
+        end
+      end
+
+      private
+
+      def extract_model_message(response)
+        candidate = response.dig("candidates", 0)
+        return {role: "model", parts: [{text: ""}]} unless candidate
+
+        content = candidate["content"]
+        return {role: "model", parts: [{text: ""}]} unless content
+
+        {
+          role: content["role"] || "model",
+          parts: content["parts"] || [{text: ""}]
+        }
+      end
+
+      def extract_chunk_text(chunk)
+        chunk.dig("candidates", 0, "content", "parts", 0, "text")
+      end
+
+      def update_history_after_stream(user_message, accumulated_text)
+        # Add user message to history
+        @history << user_message
+
+        # Add accumulated model response to history (using symbol keys like non-streaming)
+        model_response = {
+          role: "model",
+          parts: [{"text" => accumulated_text}]
+        }
+        @history << model_response
+      end
+    end
+  end
+end

data/lib/aigen/google/client.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Aigen
+  module Google
+    class Client
+      attr_reader :config, :http_client
+
+      def initialize(api_key: nil, model: nil, timeout: nil, **options)
+        @config = build_configuration(api_key, model, timeout, options)
+        @config.validate!
+        @http_client = HttpClient.new(
+          api_key: @config.api_key,
+          timeout: @config.timeout,
+          retry_count: @config.retry_count
+        )
+      end
+
+      # Generates content from the Gemini API with support for text, multimodal content,
+      # generation parameters, and safety settings.
+      #
+      # @param prompt [String, nil] simple text prompt (for backward compatibility)
+      # @param contents [Array<Hash>, nil] array of content hashes for multimodal requests
+      # @param model [String, nil] the model to use (defaults to client's default_model)
+      # @param temperature [Float, nil] controls randomness (0.0-1.0)
+      # @param top_p [Float, nil] nucleus sampling threshold (0.0-1.0)
+      # @param top_k [Integer, nil] top-k sampling limit (> 0)
+      # @param max_output_tokens [Integer, nil] maximum response tokens (> 0)
+      # @param safety_settings [Array<Hash>, nil] safety filtering configuration
+      # @param options [Hash] additional options to pass to the API
+      #
+      # @return [Hash] the API response
+      #
+      # @raise [Aigen::Google::InvalidRequestError] if validation fails (before API call)
+      # @raise [Aigen::Google::AuthenticationError] if API key is invalid
+      # @raise [Aigen::Google::RateLimitError] if rate limit is exceeded
+      # @raise [Aigen::Google::ServerError] if the API returns a server error
+      #
+      # @example Simple text prompt (backward compatible)
+      #   response = client.generate_content(prompt: "Hello")
+      #
+      # @example With generation config
+      #   response = client.generate_content(
+      #     prompt: "Tell me a story",
+      #     temperature: 0.7,
+      #     max_output_tokens: 1024
+      #   )
+      #
+      # @example Multimodal content (text + image)
+      #   text = Aigen::Google::Content.text("What is in this image?")
+      #   image = Aigen::Google::Content.image(data: base64_data, mime_type: "image/jpeg")
+      #   response = client.generate_content(contents: [text.to_h, image.to_h])
+      #
+      # @example Image generation (Nano Banana)
+      #   response = client.generate_content(
+      #     prompt: "A serene mountain landscape",
+      #     response_modalities: ["TEXT", "IMAGE"],
+      #     aspect_ratio: "16:9",
+      #     image_size: "2K"
+      #   )
+      def generate_content(prompt: nil, contents: nil, model: nil, temperature: nil, top_p: nil, top_k: nil, max_output_tokens: nil, response_modalities: nil, aspect_ratio: nil, image_size: nil, safety_settings: nil, **options)
+        model ||= @config.default_model
+
+        # Build generation config if parameters provided (validates before API call)
+        gen_config = nil
+        if temperature || top_p || top_k || max_output_tokens || response_modalities || aspect_ratio || image_size
+          gen_config = GenerationConfig.new(
+            temperature: temperature,
+            top_p: top_p,
+            top_k: top_k,
+            max_output_tokens: max_output_tokens,
+            response_modalities: response_modalities,
+            aspect_ratio: aspect_ratio,
+            image_size: image_size
+          )
+        end
+
+        # Build payload
+        payload = {}
+
+        # Handle contents (multimodal) or prompt (simple text)
+        if contents
+          payload[:contents] = contents
+        elsif prompt
+          # Backward compatibility: convert simple prompt to contents format
+          payload[:contents] = [
+            {
+              parts: [
+                {text: prompt}
+              ]
+            }
+          ]
+        end
+
+        # Add generation config if present
+        payload[:generationConfig] = gen_config.to_h if gen_config && !gen_config.to_h.empty?
+
+        # Add safety settings if present
+        payload[:safetySettings] = safety_settings if safety_settings
+
+        # Merge any additional options
+        payload.merge!(options) if options.any?
+
+        endpoint = "models/#{model}:generateContent"
+        @http_client.post(endpoint, payload)
+      end
+
+      # Streams generated content from the Gemini API with progressive chunk delivery.
+      # Supports both block-based immediate processing and lazy Enumerator evaluation.
+      #
+      # @param prompt [String] the prompt text to generate content from
+      # @param model [String, nil] the model to use (defaults to client's default_model)
+      # @param options [Hash] additional options to pass to the API (e.g., generationConfig)
+      # @yieldparam chunk [Hash] parsed JSON chunk from the streaming response (if block given)
+      #
+      # @return [nil] if block is given, returns nil after streaming completes
+      # @return [Enumerator] if no block given, returns lazy Enumerator for progressive iteration
+      #
+      # @raise [Aigen::Google::AuthenticationError] if API key is invalid
+      # @raise [Aigen::Google::InvalidRequestError] if the request is malformed
+      # @raise [Aigen::Google::RateLimitError] if rate limit is exceeded
+      # @raise [Aigen::Google::ServerError] if the API returns a server error
+      # @raise [Aigen::Google::TimeoutError] if the request times out
+      #
+      # @example Stream with block (immediate processing)
+      #   client.generate_content_stream(prompt: "Tell me a story") do |chunk|
+      #     text = chunk["candidates"][0]["content"]["parts"][0]["text"]
+      #     print text
+      #   end
+      #
+      # @example Stream with Enumerator (lazy evaluation)
+      #   stream = client.generate_content_stream(prompt: "Tell me a story")
+      #   stream.each do |chunk|
+      #     text = chunk["candidates"][0]["content"]["parts"][0]["text"]
+      #     print text
+      #   end
+      #
+      # @example Stream with lazy operations
+      #   stream = client.generate_content_stream(prompt: "Count to 10")
+      #   first_three = stream.lazy.take(3).map { |c| c["candidates"][0]["content"]["parts"][0]["text"] }.to_a
+      def generate_content_stream(prompt:, model: nil, **options, &block)
+        model ||= @config.default_model
+
+        payload = {
+          contents: [
+            {
+              parts: [
+                {text: prompt}
+              ]
+            }
+          ]
+        }
+
+        # Merge any additional generation config options
+        payload.merge!(options) if options.any?
+
+        endpoint = "models/#{model}:streamGenerateContent"
+
+        # If block given, stream with block
+        if block_given?
+          @http_client.post_stream(endpoint, payload, &block)
+        else
+          # Return Enumerator for lazy evaluation
+          Enumerator.new do |yielder|
+            @http_client.post_stream(endpoint, payload) do |chunk|
+              yielder << chunk
+            end
+          end
+        end
+      end
+
+      # Generates an image from a text prompt using Gemini image generation models.
+      # This is a convenience method that automatically sets response_modalities to ["TEXT", "IMAGE"]
+      # and returns an ImageResponse object for easy image extraction.
+      #
+      # @param prompt [String] the text description of the image to generate
+      # @param aspect_ratio [String, nil] optional aspect ratio ("1:1", "16:9", "9:16", "4:3", "3:4", "5:4", "4:5")
+      # @param size [String, nil] optional image size ("1K", "2K", "4K")
+      # @param model [String, nil] optional model name (defaults to client's model)
+      # @param options [Hash] additional options to pass to generate_content
+      #
+      # @return [Aigen::Google::ImageResponse] wrapper around the API response with convenience methods
+      #
+      # @raise [InvalidRequestError] if aspect_ratio or size are invalid
+      #
+      # @example Basic image generation
+      #   client = Aigen::Google::Client.new(model: "gemini-2.5-flash-image")
+      #   response = client.generate_image("A serene mountain landscape")
+      #   response.save("landscape.png") if response.success?
+      #
+      # @example With size and aspect ratio
+      #   response = client.generate_image(
+      #     "A futuristic cityscape",
+      #     aspect_ratio: "16:9",
+      #     size: "2K"
+      #   )
+      #   if response.success?
+      #     puts response.text
+      #     response.save("city.png")
+      #   else
+      #     puts "Failed: #{response.failure_message}"
+      #   end
+      def generate_image(prompt, aspect_ratio: nil, size: nil, model: nil, **options)
+        response = generate_content(
+          prompt: prompt,
+          model: model,
+          response_modalities: ["TEXT", "IMAGE"],
+          aspect_ratio: aspect_ratio,
+          image_size: size,
+          **options
+        )
+
+        ImageResponse.new(response)
+      end
+
+      def start_chat(history: [], model: nil, **options)
+        Chat.new(
+          client: self,
+          model: model || @config.default_model,
+          history: history
+        )
+      end
+
+      private
+
+      def build_configuration(api_key, model, timeout, options)
+        # Start with global configuration if available
+        config = if Google.configuration
+          Google.configuration.dup
+        else
+          Configuration.new
+        end
+
+        # Override with instance-specific values
+        config.api_key = api_key if api_key
+        config.default_model = model if model
+        config.timeout = timeout if timeout
+        options.each { |k, v| config.send("#{k}=", v) if config.respond_to?("#{k}=") }
+
+        config
+      end
+    end
+  end
+end

data/lib/aigen/google/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Aigen
+  module Google
+    class Configuration
+      attr_accessor :api_key, :default_model, :timeout, :retry_count
+
+      def initialize
+        @api_key = ENV.fetch("GOOGLE_API_KEY", nil)
+        @default_model = "gemini-pro"
+        @timeout = 30
+        @retry_count = 3
+      end
+
+      def validate!
+        raise ConfigurationError, "API key is required. Set via Aigen::Google.configure or ENV['GOOGLE_API_KEY']" if api_key.nil? || api_key.empty?
+      end
+    end
+  end
+end

data/lib/aigen/google/content.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Aigen
+  module Google
+    # Content represents text, image, or multimodal content for Gemini API requests.
+    # Provides builder methods for creating content and serialization to API format.
+    #
+    # @example Text content
+    #   content = Aigen::Google::Content.text("Hello, world!")
+    #   content.to_h # => {parts: [{text: "Hello, world!"}]}
+    #
+    # @example Image content (Base64-encoded)
+    #   require "base64"
+    #   image_data = Base64.strict_encode64(File.read("image.jpg"))
+    #   content = Aigen::Google::Content.image(data: image_data, mime_type: "image/jpeg")
+    #   content.to_h # => {parts: [{inline_data: {mime_type: "image/jpeg", data: "..."}}]}
+    #
+    # @example Multimodal content (text + image)
+    #   text_part = {text: "What is in this image?"}
+    #   image_part = {inline_data: {mime_type: "image/jpeg", data: base64_data}}
+    #   content = Aigen::Google::Content.new([text_part, image_part])
+    class Content
+      # Creates a text content instance.
+      #
+      # @param text [String] the text content
+      # @return [Content] a Content instance with text part
+      #
+      # @example
+      #   content = Content.text("Hello!")
+      #   content.to_h # => {parts: [{text: "Hello!"}]}
+      def self.text(text)
+        new([{text: text}])
+      end
+
+      # Creates an image content instance with Base64-encoded data.
+      #
+      # @param data [String] Base64-encoded image data (use Base64.strict_encode64)
+      # @param mime_type [String] the MIME type (e.g., "image/jpeg", "image/png")
+      # @return [Content] a Content instance with inline_data part
+      #
+      # @example
+      #   require "base64"
+      #   data = Base64.strict_encode64(File.read("photo.jpg"))
+      #   content = Content.image(data: data, mime_type: "image/jpeg")
+      def self.image(data:, mime_type:)
+        new([{
+          inline_data: {
+            mime_type: mime_type,
+            data: data
+          }
+        }])
+      end
+
+      # Initializes a Content instance with an array of parts.
+      #
+      # @param parts [Array<Hash>] array of content parts
+      #   - Text part: {text: "string"}
+      #   - Image part: {inline_data: {mime_type: "...", data: "..."}}
+      #
+      # @example
+      #   parts = [
+      #     {text: "Describe this image:"},
+      #     {inline_data: {mime_type: "image/jpeg", data: base64_data}}
+      #   ]
+      #   content = Content.new(parts)
+      def initialize(parts)
+        @parts = parts
+      end
+
+      # Serializes the content to Gemini API format.
+      #
+      # @return [Hash] the content hash with parts array
+      #
+      # @example
+      #   content = Content.text("Hello")
+      #   content.to_h # => {parts: [{text: "Hello"}]}
+      def to_h
+        {parts: @parts}
+      end
+    end
+  end
+end

data/lib/aigen/google/errors.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Aigen
+  module Google
+    # Base error class for all gem exceptions
+    class Error < StandardError; end
+
+    # Configuration-related errors
+    class ConfigurationError < Error; end
+
+    # Base class for API-related errors
+    class ApiError < Error
+      attr_reader :status_code
+
+      def initialize(message, status_code: nil)
+        super(message)
+        @status_code = status_code
+      end
+    end
+
+    # Authentication errors (401, 403)
+    class AuthenticationError < ApiError
+      def initialize(message = "Invalid API key. Get one at https://makersuite.google.com/app/apikey", status_code: 401)
+        super
+      end
+    end
+
+    # Rate limit exceeded (429)
+    class RateLimitError < ApiError
+      def initialize(message = "Rate limit exceeded. Please retry after some time.", status_code: 429)
+        super
+      end
+    end
+
+    # Invalid request errors (400, 404)
+    class InvalidRequestError < ApiError
+      def initialize(message = "Invalid request. Check your parameters.", status_code: 400)
+        super
+      end
+    end
+
+    # Server errors (500-599)
+    class ServerError < ApiError
+      def initialize(message = "Google API server error. Please retry.", status_code: 500)
+        super
+      end
+    end
+
+    # Timeout errors
+    class TimeoutError < Error
+      def initialize(message = "Request timed out after retries.")
+        super
+      end
+    end
+  end
+end