reve_ai 0.1.0 → 0.2.0

data/lib/reve_ai/resources/v2/layouts.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+require_relative "../base"
+
+module ReveAI
+  module Resources
+    class V2
+      # v2 layout pipeline operations (experimental).
+      #
+      # The layout endpoints expose lower-level control over image
+      # composition: extracting structured layouts from images, generating
+      # layouts from prompts, and rendering images from layouts.
+      #
+      # @note Experimental: these endpoints require care and experimentation
+      #   to achieve good results. For simple image generation and
+      #   prompt-based editing, prefer {V2::Images#create}.
+      #
+      # @see https://api.reve.com/console/docs Reve API Documentation
+      class Layouts < Base
+        # @return [String] API endpoint for layout extraction
+        EXTRACT_ENDPOINT = "/v2/image/extract_layout"
+
+        # @return [String] API endpoint for layout generation
+        CREATE_ENDPOINT = "/v2/image/create_layout"
+
+        # @return [String] API endpoint for layout rendering
+        RENDER_ENDPOINT = "/v2/image/render_layout"
+
+        # Extracts a structured layout from an image.
+        #
+        # @param image [Hash] Source image: exactly one of +data+ (base64
+        #   encoded image String) or +ref+ (identifier String: +"id:<uuid>"+
+        #   or +"reference:@<name>"+)
+        # @param prompt [String, nil] Optional instruction for transforming
+        #   the extracted layout (max 4000 chars)
+        # @param version [String, nil] Optional public model version alias
+        # @param breadcrumb [String, nil] Request tracking value sent as the
+        #   +breadcrumb+ query parameter; ignored by the API
+        #
+        # @return [LayoutResponse] Response containing the extracted +layout+
+        #
+        # @raise [ValidationError] if image is malformed or prompt exceeds max length
+        #
+        # @example Extract a layout from an image
+        #   result = client.v2.layouts.extract(image: { data: photo_base64 })
+        #   result.layout # => { prompt: "...", regions: [...], width: 4672, height: 3520 }
+        #
+        # @note Experimental: layout extraction commonly takes 10-40 seconds.
+        def extract(image:, prompt: nil, version: nil, breadcrumb: nil)
+          validate_raw_image!(image, "Image")
+          validate_prompt!(prompt, max_length: Configuration::V2_MAX_PROMPT_LENGTH) if prompt
+
+          body = { image: image }
+          body[:prompt] = prompt if prompt
+          body[:version] = version if version
+
+          response = post(EXTRACT_ENDPOINT, body, params: breadcrumb_params(breadcrumb))
+          LayoutResponse.new(status: response.status, headers: response.headers, body: response.body)
+        end
+
+        # Generates (or edits) a structured layout without rendering an image.
+        #
+        # @param prompt [String, nil] Description of the desired layout
+        #   (max 4000 chars); at least one of +prompt+ or +references+ is required
+        # @param references [Array<Hash>, nil] Up to 8 ordered compound
+        #   references ({Configuration::V2_MAX_REFERENCES}); each entry may
+        #   contain +image+ (a raw { data: }/{ ref: } image Hash), +layout+
+        #   (a layout Hash), and/or +prompt+ (String) — at least one per entry
+        # @param commands [Array<Hash>, nil] Ordered imperative layout edits;
+        #   each entry is a Hash with an +op+ key (add, place, shift, remove,
+        #   keep, change) plus op-specific fields
+        # @param aspect_ratio [String, nil] Layout aspect ratio; supported set
+        #   ({Configuration::ASPECT_RATIOS}), default "auto"
+        # @param version [String, nil] Optional public model version alias
+        # @param breadcrumb [String, nil] Request tracking value sent as the
+        #   +breadcrumb+ query parameter; ignored by the API
+        #
+        # @return [LayoutResponse] Response containing the generated +layout+
+        #
+        # @raise [ValidationError] if neither prompt nor references is given,
+        #   or any argument is malformed
+        #
+        # @example Free-form layout from a prompt
+        #   result = client.v2.layouts.create(prompt: "a person at a cafe")
+        #   result.layout[:regions] # => [{ label: "person", bbox: {...}, ... }]
+        #
+        # @note Experimental: layout generation commonly takes 10-40 seconds.
+        def create(prompt: nil, references: nil, commands: nil, aspect_ratio: nil, version: nil, breadcrumb: nil)
+          validate_prompt_or_references!(prompt, references)
+          validate_prompt!(prompt, max_length: Configuration::V2_MAX_PROMPT_LENGTH) if prompt
+          validate_compound_references!(references)
+          validate_commands!(commands)
+          validate_aspect_ratio!(aspect_ratio, Configuration::ASPECT_RATIOS)
+
+          body = build_create_body(prompt: prompt, references: references, commands: commands,
+                                   aspect_ratio: aspect_ratio, version: version)
+
+          response = post(CREATE_ENDPOINT, body, params: breadcrumb_params(breadcrumb))
+          LayoutResponse.new(status: response.status, headers: response.headers, body: response.body)
+        end
+
+        # Renders a final image from a target layout.
+        #
+        # @param layout [Hash] The layout to render; must include a non-empty
+        #   +regions+ Array (each region: +label+, +prompt+, +bbox+ with
+        #   normalized x0/y0/x1/y1; optional +parent+, +region_type+,
+        #   +image_index+, +image_region_index+)
+        # @param references [Array<Hash>, nil] Up to 8 ordered compound
+        #   references; same shape as {#create}
+        # @param postprocessing [Array<Hash>, nil] Postprocessing steps, each
+        #   with a +process+ key (e.g., { process: "fit_image", max_dim: 2048 })
+        # @param version [String, nil] Optional public model version alias
+        # @param accept [String, nil] Per-request Accept header: "image/png",
+        #   "image/jpeg", or "image/webp" for a binary image response, or
+        #   "application/json" (default)
+        # @param breadcrumb [String, nil] Request tracking value sent as the
+        #   +breadcrumb+ query parameter; ignored by the API
+        #
+        # @return [ImageResponse] Response containing the rendered image and
+        #   the produced +layout+
+        #
+        # @raise [ValidationError] if layout is missing or malformed
+        #
+        # @example Render a layout to an image
+        #   layout = { regions: [{ label: "cat", prompt: "a tabby cat",
+        #                          bbox: { x0: 0.2, y0: 0.2, x1: 0.8, y1: 0.8 } }] }
+        #   result = client.v2.layouts.render(layout: layout)
+        #   File.binwrite("cat.png", Base64.decode64(result.image))
+        #
+        # @note Experimental: rendering commonly takes 40-80 seconds.
+        def render(layout:, references: nil, postprocessing: nil, version: nil, accept: nil, breadcrumb: nil)
+          validate_layout!(layout)
+          validate_compound_references!(references)
+          validate_postprocessing!(postprocessing)
+
+          body = { layout: layout }
+          body[:references] = references if references
+          body[:postprocessing] = postprocessing if postprocessing
+          body[:version] = version if version
+
+          response = post(RENDER_ENDPOINT, body, params: breadcrumb_params(breadcrumb), accept: accept)
+          ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
+        end
+
+        private
+
+        # Builds the request body for the create_layout endpoint.
+        #
+        # @return [Hash] Request body with only the provided options
+        # @api private
+        def build_create_body(prompt:, references:, commands:, aspect_ratio:, version:)
+          body = {}
+          body[:prompt] = prompt if prompt
+          body[:references] = references if references
+          body[:commands] = commands if commands
+          body[:aspect_ratio] = aspect_ratio if aspect_ratio
+          body[:version] = version if version
+          body
+        end
+
+        # Returns the query params Hash for a breadcrumb, or nil.
+        #
+        # @param breadcrumb [String, nil] Breadcrumb value
+        # @return [Hash, nil] Query params
+        # @api private
+        def breadcrumb_params(breadcrumb)
+          breadcrumb ? { breadcrumb: breadcrumb } : nil
+        end
+
+        # Reads a Hash value accepting symbol or string keys.
+        #
+        # @param hash [Hash] The Hash to read
+        # @param key [Symbol] The key to look up (symbol or string form)
+        # @return [Object, nil] The value, or nil when absent
+        # @api private
+        def fetch_value(hash, key)
+          hash[key] || hash[key.to_s]
+        end
+
+        # Validates that at least one of prompt or references is present.
+        #
+        # @raise [ValidationError] if both are nil/empty
+        # @api private
+        def validate_prompt_or_references!(prompt, references)
+          return if prompt && !prompt.empty?
+          return if references && !references.empty?
+
+          raise ValidationError, "At least one of prompt or references is required"
+        end
+
+        # Validates a raw image object ({ data: } or { ref: } shape).
+        #
+        # @param image [Object] The value to validate
+        # @param label [String] Label for error messages
+        # @raise [ValidationError] if not a Hash with exactly one non-empty
+        #   String +data+ or +ref+ value
+        # @api private
+        def validate_raw_image!(image, label)
+          raise ValidationError, "#{label} must be a Hash with exactly one of 'data' or 'ref'" unless image.is_a?(Hash)
+
+          data = fetch_value(image, :data)
+          ref = fetch_value(image, :ref)
+
+          raise ValidationError, "#{label} must include exactly one of 'data' or 'ref'" if data.nil? == ref.nil?
+
+          value = data || ref
+          return if value.is_a?(String) && !value.empty?
+
+          raise ValidationError, "#{label} '#{data ? "data" : "ref"}' must be a non-empty String"
+        end
+
+        # Validates compound layout references.
+        #
+        # @param references [Array<Hash>, nil] Compound reference entries
+        # @raise [ValidationError] if not an Array of valid compound entries
+        # @api private
+        def validate_compound_references!(references)
+          return if references.nil?
+
+          unless references.is_a?(Array)
+            raise ValidationError, "References must be an Array of compound reference Hashes"
+          end
+
+          max = Configuration::V2_MAX_REFERENCES
+          raise ValidationError, "Maximum #{max} references allowed" if references.length > max
+
+          references.each_with_index { |reference, index| validate_compound_reference!(reference, index) }
+        end
+
+        # Validates a single compound reference entry.
+        #
+        # @param reference [Hash] Entry with at least one of image/layout/prompt
+        # @param index [Integer] Position in the references array
+        # @raise [ValidationError] if the entry carries none of the allowed
+        #   fields, or carries a malformed image/layout
+        # @api private
+        def validate_compound_reference!(reference, index)
+          raise ValidationError, "Reference at index #{index} must be a Hash" unless reference.is_a?(Hash)
+
+          image = fetch_value(reference, :image)
+          layout = fetch_value(reference, :layout)
+          prompt = fetch_value(reference, :prompt)
+
+          if image.nil? && layout.nil? && prompt.nil?
+            raise ValidationError,
+                  "Reference at index #{index} must include at least one of 'image', 'layout', 'prompt'"
+          end
+
+          validate_raw_image!(image, "Reference at index #{index} 'image'") if image
+          validate_reference_layout!(layout, index)
+          validate_reference_prompt!(prompt, index)
+        end
+
+        # Validates the layout value inside a compound reference.
+        #
+        # @param layout [Object] The value to check
+        # @param index [Integer] Position in the references array
+        # @raise [ValidationError] if present and not a Hash
+        # @api private
+        def validate_reference_layout!(layout, index)
+          return if layout.nil? || layout.is_a?(Hash)
+
+          raise ValidationError, "Reference at index #{index} 'layout' must be a Hash"
+        end
+
+        # Validates the prompt value inside a compound reference.
+        #
+        # @param prompt [Object] The value to check
+        # @param index [Integer] Position in the references array
+        # @raise [ValidationError] if present and not a non-empty String
+        # @api private
+        def validate_reference_prompt!(prompt, index)
+          return if prompt.nil?
+          return if prompt.is_a?(String) && !prompt.empty?
+
+          raise ValidationError, "Reference at index #{index} 'prompt' must be a non-empty String"
+        end
+
+        # Validates the target layout for rendering.
+        #
+        # @param layout [Object] The layout to validate
+        # @raise [ValidationError] if not a Hash with a non-empty regions Array
+        # @api private
+        def validate_layout!(layout)
+          regions = fetch_value(layout, :regions) if layout.is_a?(Hash)
+          return if regions.is_a?(Array) && !regions.empty?
+
+          raise ValidationError, "Layout must be a Hash with a non-empty 'regions' Array"
+        end
+
+        # Validates layout commands.
+        #
+        # @param commands [Array<Hash>, nil] Command entries
+        # @raise [ValidationError] if not an Array of Hashes with an +op+ key
+        # @api private
+        def validate_commands!(commands)
+          return if commands.nil?
+          raise ValidationError, "Commands must be an Array of Hashes with an 'op' key" unless commands.is_a?(Array)
+
+          commands.each_with_index do |command, index|
+            next if command.is_a?(Hash) && (command.key?(:op) || command.key?("op"))
+
+            raise ValidationError, "Command at index #{index} must be a Hash with an 'op' key"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/reve_ai/resources/v2.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ReveAI
+  module Resources
+    # Namespace for Reve API v2 resources.
+    #
+    # Accessed via `client.v2`. Groups the v2 image create endpoint and the
+    # experimental layout pipeline endpoints.
+    #
+    # @example Generate an image with the v2 API
+    #   result = client.v2.images.create(prompt: "A sunset over mountains")
+    #   result.layout # => { prompt: "...", regions: [...] }
+    #
+    # @see https://api.reve.com/console/docs Reve API Documentation
+    class V2
+      # @return [Client] The client instance for this namespace
+      attr_reader :client
+
+      # Creates a new v2 namespace.
+      #
+      # @param client [Client] The API client
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      # Returns the v2 images resource.
+      #
+      # @return [V2::Images] v2 image generation operations
+      def images
+        @images ||= Images.new(client)
+      end
+
+      # Returns the v2 layouts resource (experimental endpoints).
+      #
+      # @return [V2::Layouts] v2 layout pipeline operations
+      def layouts
+        @layouts ||= Layouts.new(client)
+      end
+    end
+  end
+end

