Metadata-Version: 2.4
Name: celery_root
Version: 0.3.1
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.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: pydantic-settings<3,>=2.5
Requires-Dist: pydantic>=2.12
Requires-Dist: sqlalchemy<3,>=2
Provides-Extra: mcp
Requires-Dist: django<7,>=4; extra == 'mcp'
Requires-Dist: fastmcp<3,>=2.12; extra == 'mcp'
Requires-Dist: uvicorn<1,>=0.35.0; extra == 'mcp'
Provides-Extra: otel
Requires-Dist: opentelemetry-exporter-otlp<2,>=1.33; extra == 'otel'
Requires-Dist: opentelemetry-sdk<2,>=1.30; extra == 'otel'
Provides-Extra: prometheus
Requires-Dist: prometheus-client<1,>=0.13.0; extra == 'prometheus'
Provides-Extra: web
Requires-Dist: django<7,>=4; extra == 'web'
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 control plane for Celery. It provides a Django-based UI, an event listener/collector, and helper utilities for inspecting tasks, workers, queues, and beat schedules. The Python package and distribution remain `celery_root` for compatibility.

## Features

- Task list with filtering, sorting, and detail views (args/kwargs/result/traceback).
- Task relation graph visualization (chains, groups, chords, maps).
- 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.13, `uv`, and Docker (for the demo broker/redis).

```bash
export CELERY_ROOT_WORKERS="your_app.celery:app,another_app.celery:app"
```

Start the supervisor + UI (standalone):

```bash
celery_root -A your_app.celery:app
```

Or run as a Celery subcommand:

```bash
celery -A your_app.celery:app celery_root
```

By default the UI binds to `127.0.0.1:8000`.

## Demo stack

Requirements: Python >= 3.10, `uv`, and Docker (for the demo broker/redis).

```bash
make demo-infra
make demo-worker-math
make demo-worker-text
make demo-root
```

Then open `http://127.0.0.1:8000`.

To enqueue demo tasks:

```bash
make demo-tasks
```

## Installation (repo)

Celery Root is currently built and run from this repository.

```bash
make install
```

This runs:

- `uv sync --all-extras --dev --frozen`
- `uv run pre-commit install`
- `npm --prefix frontend/graph-ui install`

Build the frontend assets:

```bash
celery_root -A demo.worker_math:app
```

Via Celery:

```bash
celery -A demo.worker_math:app celery_root
```

## Optional dependencies

Celery Root ships optional components behind extras. Install only what you need.

- `web`: Django-based UI.
- `mcp`: MCP server (FastMCP + Uvicorn) and Django for ASGI integration.
- `prometheus`: Prometheus metrics exporter.
- `otel`: OpenTelemetry exporter.

Install with `uv`:

```bash
uv sync --extra web --extra prometheus
```

Or install all extras:

```bash
uv sync --all-extras
```

Editable install with pip:

```bash
pip install -e ".[web,prometheus]"
```

## Configuration

Configuration is explicit via Pydantic models. Components are enabled when their config is provided (set to `None` to disable).

```python
from pathlib import Path

from celery_root import (
    BeatConfig,
    CeleryRootConfig,
    DatabaseConfigSqlite,
    FrontendConfig,
    OpenTelemetryConfig,
    PrometheusConfig,
)

config = CeleryRootConfig(
    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),
)
```

The web UI 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)
```

## Library usage

Start the supervisor from Python:

```python
from celery_root import CeleryRoot

root = CeleryRoot("your_app.celery:app")
root.run()
```

Provide a logger if you want Celery Root to use your logging setup (subprocess logs are forwarded via a queue):

```python
import logging

from celery_root import CeleryRoot

logger = logging.getLogger("celery_root")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler())

root = CeleryRoot("your_app.celery:app", logger=logger)
root.run()
```

## MCP server (AI tools)

Celery Root ships with an optional MCP server that exposes read-only tools over HTTP. It is designed for MCP clients (Codex CLI, Claude Code, etc.) to inspect the Celery Root store safely without write access.


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`: Deprecated (RPC-based access replaces direct DB reads).

Example:

```bash
export CELERY_ROOT_MCP_ENABLED=1
export CELERY_ROOT_MCP_AUTH_KEY="your-secret-token"
```

Start the supervisor (or MCP server) and open the Settings page to copy client snippets.

## Development

Run checks locally:

```bash
uv run precommit
uv run mypy
uv run pytest
```

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