Metadata-Version: 2.4
Name: pgloom
Version: 0.3.0
Summary: Postgres-backed reusable workflow and task orchestration runtime.
Author-email: Josh Cassidy <cassidy.joshua@googlemail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/joshorig/pgloom
Project-URL: Repository, https://github.com/joshorig/pgloom
Project-URL: Issues, https://github.com/joshorig/pgloom/issues
Project-URL: Changelog, https://github.com/joshorig/pgloom/blob/main/CHANGELOG.md
Keywords: orchestration,workflow,postgres,task-queue,agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psycopg[binary,pool]>=3.2
Requires-Dist: pydantic>=2
Requires-Dist: pydantic-settings>=2
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: python-dotenv>=1
Requires-Dist: PyYAML>=6
Requires-Dist: jsonschema>=4
Requires-Dist: structlog>=24
Requires-Dist: tenacity>=8
Requires-Dist: httpx>=0.27
Requires-Dist: orjson>=3
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: pytest-xdist>=3; extra == "dev"
Requires-Dist: pytest-timeout>=2; extra == "dev"
Requires-Dist: freezegun>=1; extra == "dev"
Requires-Dist: testcontainers[postgresql]>=4; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML>=6; extra == "dev"
Dynamic: license-file

# pgloom

[![PyPI version](https://img.shields.io/pypi/v/pgloom.svg?cacheSeconds=300)](https://pypi.org/project/pgloom/)
[![Python versions](https://img.shields.io/pypi/pyversions/pgloom.svg?cacheSeconds=300)](https://pypi.org/project/pgloom/)
[![License](https://img.shields.io/github/license/joshorig/pgloom.svg)](LICENSE)
[![CI](https://github.com/joshorig/pgloom/actions/workflows/ci.yml/badge.svg)](https://github.com/joshorig/pgloom/actions/workflows/ci.yml)

`pgloom` is a Postgres-backed workflow and task orchestration runtime for
building domain-specific automation systems. It provides durable workflow state,
task dependencies, worker leases, slots, approvals, idempotency records, model
usage accounting, artifacts, notifications, health checks, and a scenario
harness.

## Quickstart

```bash
pip install pgloom
createdb pgloom_dev
export PGLOOM_DATABASE_URL=postgresql://localhost/pgloom_dev
pgloom db migrate
pgloom workflow create --domain demo --name smoke
pgloom task enqueue --workflow-id <workflow_id> --slot fake --task-type fake.complete
pgloom worker run-once --slot fake
```

For local development:

```bash
scripts/bootstrap_dev_env.sh
source .venv/bin/activate
just test
```

## Concepts

```mermaid
flowchart LR
  W[Workflow] --> T[Tasks]
  T --> D[Dependencies]
  T --> S[Slots]
  S --> R[Workers]
  T --> H[Handlers]
  H --> E[Events]
  H --> A[Artifacts]
  H --> M[Model usage]
```

- **Workflows** group related tasks and carry domain metadata.
- **Tasks** are durable units of work with state, attempts, payloads, results,
  blockers, dependencies, and leases.
- **Slots** model constrained execution capacity such as `claude`, `codex`, or
  `qa`.
- **Handlers** are application code that claims tasks and returns structured
  outcomes.

## Embedding

Domain orchestrators import `pgloom` and keep their own domain behavior outside
the core runtime. `engineering-orchestrator` is the reference consumer planned
for engineering-specific planner, implementer, reviewer, QA, historian, GitHub,
BRAID, worktree, and Telegram behavior.

## Documentation

- [Architecture](docs/architecture.md)
- [Postgres schema](docs/postgres-schema.md)
- [Scenario harness](docs/scenario-harness.md)
- [Release process](docs/release-process.md)
