aigen-google 0.1.0

data/lib/aigen/google/generation_config.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Aigen
+  module Google
+    # GenerationConfig controls generation parameters for the Gemini API.
+    # Validates parameter ranges and raises InvalidRequestError before API calls.
+    #
+    # @example Basic configuration
+    #   config = Aigen::Google::GenerationConfig.new(temperature: 0.7, max_output_tokens: 1024)
+    #   config.to_h # => {temperature: 0.7, maxOutputTokens: 1024}
+    #
+    # @example All parameters
+    #   config = Aigen::Google::GenerationConfig.new(
+    #     temperature: 0.9,
+    #     top_p: 0.95,
+    #     top_k: 40,
+    #     max_output_tokens: 2048
+    #   )
+    class GenerationConfig
+      # Initializes a GenerationConfig instance with optional parameters.
+      # Validates all parameters and raises InvalidRequestError if invalid.
+      #
+      # @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 response_modalities [Array<String>, nil] output modalities: ["TEXT"], ["IMAGE"], or ["TEXT", "IMAGE"]
+      # @param aspect_ratio [String, nil] image aspect ratio: "1:1", "16:9", "9:16", "4:3", "3:4", "5:4", "4:5"
+      # @param image_size [String, nil] image resolution: "1K", "2K", "4K" (uppercase required)
+      #
+      # @raise [InvalidRequestError] if any parameter is out of valid range
+      #
+      # @example
+      #   config = GenerationConfig.new(temperature: 0.5)
+      #
+      # @example Image generation
+      #   config = GenerationConfig.new(
+      #     response_modalities: ["TEXT", "IMAGE"],
+      #     aspect_ratio: "16:9",
+      #     image_size: "2K"
+      #   )
+      def initialize(temperature: nil, top_p: nil, top_k: nil, max_output_tokens: nil, response_modalities: nil, aspect_ratio: nil, image_size: nil)
+        validate_temperature(temperature) if temperature
+        validate_top_p(top_p) if top_p
+        validate_top_k(top_k) if top_k
+        validate_max_output_tokens(max_output_tokens) if max_output_tokens
+        validate_response_modalities(response_modalities) if response_modalities
+        validate_aspect_ratio(aspect_ratio) if aspect_ratio
+        validate_image_size(image_size) if image_size
+
+        @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
+
+      # Serializes the configuration to Gemini API format with camelCase keys.
+      # Omits nil values from the output.
+      #
+      # @return [Hash] the configuration hash with camelCase keys
+      #
+      # @example
+      #   config = GenerationConfig.new(temperature: 0.7, max_output_tokens: 1024)
+      #   config.to_h # => {temperature: 0.7, maxOutputTokens: 1024}
+      def to_h
+        result = {}
+        result[:temperature] = @temperature unless @temperature.nil?
+        result[:topP] = @top_p unless @top_p.nil?
+        result[:topK] = @top_k unless @top_k.nil?
+        result[:maxOutputTokens] = @max_output_tokens unless @max_output_tokens.nil?
+        result[:responseModalities] = @response_modalities unless @response_modalities.nil?
+
+        # Image generation parameters go under imageConfig
+        if @aspect_ratio || @image_size
+          image_config = {}
+          image_config[:aspectRatio] = @aspect_ratio unless @aspect_ratio.nil?
+          image_config[:imageSize] = @image_size unless @image_size.nil?
+          result[:imageConfig] = image_config
+        end
+
+        result
+      end
+
+      private
+
+      def validate_temperature(value)
+        unless value.between?(0.0, 1.0)
+          raise InvalidRequestError.new(
+            "temperature must be between 0.0 and 1.0, got #{value}",
+            status_code: nil
+          )
+        end
+      end
+
+      def validate_top_p(value)
+        unless value.between?(0.0, 1.0)
+          raise InvalidRequestError.new(
+            "top_p must be between 0.0 and 1.0, got #{value}",
+            status_code: nil
+          )
+        end
+      end
+
+      def validate_top_k(value)
+        unless value > 0
+          raise InvalidRequestError.new(
+            "top_k must be greater than 0, got #{value}",
+            status_code: nil
+          )
+        end
+      end
+
+      def validate_max_output_tokens(value)
+        unless value > 0
+          raise InvalidRequestError.new(
+            "max_output_tokens must be greater than 0, got #{value}",
+            status_code: nil
+          )
+        end
+      end
+
+      def validate_response_modalities(value)
+        unless value.is_a?(Array)
+          raise InvalidRequestError.new(
+            "response_modalities must be an array",
+            status_code: nil
+          )
+        end
+
+        if value.empty?
+          raise InvalidRequestError.new(
+            "response_modalities must not be empty",
+            status_code: nil
+          )
+        end
+
+        valid_modalities = ["TEXT", "IMAGE"]
+        invalid = value - valid_modalities
+        unless invalid.empty?
+          raise InvalidRequestError.new(
+            "response_modalities must only contain TEXT or IMAGE, got: #{invalid.join(", ")}",
+            status_code: nil
+          )
+        end
+      end
+
+      def validate_aspect_ratio(value)
+        valid_ratios = ["1:1", "16:9", "9:16", "4:3", "3:4", "5:4", "4:5"]
+        unless valid_ratios.include?(value)
+          raise InvalidRequestError.new(
+            "aspect_ratio must be one of #{valid_ratios.join(", ")}, got #{value}",
+            status_code: nil
+          )
+        end
+      end
+
+      def validate_image_size(value)
+        valid_sizes = ["1K", "2K", "4K"]
+        unless valid_sizes.include?(value)
+          raise InvalidRequestError.new(
+            "image_size must be one of #{valid_sizes.join(", ")}, got #{value}",
+            status_code: nil
+          )
+        end
+      end
+    end
+  end
+end

