Metadata-Version: 2.4
Name: z4j
Version: 1.0.1
Summary: z4j - open-source control plane for Python task infrastructure
Project-URL: Homepage, https://z4j.com
Project-URL: Source, https://github.com/z4jdev/z4j
Project-URL: Documentation, https://z4j.dev
Project-URL: Issues, https://github.com/z4jdev/z4j/issues
Project-URL: Changelog, https://github.com/z4jdev/z4j/blob/main/CHANGELOG.md
Author: z4j contributors
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: celery,control-plane,dashboard,django,flower,monitoring,queue,task,worker,z4j
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Celery
Classifier: Framework :: Django
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: z4j-brain>=1.0.1
Requires-Dist: z4j-core>=1.0.1
Provides-Extra: agents
Requires-Dist: z4j-apscheduler>=1.0.1; extra == 'agents'
Requires-Dist: z4j-arq>=1.0.1; extra == 'agents'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'agents'
Requires-Dist: z4j-bare>=1.0.1; extra == 'agents'
Requires-Dist: z4j-celery>=1.0.1; extra == 'agents'
Requires-Dist: z4j-celerybeat>=1.0.1; extra == 'agents'
Requires-Dist: z4j-django>=1.0.1; extra == 'agents'
Requires-Dist: z4j-dramatiq>=1.0.1; extra == 'agents'
Requires-Dist: z4j-fastapi>=1.0.1; extra == 'agents'
Requires-Dist: z4j-flask>=1.0.1; extra == 'agents'
Requires-Dist: z4j-huey>=1.0.1; extra == 'agents'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'agents'
Requires-Dist: z4j-rq>=1.0.1; extra == 'agents'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'agents'
Requires-Dist: z4j-taskiq>=1.0.1; extra == 'agents'
Requires-Dist: z4j-taskiqscheduler>=1.0.1; extra == 'agents'
Provides-Extra: all
Requires-Dist: z4j-apscheduler>=1.0.1; extra == 'all'
Requires-Dist: z4j-arq>=1.0.1; extra == 'all'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'all'
Requires-Dist: z4j-bare>=1.0.1; extra == 'all'
Requires-Dist: z4j-brain[postgres]>=1.0.1; extra == 'all'
Requires-Dist: z4j-celery>=1.0.1; extra == 'all'
Requires-Dist: z4j-celerybeat>=1.0.1; extra == 'all'
Requires-Dist: z4j-django>=1.0.1; extra == 'all'
Requires-Dist: z4j-dramatiq>=1.0.1; extra == 'all'
Requires-Dist: z4j-fastapi>=1.0.1; extra == 'all'
Requires-Dist: z4j-flask>=1.0.1; extra == 'all'
Requires-Dist: z4j-huey>=1.0.1; extra == 'all'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'all'
Requires-Dist: z4j-rq>=1.0.1; extra == 'all'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'all'
Requires-Dist: z4j-taskiq>=1.0.1; extra == 'all'
Requires-Dist: z4j-taskiqscheduler>=1.0.1; extra == 'all'
Provides-Extra: apscheduler
Requires-Dist: z4j-apscheduler>=1.0.1; extra == 'apscheduler'
Provides-Extra: arq
Requires-Dist: z4j-arq>=1.0.1; extra == 'arq'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'arq'
Provides-Extra: bare
Requires-Dist: z4j-bare>=1.0.1; extra == 'bare'
Provides-Extra: celery
Requires-Dist: z4j-celery>=1.0.1; extra == 'celery'
Requires-Dist: z4j-celerybeat>=1.0.1; extra == 'celery'
Provides-Extra: django
Requires-Dist: z4j-django>=1.0.1; extra == 'django'
Provides-Extra: dramatiq
Requires-Dist: z4j-dramatiq>=1.0.1; extra == 'dramatiq'
Provides-Extra: fastapi
Requires-Dist: z4j-fastapi>=1.0.1; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: z4j-flask>=1.0.1; extra == 'flask'
Provides-Extra: huey
Requires-Dist: z4j-huey>=1.0.1; extra == 'huey'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'huey'
Provides-Extra: postgres
Requires-Dist: z4j-brain[postgres]>=1.0.1; extra == 'postgres'
Provides-Extra: rq
Requires-Dist: z4j-rq>=1.0.1; extra == 'rq'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'rq'
Provides-Extra: taskiq
Requires-Dist: z4j-taskiq>=1.0.1; extra == 'taskiq'
Requires-Dist: z4j-taskiqscheduler>=1.0.1; extra == 'taskiq'
Description-Content-Type: text/markdown

