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

The companion adapter inventories Huey's periodic-task registry. Its decorators supply the initial schedule definitions. With durable control (NativeScheduleControl) installed in the actual periodic consumer, the companion adapter applies dashboard create, edit, pause, resume and delete as durable overrides. See Huey periodic setup.

Without durable control, the companion adapter provides inventory and Run now only.

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.