data/lib/reve_ai/response.rb

@@ -3,9 +3,13 @@
 module ReveAI
   # Base response wrapper for API responses.
   #
-  # Provides access to HTTP status, headers, and parsed response body.
+  # Provides access to HTTP status, headers, and response body. The body is a
+  # parsed Hash for JSON responses, or the raw image String (bytes) when the
+  # API answers with a binary body (Accept: image/*); in that case all
+  # metadata is carried by the X-Reve-* response headers.
   #
   # @see ImageResponse
+  # @see LayoutResponse
   class Response
     # @return [Integer] HTTP status code
     attr_reader :status
@@ -13,14 +17,15 @@ module ReveAI
     # @return [Hash] Response headers
     attr_reader :headers
 
-    # @return [Hash] Parsed response body
+    # @return [Hash, String] Parsed response body, or raw bytes String
+    #   for binary (image/*) responses
     attr_reader :body
 
     # Creates a new response wrapper.
     #
     # @param status [Integer] HTTP status code
     # @param headers [Hash] Response headers
-    # @param body [Hash] Parsed response body
+    # @param body [Hash, String] Parsed response body, or raw bytes String
     def initialize(status:, headers:, body:)
       @status = status
       @headers = headers
@@ -34,20 +39,42 @@ module ReveAI
       status >= 200 && status < 300
     end
 
