Huey

Requires Huey 2.4+, on Huey 2 or Huey 3, Python 3.11+. See the compatibility matrix for the full pin string.

Install

pip install z4j-huey

Wiring

Construct the adapter with the Huey instance and start the agent in the consumer process:

from z4j_bare import install_agent
from z4j_huey import HueyEngineAdapter

runtime = install_agent(engines=[HueyEngineAdapter(huey=huey)])

The Flask adapter reads app.config["HUEY"] (the instance or an import path) and the FastAPI adapter takes z4j_lifespan(huey=...). z4j-django discovers only Celery, so Django deployments wire the adapter as above.

What it captures

Huey exposes signals:

Huey signal	z4j event
`SIGNAL_ENQUEUED` / `SIGNAL_SCHEDULED`	`task.received`
`SIGNAL_EXECUTING`	`task.started`
`SIGNAL_COMPLETE`	`task.succeeded`
`SIGNAL_RETRYING`	`task.retried`
exhausted `SIGNAL_ERROR`	`task.failed`
`SIGNAL_INTERRUPTED` / `SIGNAL_EXPIRED`	`task.failed`
`SIGNAL_REVOKED`	`task.revoked`
exhausted `SIGNAL_CANCELED`	`task.revoked`
`SIGNAL_LOCKED` with no retries remaining	`task.revoked`

Actions

Verb	How
`submit`	instantiate the registered Huey Task and call `huey.enqueue(...)`
`retry`	re-enqueue only with both complete operator replacement collections
`cancel`	call `huey.revoke_by_id(task_id)` to prevent pending work from starting; running work is not interrupted

Cancel is advertised with that pending-only contract, and its command result reports pending_only: true. Purge, bulk retry, dead-letter listing and dead-letter replay are not advertised. Huey has no dead-letter store and no primitive here that meets those z4j contracts.

Periodic tasks

Huey's @huey.periodic_task(crontab(...)) decorators are code. Once the application has imported them, the companion adapter inventories Huey's periodic-task registry at agent start and surfaces those definitions as read-only schedules in the dashboard. It does not scan source files for decorated functions.

The companion adapter inventories these definitions but does not advertise pause, enable, disable, create, update, delete, or trigger-now.

Sqlite / in-memory huey

Single-process setups (SQLite huey, MemoryHuey) work but each process has its own queue. z4j reports no Huey queue list, so the dashboard shows only the tasks each process's events describe.

Caveats

No chord/group primitives.

See scheduler: huey-periodic.