Class: ReductoAI::Resources::Jobs

Inherits:
Object
  • Object
show all
Includes:
JobStatus
Defined in:
lib/reducto_ai/resources/jobs.rb

Overview

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.

Examples:

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 client.jobs.completed?(status)
  sleep 2
end
result = status["result"]

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)

Constant Summary

Constants included from JobStatus

JobStatus::STATUS_MAP

Instance Method Summary collapse

Methods included from JobStatus

#completed?, #completing?, #failed?, #in_progress?, #normalize_status, #pending?, #terminal?

Constructor Details

#initialize(client) ⇒ Jobs

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Jobs.

Parameters:

  • client (Client) —

    the Reducto API client



30
31
32
 
# File 'lib/reducto_ai/resources/jobs.rb', line 30

def initialize(client)
  @client = client
end

Instance Method Details

#cancel(job_id:) ⇒ Hash

Cancels a running async job.

Examples:

client.jobs.cancel(job_id: "job_abc123")

Parameters:

  • job_id (String) —

    Job identifier to cancel

Returns:

  • (Hash) —

    Cancellation result

Raises:

  • (ArgumentError) —

    if job_id is nil or empty

  • (ClientError) —

    if job doesn't exist or is not cancellable

See Also:



81
82
83
84
85
 
# File 'lib/reducto_ai/resources/jobs.rb', line 81

def cancel(job_id:)
  validate_job_id!(job_id)

  @client.request(:post, "/cancel/#{job_id}")
end

#configure_webhook ⇒ String

Configures webhook notifications for async jobs.

Examples:

client.jobs.configure_webhook

Returns:

  • (String) —

    Svix portal URL for webhook configuration

See Also:



161
162
163
164
 
# File 'lib/reducto_ai/resources/jobs.rb', line 161

def configure_webhook
  response = @client.request(:post, "/configure_webhook")
  normalize_webhook_portal_url(response)
end

#list(**options) ⇒ Hash

Lists jobs with optional filtering.

Examples:

List recent jobs

jobs = client.jobs.list(limit: 10)
jobs["jobs"].each { |job| puts job["job_id"] }

Filter by status

failed_jobs = client.jobs.list(status: "failed")

Parameters:

  • options (Hash) —

    Query parameters for filtering

Options Hash (**options):

  • :status (String) —

    Filter by raw job status returned by Reducto

  • :limit (Integer) —

    Maximum number of jobs to return

  • :offset (Integer) —

    Pagination offset

Returns:

  • (Hash) —

    Job list with pagination metadata

See Also:



62
63
64
65
66
 
# File 'lib/reducto_ai/resources/jobs.rb', line 62

def list(**options)
  params = options.compact
  response = @client.request(:get, "/jobs", params: params)
  normalize_job_list(response)
end

#retrieve(job_id:) ⇒ Hash

Retrieves job status and results.

Used to poll async jobs until completion. Completed jobs include full results in the response.

Examples:

Poll until complete

loop do
  status = client.jobs.retrieve(job_id: job_id)
  break if client.jobs.terminal?(status)
  sleep 2
end

Parameters:

  • job_id (String) —

    Job identifier to retrieve

Returns:

  • (Hash) —

    Job status with keys:

    • "job_id" [String] - Job identifier
    • "status" [String] - Current raw Reducto status (for example "Pending", "Completed", "Failed")
    • "result" [Hash] - Results (only present when the job completed)
    • "error" [String] - Error message (only present when the job failed)

Raises:

  • (ArgumentError) —

    if job_id is nil or empty

  • (ClientError) —

    if job doesn't exist

See Also:



111
112
113
114
115
 
# File 'lib/reducto_ai/resources/jobs.rb', line 111

def retrieve(job_id:)
  validate_job_id!(job_id)

  @client.request(:get, "/job/#{job_id}")
end

#upload(file:, extension: nil) ⇒ Hash

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.

Examples:

Upload local PDF

upload = client.jobs.upload(file: "/path/to/invoice.pdf")
result = client.parse.sync(input: upload["url"])

Upload with File object

File.open("/path/to/doc.pdf", "rb") do |f|
  upload = client.jobs.upload(file: f, extension: "pdf")
end

Parameters:

  • file (String, File, IO) —

    File path or file-like object to upload

  • extension (String, nil) (defaults to: nil) —

    File extension override (e.g., "pdf", "png")

Returns:

  • (Hash) —

    Upload result with keys:

    • "url" [String] - Uploaded file URL for use in API calls
    • "job_id" [String] - Upload job identifier

Raises:

  • (ArgumentError) —

    if file is nil or path doesn't exist

  • (ServerError) —

    if upload fails

See Also:



142
143
144
145
146
147
148
149
150
151
 
# File 'lib/reducto_ai/resources/jobs.rb', line 142

def upload(file:, extension: nil)
  raise ArgumentError, "file is required" if file.nil?

  upload_io = build_upload_io(file)
  body = { file: upload_io }
  params = {}
  params[:extension] = extension unless extension.nil?

  @client.request(:post, "/upload", body: body, params: params)
end

#version ⇒ Hash

Returns API version information.

Examples:

version_info = client.jobs.version
puts version_info["version"]

Returns:

  • (Hash) —

    Version details



41
42
43
 
# File 'lib/reducto_ai/resources/jobs.rb', line 41

def version
  @client.request(:get, "/version")
end

#wait(job_id:, interval: 2, timeout: nil, max_attempts: nil, raise_on_failure: true) ⇒ Object 



166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/reducto_ai/resources/jobs.rb', line 166

def wait(job_id:, interval: 2, timeout: nil, max_attempts: nil, raise_on_failure: true)
  validate_wait_arguments!(interval: interval, timeout: timeout, max_attempts: max_attempts)

  started_at = monotonic_time
  attempts = 0

  loop do
    attempts += 1
    response = retrieve(job_id: job_id)
    terminal_response = resolve_terminal_response(job_id, response, raise_on_failure)
    return terminal_response if terminal_response

    raise_if_attempt_limit_reached!(job_id, response, attempts, max_attempts)
    raise_if_timeout_exceeded!(job_id, response, started_at, timeout)
    sleep(interval)
  end
end