Metadata-Version: 2.4
Name: z4j
Version: 1.2.0
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.3,>=1.2.0
Requires-Dist: z4j-core<1.3,>=1.2.0
Provides-Extra: agents
Requires-Dist: z4j-apscheduler>=1.0.1; extra == 'agents'
Requires-Dist: z4j-arq>=1.1.2; extra == 'agents'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'agents'
Requires-Dist: z4j-bare>=1.2.0; extra == 'agents'
Requires-Dist: z4j-celery>=1.1.2; extra == 'agents'
Requires-Dist: z4j-celerybeat>=1.0.1; extra == 'agents'
Requires-Dist: z4j-django>=1.2.0; extra == 'agents'
Requires-Dist: z4j-dramatiq>=1.1.2; extra == 'agents'
Requires-Dist: z4j-fastapi>=1.2.0; extra == 'agents'
Requires-Dist: z4j-flask>=1.2.0; extra == 'agents'
Requires-Dist: z4j-huey>=1.1.2; extra == 'agents'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'agents'
Requires-Dist: z4j-rq>=1.1.2; extra == 'agents'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'agents'
Requires-Dist: z4j-taskiq>=1.1.2; 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.1.2; extra == 'all'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'all'
Requires-Dist: z4j-bare>=1.2.0; extra == 'all'
Requires-Dist: z4j-brain[postgres]<1.3,>=1.2.0; extra == 'all'
Requires-Dist: z4j-celery>=1.1.2; extra == 'all'
Requires-Dist: z4j-celerybeat>=1.0.1; extra == 'all'
Requires-Dist: z4j-django>=1.2.0; extra == 'all'
Requires-Dist: z4j-dramatiq>=1.1.2; extra == 'all'
Requires-Dist: z4j-fastapi>=1.2.0; extra == 'all'
Requires-Dist: z4j-flask>=1.2.0; extra == 'all'
Requires-Dist: z4j-huey>=1.1.2; extra == 'all'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'all'
Requires-Dist: z4j-rq>=1.1.2; extra == 'all'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'all'
Requires-Dist: z4j-taskiq>=1.1.2; 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.1.2; extra == 'arq'
Requires-Dist: z4j-arqcron>=1.0.1; extra == 'arq'
Provides-Extra: bare
Requires-Dist: z4j-bare>=1.2.0; extra == 'bare'
Provides-Extra: celery
Requires-Dist: z4j-celery>=1.1.2; extra == 'celery'
Requires-Dist: z4j-celerybeat>=1.0.1; extra == 'celery'
Provides-Extra: django
Requires-Dist: z4j-django>=1.2.0; extra == 'django'
Provides-Extra: dramatiq
Requires-Dist: z4j-dramatiq>=1.1.2; extra == 'dramatiq'
Provides-Extra: fastapi
Requires-Dist: z4j-fastapi>=1.2.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: z4j-flask>=1.2.0; extra == 'flask'
Provides-Extra: huey
Requires-Dist: z4j-huey>=1.1.2; extra == 'huey'
Requires-Dist: z4j-hueyperiodic>=1.0.1; extra == 'huey'
Provides-Extra: postgres
Requires-Dist: z4j-brain[postgres]<1.3,>=1.2.0; extra == 'postgres'
Provides-Extra: rq
Requires-Dist: z4j-rq>=1.1.2; extra == 'rq'
Requires-Dist: z4j-rqscheduler>=1.0.1; extra == 'rq'
Provides-Extra: taskiq
Requires-Dist: z4j-taskiq>=1.1.2; 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.10 (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 - 30 seconds

```bash
pip install z4j
z4j serve
```

That's the entire setup. The first run automatically:

1. Creates `~/.z4j/z4j.db` (bundled SQLite, no Postgres needed for evaluation).
2. Mints HMAC signing keys to `~/.z4j/secret.env` (sessions + audit-log chaining survive restarts).
3. Runs Alembic migrations to head.
4. Boots the brain on `http://localhost:7700`.
5. Prints a one-time setup URL like `http://localhost:7700/setup?token=...`.

Open the URL in your browser, create the admin account, and you
land on the dashboard. Everything self-contained in `~/.z4j/`. To
start fresh: delete that directory and re-run.

See [z4j-brain](https://pypi.org/project/z4j-brain/) for the
complete configuration reference (defaults, retention, rate limits,
Argon2 cost, etc.). For production, set `Z4J_SECRET`,
`Z4J_SESSION_SECRET`, `Z4J_DATABASE_URL`, `Z4J_PUBLIC_URL`, and
`Z4J_ALLOWED_HOSTS` explicitly via env vars and back up the secret
store.

## 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.

## Docker Compose recipes

Prefer Docker to pip? This repo ships three ready-to-use compose
files alongside the Python package:

```bash
git clone https://github.com/z4jdev/z4j.git
cd z4j
cp .env.example .env     # fill in Z4J_SECRET, Z4J_SESSION_SECRET, etc.
```

Then pick your mode:

```bash
# Evaluation / homelab (SQLite bundled in the image):
docker compose up -d

# Production self-host (adds PostgreSQL 18 sidecar):
docker compose -f docker-compose.postgres.yml up -d

# Add Caddy auto-HTTPS on top of either mode:
docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d
# or:
docker compose -f docker-compose.postgres.yml -f docker-compose.caddy.yml up -d
```

All three compose files reference the same `z4jdev/z4j:latest`
image from [Docker Hub](https://hub.docker.com/r/z4jdev/z4j) - the
mode switch happens at runtime via `Z4J_DATABASE_URL`, not at build
time. Caddy is an optional overlay that layers auto-HTTPS on top.

Full deployment walkthrough, reverse-proxy alternatives (nginx,
Traefik, Cloudflare Tunnel), and production hardening guide:
<https://z4j.dev>.

## 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>