+    # Checks if the response body is raw binary data (e.g., image bytes).
+    #
+    # @return [Boolean] true if body is not a parsed JSON Hash
+    def binary?
+      !body.is_a?(Hash)
+    end
+
     # Returns the request ID for this response.
     #
     # Useful for debugging and support requests.
     #
     # @return [String, nil] Request ID from body or headers
     def request_id
-      body[:request_id] || headers["x-reve-request-id"]
+      body_value(:request_id) || headers["x-reve-request-id"]
+    end
+
+    private
+
+    # Reads a key from the body when it is a Hash (JSON response).
+    #
+    # Binary (String) bodies have no keys; header fallbacks apply instead.
+    #
+    # @param key [Symbol] Body key to read
+    # @return [Object, nil] Body value, or nil for binary bodies
+    # @api private
+    def body_value(key)
+      body[key] if body.is_a?(Hash)
     end
   end
 
   # Response wrapper for image generation API responses.
   #
   # Provides convenient accessors for image data, version info,
-  # content policy status, and credit usage.
+  # content policy status, and credit usage. All accessors work for both
+  # JSON responses (values from the parsed body) and binary responses
+  # (values from the X-Reve-* headers).
   #
   # @example Accessing image data
   #   result = client.images.create(prompt: "A sunset")