# z4j

**Open-source control plane for Python task infrastructure.**
**License:** AGPL v3 - commercial license available (contact `licensing@z4j.com`).
**Status:** v1.0.1 (production-ready).

A modern, self-hosted alternative to Flower / Prometheus-only task
monitoring. Monitor, manage, and control Celery / RQ / Dramatiq /
Huey / arq / TaskIQ / APScheduler workers, tasks, schedules, and
queues from a single dashboard.

This is the **umbrella package**. Installing `z4j` gets you the
flagship experience (brain + dashboard + SQLite) plus a clean way
to layer in adapter engines via extras.

## Quick start

```bash
pip install z4j

# Generate the two required HMAC signing secrets
export Z4J_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(48))")
export Z4J_SESSION_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(48))")

z4j-brain migrate upgrade head
z4j-brain serve
```

On first run, `z4j-brain serve` prints a one-time setup URL
(`http://localhost:7700/setup?token=...`). Open it in your browser
to create the admin account, then you land on the dashboard at
`http://localhost:7700/`.

See [z4j-brain](https://pypi.org/project/z4j-brain/) for the
complete configuration reference (defaults, retention, rate limits,
Argon2 cost, etc.).

## Install shapes

```bash
# Just the brain (dashboard + SQLite)
pip install z4j

# Brain + Celery adapter (pulls z4j-celery + z4j-celerybeat)
pip install "z4j[celery]"

# Brain + Django + Celery
pip install "z4j[django,celery]"

# Switch the brain to PostgreSQL
pip install "z4j[postgres]"

# Every adapter engine at once (useful for CI)
pip install "z4j[agents]"

# The kitchen sink
pip install "z4j[all]"
```

## Which adapter extras exist

| Extra | Installs | For |
|---|---|---|
| `[celery]` | z4j-celery + z4j-celerybeat | Celery workers + beat scheduler |
| `[django]` | z4j-django | Django task telemetry |
| `[flask]` | z4j-flask | Flask background tasks |
| `[fastapi]` | z4j-fastapi | FastAPI BackgroundTasks |
| `[rq]` | z4j-rq + z4j-rqscheduler | RQ workers + rq-scheduler |
| `[dramatiq]` | z4j-dramatiq | Dramatiq actors |
| `[huey]` | z4j-huey + z4j-hueyperiodic | Huey + periodic tasks |
| `[arq]` | z4j-arq + z4j-arqcron | arq workers + cron |
| `[taskiq]` | z4j-taskiq + z4j-taskiqscheduler | TaskIQ + scheduler |
| `[apscheduler]` | z4j-apscheduler | APScheduler jobs |
| `[bare]` | z4j-bare | Bare (no engine) agents |

## Which umbrella extras exist

| Extra | Installs | For |
|---|---|---|
| `[postgres]` | z4j-brain[postgres] (asyncpg) | Production PostgreSQL backend |
| `[agents]` | every engine adapter | Full-stack dev / CI testing |
| `[all]` | `[agents,postgres]` | Kitchen sink |

## Agent-only installs (no AGPL in your app's venv)

If you're adding z4j to an existing Django / Celery / Flask
application and you need Apache-2.0-only dependencies (no AGPL
in your proprietary code's venv), skip the umbrella and install
the standalone adapter packages directly:

```bash
pip install z4j-core z4j-django    # SDK + Django adapter
pip install z4j-celery             # SDK + Celery adapter
pip install z4j-rq                 # SDK + RQ adapter
```

Every adapter package is **Apache 2.0** and depends only on
`z4j-core` (also Apache 2.0). Point `Z4J_BRAIN_URL` at a running
brain and the adapter will start streaming telemetry.

## Licensing

`z4j` (this umbrella package) is **AGPL v3** because it installs
`z4j-brain` by default. If that is incompatible with your policy,
use the agent-only install recipe above.

- Agent packages (`z4j-core`, `z4j-celery`, `z4j-django`, ...):
  **Apache 2.0**. Free for proprietary use.
- Brain server (`z4j-brain`): **AGPL v3**. Commercial license
  available - contact `licensing@z4j.com`.

The split is deliberate. The brain is the network service operators
run; the agents are the client libraries integrators embed. AGPL
protects the server; Apache makes integration frictionless.

## Documentation

Complete documentation, tutorials, API reference, deployment
guides: <https://z4j.dev>.

- Source: <https://github.com/z4jdev/z4j>
- Issues: <https://github.com/z4jdev/z4j/issues>
- Changelog: <https://github.com/z4jdev/z4j/blob/main/CHANGELOG.md>
