Running AI Work in the Background with FastAPI and Persistent Jobs

Distinguish HTTP handling from durable work

FastAPI can accept a request quickly and return a job identifier. The durable part is the database record, queue or claim mechanism, worker lifecycle and saved result. FastAPI BackgroundTasks is useful for some work after a response, but it does not itself provide a persistent distributed job queue.

The development record describes artifact jobs and task activity for indexing, organisation and Q&A. An effective implementation has explicit queued, running, completed and failed states, with stale or cancelled outcomes where appropriate. Users need to recover the result after navigation rather than depending on a single open connection.

Deduplicate an explicit operation

A retry and a genuinely new analysis need different identities. The illustrative key below includes the case, requested operation and relevant versions. In production, enforce uniqueness transactionally and include all inputs that affect the result, including a question hash for Q&A.

import hashlib
import json

def operation_key(case_id, operation, source_revision, config_version):
    payload = [case_id, operation, source_revision, config_version]
    encoded = json.dumps(payload, separators=(",", ":")).encode()
    return hashlib.sha256(encoded).hexdigest()

assert operation_key("demo", "index", 4, "v1") == operation_key("demo", "index", 4, "v1")
assert operation_key("demo", "index", 4, "v1") != operation_key("demo", "index", 5, "v1")

Plan for a worker that stops halfway through

A lease or claim can expire after a crash, but a retry must not blindly repeat an already completed paid call. Persist stage outcomes, provider identifiers where available, bounded retry decisions and the final artifact. Exactly-once execution is not guaranteed merely by adding a unique job key.

Test a browser refresh during work, duplicate submissions, a worker restart and evidence changing before completion. Report meaningful progress such as prepared sources or completed stages. A percentage that advances while nothing durable has happened makes the interface look reassuring while making failures harder to understand.