celery_root 0.1.0__tar.gz

celery_root-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 Christian-Hauke Poensgen
+# SPDX-FileCopyrightText: 2026 Maximilian Dolling
+# SPDX-FileContributor: AUTHORS.md
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+__pycache__/
+*.py[cod]
+*.egg-info/
+.dist/
+dist/
+build/
+.venv/
+node_modules/
+.env
+.env.*
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.db
+*.db
+*.db-shm
+*.db-wal
+.db-shm
+.db-wal
+*.sqlite3
+celerybeat-schedule
+celerybeat-schedule.*
+logs/
+*.log
+.idea/
+.vscode/
+.DS_Store
+/demo/data
+/celery_root/web/
+.coverage
+coverage.xml
+/htmlcov/

celery_root-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,59 @@
+# SPDX-FileCopyrightText: 2026 Christian-Hauke Poensgen
+# SPDX-FileCopyrightText: 2026 Maximilian Dolling
+# SPDX-FileContributor: AUTHORS.md
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+default_language_version:
+  python: python3.14
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        args:
+          - --markdown-linebreak-ext=md
+      - id: end-of-file-fixer
+      - id: check-json
+        exclude: ^frontend/graph-ui/node_modules/
+      - id: check-toml
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: check-ast
+      - id: check-case-conflict
+      - id: debug-statements
+      - id: detect-private-key
+      - id: name-tests-test
+        args: [--pytest-test-first]
+        exclude: ^tests/fixtures/
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: 'v0.15.0'
+    hooks:
+    # Run the formatter.
+    - id: ruff-format
+    # Run the linter.
+    - id: ruff-check
+      args: [ --fix ]
+  - repo: https://github.com/fsfe/reuse-tool
+    rev: 'v6.2.0'
+    hooks:
+      - id: reuse
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy celery_root demo tests
+        language: system
+        types: [python]
+        pass_filenames: false
+        args: []
+      - id: pytest
+        name: pytest
+        entry: make test
+        language: system
+        pass_filenames: false
+        always_run: true
+        args: []

celery_root-0.1.0/AGENTS.md

@@ -0,0 +1,62 @@
+<!--
+SPDX-FileCopyrightText: 2026 Christian-Hauke Poensgen
+SPDX-FileCopyrightText: 2026 Maximilian Dolling
+SPDX-FileContributor: AUTHORS.md
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+# Agent guidelines — Celery Root
+
+Instructions for AI agents (and humans) working in this repo.
+
+---
+
+## Version control
+
+- We use **git**. All changes go through commits; work is tracked in branches/PRs as appropriate.
+- Before committing, run the checks below (or rely on pre-commit).
+
+---
+
+## Code quality
+
+### Typing and mypy
+
+- **Fully typed:** All Python code must be type-annotated. Use type hints for function parameters, return types, and module-level names where it helps clarity.
+- **mypy (strict):** The codebase is checked with mypy in strict mode. No commits that break `mypy` on the project.
+
+Run type checking:
+
+```bash
+make lint
+```
+
+### Rough checks (pre-commit)
+
+We use **pre-commit** to run a consistent set of checks before each commit. Install and run:
+
+```bash
+uv run pre-commit install
+```
+
+Thereafter, every `git commit` runs the configured hooks (e.g. ruff, mypy, tests). Fix any failures before committing, or temporarily bypass with `git commit --no-verify` only when justified.
+
+Typical hooks to have:
+
+- **ruff** — lint and format (or separate format hook).
+- **mypy** — type checking.
+- Optional: **pytest** or a fast smoke test so the tree stays green.
+
+Pre-commit config lives in `.pre-commit-config.yaml`. Keep it so that “rough” checks (lint + types + maybe a quick test) pass on commit.
+
+---
+
+## Summary
+
+| Requirement | How |
+|-------------|-----|
+| Fully typed | Type hints throughout; mypy strict. |
+| mypy checked | `uv run mypy` must pass. |
+| Rough checks on commit | pre-commit hooks (ruff, mypy, etc.). |
+| Git | All changes via git; no bypassing checks without good reason. |