@@ -66,28 +93,48 @@ module ReveAI
   #
   # @see Response
   class ImageResponse < Response
-    # Returns the base64 encoded image data.
+    # Returns the image data.
     #
-    # The image is in PNG format. Use Base64.decode64 to get raw bytes.
+    # For JSON responses this is the base64 encoded image; for binary
+    # responses (Accept: image/*) it is the raw image bytes in the
+    # negotiated format, ready to write to disk without decoding.
     #
-    # @return [String, nil] Base64 encoded PNG image data
+    # @return [String, nil] Base64 encoded image data (JSON response) or
+    #   raw image bytes (binary response)
     #
-    # @example Save to file
+    # @example Save a JSON (base64) response to file
     #   require "base64"
-    #   png_bytes = Base64.decode64(result.image)
-    #   File.binwrite("output.png", png_bytes)
+    #   File.binwrite("output.png", Base64.decode64(result.image))
+    #
+    # @example Save a binary response to file (no Base64 decode needed)
+    #   File.binwrite("output.webp", result.image)
     def image
-      body[:image]
+      binary? ? body : body[:image]
     end
 
     # Alias for {#image}.
     #
-    # @return [String, nil] Base64 encoded PNG image data
+    # @note Despite the name, binary responses (Accept: image/*) return raw
+    #   image bytes here, not base64 data.
+    #
+    # @return [String, nil] Base64 encoded image data (JSON response) or
+    #   raw image bytes (binary response)
     # @see #image
     def base64
       image
     end
 