data/lib/aigen/google/http_client.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Aigen
+  module Google
+    class HttpClient
+      BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+
+      def initialize(api_key:, timeout: 30, retry_count: 3)
+        @api_key = api_key
+        @timeout = timeout
+        @retry_count = retry_count
+      end
+
+      def post(path, payload, attempt: 1)
+        response = connection.post(path) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.headers["x-goog-api-key"] = @api_key
+          req.body = payload.to_json
+        end
+
+        handle_response(response, path, payload, attempt)
+      rescue Faraday::Error => e
+        # Handle timeout-like errors (including WebMock's .to_timeout)
+        is_timeout = e.is_a?(Faraday::TimeoutError) ||
+          e.is_a?(::Timeout::Error) ||
+          e.message.include?("execution expired") ||
+          e.message.include?("timed out")
+
+        if is_timeout
+          if attempt >= @retry_count
+            raise TimeoutError, "Request timed out after #{@retry_count} retries"
+          end
+          backoff_seconds = 2**(attempt - 1) # 1s, 2s, 4s
+          sleep backoff_seconds
+          post(path, payload, attempt: attempt + 1)
+        else
+          # Network connection errors
+          raise ServerError.new("Network error: #{e.message}", status_code: nil)
+        end
+      end
+
+      # Makes a streaming POST request to the Gemini API.
+      # Processes chunked responses and yields each parsed chunk to the provided block.
+      #
+      # @param path [String] the API endpoint path
+      # @param payload [Hash] the request payload (will be JSON encoded)
+      # @yieldparam chunk [Hash] parsed JSON chunk from the streaming response
+      #
+      # @return [nil] always returns nil when block is given
+      #
+      # @raise [ArgumentError] if no block is provided
+      # @raise [Aigen::Google::AuthenticationError] if API key is invalid (401/403)
+      # @raise [Aigen::Google::InvalidRequestError] if request is malformed (400/404)
+      # @raise [Aigen::Google::RateLimitError] if rate limit is exceeded (429)
+      # @raise [Aigen::Google::ServerError] if server error occurs (500+) or network error
+      #
+      # @example Stream generated content chunks
+      #   http_client.post_stream("models/gemini-pro:streamGenerateContent", payload) do |chunk|
+      #     text = chunk["candidates"][0]["content"]["parts"][0]["text"]
+      #     print text
+      #   end
+      def post_stream(path, payload, &block)
+        raise ArgumentError, "block required for streaming" unless block_given?
+
+        buffer = ""
+
+        response = connection.post(path) do |req|
+          req.headers["Content-Type"] = "application/json"
+          req.headers["x-goog-api-key"] = @api_key
+          req.body = payload.to_json
+
+          req.options.on_data = proc do |chunk, _total_bytes|
+            buffer += chunk
+
+            # Process complete lines (newline-delimited JSON)
+            while (newline_index = buffer.index("\n"))
+              line = buffer.slice!(0, newline_index + 1).strip
+              next if line.empty?
+
+              begin
+                parsed_chunk = JSON.parse(line)
+                block.call(parsed_chunk)
+              rescue JSON::ParserError => e
+                raise ServerError.new("Invalid JSON in stream chunk: #{e.message}", status_code: nil)
+              end
+            end
+          end
+        end
+
+        # Check for non-200 status codes
+        handle_stream_response_status(response)
+
+        nil
+      rescue Faraday::Error => e
+        raise ServerError.new("Network error during streaming: #{e.message}", status_code: nil)
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(url: BASE_URL) do |conn|
+          conn.options.timeout = @timeout
+          conn.adapter Faraday.default_adapter do |http|
+            http.open_timeout = 5
+            http.read_timeout = @timeout
+          end
+        end
+      end
+
+      def handle_response(response, path, payload, attempt)
+        case response.status
+        when 200..299
+          begin
+            JSON.parse(response.body)
+          rescue JSON::ParserError => e
+            raise ServerError.new("Invalid JSON response from API: #{e.message}", status_code: response.status)
+          end
+        when 400
+          raise InvalidRequestError.new(extract_error_message(response), status_code: 400)
+        when 401, 403
+          raise AuthenticationError.new("Invalid API key. Get one at https://makersuite.google.com/app/apikey", status_code: response.status)
+        when 404
+          raise InvalidRequestError.new("Resource not found. Check model name and endpoint.", status_code: 404)
+        when 429
+          retry_response(path, payload, attempt, RateLimitError.new(extract_error_message(response), status_code: 429))
+        when 500..599
+          retry_response(path, payload, attempt, ServerError.new(extract_error_message(response), status_code: response.status))
+        else
+          raise ApiError.new("Unexpected status code: #{response.status}", status_code: response.status)
+        end
+      end
+
+      def retry_response(path, payload, attempt, error)
+        if attempt >= @retry_count
+          raise error
+        end
+
+        backoff_seconds = 2**(attempt - 1) # 1s, 2s, 4s
+        sleep backoff_seconds
+        post(path, payload, attempt: attempt + 1)
+      end
+
+      def extract_error_message(response)
+        body = JSON.parse(response.body)
+        body.dig("error", "message") || response.body
+      rescue JSON::ParserError
+        response.body
+      end
+
+      def handle_stream_response_status(response)
+        case response.status
+        when 200..299
+          # Success - streaming completed
+        when 400
+          raise InvalidRequestError.new(extract_error_message(response), status_code: 400)
+        when 401, 403
+          raise AuthenticationError.new("Invalid API key. Get one at https://makersuite.google.com/app/apikey", status_code: response.status)
+        when 404
+          raise InvalidRequestError.new("Resource not found. Check model name and endpoint.", status_code: 404)
+        when 429
+          raise RateLimitError.new(extract_error_message(response), status_code: 429)
+        when 500..599
+          raise ServerError.new(extract_error_message(response), status_code: response.status)
+        else
+          raise ApiError.new("Unexpected status code: #{response.status}", status_code: response.status)
+        end
+      end
+    end
+  end
+end