celery_root-0.1.0/AUTHORS.md

@@ -0,0 +1,11 @@
+<!--
+SPDX-FileCopyrightText: 2026 Christian-Hauke Poensgen
+SPDX-FileCopyrightText: 2026 Maximilian Dolling
+SPDX-FileContributor: AUTHORS.md
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+- Christian-Hauke Poensgen
+- OpenAI Codex
+- Maximilian Dolling

celery_root-0.1.0/LICENSES/BSD-3-Clause.txt

@@ -0,0 +1,11 @@
+Copyright (c) 2026, Entities listed in ../AUTHORS.md
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

celery_root-0.1.0/Makefile

@@ -0,0 +1,83 @@
+# SPDX-FileCopyrightText: 2026 Christian-Hauke Poensgen
+# SPDX-FileCopyrightText: 2026 Maximilian Dolling
+# SPDX-FileContributor: AUTHORS.md
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+SHELL := /bin/sh
+
+.PHONY: build \
+		dist \
+		dist_clean \
+		install \
+		lint \
+		publish \
+		publish_test
+
+install_frontend:
+	npm --prefix frontend/graph-ui install
+
+install_backend:
+	uv sync --all-extras --dev --frozen
+	uv run pre-commit install
+
+install: install_backend install_frontend
+
+clean:
+	rm -rf demo/data/logs
+
+build_frontend: install_frontend
+	npm --prefix frontend/graph-ui run build
+
+build: build_frontend
+
+dist: build_frontend
+	uv build --no-sources
+
+dist_clean:
+	rm -rf dist
+
+lint:
+	uv run pre-commit run --all-files
+
+test: test_ci
+	uv run coverage html
+
+test_ci:
+	uv run coverage run --branch -m pytest -q -vv
+	uv run coverage xml
+	uv run coverage report
+
+docker_network:
+	docker network create celery_root_demo || true
+
+demo_stop_infra:
+	docker compose -p celery_root_demo -f demo/infra.docker-compose.yml down --volumes --remove-orphans
+
+demo_start_infra: docker_network
+	docker compose -p celery_root_demo -f demo/infra.docker-compose.yml up -d
+
+demo_worker_math: demo_start_infra
+	uv run celery -A demo.worker_math worker -n math@%h -l INFO
+
+demo_worker_text: demo_start_infra
+	uv run celery -A demo.worker_text worker -n text@%h -l INFO
+
+demo_worker_sleep: demo_start_infra
+	BROKER3_URL=$(BROKER3_URL) BACKEND3_URL=$(BACKEND3_URL) uv run celery -A demo.worker_sleep worker -n sleep@%h -l INFO
+
+demo_workers: demo_start_infra
+	docker compose -p celery_root_demo -f demo/worker.docker-compose.yml up --build
+
+demo_tasks:
+	uv run python demo/schedule_demo_tasks.py
+
+demo_graph_tasks:
+	uv run python demo/schedule_demo_tasks.py
+
+demo_root: clean build
+	uv run python celery_root/components/web/manage.py migrate
+	uv run python demo/main.py
+
+apply_license:
+	uv run reuse annotate -c "Christian-Hauke Poensgen" -c "Maximilian Dolling" -l "BSD-3-Clause" -y "2026" --contributor "AUTHORS.md" -r .

celery_root-0.1.0/NEXT_STEPS.md

