reducto_ai 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00ad6f946c48de4c4638894e5cce87f594601c85b47ab09714289a21111f83e5
-  data.tar.gz: 4ffffbf8a965b92f7e3395604e6be7736764d37a741e7ca589cec36adf2f5dc9
+  metadata.gz: fca3ba2a817b1f51125400a08cdee95435107e7a1f16df0d8c2cd7cbb3304a8a
+  data.tar.gz: 80fe552733b22de584c8999e55b36930d9d6e59578486728b70d3d169e26c9d4
 SHA512:
-  metadata.gz: 5a3a7fd5765ef62bd9e9ea56c137c8d84b75741c9dce2c152ecb19b6d95c08f489a64994d71ca4ceb513c3e1144d45cc057232f18f81c546529a5fe1ec0c999c
-  data.tar.gz: 205ba689712f16f646eba2e00f29b93e579adc68aa2966c5985dd55b5802afd0ede7b441f7eaaf1b4d3578e273d48dfe7f6f15f9667bf7c1e8af3acb0ebeb947
+  metadata.gz: 0b3d764d2e1220b1e3fe15eba6ac9d56c9046abafdd68437ed2aaa87e935ed626c58573659af664b9077b178454fe5d961ef1d2621e97ef8c6d080aa22b240b8
+  data.tar.gz: d45dced01076b031189f8f299c3438f9698df14738b41abc0012932a7a52703271ca0ee6fa96557c5915fa4c98365e881bf1bb7a638367cb9e5e4c9674623f01

data/.yardopts

@@ -0,0 +1,6 @@
+--markup markdown
+--no-private
+lib/**/*.rb
+- README.md
+- CHANGELOG.md
+- LICENSE.txt

data/README.md