data/lib/aigen/google/image_response.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Aigen
+  module Google
+    # Wraps an image generation API response with convenient helper methods.
+    # Provides easy access to generated images, text descriptions, and status information.
+    #
+    # @example Basic usage
+    #   response = client.generate_image("A cute puppy")
+    #   if response.success?
+    #     response.save("puppy.png")
+    #     puts response.text
+    #   end
+    #
+    # @example Checking for failures
+    #   response = client.generate_image("problematic prompt")
+    #   unless response.success?
+    #     puts "Failed: #{response.failure_reason}"
+    #     puts response.failure_message
+    #   end
+    class ImageResponse
+      attr_reader :raw_response
+
+      # Creates a new ImageResponse from a Gemini API response.
+      #
+      # @param response [Hash] the raw API response hash
+      def initialize(response)
+        @raw_response = response
+      end
+
+      # Checks if the image generation was successful.
+      #
+      # @return [Boolean] true if generation succeeded, false otherwise
+      def success?
+        finish_reason == "STOP"
+      end
+
+      # Checks if an image is present in the response.
+      #
+      # @return [Boolean] true if image data exists, false otherwise
+      def has_image?
+        !image_part.nil?
+      end
+
+      # Returns the text description that accompanied the generated image.
+      #
+      # @return [String, nil] the text description or nil if not present
+      def text
+        text_part&.dig("text")
+      end
+
+      # Returns the decoded binary image data.
+      #
+      # @return [String, nil] binary image data or nil if no image present
+      def image_data
+        return nil unless has_image?
+
+        Base64.decode64(image_part["inlineData"]["data"])
+      end
+
+      # Returns the MIME type of the generated image.
+      #
+      # @return [String, nil] MIME type (e.g., "image/png") or nil if no image
+      def mime_type
+        image_part&.dig("inlineData", "mimeType")
+      end
+
+      # Saves the generated image to the specified file path.
+      #
+      # @param path [String] the file path to save the image
+      # @raise [Aigen::Google::Error] if no image data is present
+      #
+      # @example
+      #   response.save("output.png")
+      def save(path)
+        raise Error, "No image data to save" unless has_image?
+
+        File.write(path, image_data)
+      end
+
+      # Returns the finish reason for failed generations.
+      #
+      # @return [String, nil] the finish reason or nil if successful
+      def failure_reason
+        return nil if success?
+
+        candidate.dig("finishReason")
+      end
+
+      # Returns the failure message for failed generations.
+      #
+      # @return [String, nil] the failure message or nil if successful
+      def failure_message
+        return nil if success?
+
+        candidate.dig("finishMessage")
+      end
+
+      private
+
+      def candidate
+        @raw_response.dig("candidates", 0) || {}
+      end
+
+      def parts
+        candidate.dig("content", "parts") || []
+      end
+
+      def text_part
+        parts.find { |p| p.key?("text") }
+      end
+
+      def image_part
+        parts.find { |p| p.key?("inlineData") }
+      end
+
+      def finish_reason
+        candidate.dig("finishReason")
+      end
+    end
+  end
+end