+    # Returns the layout object for this generation.
+    #
+    # Present on v2 create/render JSON responses; nil on v1 responses and
+    # on binary (Accept: image/*) responses.
+    #
+    # @return [Hash, nil] Layout Hash (e.g., +prompt+, +regions+, +width+,
+    #   +height+), or nil when absent
+    def layout
+      body_value(:layout)
+    end
+
     # Returns the model version used for generation.
     #
     # @return [String, nil] Model version (e.g., "reve-create@20250915")
@@ -95,7 +142,7 @@ module ReveAI
     # @example
     #   result.version # => "reve-create@20250915"
     def version
-      body[:version] || headers["x-reve-version"]
+      body_value(:version) || headers["x-reve-version"]
     end
 
     # Checks if the generated image violates content policy.
@@ -107,7 +154,7 @@ module ReveAI
     #     puts "Warning: Content policy violated"
     #   end
     def content_violation?
-      body[:content_violation] == true ||
+      body_value(:content_violation) == true ||
         headers["x-reve-content-violation"] == "true"
     end
 
@@ -118,7 +165,7 @@ module ReveAI
     # @example
     #   puts "This request used #{result.credits_used} credits"
     def credits_used
-      body[:credits_used] || headers["x-reve-credits-used"]&.to_i
+      body_value(:credits_used) || headers["x-reve-credits-used"]&.to_i
     end
 
     # Returns the number of credits remaining after this request.
