Pulse (phzyx-pulse)

Reliable-by-default background tasks for modern Python.

Install

uv add phzyx-pulse

export PULSE_BROKER_URL=redis://localhost:6379/0
export PULSE_IMPORTS=myapp.tasks
pulse worker

Quick start (eager — no worker)

from phzyx.pulse import Pulse, set_app, task

set_app(Pulse(eager=True))

@task
def add(x: int, y: int) -> int:
    return x + y

print(add.delay(1, 2).get())  # 3

Worker mode

# tasks.py
from phzyx.pulse import task

@task
def add(x: int, y: int) -> int:
    return x + y

export PULSE_IMPORTS=tasks
export PULSE_BROKER_URL=redis://localhost:6379/0
# terminal A
pulse worker -v
# terminal B — enqueue from Python with the same tasks imported

CLI

pulse --version
pulse info
pulse doctor
pulse worker --queue default
pulse beat
pulse dashboard --port 8787
pulse retry <job-id>

Design locks

• Import phzyx.pulse only (not phzyx_pulse)
• Late ACK by default
• No pickle default serializer (JSON)
• ETA stored on broker (not worker RAM)
• Built-in DLQ + lease tokens + visibility reclaim
• Not part of Forge — separate product under phzyxyz/pulse

Docs

• Site: https://phzyx.xyz/pulse
• Local guides under docs/ (getting started, Celery migration, edge cases, press)

Realistic stack (OrbStack)

./examples/realistic_stack/scripts/up.sh
# API  http://127.0.0.1:18443/health
# Dash http://127.0.0.1:18787/
# Redis localhost:16379

Stack press (benchmarks)

uv pip install 'phzyx-pulse[press]'
PYTHONPATH=src:. uv run python -m benchmarks.press.run_all_mp \
  --n 1000 --work-iters 5000 --workers 2 4
# → benchmarks/press/RESULTS/SUMMARY_MP.md

Not under forge

Product code lives only here. Do not add Pulse packages to the Forge tree.