Adapter axes

z4j adapters are organized along three independent axes. They compose freely: any framework × any engine × any scheduler is supported.

Axis 1: Framework

A framework adapter knows how your process boots and how to read its settings.

Package	Covers
z4j-django	Django 4.2+, no adapter cap. Reads settings.Z4J. Uses app-config for agent lifecycle.
z4j-flask	Flask 2.3.3+. Z4J(app), or Z4J() then init_app(app) in an app factory; reads app.config or the environment.
z4j-fastapi	FastAPI 0.109.1+. Z4JAgent context manager in the lifespan.
z4j-bare	Any Python 3.11+ process. Direct Agent(...) usage. Foundation of all others.

All framework adapters delegate the actual agent runtime to z4j-bare.

Axis 2: Engine

An engine adapter knows how your queue enqueues, executes, and fails tasks.

Package	Engine	Native retry	Native cancel	Bulk retry	Schedule support
z4j-celery	Celery 5.2.2+	✓	✓	✓	celery-beat
z4j-rq	RQ 1.10.1+	✓	✓	✓	rq-scheduler
z4j-dramatiq	Dramatiq 1.14+	✓	with dramatiq-abort (pending only)	no	APScheduler
z4j-huey	Huey 2.4+	complete replacements	✓ (pending only)	no	huey-periodic
z4j-arq	arq 0.26+	no	✓	no	arq cron
z4j-taskiq	taskiq 0.11+	no	no	no	taskiqscheduler

The brain stores redacted inputs and does not rebuild executable task payloads. "Complete replacements" means the operator supplies both args and kwargs. The brain's retry, cancel, bulk-retry and dead-letter routes carry no engine list. They accept any engine the target agent's current session advertises together with the action's capability (retry_task, cancel_task, bulk_retry, requeue_dead_letter, list_dead_letters) and never substitute another engine for the one named. The command routes answer 422 when the agent does not advertise the engine or the action; the dead-letter listing instead answers 409 when no online agent advertises list_dead_letters for the engine, and keeps 422 for a malformed engine, cursor or limit. On every path, including automation rules, a retry is delivered only to a session whose adapter attests the safe retry contract for that engine.

Axis 3: Scheduler

A scheduler adapter inventories periodic tasks and exposes only the mutations its schedule source can honor.

Package	Scheduler	Read	Write	Notes
z4j-celerybeat	celery-beat	✓	✓ (if django-celery-beat)	Filesystem beat is read-only
z4j-rqscheduler	rq-scheduler	✓	disable / delete / trigger	No create, update, or enable
z4j-apscheduler	APScheduler 3	✓	enable / disable / delete / trigger	No create or update; works standalone or with Dramatiq
z4j-hueyperiodic	Huey periodic tasks	✓	read-only	Decorators are code; UI can't add new ones
z4j-arqcron	arq cron jobs	✓	read-only	Same limitation, decorators in source
z4j-taskiqscheduler	taskiq-scheduler	✓	read-only; delete when the source implements delete_schedule	Standard label source is decorator-defined

Composing adapters

You install one framework + one or more engines + zero or more schedulers:

# Django + Celery + beat
pip install z4j-django z4j-celery z4j-celerybeat

# Flask + RQ + scheduler + Dramatiq + APScheduler (unusual but supported)
pip install z4j-flask z4j-rq z4j-rqscheduler z4j-dramatiq z4j-apscheduler

Framework adapters import whichever engine adapters are installed and wire them from the framework's own configuration, not from entry points: z4j-django looks for the Celery app by convention (<project>.celery_app, then <project>.celery; Celery is the only engine it wires) and for celery-beat; z4j-flask reads each engine's handle from app.config; z4j-fastapi takes the engine objects as keyword arguments; z4j-bare takes the adapter list explicitly.

Custom adapters

The adapter interface is internal and not currently documented for third-party authors. If you need a custom engine adapter, the existing packages (z4j-celery, z4j-rq, etc.) are the working reference implementations.

See the per-engine pages for the exact adapter surface of each.