data/lib/aigen/google/safety_settings.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Aigen
+  module Google
+    # SafetySettings configures content filtering for the Gemini API.
+    # Provides constants for harm categories and thresholds, with sensible defaults.
+    #
+    # @example Using default settings (BLOCK_MEDIUM_AND_ABOVE for all categories)
+    #   settings = Aigen::Google::SafetySettings.default
+    #
+    # @example Custom settings
+    #   settings = Aigen::Google::SafetySettings.new([
+    #     {
+    #       category: Aigen::Google::SafetySettings::HARM_CATEGORY_HATE_SPEECH,
+    #       threshold: Aigen::Google::SafetySettings::BLOCK_LOW_AND_ABOVE
+    #     }
+    #   ])
+    class SafetySettings
+      # Harm category constants
+      HARM_CATEGORY_HATE_SPEECH = "HARM_CATEGORY_HATE_SPEECH"
+      HARM_CATEGORY_DANGEROUS_CONTENT = "HARM_CATEGORY_DANGEROUS_CONTENT"
+      HARM_CATEGORY_HARASSMENT = "HARM_CATEGORY_HARASSMENT"
+      HARM_CATEGORY_SEXUALLY_EXPLICIT = "HARM_CATEGORY_SEXUALLY_EXPLICIT"
+
+      # Threshold constants
+      BLOCK_NONE = "BLOCK_NONE"
+      BLOCK_LOW_AND_ABOVE = "BLOCK_LOW_AND_ABOVE"
+      BLOCK_MEDIUM_AND_ABOVE = "BLOCK_MEDIUM_AND_ABOVE"
+      BLOCK_ONLY_HIGH = "BLOCK_ONLY_HIGH"
+
+      # Returns default safety settings with BLOCK_MEDIUM_AND_ABOVE for all categories.
+      #
+      # @return [Array<Hash>] array of default safety settings
+      #
+      # @example
+      #   defaults = SafetySettings.default
+      #   # => [
+      #   #   {category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_MEDIUM_AND_ABOVE"},
+      #   #   {category: "HARM_CATEGORY_DANGEROUS_CONTENT", threshold: "BLOCK_MEDIUM_AND_ABOVE"},
+      #   #   ...
+      #   # ]
+      def self.default
+        [
+          {category: HARM_CATEGORY_HATE_SPEECH, threshold: BLOCK_MEDIUM_AND_ABOVE},
+          {category: HARM_CATEGORY_DANGEROUS_CONTENT, threshold: BLOCK_MEDIUM_AND_ABOVE},
+          {category: HARM_CATEGORY_HARASSMENT, threshold: BLOCK_MEDIUM_AND_ABOVE},
+          {category: HARM_CATEGORY_SEXUALLY_EXPLICIT, threshold: BLOCK_MEDIUM_AND_ABOVE}
+        ]
+      end
+
+      # Initializes a SafetySettings instance with an array of settings.
+      #
+      # @param settings [Array<Hash>] array of safety settings
+      #   Each setting: {category: "HARM_CATEGORY_...", threshold: "BLOCK_..."}
+      #
+      # @example
+      #   settings = SafetySettings.new([
+      #     {category: HARM_CATEGORY_HATE_SPEECH, threshold: BLOCK_LOW_AND_ABOVE}
+      #   ])
+      def initialize(settings)
+        @settings = settings
+      end
+
+      # Serializes the safety settings to Gemini API format.
+      #
+      # @return [Array<Hash>] the settings array in API format
+      #
+      # @example
+      #   settings = SafetySettings.new([
+      #     {category: HARM_CATEGORY_HATE_SPEECH, threshold: BLOCK_MEDIUM_AND_ABOVE}
+      #   ])
+      #   settings.to_h # => [{category: "HARM_CATEGORY_HATE_SPEECH", threshold: "BLOCK_MEDIUM_AND_ABOVE"}]
+      def to_h
+        @settings
+      end
+    end
+  end
+end