@@ -2,6 +2,8 @@
 
 Ruby wrapper on [ReductoAI API](https://docs.reducto.ai/api-reference)
 
+[![Gem Version](https://badge.fury.io/rb/reducto_ai.svg)](https://badge.fury.io/rb/reducto_ai)
+
 ## Installation
 
 ```

data/Rakefile

@@ -9,4 +9,11 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  # YARD not available
+end
+
 task default: %i[test rubocop]

data/lib/reducto_ai/client.rb

@@ -11,9 +11,60 @@ require_relative "resources/pipeline"
 require_relative "resources/jobs"
 
 module ReductoAI
+  # HTTP client for the Reducto document intelligence API.
+  #
+  # Provides access to all Reducto API endpoints through resource objects.
+  # Configure globally via {ReductoAI.configure} or pass parameters directly
+  # to the constructor.
+  #
+  # @example Using global configuration
+  #   ReductoAI.configure do |config|
+  #     config.api_key = ENV["REDUCTO_API_KEY"]
+  #   end
+  #
+  #   client = ReductoAI::Client.new
+  #   client.parse.sync(input: "https://example.com/doc.pdf")
+  #
+  # @example Using per-instance configuration
+  #   client = ReductoAI::Client.new(
+  #     api_key: "your-key",
+  #     read_timeout: 60
+  #   )
+  #
+  # @see Resources::Parse
+  # @see Resources::Extract
+  # @see Resources::Split
+  # @see Resources::Edit
+  # @see Resources::Pipeline
+  # @see Resources::Jobs
   class Client
-    attr_reader :api_key, :base_url, :logger, :open_timeout, :read_timeout
-
+    # @return [String] Reducto API key
+    attr_reader :api_key
+
+    # @return [String] Base URL for API requests
+    attr_reader :base_url
+
+    # @return [Logger] Logger instance for debugging
+    attr_reader :logger
+
+    # @return [Integer] Connection open timeout in seconds
+    attr_reader :open_timeout
+
+    # @return [Integer] Request read timeout in seconds
+    attr_reader :read_timeout
+
+    # Creates a new Reducto API client.
+    #
+    # @param api_key [String, nil] Reducto API key (defaults to global config)
+    # @param base_url [String, nil] API base URL (defaults to global config)
+    # @param logger [Logger, nil] Logger instance (defaults to global config)
+    # @param open_timeout [Integer, nil] Connection timeout in seconds (defaults to global config)
+    # @param read_timeout [Integer, nil] Read timeout in seconds (defaults to global config)
+    #
+    # @raise [ArgumentError] if api_key is missing or empty
+    #
+    # @example
+    #   client = ReductoAI::Client.new(api_key: "sk-...")
     def initialize(api_key: nil, base_url: nil, logger: nil, open_timeout: nil, read_timeout: nil)
       configuration = ReductoAI.config
 
@@ -26,30 +77,68 @@ module ReductoAI
       raise ArgumentError, "Missing API key for ReductoAI" if @api_key.to_s.empty?
     end
 
+    # Returns the Parse resource for document parsing operations.
+    #
+    # @return [Resources::Parse] parse operations interface
+    # @see Resources::Parse
     def parse
       @parse ||= Resources::Parse.new(self)
     end
 
+    # Returns the Extract resource for structured data extraction.
+    #
+    # @return [Resources::Extract] extract operations interface
+    # @see Resources::Extract
     def extract
       @extract ||= Resources::Extract.new(self)
     end
 
+    # Returns the Split resource for document splitting operations.
+    #
+    # @return [Resources::Split] split operations interface
+    # @see Resources::Split
     def split
       @split ||= Resources::Split.new(self)
     end
 
+    # Returns the Edit resource for PDF markup operations.
+    #
+    # @return [Resources::Edit] edit operations interface
+    # @see Resources::Edit
     def edit
       @edit ||= Resources::Edit.new(self)
     end
 
+    # Returns the Pipeline resource for multi-step workflows.
+    #
+    # @return [Resources::Pipeline] pipeline operations interface
+    # @see Resources::Pipeline
     def pipeline
       @pipeline ||= Resources::Pipeline.new(self)
     end
 
+    # Returns the Jobs resource for job management operations.
+    #
+    # @return [Resources::Jobs] jobs operations interface
+    # @see Resources::Jobs
     def jobs
       @jobs ||= Resources::Jobs.new(self)
     end
 
+    # Makes an HTTP request to the Reducto API.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete)
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] request body
+    # @param params [Hash, nil] query parameters
+    #
+    # @return [Hash] parsed JSON response
+    # @raise [AuthenticationError] on 401 responses
+    # @raise [ClientError] on 4xx responses
+    # @raise [ServerError] on 5xx responses
+    # @raise [NetworkError] on connection/timeout failures
+    #
+    # @api private
     def request(method, path, body: nil, params: nil)
       response = execute_request(method, path, body: body, params: params)
       log_response(method, path, response)
@@ -58,6 +147,13 @@ module ReductoAI
       raise NetworkError, "Network error: #{e.message}"
     end
 
+    # Convenience method for POST requests.
+    #
+    # @param path [String] API endpoint path
+    # @param body [Hash] request body
+    # @return [Hash] parsed JSON response
+    #
+    # @api private
     def post(path, body)
       request(:post, path, body: body)
     end

data/lib/reducto_ai/config.rb

@@ -3,10 +3,48 @@
 require "logger"
 
 module ReductoAI
+  # Configuration class for the ReductoAI client.
+  #
+  # Manages API credentials, timeouts, logging, and exception handling behavior.
+  # Configuration can be set via environment variables or through the global
+  # {ReductoAI.configure} method.
+  #
+  # @example Environment-based configuration
+  #   # Set these environment variables:
+  #   # REDUCTO_API_KEY=your-api-key
+  #   # REDUCTO_BASE_URL=https://platform.reducto.ai
+  #   # REDUCTO_OPEN_TIMEOUT=10
+  #   # REDUCTO_READ_TIMEOUT=60
+  #
+  #   config = ReductoAI::Config.new
+  #   config.api_key # => "your-api-key"
+  #
+  # @example Explicit configuration
+  #   ReductoAI.configure do |config|
+  #     config.api_key = "your-api-key"
+  #     config.logger = Rails.logger
+  #     config.open_timeout = 10
+  #   end
   class Config
-    attr_accessor :api_key, :base_url, :open_timeout, :read_timeout, :raise_exceptions
+    # @return [String, nil] Reducto API key (from REDUCTO_API_KEY env var)
+    attr_accessor :api_key
+
+    # @return [String] Base URL for Reducto API (default: https://platform.reducto.ai)
+    attr_accessor :base_url
+
+    # @return [Integer] Connection open timeout in seconds (default: 5)
+    attr_accessor :open_timeout
+
+    # @return [Integer] Request read timeout in seconds (default: 30)
+    attr_accessor :read_timeout
+
+    # @return [Boolean] Whether to raise exceptions on API errors (default: true)
+    attr_accessor :raise_exceptions
+
+    # @return [Logger] Logger instance for debugging
     attr_writer :logger
 
+    # Creates a new configuration instance with defaults from environment variables.
     def initialize
       @api_key = ENV.fetch("REDUCTO_API_KEY", nil)
       @base_url = ENV.fetch("REDUCTO_BASE_URL", "https://platform.reducto.ai")
@@ -15,12 +53,18 @@ module ReductoAI
       @raise_exceptions = true
     end
 
+    # Returns the logger instance.
+    #
+    # Defaults to `Rails.logger` if Rails is available, otherwise a stderr Logger.
+    #
+    # @return [Logger] the logger instance
     def logger
       @logger ||= (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) || Logger.new($stderr)
     end
 
     private
 
+    # @private
     def integer_or_default(key, default)
       Integer(ENV.fetch(key, default))
     rescue StandardError

data/lib/reducto_ai/engine.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 module ReductoAI
+  # Rails engine for automatic initialization in Rails applications.
+  #
+  # Provides Rails integration for the ReductoAI gem, enabling automatic
+  # loading and configuration within Rails applications.
+  #
+  # @api private
   if defined?(Rails)
     class Engine < ::Rails::Engine
       isolate_namespace ReductoAI

data/lib/reducto_ai/errors.rb

@@ -1,9 +1,33 @@
 # frozen_string_literal: true
 
 module ReductoAI
+  # Base error class for all Reducto API errors.
+  #
+  # All API-related exceptions inherit from this class and include
+  # HTTP status code and response body for debugging.
+  #
+  # @example Handling errors
+  #   begin
+  #     client.parse.sync(input: "invalid-url")
+  #   rescue ReductoAI::AuthenticationError => e
+  #     puts "Auth failed: #{e.message}"
+  #   rescue ReductoAI::ClientError => e
+  #     puts "Client error (#{e.status}): #{e.body}"
+  #   rescue ReductoAI::Error => e
+  #     puts "API error: #{e.message}"
+  #   end
   class Error < StandardError
-    attr_reader :status, :body
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status
 
+    # @return [Hash, String, nil] Response body
+    attr_reader :body
+
+    # Creates a new error instance.
+    #
+    # @param message [String, nil] Error message
+    # @param status [Integer, nil] HTTP status code
+    # @param body [Hash, String, nil] Response body
     def initialize(message = nil, status: nil, body: nil)
       super(message)
       @status = status
@@ -11,8 +35,46 @@ module ReductoAI
     end
   end
 
+  # Raised on 401 Unauthorized responses.
+  #
+  # Indicates invalid or missing API key.
+  #
+  # @example
+  #   # Raised when API key is invalid
+  #   client = ReductoAI::Client.new(api_key: "invalid-key")
+  #   client.parse.sync(input: "https://example.com/doc.pdf")
+  #   # => ReductoAI::AuthenticationError: Unauthorized (401): check API key
   class AuthenticationError < Error; end
+
+  # Raised on 4xx client errors (400, 404, 422).
+  #
+  # Indicates invalid request parameters, missing resources, or
+  # validation failures.
+  #
+  # @example
+  #   # Raised when input is invalid
+  #   client.parse.sync(input: "not-a-valid-url")
+  #   # => ReductoAI::ClientError: HTTP 400: Invalid input URL
   class ClientError < Error; end
+
+  # Raised on 5xx server errors.
+  #
+  # Indicates Reducto API internal errors or temporary failures.
+  #
+  # @example
+  #   # Raised on API server issues
+  #   client.parse.sync(input: "https://example.com/doc.pdf")
+  #   # => ReductoAI::ServerError: HTTP 500: Internal server error
   class ServerError < Error; end
+
+  # Raised on network connection or timeout failures.
+  #
+  # Indicates network issues, DNS failures, or timeout exceeded.
+  #
+  # @example
+  #   # Raised when request times out
+  #   client = ReductoAI::Client.new(read_timeout: 1)
+  #   client.parse.sync(input: "https://example.com/large-doc.pdf")
+  #   # => ReductoAI::NetworkError: Network error: execution expired
   class NetworkError < Error; end
 end

data/lib/reducto_ai/resources/edit.rb

@@ -2,11 +2,52 @@
 
 module ReductoAI
   module Resources
+    # Edit resource for PDF markup and annotation operations.
+    #
+    # Generates marked-up PDFs with highlights, annotations, or redactions
+    # based on natural language instructions.
+    #
+    # @example Highlight key terms
+    #   client = ReductoAI::Client.new
+    #   result = client.edit.sync(
+    #     input: "https://example.com/contract.pdf",
+    #     instructions: "Highlight all mentions of payment terms and deadlines"
+    #   )
+    #   marked_pdf_url = result["result"]["document_url"]
+    #
+    # @note Edit operations consume credits based on document size and
+    #   instruction complexity.
     class Edit
+      # @param client [Client] the Reducto API client
+      # @api private
       def initialize(client)
         @client = client
       end
 
+      # Generates a marked-up PDF synchronously.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param instructions [String] Natural language editing instructions
+      #   (e.g., "Highlight all dates", "Redact personal information")
+      # @param options [Hash] Additional editing options
+      #
+      # @return [Hash] Edit results with keys:
+      #   * "job_id" [String] - Job identifier
+      #   * "status" [String] - Job status ("succeeded")
+      #   * "result" [Hash] - Contains "document_url" with marked PDF
+      #   * "usage" [Hash] - Credit usage details
+      #
+      # @raise [ArgumentError] if input or instructions are nil/empty
+      # @raise [ClientError] if instructions are invalid
+      # @raise [ServerError] if editing fails
+      #
+      # @example Redact sensitive info
+      #   result = client.edit.sync(
+      #     input: "https://example.com/report.pdf",
+      #     instructions: "Redact all social security numbers"
+      #   )
+      #
+      # @see https://docs.reducto.ai/api-reference/edit Reducto Edit API
       def sync(input:, instructions:, **options)
         raise ArgumentError, "input is required" if input.nil?
         if instructions.nil? || (instructions.respond_to?(:empty?) && instructions.empty?)
@@ -17,6 +58,30 @@ module ReductoAI
         @client.post("/edit", payload)
       end
 
+      # Generates a marked-up PDF asynchronously.
+      #
+      # Returns immediately with a job_id. Poll with {Jobs#retrieve} to get results.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param instructions [String] Natural language editing instructions
+      # @param async [Boolean, nil] Async mode flag
+      # @param options [Hash] Additional editing options
+      #
+      # @return [Hash] Job status with keys:
+      #   * "job_id" [String] - Job identifier for polling
+      #   * "status" [String] - Initial status ("processing")
+      #
+      # @raise [ArgumentError] if input or instructions are nil/empty
+      #
+      # @example
+      #   job = client.edit.async(
+      #     input: "https://example.com/legal-doc.pdf",
+      #     instructions: "Highlight all liability clauses"
+      #   )
+      #   job_id = job["job_id"]
+      #
+      # @see Jobs#retrieve
+      # @see https://docs.reducto.ai/api-reference/edit-async
       def async(input:, instructions:, async: nil, **options)
         raise ArgumentError, "input is required" if input.nil?
         if instructions.nil? || (instructions.respond_to?(:empty?) && instructions.empty?)
@@ -31,11 +96,13 @@ module ReductoAI
 
       private
 
+      # @private
       def build_payload(input, instructions, options)
         document_url = normalize_input(input)
         { document_url: document_url, edit_instructions: instructions, **options }.compact
       end
 
+      # @private
       def normalize_input(input)
         return input unless input.is_a?(Hash)
 

data/lib/reducto_ai/resources/extract.rb

@@ -2,11 +2,62 @@
 
 module ReductoAI
   module Resources
+    # Extract resource for structured data extraction.
+    #
+    # Extracts specific information from documents based on a schema or instructions.
+    # Returns structured JSON data matching the provided schema.
+    #
+    # @example Extract with schema
+    #   client = ReductoAI::Client.new
+    #   schema = {
+    #     invoice_number: "string",
+    #     total_amount: "number",
+    #     line_items: ["object"]
+    #   }
+    #
+    #   result = client.extract.sync(
+    #     input: "https://example.com/invoice.pdf",
+    #     instructions: schema
+    #   )
+    #   puts result["result"]
+    #
+    # @note Extraction operations consume credits based on document complexity
+    #   and schema size.
     class Extract
+      # @param client [Client] the Reducto API client
+      # @api private
       def initialize(client)
         @client = client
       end
 
+      # Extracts structured data from a document synchronously.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param instructions [Hash, String] Extraction schema or instructions.
+      #   Can be a simple hash (auto-wrapped as `{ schema: ... }`) or
+      #   a full instructions hash with a :schema key.
+      # @param options [Hash] Additional extraction options
+      #
+      # @return [Hash] Extraction results with keys:
+      #   * "job_id" [String] - Job identifier
+      #   * "status" [String] - Job status ("succeeded")
+      #   * "result" [Hash] - Extracted data matching schema
+      #   * "usage" [Hash] - Credit usage details
+      #
+      # @raise [ArgumentError] if input or instructions are nil/empty
+      # @raise [ClientError] if schema is invalid
+      # @raise [ServerError] if extraction fails
+      #
+      # @example Extract invoice data
+      #   result = client.extract.sync(
+      #     input: "https://example.com/invoice.pdf",
+      #     instructions: {
+      #       invoice_number: "string",
+      #       total: "number"
+      #     }
+      #   )
+      #
+      # @see https://docs.reducto.ai/api-reference/extract Reducto Extract API
       def sync(input:, instructions:, **options)
         raise ArgumentError, "input is required" if input.nil?
         if instructions.nil? || (instructions.respond_to?(:empty?) && instructions.empty?)
@@ -17,6 +68,30 @@ module ReductoAI
         @client.post("/extract", payload)
       end
 
+      # Extracts structured data from a document asynchronously.
+      #
+      # Returns immediately with a job_id. Poll with {Jobs#retrieve} to get results.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param instructions [Hash, String] Extraction schema (same as {#sync})
+      # @param async [Boolean, nil] Async mode flag
+      # @param options [Hash] Additional extraction options
+      #
+      # @return [Hash] Job status with keys:
+      #   * "job_id" [String] - Job identifier for polling
+      #   * "status" [String] - Initial status ("processing")
+      #
+      # @raise [ArgumentError] if input or instructions are nil/empty
+      #
+      # @example Start async extraction
+      #   job = client.extract.async(
+      #     input: "https://example.com/contract.pdf",
+      #     instructions: { parties: ["string"], terms: "string" }
+      #   )
+      #   job_id = job["job_id"]
+      #
+      # @see Jobs#retrieve
+      # @see https://docs.reducto.ai/api-reference/extract-async
       def async(input:, instructions:, async: nil, **options)
         raise ArgumentError, "input is required" if input.nil?
         if instructions.nil? || (instructions.respond_to?(:empty?) && instructions.empty?)
@@ -31,6 +106,7 @@ module ReductoAI
 
       private
 
+      # @private
       def build_payload(input, instructions, options)
         normalized_input = normalize_input(input)
         normalized_instructions = normalize_instructions(instructions)
@@ -38,12 +114,14 @@ module ReductoAI
         { input: normalized_input, instructions: normalized_instructions, **options }.compact
       end
 
+      # @private
       def normalize_input(input)
         return input unless input.is_a?(Hash)
 
         input[:url] || input["url"] || input
       end
 
+      # @private
       def normalize_instructions(instructions)
         return { schema: instructions } unless instructions.is_a?(Hash)
         return instructions if instructions.key?(:schema) || instructions.key?("schema")

data/lib/reducto_ai/resources/jobs.rb

@@ -2,32 +2,140 @@
 
 module ReductoAI
   module Resources
+    # Jobs resource for job management and file upload operations.
+    #
+    # Provides methods to list, retrieve, cancel jobs, upload files,
+    # and configure webhooks for async job notifications.
+    #
+    # @example Poll for job completion
+    #   client = ReductoAI::Client.new
+    #   job = client.parse.async(input: "https://example.com/doc.pdf")
+    #
+    #   loop do
+    #     status = client.jobs.retrieve(job_id: job["job_id"])
+    #     break if status["status"] == "succeeded"
+    #     sleep 2
+    #   end
+    #   result = status["result"]
+    #
+    # @example Upload a local file
+    #   upload_result = client.jobs.upload(file: "/path/to/document.pdf")
+    #   document_url = upload_result["url"]
+    #   client.parse.sync(input: document_url)
     class Jobs
+      # @param client [Client] the Reducto API client
+      # @api private
       def initialize(client)
         @client = client
       end
 
+      # Returns API version information.
+      #
+      # @return [Hash] Version details
+      #
+      # @example
+      #   version_info = client.jobs.version
+      #   puts version_info["version"]
       def version
         @client.request(:get, "/version")
       end
 
+      # Lists jobs with optional filtering.
+      #
+      # @param options [Hash] Query parameters for filtering
+      # @option options [String] :status Filter by job status ("processing", "succeeded", "failed")
+      # @option options [Integer] :limit Maximum number of jobs to return
+      # @option options [Integer] :offset Pagination offset
+      #
+      # @return [Hash] Job list with pagination metadata
+      #
+      # @example List recent jobs
+      #   jobs = client.jobs.list(limit: 10)
+      #   jobs["jobs"].each { |job| puts job["job_id"] }
+      #
+      # @example Filter by status
+      #   failed_jobs = client.jobs.list(status: "failed")
+      #
+      # @see https://docs.reducto.ai/api-reference/jobs
       def list(**options)
         params = options.compact
         @client.request(:get, "/jobs", params: params)
       end
 
+      # Cancels a running async job.
+      #
+      # @param job_id [String] Job identifier to cancel
+      #
+      # @return [Hash] Cancellation result
+      #
+      # @raise [ArgumentError] if job_id is nil or empty
+      # @raise [ClientError] if job doesn't exist or is not cancellable
+      #
+      # @example
+      #   client.jobs.cancel(job_id: "job_abc123")
+      #
+      # @see https://docs.reducto.ai/api-reference/cancel
       def cancel(job_id:)
         raise ArgumentError, "job_id is required" if job_id.nil? || job_id.to_s.strip.empty?
 
         @client.request(:post, "/cancel/#{job_id}")
       end
 
+      # Retrieves job status and results.
+      #
+      # Used to poll async jobs until completion. Completed jobs include
+      # full results in the response.
+      #
+      # @param job_id [String] Job identifier to retrieve
+      #
+      # @return [Hash] Job status with keys:
+      #   * "job_id" [String] - Job identifier
+      #   * "status" [String] - Current status ("processing", "succeeded", "failed")
+      #   * "result" [Hash] - Results (only present when status is "succeeded")
+      #   * "error" [String] - Error message (only present when status is "failed")
+      #
+      # @raise [ArgumentError] if job_id is nil or empty
+      # @raise [ClientError] if job doesn't exist
+      #
+      # @example Poll until complete
+      #   loop do
+      #     status = client.jobs.retrieve(job_id: job_id)
+      #     break if %w[succeeded failed].include?(status["status"])
+      #     sleep 2
+      #   end
+      #
+      # @see https://docs.reducto.ai/api-reference/job
       def retrieve(job_id:)
         raise ArgumentError, "job_id is required" if job_id.nil? || job_id.to_s.strip.empty?
 
         @client.request(:get, "/job/#{job_id}")
       end
 
+      # Uploads a local file to Reducto's storage.
+      #
+      # Returns a URL that can be used as input for other API operations.
+      # Useful when processing local files instead of publicly accessible URLs.
+      #
+      # @param file [String, File, IO] File path or file-like object to upload
+      # @param extension [String, nil] File extension override (e.g., "pdf", "png")
+      #
+      # @return [Hash] Upload result with keys:
+      #   * "url" [String] - Uploaded file URL for use in API calls
+      #   * "job_id" [String] - Upload job identifier
+      #
+      # @raise [ArgumentError] if file is nil or path doesn't exist
+      # @raise [ServerError] if upload fails
+      #
+      # @example Upload local PDF
+      #   upload = client.jobs.upload(file: "/path/to/invoice.pdf")
+      #   result = client.parse.sync(input: upload["url"])
+      #
+      # @example Upload with File object
+      #   File.open("/path/to/doc.pdf", "rb") do |f|
+      #     upload = client.jobs.upload(file: f, extension: "pdf")
+      #   end
+      #
+      # @see https://docs.reducto.ai/api-reference/upload
       def upload(file:, extension: nil)
         raise ArgumentError, "file is required" if file.nil?
 
@@ -39,12 +147,21 @@ module ReductoAI
         @client.request(:post, "/upload", body: body, params: params)
       end
 
+      # Configures webhook notifications for async jobs.
+      #
+      # @return [Hash] Webhook configuration result
+      #
+      # @example
+      #   client.jobs.configure_webhook
+      #
+      # @see https://docs.reducto.ai/api-reference/configure-webhook
       def configure_webhook
         @client.request(:post, "/configure_webhook")
       end
 
       private
 
+      # @private
       def build_upload_io(file)
         if file.is_a?(String)
           raise ArgumentError, "file path does not exist" unless File.exist?(file)

data/lib/reducto_ai/resources/parse.rb

@@ -1,12 +1,68 @@
 # frozen_string_literal: true
 
 module ReductoAI
+  # Resource classes for Reducto API endpoints.
+  #
+  # Each resource class corresponds to a set of related API operations
+  # (Parse, Extract, Split, Edit, Pipeline, Jobs).
   module Resources
+    # Parse resource for document parsing operations.
+    #
+    # Converts documents (PDFs, images, etc.) into structured formats like
+    # Markdown, JSON, or HTML. Supports both synchronous and asynchronous modes.
+    #
+    # @example Synchronous parsing
+    #   client = ReductoAI::Client.new
+    #   result = client.parse.sync(
+    #     input: "https://example.com/document.pdf",
+    #     output_formats: { markdown: true }
+    #   )
+    #   puts result["result"]["markdown"]
+    #
+    # @example Asynchronous parsing
+    #   job = client.parse.async(
+    #     input: { url: "https://example.com/large-doc.pdf" },
+    #     async: true
+    #   )
+    #   job_id = job["job_id"]
+    #
+    # @note Each parse operation consumes credits based on document complexity.
+    #   See Reducto documentation for pricing details.
     class Parse
+      # @param client [Client] the Reducto API client
+      # @api private
       def initialize(client)
         @client = client
       end
 
+      # Parses a document synchronously.
+      #
+      # Blocks until parsing completes and returns the full result.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param options [Hash] Additional parsing options
+      # @option options [Hash] :output_formats Output format configuration
+      #   (e.g., `{ markdown: true, html: true }`)
+      # @option options [String] :mode Processing mode ("ocr", "auto")
+      # @option options [Boolean] :use_cache Whether to use cached results
+      #
+      # @return [Hash] Parsed document with keys:
+      #   * "job_id" [String] - Job identifier
+      #   * "status" [String] - Job status ("succeeded")
+      #   * "result" [Hash] - Parsed content by format (e.g., "markdown", "html")
+      #   * "usage" [Hash] - Credit usage details
+      #
+      # @raise [ArgumentError] if input is nil
+      # @raise [ClientError] if document URL is invalid or inaccessible
+      # @raise [ServerError] if parsing fails
+      #
+      # @example Parse to markdown
+      #   result = client.parse.sync(
+      #     input: "https://example.com/doc.pdf",
+      #     output_formats: { markdown: true }
+      #   )
+      #
+      # @see https://docs.reducto.ai/api-reference/parse Reducto Parse API
       def sync(input:, **options)
         raise ArgumentError, "input is required" if input.nil?
 
@@ -15,6 +71,33 @@ module ReductoAI
         @client.post("/parse", payload)
       end
 
+      # Parses a document asynchronously.
+      #
+      # Returns immediately with a job_id. Poll with {Jobs#retrieve} to get results.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param async [Boolean, nil] Async mode flag (defaults to true if not provided)
+      # @param options [Hash] Additional parsing options (same as {#sync})
+      #
+      # @return [Hash] Job status with keys:
+      #   * "job_id" [String] - Job identifier for polling
+      #   * "status" [String] - Initial status ("processing")
+      #
+      # @raise [ArgumentError] if input is nil
+      #
+      # @example Start async parse and poll
+      #   job = client.parse.async(input: "https://example.com/doc.pdf")
+      #   job_id = job["job_id"]
+      #
+      #   # Poll for completion
+      #   loop do
+      #     status = client.jobs.retrieve(job_id: job_id)
+      #     break if status["status"] == "succeeded"
+      #     sleep 2
+      #   end
+      #
+      # @see Jobs#retrieve
+      # @see https://docs.reducto.ai/api-reference/parse-async Reducto Async Parse
       def async(input:, async: nil, **options)
         raise ArgumentError, "input is required" if input.nil?
 
@@ -28,6 +111,7 @@ module ReductoAI
 
       private
 
+      # @private
       def normalize_input(input)
         return input unless input.is_a?(Hash)
 

data/lib/reducto_ai/resources/pipeline.rb

@@ -2,11 +2,58 @@
 
 module ReductoAI
   module Resources
+    # Pipeline resource for multi-step document processing workflows.
+    #
+    # Orchestrates multiple Reducto operations (parse, extract, split, edit)
+    # in a single request, with outputs from earlier steps feeding into later ones.
+    #
+    # @example Parse then extract
+    #   client = ReductoAI::Client.new
+    #   result = client.pipeline.sync(
+    #     input: "https://example.com/invoice.pdf",
+    #     steps: [
+    #       { type: "parse", output_formats: { markdown: true } },
+    #       { type: "extract", instructions: { total: "number", date: "string" } }
+    #     ]
+    #   )
+    #   extracted_data = result["result"]["steps"][1]["result"]
+    #
+    # @note Pipeline operations consume credits based on all steps executed.
     class Pipeline
+      # @param client [Client] the Reducto API client
+      # @api private
       def initialize(client)
         @client = client
       end
 
+      # Executes a multi-step pipeline synchronously.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param steps [Array<Hash>] Array of step configurations. Each step
+      #   must have a :type key ("parse", "extract", "split", "edit") and
+      #   type-specific options.
+      # @param options [Hash] Additional pipeline options
+      #
+      # @return [Hash] Pipeline results with keys:
+      #   * "job_id" [String] - Job identifier
+      #   * "status" [String] - Job status ("succeeded")
+      #   * "result" [Hash] - Contains "steps" array with each step's result
+      #   * "usage" [Hash] - Credit usage details
+      #
+      # @raise [ArgumentError] if input or steps are nil/empty
+      # @raise [ClientError] if step configuration is invalid
+      # @raise [ServerError] if pipeline execution fails
+      #
+      # @example Parse and extract in one request
+      #   result = client.pipeline.sync(
+      #     input: "https://example.com/form.pdf",
+      #     steps: [
+      #       { type: "parse" },
+      #       { type: "extract", instructions: { name: "string", amount: "number" } }
+      #     ]
+      #   )
+      #
+      # @see https://docs.reducto.ai/api-reference/pipeline Reducto Pipeline API
       def sync(input:, steps:, **options)
         raise ArgumentError, "input is required" if input.nil?
         raise ArgumentError, "steps are required" if steps.nil? || (steps.respond_to?(:empty?) && steps.empty?)
@@ -15,6 +62,33 @@ module ReductoAI
         @client.post("/pipeline", payload)
       end
 
+      # Executes a multi-step pipeline asynchronously.
+      #
+      # Returns immediately with a job_id. Poll with {Jobs#retrieve} to get results.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param steps [Array<Hash>] Array of step configurations (same as {#sync})
+      # @param async [Boolean, nil] Async mode flag
+      # @param options [Hash] Additional pipeline options
+      #
+      # @return [Hash] Job status with keys:
+      #   * "job_id" [String] - Job identifier for polling
+      #   * "status" [String] - Initial status ("processing")
+      #
+      # @raise [ArgumentError] if input or steps are nil/empty
+      #
+      # @example
+      #   job = client.pipeline.async(
+      #     input: "https://example.com/complex-doc.pdf",
+      #     steps: [
+      #       { type: "split" },
+      #       { type: "parse", output_formats: { markdown: true } }
+      #     ]
+      #   )
+      #   job_id = job["job_id"]
+      #
+      # @see Jobs#retrieve
+      # @see https://docs.reducto.ai/api-reference/pipeline-async
       def async(input:, steps:, async: nil, **options)
         raise ArgumentError, "input is required" if input.nil?
         raise ArgumentError, "steps are required" if steps.nil? || (steps.respond_to?(:empty?) && steps.empty?)

data/lib/reducto_ai/resources/split.rb

@@ -2,11 +2,49 @@
 
 module ReductoAI
   module Resources
+    # Split resource for document splitting operations.
+    #
+    # Divides documents into logical sections based on content structure,
+    # returning page ranges and metadata for each section.
+    #
+    # @example Split document into sections
+    #   client = ReductoAI::Client.new
+    #   result = client.split.sync(
+    #     input: "https://example.com/report.pdf"
+    #   )
+    #   result["result"]["sections"].each do |section|
+    #     puts "#{section['title']}: pages #{section['start_page']}-#{section['end_page']}"
+    #   end
+    #
+    # @note Split operations consume credits based on document size.
     class Split
+      # @param client [Client] the Reducto API client
+      # @api private
       def initialize(client)
         @client = client
       end
 
+      # Splits a document into sections synchronously.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param options [Hash] Additional splitting options
+      #
+      # @return [Hash] Split results with keys:
+      #   * "job_id" [String] - Job identifier
+      #   * "status" [String] - Job status ("succeeded")
+      #   * "result" [Hash] - Sections with page ranges
+      #   * "usage" [Hash] - Credit usage details
+      #
+      # @raise [ArgumentError] if input is nil
+      # @raise [ClientError] if document URL is invalid
+      # @raise [ServerError] if splitting fails
+      #
+      # @example
+      #   result = client.split.sync(
+      #     input: "https://example.com/document.pdf"
+      #   )
+      #
+      # @see https://docs.reducto.ai/api-reference/split Reducto Split API
       def sync(input:, **options)
         raise ArgumentError, "input is required" if input.nil?
 
@@ -15,6 +53,28 @@ module ReductoAI
         @client.post("/split", payload)
       end
 
+      # Splits a document into sections asynchronously.
+      #
+      # Returns immediately with a job_id. Poll with {Jobs#retrieve} to get results.
+      #
+      # @param input [String, Hash] Document URL or hash with :url key
+      # @param async [Boolean, nil] Async mode flag
+      # @param options [Hash] Additional splitting options
+      #
+      # @return [Hash] Job status with keys:
+      #   * "job_id" [String] - Job identifier for polling
+      #   * "status" [String] - Initial status ("processing")
+      #
+      # @raise [ArgumentError] if input is nil
+      #
+      # @example
+      #   job = client.split.async(
+      #     input: "https://example.com/book.pdf"
+      #   )
+      #   job_id = job["job_id"]
+      #
+      # @see Jobs#retrieve
+      # @see https://docs.reducto.ai/api-reference/split-async
       def async(input:, async: nil, **options)
         raise ArgumentError, "input is required" if input.nil?
 
@@ -28,6 +88,7 @@ module ReductoAI
 
       private
 
+      # @private
       def normalize_input(input)
         return input unless input.is_a?(Hash)
 

data/lib/reducto_ai/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module ReductoAI
-  VERSION = "0.1.0"
+  # Gem version
+  VERSION = "0.1.1"
 end

data/lib/reducto_ai.rb

@@ -6,16 +6,53 @@ require_relative "reducto_ai/errors"
 require_relative "reducto_ai/client"
 require_relative "reducto_ai/engine"
 
+# Main namespace for the ReductoAI gem.
+#
+# Provides global configuration management for the Reducto API client.
+# Use {.configure} to set API credentials and options, then create a {Client}
+# instance to interact with the Reducto document intelligence API.
+#
+# @example Basic configuration
+#   ReductoAI.configure do |config|
+#     config.api_key = ENV.fetch("REDUCTO_API_KEY")
+#     config.base_url = "https://platform.reducto.ai"
+#   end
+#
+#   client = ReductoAI::Client.new
+#   result = client.parse.sync(input: "https://example.com/document.pdf")
+#
+# @see Client
+# @see Config
 module ReductoAI
   class << self
+    # Returns the global configuration instance.
+    #
+    # @return [Config] the current configuration object
     def config
       @config ||= Config.new
     end
 
+    # Configures the ReductoAI client globally.
+    #
+    # @example Set API key and timeouts
+    #   ReductoAI.configure do |config|
+    #     config.api_key = "your-api-key"
+    #     config.open_timeout = 10
+    #     config.read_timeout = 60
+    #   end
+    #
+    # @yield [config] Gives the configuration object to the block
+    # @yieldparam config [Config] the configuration instance to modify
+    # @return [void]
     def configure
       yield(config)
     end
 
+    # Resets the global configuration to nil.
+    #
+    # Primarily used for testing to ensure a clean configuration state.
+    #
+    # @return [void]
     def reset_configuration!
       @config = nil
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: reducto_ai
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - dpaluy
@@ -44,8 +44,12 @@ email:
 - dpaluy@users.noreply.github.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
@@ -69,8 +73,10 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/dpaluy/reducto_ai
+  documentation_uri: https://rubydoc.info/gems/reducto_ai
   source_code_uri: https://github.com/dpaluy/reducto_ai
   changelog_uri: https://github.com/dpaluy/reducto_ai/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dpaluy/reducto_ai/issues
 rdoc_options: []
 require_paths:
 - lib
@@ -85,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client for the Reducto document intelligence API.
 test_files: []