@@ -0,0 +1,65 @@
+<!--
+SPDX-FileCopyrightText: 2026 Christian-Hauke Poensgen
+SPDX-FileCopyrightText: 2026 Maximilian Dolling
+SPDX-FileContributor: AUTHORS.md
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+# NEXT_STEPS
+
+## Flower config parity (backwards compatibility)
+
+Source: https://flower.readthedocs.io/en/latest/config.html
+
+Legend: [x] supported, [~] partial, [ ] missing
+
+| Flower option | Meaning (short) | Root status | Current mapping / notes |
+| --- | --- | --- | --- |
+| address | bind address | [~] | `FrontendConfig.host` in `celery_root/config.py` (defaults differ: Flower empty string vs Root 127.0.0.1) |
+| port | bind port | [~] | `FrontendConfig.port` in `celery_root/config.py` (defaults differ: Flower 5555 vs Root 8000) |
+| debug | debug mode | [x] | `FrontendConfig.debug` + CLI `--debug/--no-debug` |
+| auth | allowlist regex | [x] | `FrontendConfig.auth` via `celery_root/components/web/auth.py` (supports FLOWER_AUTH) |
+| basic_auth | basic auth users | [x] | `FrontendConfig.basic_auth` via `celery_root/components/web/auth.py` (supports FLOWER_BASIC_AUTH) |
+| auth_provider | oauth provider | [x] | `FrontendConfig.auth_provider` (supports FLOWER_AUTH_PROVIDER) |
+| oauth2_key | oauth client id | [x] | `FrontendConfig.oauth2_key` (supports FLOWER_OAUTH2_KEY) |
+| oauth2_secret | oauth client secret | [x] | `FrontendConfig.oauth2_secret` (supports FLOWER_OAUTH2_SECRET) |
+| oauth2_redirect_uri | oauth redirect | [x] | `FrontendConfig.oauth2_redirect_uri` (supports FLOWER_OAUTH2_REDIRECT_URI) |
+| cookie_secret | secure cookie secret | [ ] | No explicit mapping; Django uses `FrontendConfig.secret_key` but not Flower compatible |
+| xheaders | trust proxy headers | [ ] | Not implemented in Django middleware stack |
+| url_prefix | non-root UI path | [ ] | No URL prefix support in routing/static paths |
+| unix_socket | run on unix socket | [ ] | Dev server does not support UNIX sockets |
+| certfile | TLS cert | [ ] | No TLS support in dev server/uvicorn |
+| keyfile | TLS key | [ ] | No TLS support in dev server/uvicorn |
+| ca_certs | TLS CA bundle | [ ] | No TLS support in dev server/uvicorn |
+| broker_api | RabbitMQ management API | [ ] | No broker management API integration |
+| enable_events | periodic enable_events | [~] | Always enabled in `celery_root/core/event_listener.py`, not configurable |
+| inspect_timeout | inspect timeout (ms) | [ ] | Fixed at 1.0s in `celery_root/core/engine/brokers/base.py` |
+| auto_refresh | auto-refresh workers | [ ] | JS polling exists but no config flag or env mapping |
+| natural_time | relative timestamps | [ ] | UI uses absolute timestamps only |
+| tasks_columns | /tasks columns | [ ] | Columns fixed in `celery_root/components/web/templates/tasks/list.html` |
+| format_task | custom task formatter | [ ] | No hook for redaction/formatting |
+| persistent | persist state | [~] | Always persists to SQLite; no toggle |
+| db | state db file | [~] | `DatabaseConfigSqlite.db_path` exists, not Flower-compatible flag |
+| state_save_interval | periodic state save | [ ] | DB writes are continuous; no interval control |
+| max_workers | memory cap for workers | [ ] | No cap implemented |
+| max_tasks | memory cap for tasks | [ ] | No cap implemented |
+| purge_offline_workers | auto-prune offline | [ ] | No auto-prune behavior |
+| task_runtime_metric_buckets | metrics buckets | [ ] | Buckets are fixed in metrics exporters |
+| conf | config file path | [ ] | No `flowerconfig.py` loader or `--conf` |
+
+## Missing compatibility surfaces
+
+- [ ] Load `flowerconfig.py` / `--conf` and map keys into `CeleryRootConfig`.
+- [ ] Read all `FLOWER_*` env vars (not just auth) and map to Root settings.
+- [ ] CLI flags parity for Flower options (accept `celery flower ...` style flags for the Celery Root entrypoint).
+
+## Feature parity tasks (top priority)
+
+- [ ] Implement `url_prefix` and `xheaders` for reverse proxy deployments.
+- [ ] Add TLS support or document proxy termination (`certfile`/`keyfile`/`ca_certs`).
+- [ ] Make event enabling configurable (`enable_events`, `inspect_timeout`).
+- [ ] Add task list customization (`tasks_columns`, `format_task`, `natural_time`).
+- [ ] Add state retention controls (`persistent`, `db`, `state_save_interval`, `max_workers`, `max_tasks`, `purge_offline_workers`).
+- [ ] Implement broker management integration (`broker_api`) for queue stats.
+- [ ] Make metrics buckets configurable (`task_runtime_metric_buckets`).

