reve_ai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 280bf1673c22b411163ea4dad09eae4a7ca07a06dceefee1d10b54cc2a07a097
+  data.tar.gz: 288d3493fcd73b1827003b785c29fd0c7ce53a76a302769e03054686508d2dc4
+SHA512:
+  metadata.gz: 604e38817990a60d470e0c24b96033c88b27774012e6dac07e6392c7f413d02fd8c123a92978868eb972790dea4ad23f11ce73226c11db88f0c3a5482aff7e52
+  data.tar.gz: 202c65bafdcd96b002cff7a083f10b7efd4c05e187b0add59831833e8d6dfd88e7aa0fac49037b986a5aedb4bcf19eceb3b6d4a679741a2acb3bd7577bc5a27f

data/README.md

@@ -0,0 +1,204 @@
+# ReveAI
+
+Ruby client for the [Reve image generation API](https://api.reve.com/console/docs).
+
+[![Gem Version](https://badge.fury.io/rb/reve_ai.svg)](https://badge.fury.io/rb/reve_ai)
+[![ci](https://github.com/dpaluy/reve_ai/actions/workflows/ci.yml/badge.svg)](https://github.com/dpaluy/reve_ai/actions/workflows/ci.yml)
+
+## Installation
+
+```
+bundle add reve_ai
+```
+
+## Usage
+
+Configure once:
+
+```ruby
+ReveAI.configure do |config|
+  config.api_key = ENV.fetch("REVE_AI_API_KEY")
+end
+```
+
+### Create Image
+
+Generate an image from a text prompt:
+
+```ruby
+client = ReveAI::Client.new
+
+response = client.images.create(prompt: "A beautiful sunset over mountains")
+
+response.image          # => "base64encodeddata..."
+response.version        # => "reve-create@20250915"
+response.request_id     # => "rsid-..."
+response.credits_used   # => 18
+response.credits_remaining # => 982
+```
+
+With aspect ratio:
+
+```ruby
+response = client.images.create(
+  prompt: "A beautiful sunset over mountains",
+  aspect_ratio: "16:9"  # Options: 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 1:1 (default: 3:2)
+)
+```
+
+With specific model version:
+
+```ruby
+response = client.images.create(
+  prompt: "A beautiful sunset over mountains",
+  version: "reve-create@20250915"  # Or "latest" (default)
+)
+```
+
+### Edit Image
+
+Modify an existing image using text instructions:
+
+```ruby
+require "base64"
+
+client = ReveAI::Client.new
+
+# Load and encode the image
+image_data = Base64.strict_encode64(File.read("my-image.png"))
+
+response = client.images.edit(
+  edit_instruction: "Add dramatic clouds to the sky",
+  reference_image: image_data
+)
+
+response.image   # => "base64editeddata..."
+response.version # => "reve-edit@20250915"
+```
+
+Available versions for edit: `latest`, `latest-fast`, `reve-edit@20250915`, `reve-edit-fast@20251030`
+
+### Remix Images
+
+Combine text prompts with reference images to create new variations:
+
+```ruby
+require "base64"
+
+client = ReveAI::Client.new
+
+# Load and encode reference images
+image1 = Base64.strict_encode64(File.read("person.png"))
+image2 = Base64.strict_encode64(File.read("background.png"))
+
+# Use <img>N</img> tags to reference specific images by index
+response = client.images.remix(
+  prompt: "The person from <img>0</img> standing in the scene from <img>1</img>",
+  reference_images: [image1, image2],
+  aspect_ratio: "16:9"  # Optional
+)
+
+response.image   # => "base64remixeddata..."
+response.version # => "reve-remix@20250915"
+```
+
+Available versions for remix: `latest`, `latest-fast`, `reve-remix@20250915`, `reve-remix-fast@20251030`
+
+### Rails
+
+Create `config/initializers/reve_ai.rb`:
+
+```ruby
+ReveAI.configure do |c|
+  c.api_key = Rails.application.credentials.dig(:reve, :api_key)
+  # c.base_url = "https://api.reve.com"
+  # c.timeout = 120
+  # c.open_timeout = 30
+  # c.max_retries = 2
+end
+```
+
+### Error Handling
+
+The gem provides detailed error classes for different scenarios:
+
+```ruby
+begin
+  client.images.create(prompt: "A sunset")
+rescue ReveAI::ValidationError => e
+  # Input validation failed (prompt too long, invalid aspect ratio, etc.)
+  puts "Validation error: #{e.message}"
+rescue ReveAI::UnauthorizedError => e
+  # Invalid API key (401)
+  puts "Auth error: #{e.message}"
+rescue ReveAI::InsufficientCreditsError => e
+  # Budget has run out (402)
+  puts "Out of credits: #{e.message}"
+rescue ReveAI::UnprocessableEntityError => e
+  # Inputs could not be understood (422)
+  puts "Unprocessable: #{e.message}"
+rescue ReveAI::RateLimitError => e
+  # Rate limited (429) - check retry_after
+  puts "Rate limited. Retry after: #{e.retry_after} seconds"
+rescue ReveAI::BadRequestError => e
+  # Invalid request parameters (400)
+  puts "Bad request: #{e.message}"
+rescue ReveAI::ServerError => e
+  # Server-side error (5xx)
+  puts "Server error: #{e.message}"
+rescue ReveAI::TimeoutError => e
+  # Request timed out
+  puts "Timeout: #{e.message}"
+rescue ReveAI::ConnectionError => e
+  # Connection failed
+  puts "Connection error: #{e.message}"
+end
+```
+
+### Content Moderation
+
+The API may flag content violations:
+
+```ruby
+response = client.images.create(prompt: "...")
+
+if response.content_violation?
+  puts "Content was flagged by moderation"
+end
+```
+
+### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `api_key` | `ENV["REVE_AI_API_KEY"]` | Your Reve API key |
+| `base_url` | `https://api.reve.com` | API base URL |
+| `timeout` | `120` | Request timeout in seconds |
+| `open_timeout` | `30` | Connection timeout in seconds |
+| `max_retries` | `2` | Number of retries for failed requests |
+| `logger` | `nil` | Logger instance for debugging |
+| `debug` | `false` | Enable debug logging |
+
+### Validation Constraints
+
+| Constraint | Value |
+|------------|-------|
+| Max prompt length | 2560 characters |
+| Max reference images (remix) | 6 |
+| Valid aspect ratios | 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 1:1 |
+
+## Development
+
+```
+bundle install
+bundle exec rake test
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/dpaluy/reve_ai.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/reve_ai/client.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ReveAI
+  # HTTP client for the Reve image generation API.
+  #
+  # Provides access to all Reve API endpoints through resource objects.
+  # Configure globally via {ReveAI.configure} or pass parameters directly
+  # to the constructor.
+  #
+  # @example Using global configuration
+  #   ReveAI.configure do |config|
+  #     config.api_key = ENV["REVE_AI_API_KEY"]
+  #   end
+  #
+  #   client = ReveAI::Client.new
+  #   result = client.images.create(prompt: "A cat wearing a hat")
+  #
+  # @example Using per-instance configuration
+  #   client = ReveAI::Client.new(
+  #     api_key: "your-key",
+  #     timeout: 60
+  #   )
+  #
+  # @see Resources::Images
+  # @see Configuration
+  class Client
+    # @return [Configuration] Configuration instance for this client
+    attr_reader :configuration
+
+    # Creates a new Reve API client.
+    #
+    # @param api_key [String, nil] API key (defaults to global config or ENV["REVE_AI_API_KEY"])
+    # @param options [Hash] Additional configuration options
+    # @option options [String] :base_url Base URL for API requests
+    # @option options [Integer] :timeout Request timeout in seconds
+    # @option options [Integer] :open_timeout Connection timeout in seconds
+    # @option options [Integer] :max_retries Number of retry attempts
+    # @option options [Logger] :logger Logger instance for debugging
+    # @option options [Boolean] :debug Enable debug logging
+    #
+    # @raise [ConfigurationError] if api_key is missing or empty
+    #
+    # @example
+    #   client = ReveAI::Client.new(api_key: "your-api-key")
+    def initialize(api_key: nil, **options)
+      @configuration = build_configuration(api_key, options)
+      validate_configuration!
+    end
+
+    # Returns the Images resource for image generation operations.
+    #
+    # @return [Resources::Images] Image operations interface
+    # @see Resources::Images
+    #
+    # @example Generate an image
+    #   result = client.images.create(prompt: "A sunset over mountains")
+    #   puts result.base64 # Base64 encoded PNG
+    #
+    # @example Edit an image
+    #   result = client.images.edit(
+    #     edit_instruction: "Make the sky more blue",
+    #     reference_image: base64_encoded_image
+    #   )
+    #
+    # @example Remix images
+    #   result = client.images.remix(
+    #     prompt: "Combine <img>1</img> and <img>2</img> into one scene",
+    #     reference_images: [image1_base64, image2_base64]
+    #   )
+    def images
+      @images ||= Resources::Images.new(self)
+    end
+
+    # Returns the HTTP client for making API requests.
+    #
+    # @return [HTTP::Client] HTTP client instance
+    # @api private
+    def http_client
+      @http_client ||= HTTP::Client.new(configuration)
+    end
+
+    private
+
+    # Builds configuration from global config and options.
+    #
+    # @param api_key [String, nil] API key override
+    # @param options [Hash] Configuration options
+    # @return [Configuration] Merged configuration
+    # @api private
+    def build_configuration(api_key, options)
+      config = ReveAI.configuration&.dup || Configuration.new
+      config.api_key = api_key if api_key
+      options.each { |key, value| config.public_send("#{key}=", value) }
+      config
+    end
+
+    # Validates that required configuration is present.
+    #
+    # @raise [ConfigurationError] if API key is missing
+    # @api private
+    def validate_configuration!
+      raise ConfigurationError, "API key is required" unless configuration.valid?
+    end
+  end
+end

data/lib/reve_ai/configuration.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ReveAI
+  # Configuration settings for the ReveAI client.
+  #
+  # Stores API credentials and connection settings. Can be configured globally
+  # via {ReveAI.configure} or per-instance when creating a {Client}.
+  #
+  # @example Global configuration
+  #   ReveAI.configure do |config|
+  #     config.api_key = ENV["REVE_AI_API_KEY"]
+  #     config.timeout = 120
+  #     config.debug = true
+  #   end
+  #
+  # @example Environment variable
+  #   # Set REVE_AI_API_KEY environment variable
+  #   export REVE_AI_API_KEY="your-api-key"
+  #
+  #   # API key is automatically loaded
+  #   client = ReveAI::Client.new
+  #
+  # @see Client
+  class Configuration
+    # @return [String] Default base URL for the Reve API
+    DEFAULT_BASE_URL = "https://api.reve.com"
+
+    # @return [Integer] Default request timeout in seconds (2 minutes for image generation)
+    DEFAULT_TIMEOUT = 120
+
+    # @return [Integer] Default connection open timeout in seconds
+    DEFAULT_OPEN_TIMEOUT = 30
+
+    # @return [Integer] Default number of retry attempts for failed requests
+    DEFAULT_MAX_RETRIES = 2
+
+    # @return [Array<String>] Valid aspect ratios for image generation
+    VALID_ASPECT_RATIOS = %w[16:9 9:16 3:2 2:3 4:3 3:4 1:1].freeze
+
+    # @return [Integer] Maximum allowed prompt length in characters
+    MAX_PROMPT_LENGTH = 2560
+
+    # @return [Integer] Maximum number of reference images for remix operations
+    MAX_REFERENCE_IMAGES = 6
+
+    # @return [String, nil] Reve API key for authentication
+    attr_accessor :api_key
+
+    # @return [String] Base URL for API requests (defaults to https://api.reve.com)
+    attr_accessor :base_url
+
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] Connection open timeout in seconds
+    attr_accessor :open_timeout
+
+    # @return [Integer] Number of retry attempts for transient failures
+    attr_accessor :max_retries
+
+    # @return [Logger, nil] Logger instance for debug output
+    attr_accessor :logger
+
+    # @return [Boolean] Enable debug logging of HTTP requests/responses
+    attr_accessor :debug
+
+    # Creates a new configuration with default values.
+    #
+    # Automatically loads API key from the REVE_AI_API_KEY environment variable
+    # if present.
+    #
+    # @example
+    #   config = ReveAI::Configuration.new
+    #   config.api_key = "your-api-key"
+    #   config.timeout = 60
+    def initialize
+      @api_key = ENV.fetch("REVE_AI_API_KEY", nil)
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+      @logger = nil
+      @debug = false
+    end
+
+    # Checks if the configuration has a valid API key.
+    #
+    # @return [Boolean] true if api_key is present and not empty
+    #
+    # @example
+    #   config = ReveAI::Configuration.new
+    #   config.valid? # => false
+    #
+    #   config.api_key = "your-key"
+    #   config.valid? # => true
+    def valid?
+      !api_key.nil? && !api_key.empty?
+    end
+  end
+end

data/lib/reve_ai/errors.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module ReveAI
+  # Base error class for all ReveAI errors.
+  #
+  # All library exceptions inherit from this class.
+  #
+  # @example Catching all ReveAI errors
+  #   begin
+  #     client.images.create(prompt: "A cat")
+  #   rescue ReveAI::Error => e
+  #     puts "ReveAI error: #{e.message}"
+  #   end
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or missing.
+  #
+  # @example
+  #   client = ReveAI::Client.new(api_key: nil)
+  #   # => ReveAI::ConfigurationError: API key is required
+  class ConfigurationError < Error; end
+
+  # Raised when input validation fails before making an API call.
+  #
+  # @example Invalid prompt
+  #   client.images.create(prompt: "")
+  #   # => ReveAI::ValidationError: Prompt is required
+  #
+  # @example Invalid aspect ratio
+  #   client.images.create(prompt: "A cat", aspect_ratio: "5:3")
+  #   # => ReveAI::ValidationError: Invalid aspect_ratio '5:3'. Must be one of: 16:9, 9:16, ...
+  class ValidationError < Error; end
+
+  # Base class for network-level errors.
+  #
+  # Indicates connection or transport failures rather than API errors.
+  class NetworkError < Error; end
+
+  # Raised when a request times out.
+  #
+  # @example
+  #   # Request exceeded timeout
+  #   client.images.create(prompt: "A complex scene...")
+  #   # => ReveAI::TimeoutError: Request timed out: execution expired
+  class TimeoutError < NetworkError; end
+
+  # Raised when unable to establish a connection to the API.
+  #
+  # @example
+  #   # DNS failure or network unreachable
+  #   # => ReveAI::ConnectionError: Connection failed: getaddrinfo: nodename nor servname provided
+  class ConnectionError < NetworkError; end
+
+  # Base class for API errors with HTTP status and response details.
+  #
+  # All API-related exceptions inherit from this class and include
+  # HTTP status code, response body, and headers for debugging.
+  #
+  # @example Handling API errors
+  #   begin
+  #     client.images.create(prompt: "...")
+  #   rescue ReveAI::UnauthorizedError => e
+  #     puts "Auth failed: #{e.message}"
+  #     puts "Status: #{e.status}"
+  #   rescue ReveAI::RateLimitError => e
+  #     puts "Rate limited, retry after #{e.retry_after} seconds"
+  #   rescue ReveAI::APIError => e
+  #     puts "API error (#{e.status}): #{e.message}"
+  #     puts "Request ID: #{e.request_id}"
+  #   end
+  class APIError < Error
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status
+
+    # @return [Hash] Response body parsed as Hash
+    attr_reader :body
+
+    # @return [Hash] Response headers
+    attr_reader :headers
+
+    # Creates a new API error instance.
+    #
+    # @param message [String, nil] Error message
+    # @param status [Integer, nil] HTTP status code
+    # @param body [Hash, nil] Response body
+    # @param headers [Hash, nil] Response headers
+    def initialize(message = nil, status: nil, body: nil, headers: nil)
+      @status = status
+      @body = body || {}
+      @headers = headers || {}
+      super(message)
+    end
+
+    # Returns the request ID from response headers.
+    #
+    # Useful for debugging and support requests.
+    #
+    # @return [String, nil] Request ID if present
+    def request_id
+      headers["x-reve-request-id"]
+    end
+
+    # Returns the error code from the response body.
+    #
+    # @return [String, nil] Error code (e.g., "PROMPT_TOO_LONG", "INVALID_API_KEY")
+    def error_code
+      body[:error_code]
+    end
+  end
+
+  # Raised on 400 Bad Request responses.
+  #
+  # Indicates invalid request parameters or malformed request body.
+  #
+  # @example
+  #   # Prompt too long
+  #   client.images.create(prompt: "x" * 10000)
+  #   # => ReveAI::BadRequestError: Prompt exceeds maximum length
+  class BadRequestError < APIError; end
+
+  # Raised on 401 Unauthorized responses.
+  #
+  # Indicates invalid or missing API key.
+  #
+  # @example
+  #   client = ReveAI::Client.new(api_key: "invalid-key")
+  #   client.images.create(prompt: "A cat")
+  #   # => ReveAI::UnauthorizedError: Invalid API key
+  class UnauthorizedError < APIError; end
+
+  # Raised on 402 Payment Required responses.
+  #
+  # Indicates the account has run out of credits.
+  #
+  # @example
+  #   # Account has insufficient credits
+  #   client.images.create(prompt: "A cat")
+  #   # => ReveAI::InsufficientCreditsError: Your budget has run out
+  class InsufficientCreditsError < APIError; end
+
+  # Raised on 403 Forbidden responses.
+  #
+  # Indicates the API key lacks permission for the requested operation.
+  class ForbiddenError < APIError; end
+
+  # Raised on 404 Not Found responses.
+  #
+  # Indicates the requested resource does not exist.
+  class NotFoundError < APIError; end
+
+  # Raised on 422 Unprocessable Entity responses.
+  #
+  # Indicates the inputs could not be understood or processed.
+  #
+  # @example
+  #   # Invalid reference image format
+  #   client.images.edit(edit_instruction: "...", reference_image: "not-valid-base64")
+  #   # => ReveAI::UnprocessableEntityError: The inputs could not be understood
+  class UnprocessableEntityError < APIError; end
+
+  # Raised on 429 Too Many Requests responses.
+  #
+  # Indicates the rate limit has been exceeded. Check {#retry_after}
+  # to determine when to retry.
+  #
+  # @example
+  #   begin
+  #     client.images.create(prompt: "A cat")
+  #   rescue ReveAI::RateLimitError => e
+  #     sleep e.retry_after
+  #     retry
+  #   end
+  class RateLimitError < APIError
+    # Returns the retry-after header value in seconds.
+    #
+    # Indicates how long to wait before retrying the request.
+    #
+    # @return [Integer, nil] Seconds to wait before retrying
+    def retry_after
+      headers["retry-after"]&.to_i
+    end
+  end
+
+  # Raised on 5xx server error responses.
+  #
+  # Indicates an internal server error on the Reve API side.
+  # These are typically transient and can be retried.
+  #
+  # @example
+  #   # Server error
+  #   client.images.create(prompt: "A cat")
+  #   # => ReveAI::ServerError: Internal server error
+  class ServerError < APIError; end
+end