@@ -130,7 +177,51 @@ module ReveAI
     #     puts "Warning: Low credit balance"
     #   end
     def credits_remaining
-      body[:credits_remaining] || headers["x-reve-credits-remaining"]&.to_i
+      body_value(:credits_remaining) || headers["x-reve-credits-remaining"]&.to_i
+    end
+  end
+
+  # Response wrapper for layout-only API responses.
+  #
+  # Returned by the v2 extract_layout and create_layout endpoints, which
+  # produce a layout object but no image. Accessors fall back to the
+  # X-Reve-* headers when the body carries no value.
+  #
+  # @example Inspecting a layout
+  #   result = client.v2.layouts.extract(image: base64_image)
+  #   result.layout # => { prompt: "...", regions: [...], width: 4096, height: 2560 }
+  #
+  # @see Response
+  # @see ImageResponse
+  class LayoutResponse < Response
+    # Returns the layout object.
+    #
+    # @return [Hash, nil] Layout Hash (e.g., +prompt+, +regions+, +width+,
+    #   +height+), or nil when absent
+    def layout
+      body_value(:layout)
+    end
+
+    # Checks if the request violates content policy.
+    #
+    # @return [Boolean] true if content policy was violated
+    def content_violation?
+      body_value(:content_violation) == true ||
+        headers["x-reve-content-violation"] == "true"
+    end
+
+    # Returns the number of credits used for this request.
+    #
+    # @return [Integer, nil] Credits consumed by this request
+    def credits_used
+      body_value(:credits_used) || headers["x-reve-credits-used"]&.to_i
+    end
+
+    # Returns the number of credits remaining after this request.
+    #
+    # @return [Integer, nil] Remaining credit balance
+    def credits_remaining
+      body_value(:credits_remaining) || headers["x-reve-credits-remaining"]&.to_i
     end
   end
 end

data/lib/reve_ai/version.rb

@@ -2,5 +2,5 @@
 
 module ReveAI
   # @return [String] Current gem version
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/reve_ai.rb

@@ -7,6 +7,10 @@ require_relative "reve_ai/response"
 require_relative "reve_ai/http/client"
 require_relative "reve_ai/resources/base"
 require_relative "reve_ai/resources/images"
+require_relative "reve_ai/resources/effects"
+require_relative "reve_ai/resources/v2"
+require_relative "reve_ai/resources/v2/images"
+require_relative "reve_ai/resources/v2/layouts"
 require_relative "reve_ai/client"
 
 # Ruby client for the Reve image generation API.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reve_ai
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - dpaluy
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -44,8 +58,10 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files:
+- CHANGELOG.md
 - README.md
 files:
+- CHANGELOG.md
 - README.md
 - Rakefile
 - lib/reve_ai.rb
@@ -54,7 +70,11 @@ files:
 - lib/reve_ai/errors.rb
 - lib/reve_ai/http/client.rb
 - lib/reve_ai/resources/base.rb
+- lib/reve_ai/resources/effects.rb
 - lib/reve_ai/resources/images.rb
+- lib/reve_ai/resources/v2.rb
+- lib/reve_ai/resources/v2/images.rb
+- lib/reve_ai/resources/v2/layouts.rb
 - lib/reve_ai/response.rb
 - lib/reve_ai/version.rb
 homepage: https://github.com/dpaluy/reve_ai
@@ -81,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client for the Reve image generation API.
 test_files: []