data/lib/aigen/google/version.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Aigen
+  module Google
+    def self.gem_version
+      Gem::Version.new(VERSION::STRING)
+    end
+
+    module VERSION
+      MAJOR = 0
+      MINOR = 1
+      TINY = 0
+      PRE = nil
+      BUILD = nil
+      STRING = [MAJOR, MINOR, TINY, PRE, BUILD].compact.join(".")
+    end
+  end
+end

data/lib/aigen/google.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "google/version"
+require_relative "google/errors"
+require_relative "google/configuration"
+require_relative "google/content"
+require_relative "google/generation_config"
+require_relative "google/safety_settings"
+require_relative "google/http_client"
+require_relative "google/image_response"
+require_relative "google/chat"
+require_relative "google/client"
+
+module Aigen
+  module Google
+    class << self
+      attr_accessor :configuration
+
+      def configure
+        self.configuration ||= Configuration.new
+        yield(configuration) if block_given?
+        configuration
+      end
+    end
+  end
+end

data/sig/aigen/google.rbs

@@ -0,0 +1,6 @@
+module Aigen
+  module Google
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: aigen-google
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lauri Jutila
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Ruby-native SDK for Google's Generative AI (Gemini) APIs, providing
+  text generation, chat, streaming, multimodal content, and image generation (Nano
+  Banana) support.
+email:
+- ljuti@nmux.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/aigen/google.rb
+- lib/aigen/google/chat.rb
+- lib/aigen/google/client.rb
+- lib/aigen/google/configuration.rb
+- lib/aigen/google/content.rb
+- lib/aigen/google/errors.rb
+- lib/aigen/google/generation_config.rb
+- lib/aigen/google/http_client.rb
+- lib/aigen/google/image_response.rb
+- lib/aigen/google/safety_settings.rb
+- lib/aigen/google/version.rb
+- sig/aigen/google.rbs
+homepage: https://github.com/neuralmux/aigen-google
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/neuralmux/aigen-google
+  source_code_uri: https://github.com/neuralmux/aigen-google
+  changelog_uri: https://github.com/neuralmux/aigen-google/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby SDK for Google Generative AI (Gemini API)
+test_files: []