Jobs

15. Jobs#

15.1. Job states#

A job moves through the following states, exposed as strings on job.status and as constants on JobStatus:

State

Constant

Meaning

pending

JobStatus.PENDING

Created but not yet started.

running

JobStatus.RUNNING

The pipeline is executing.

done

JobStatus.DONE

Completed successfully; job.result holds the issue list.

failed

JobStatus.FAILED

An exception occurred; job.error holds the message.

cancelled

JobStatus.CANCELLED

Stopped in response to job.cancel().

The valid transitions are:

pending → running → done → failed → cancelled

15.2. Waiting for results#

Method

Behaviour

job.wait_sync(timeout=None)

Blocks the calling thread until the job completes, fails, or the timeout expires, then returns job.result.

await job.wait(timeout=None)

The async equivalent; suspends the coroutine instead of blocking the thread.

Both raise RuntimeError if the job ended in the failed or cancelled state, so wrap the call when failure is possible:

try:
    result = job.wait_sync(timeout=300)
except RuntimeError as exc:
    print("Review did not complete:", exc)

Note

Timeout behaviour If the timeout elapses before the job finishes, the wait returns rather than raising, but the result will reflect the job’s current (possibly unfinished) state. Check job.status if you need to distinguish “still running” from “done” after a timeout.

15.3. Cancelling a job#

Call job.cancel() to request cancellation. This sets an internal flag; the running pipeline observes it and stops at the next agent boundary, after which the job transitions to cancelled. Cancellation is therefore cooperative — it does not interrupt an in-flight LLM call mid-stream, but it prevents the next agent from starting.

job = client.submit(large_metadata)

# ... later, decide to stop ...
job.cancel()

# the job will settle into the 'cancelled' state at the next boundary

15.4. Inspecting and cleaning up jobs#

Each Job carries everything you need to inspect its outcome without re-running:

  • job.job_id — the unique identifier (a UUID string).

  • job.status — the current state.

  • job.result — the list of detected issues once done.

  • job.error — the error message if the job failed.

Because the client keeps a registry of jobs, call cleanup_jobs() periodically in long-running services to release the memory held by completed jobs.

Contents