celery_root-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: celery_root
+Version: 0.1.0
+Summary: Command & Control for Celery Workers
+Project-URL: Documentation, https://docs.celeryroot.eu/
+Project-URL: Repository, https://github.com/christianhpoe/celery_root
+Project-URL: Issues, https://github.com/christianhpoe/celery_root/issues
+Author: Christian-Hauke Poensgen, Maximilian Dolling
+License-Expression: BSD-3-Clause
+License-File: LICENSES/BSD-3-Clause.txt
+Keywords: celery,mcp,monitoring,observability,otel,prometheus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Celery
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+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 :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: celery[tblib]<6,>=5.0.5
+Requires-Dist: click>=8.1
+Requires-Dist: django<7,>=4
+Requires-Dist: fastmcp<3,>=2.12
+Requires-Dist: opentelemetry-exporter-otlp<2,>=1.33
+Requires-Dist: opentelemetry-sdk<2,>=1.30
+Requires-Dist: prometheus-client<1,>=0.13.0
+Requires-Dist: pydantic-settings<3,>=2.5
+Requires-Dist: pydantic>=2.12
+Requires-Dist: sqlalchemy<3,>=2
+Requires-Dist: uvicorn<1,>=0.35.0
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: 2026 Christian-Hauke Poensgen
+SPDX-FileCopyrightText: 2026 Maximilian Dolling
+SPDX-FileContributor: AUTHORS.md
+
+SPDX-License-Identifier: BSD-3-Clause
+-->
+
+# Celery Root
+
+Docs: https://docs.celeryroot.eu
+
+Celery Root is a command & control plane for Celery
+It ships with a Django-based UI, a lightweight event listener/collector, and helper utilities for inspecting
+queues, tasks, workers, and beat schedules. The distribution and Python package names are still
+`celery_root` for compatibility; only the product name and visuals have changed.
+
+## Features
+
+- Task list with filtering, sorting, and details (args/kwargs/result/traceback).
+- Task relation graph visualization.
+- Worker fleet overview and per-worker drill-down.
+- Broker queue inspection and purge actions.
+- Beat schedule overview and editor.
+- Pluggable storage (SQLite by default).
+
+## Quickstart (demo)
+
+Requirements: Python >= 3.10, `uv`, and Docker (for the demo broker/redis).
+
+```bash
+make demo-infra
+```
+
+Start the demo workers in separate terminals:
+
+```bash
+make demo-worker-math
+```
+
+```bash
+make demo-worker-text
+```
+
+Launch the Celery Root supervisor + web UI:
+
+```bash
+make demo-root
+```
+
+Then open `http://127.0.0.1:5555`.
+
+To enqueue demo tasks:
+
+```bash
+make demo-tasks
+```
+
+## Running the web UI
+
+If you already have Celery workers and a broker running, you can point the UI at your apps via
+`CELERY_ROOT_WORKERS` and run the web server:
+
+```bash
+export CELERY_ROOT_WORKERS="your_app.celery:app,another_app.celery:app"
+uv run python celery_root/components/web/manage.py migrate
+uv run python -m celery_root.components.web.devserver --host 127.0.0.1 --port 8000
+```
+
+The UI reads task/worker data from the Celery Root SQLite store (see configuration below).
+
+## CLI usage
+
+You can run the supervisor via the CLI, either standalone or as a Celery subcommand.
+
+Standalone:
+
+```bash
+celery-root -A demo.worker_math:app
+```
+
+Via Celery:
+
+```bash
+celery -A demo.worker_math:app celery_root
+```
+
+## Configuration
+
+Configuration is explicit via Pydantic models:
+
+```python
+from pathlib import Path
+
+from celery_root import (
+    BeatConfig,
+    CeleryRootConfig,
+    DatabaseConfigSqlite,
+    FrontendConfig,
+    LoggingConfigFile,
+    OpenTelemetryConfig,
+    PrometheusConfig,
+)
+
+config = CeleryRootConfig(
+    logging=LoggingConfigFile(log_dir=Path("./logs")),
+    database=DatabaseConfigSqlite(db_path=Path("./celery_root.db")),
+    beat=BeatConfig(schedule_path=Path("./celerybeat-schedule")),
+    prometheus=PrometheusConfig(port=8001, prometheus_path="/metrics"),
+    open_telemetry=OpenTelemetryConfig(endpoint="http://localhost:4317"),
+    frontend=FrontendConfig(host="127.0.0.1", port=5555),
+)
+```
+
+Components are enabled when their config is provided (set to `None` to disable).
+
+The web UI still reads worker import paths from `CELERY_ROOT_WORKERS` (comma-separated).
+
+If you need to override settings before Django settings load:
+
+```python
+from celery_root.config import set_settings
+
+set_settings(config)
+```
+
+`BROKER_URL` and `BACKEND_URL` are standard Celery settings used by the demo math worker. The demo text and sleep
+workers use `BROKER2_URL`/`BACKEND2_URL` and `BROKER3_URL`/`BACKEND3_URL` respectively.
+
+## Library usage
+
+For programmatic use, you can start the supervisor from Python:
+
+```python
+from celery_root import CeleryRoot
+
+root = CeleryRoot("your_app.celery:app")
+root.run()
+```
+
+## MCP server (AI tools)
+
+Celery Root ships with an optional MCP server that exposes read-only tools over HTTP.
+It is designed to let MCP clients (Codex CLI, Claude Code, etc.) inspect the Celery Root
+SQLite store safely without write access.
+
+How it works:
+
+- The MCP server runs as a separate process when `CELERY_ROOT_MCP_ENABLED=1`.
+- Requests are served from the Celery Root SQLite store using a read-only SQLAlchemy engine.
+- Tools include schema discovery, limited SQL querying (SELECT/WITH only), and a
+  dashboard stats payload that matches the web UI.
+- Authentication is enforced with a static bearer token (`CELERY_ROOT_MCP_AUTH_KEY`).
+- The web Settings page renders copy/paste snippets for MCP client configuration
+  and CLI commands for Codex + Claude.
+
+Configuration:
+
+- `CELERY_ROOT_MCP_ENABLED`: Enable the MCP server (`1`/`true`).
+- `CELERY_ROOT_MCP_HOST`: Host interface (default: `127.0.0.1`).
+- `CELERY_ROOT_MCP_PORT`: Port (default: `9100`).
+- `CELERY_ROOT_MCP_PATH`: Base path (default: `/mcp/`).
+- `CELERY_ROOT_MCP_AUTH_KEY`: Required auth token for clients.
+- `CELERY_ROOT_MCP_READONLY_DB_URL`: Optional read-only database URL (defaults to
+  SQLite read-only mode using `CELERY_ROOT_DB_PATH`). If you provide a regular
+  database URL via `CELERY_ROOT_MCP_READONLY_DB_URL`, it is used as-is; ensure
+  the credentials are truly read-only or queries will not be protected by the
+  database itself.
+
+Example:
+
+```bash
+export CELERY_ROOT_MCP_ENABLED=1
+export CELERY_ROOT_MCP_AUTH_KEY="your-secret-token"
+```
+
+Start the supervisor (or MCP server) and then open the Settings page to grab the
+client config snippets. The page includes JSON config for MCP clients plus CLI
+examples for Codex and Claude.
+
+## Development
+
+Run checks locally:
+
+```bash
+uv run precommit
+```
+
+Run tests directly:
+
+```bash
+uv run pytest
+```
+
+Type checking:
+
+```bash
+uv run mypy
+```
+
+## Project structure
+
+- `celery_root/components/`: optional components (web, metrics, beat).
+- `celery_root/core/`: engine + DB + logging internals.
+- `demo/`: demo workers and task scripts.
+- `tests/`: unit and integration tests.