> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sluice.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

> Complete reference for the Sluice Python SDK — all parameters, environment variables, and behaviors.

## Installation

```bash theme={null}
pip install sluice-celery
```

**Requirements:**

* Python 3.11, 3.12, or 3.13
* Celery 5.3 or later
* urllib3 2.0 or later (installed automatically)

## `sluice.init()`

The single public API for V0. Call this once at application startup, before Celery workers begin processing tasks.

```python theme={null}
import sluice

sluice.init(
    api_key="sk_live_...",
    connection_id="550e8400-e29b-41d4-a716-446655440000",
)
```

### Parameters

| Parameter       | Type          | Default | Description                                                                                                                               |
| --------------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`       | `str \| None` | `None`  | Your Sluice API key. Falls back to the `SLUICE_API_KEY` environment variable.                                                             |
| `connection_id` | `str \| None` | `None`  | Your Sluice connection UUID. Falls back to the `SLUICE_CONNECTION_ID` environment variable. Found in the dashboard under **Connections**. |

Both parameters are keyword-only (no positional arguments).

### Environment variables

| Variable               | Description                                                             |
| ---------------------- | ----------------------------------------------------------------------- |
| `SLUICE_API_KEY`       | Fallback for `api_key` parameter. Use this to keep secrets out of code. |
| `SLUICE_CONNECTION_ID` | Fallback for `connection_id` parameter.                                 |

The resolution order is: explicit parameter > environment variable. If neither is set, `init()` raises `SluiceConfigError`.

### Behavior

When `sluice.init()` is called, the SDK:

1. **Validates configuration** — checks that `api_key` and `connection_id` are non-empty and that the connection ID is a valid UUID. Raises `SluiceConfigError` immediately if validation fails.

2. **Detects framework** — checks whether Django is installed. If Django is detected, the SDK eagerly installs its Celery Bootstep on the current Celery app.

3. **Connects to `celeryd_init` signal** — regardless of framework, the SDK registers a handler on Celery's `celeryd_init` signal. This fires when each worker process starts and installs the monitoring Bootstep.

4. **Auto-configures Celery** — the Bootstep sets three critical flags that are `False` by default in Celery:

   | Celery Setting            | Set To | Why                                                                                                                        |
   | ------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
   | `worker_send_task_events` | `True` | Enables the event stream — without this, Sluice receives nothing.                                                          |
   | `task_send_sent_event`    | `True` | Emits a `task-sent` event when a task is dispatched, allowing Sluice to distinguish "sent but not started" from "unknown". |
   | `task_track_started`      | `True` | Emits a `task-started` event, enabling execution time tracking.                                                            |

5. **Captures and forwards events** — listens to all Celery task and worker events, normalizes them to Sluice's unified model, batches them, and sends them to the Sluice API over HTTPS.

<Warning>
  **Call `init()` only once.** If called multiple times, the SDK logs a warning and ignores subsequent calls. Only the first invocation takes effect.
</Warning>

### Exceptions

| Exception           | When                                        | Impact                                                                                                |
| ------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `SluiceConfigError` | API key or connection ID is missing/invalid | Raised at startup — blocks `init()`. Your worker still starts normally, but monitoring is not active. |

Configuration errors are the **only** exceptions the SDK raises. All runtime errors — network failures, API errors, serialization issues — are caught and logged. The SDK never crashes your Celery worker.

## Celery state mapping

The SDK maps Celery's native task states to Sluice's unified model:

| Celery State | Sluice State | Notes                                                                                                             |
| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `PENDING`    | `unknown`    | Celery's PENDING means "no information about this task" — not "waiting in queue". This is a critical distinction. |
| `RECEIVED`   | `queued`     | Worker received the task but hasn't started executing it.                                                         |
| `STARTED`    | `active`     | Task is currently executing (requires `task_track_started=True`).                                                 |
| `SUCCESS`    | `completed`  | Task finished successfully.                                                                                       |
| `FAILURE`    | `failed`     | Task raised an exception.                                                                                         |
| `RETRY`      | `retrying`   | Task will be retried.                                                                                             |
| `REVOKED`    | `cancelled`  | Task was revoked by the user or system.                                                                           |
| `REJECTED`   | `failed`     | Worker rejected the task (usually a configuration issue).                                                         |

## Supported versions

| Dependency      | Minimum | Tested                                                      |
| --------------- | ------- | ----------------------------------------------------------- |
| Python          | 3.11    | 3.11, 3.12, 3.13                                            |
| Celery          | 5.3     | 5.3, 5.4, 5.5, 5.6                                          |
| Redis broker    | Any     | Redis 6+, Redis 7+                                          |
| RabbitMQ broker | Any     | Not tested in V0 — events should work but are not validated |

## Where to call `init()`

The `init()` call must execute before Celery workers start. The exact location depends on your framework:

| Framework             | Location                                             | Example                                          |
| --------------------- | ---------------------------------------------------- | ------------------------------------------------ |
| **Django**            | `settings.py` or the Celery app module (`celery.py`) | `sluice.init()` after `CELERY_BROKER_URL` is set |
| **FastAPI**           | Application entrypoint (`main.py`)                   | Top-level, before `app = FastAPI()`              |
| **Flask**             | Application factory or entrypoint                    | Inside `create_app()` or at module level         |
| **Standalone Celery** | `celeryconfig.py` or `tasks.py`                      | Alongside your Celery app definition             |