django-dbos 0.1.0__tar.gz

django_dbos-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions: {}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pyrefly check --project-excludes 'examples/**'
+
+  tests:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv run --python ${{ matrix.python-version }} pytest -m "not integration"
+
+  coverage:
+    # Whole suite against a real system database (PostgreSQL via
+    # testcontainers on the runner's Docker): unit tests plus admin pages,
+    # cron, capacity, dbos migrate and the two-process web/worker scenario.
+    # Subprocesses are measured too; fails under the fail_under floor.
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
+      - run: uv run coverage run -m pytest --dbos-system-db=postgres
+      - run: uv run coverage combine
+      - run: uv run coverage report --skip-covered --format=markdown >> "$GITHUB_STEP_SUMMARY"

django_dbos-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Documentation
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    # GitHub Pages is not available on private repositories (free plan): skip
+    # until the repository is public and Pages is enabled once (see AGENTS.md).
+    if: ${{ !github.event.repository.private }}
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: 3.x
+      - run: pip install zensical
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: site
+      - uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
+        id: deployment

django_dbos-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
+        with:
+          enable-cache: false
+      # Refuse to publish a tag that does not match the version in pyproject.toml.
+      - run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    # Trusted publishing: PyPI accepts the OIDC token of this workflow
+    # (release.yml) running in the `pypi` environment, no API token needed.
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    environment:
+      name: pypi
+      url: https://pypi.org/project/django-dbos/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@ed21f2f24f8dd64503750218de024bcf64c7250a # v7.1.5
+        with:
+          enable-cache: false
+      - run: uv publish --trusted-publishing always

django_dbos-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# DBOS
+dbos/
+dbos.sqlite*
+*.sqlite3
+
+# ZCode local plans
+.zcode/
+
+# Docs build output
+site/

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

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.10.1
+    hooks:
+      - id: commitizen
+      - id: commitizen-branch
+        stages: [pre-push]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/osprey-oss/deptry.git
+    rev: 0c39226d761685125c5ff71ca81282d6751c9540 # 0.25.1
+    hooks:
+      - id: deptry
+        # The upstream hook hardcodes `deptry .` and would flag the test/dev
+        # tooling; scan only the shipped package.
+        entry: deptry django_dbos
+        pass_filenames: false
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: v1.32.0
+    hooks:
+      - id: zizmor
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # v6.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

django_dbos-0.1.0/AGENTS.md

@@ -0,0 +1,137 @@
+# AGENTS.md
+
+Reference for AI coding agents (and humans) working on this repository.
+
+## Project
+
+`django-dbos` is a DBOS-backed backend for Django's `django.tasks` framework:
+durable background tasks, cron scheduling (`@cron`), optional Sentry cron
+monitors, admin pages and a worker-capacity report. Published on PyPI.
+
+## Layout
+
+- Flat package layout: `django_dbos/` at the repo root (no `src/`), managed by **uv** and built with **hatchling**.
+- `docs/` holds the user-facing documentation (Markdown only). The zensical
+  config lives at the root: `zensical.toml` (standard layout, do not move it
+  into `docs/` — the docs dir resolves relative to the config file).
+- Tests in `tests/` are plain functions (not Django `TestCase` unless a DB is
+  needed); integration tests are marked `integration` and run against a real
+  system database (PostgreSQL via testcontainers, SQLite file fallback;
+  `test_cockroachdb.py` starts its own CockroachDB container).
+- `examples/` holds standalone runnable projects (own `pyproject.toml`/`uv.lock`,
+  `django-dbos` pulled in as an editable path dependency) demonstrating the
+  package end to end; not part of the root `uv` project or its dependency
+  extras, so `uv run pyrefly check` needs `--project-excludes 'examples/**'`
+  (its imports are not installed in the root `.venv`) — see Commands below.
+
+## Commands
+
+```sh
+uv run pytest                          # unit tests
+uv run pytest -m integration           # integration tests (Docker recommended)
+uv run coverage run -m pytest && uv run coverage combine && uv run coverage report   # coverage, see note
+uv run ruff check . && uv run ruff format --check .
+uv run pyrefly check --project-excludes 'examples/**'   # type check (examples/ are separate projects)
+uv run deptry django_dbos              # dependency hygiene (package only)
+uv run --group doc zensical build      # docs (runs from the repo root)
+uv run --with playwright scripts/admin_screenshots.py   # regenerate docs/assets/admin/*.png after admin UI changes
+uv run benchmarks/serializers.py   # serializer timings quoted in docs/configuration.md
+uv run cz bump                         # release (commitizen)
+```
+
+### Coverage
+
+Measured with branch coverage over `django_dbos`, floor **98 %** in
+`[tool.coverage.report]`. Always measure with `coverage run -m pytest`, **not**
+`pytest --cov`: the pytest plugin is imported by pytest before pytest-cov
+starts tracing, so module-level lines would be reported as uncovered.
+Subprocesses (the plugin's pytester runs, the two-process worker) are measured
+too (`parallel = true`, `patch = ["subprocess"]`): each process writes its own
+`.coverage.*` file, so run `coverage combine` before `coverage report`. A
+subprocess killed abruptly writes no data.
+
+### Test environment
+
+- `[tool.uv] exclude-newer = "7 days"` pins fresh package resolution.
+- `DJANGO_SETTINGS_MODULE=tests.settings`; `filterwarnings = ["error"]` —
+  warnings fail tests.
+- Docker available → Postgres testcontainers for integration tests; otherwise
+  SQLite file fallback.
+
+## Publishing the docs
+
+The Documentation workflow deploys `zensical build` to GitHub Pages. It is
+skipped while the repository is private (Pages needs a paid plan there).
+When the repository goes public, enable Pages **once** with the "GitHub
+Actions" source — `gh api -X POST repos/lewoudar/django-dbos/pages -f build_type=workflow`
+or Settings › Pages — then every push to `main` deploys.
+
+## Conventions
+
+- Commit messages follow **conventional commits** (commitizen,
+  `cz_conventional_commits`, tag format `v$version`); CHANGELOG generated by
+  commitizen through `changelog_template.md.j2` (config key
+  `[tool.commitizen] template = ...`; regenerate with `cz changelog`, use
+  `--incremental` to preserve manually edited sections).
+- Logging through structlog under the `django_dbos` logger.
+- CI workflows have their actions pinned by SHA (zizmor-checked); run
+  `uv run prek run --all-files` before committing (ruff, commitizen, deptry,
+  zizmor).
+- The pytest plugin's runtime imports (pytest, testcontainers) are the
+  `django-dbos[test]` extra; deptry checks the package against the declared
+  dependencies and extras, so keep the extra in sync with the plugin.
+- Python ≥ 3.12, Django ≥ 6.0.
+
+## Process model (do not regress)
+
+- Only `dbos worker` (and the `dbos_system` test fixture) may call
+  `dbos_setup.ensure_launched()`: `DBOS.launch()` starts queue/scheduler/
+  recovery threads, i.e. it turns the process into a worker. Everything else
+  (backend enqueue/get_result, admin views, `capacity.collect`) goes through
+  `client.get_client()` (a `DBOSClient`, system database only).
+- The worker registers every known task (`tasks.known_tasks()`, filled by
+  `DBOSTask.__post_init__`) as a workflow *before* launch; clients enqueue by
+  workflow name and never hold workflow code.
+- `manage.py migrate` migrates the system database through a `post_migrate`
+  receiver (`system_db.migrate_after_django_migrate`): a plain
+  `SystemDatabase` handle, never `ensure_launched()`. It must stay skipped for
+  `flush` (no `plan`), non-default aliases and test databases.
+- Worker heartbeats live in the `WorkerHeartbeat` model (Django database),
+  not in the cache; the package ships a migration.
+
+## Pitfalls learned the hard way
+
+- `DBOSBackend.__init__` must not raise: Django builds the backend while
+  importing task modules and running its checks. A bad queue declaration is
+  stored, reported by `django_dbos.E001` and raised on enqueue. In tests,
+  override the backend's `OPTIONS` with
+  `tests.helpers.set_dbos_options(settings, {...})`.
+- CockroachDB system database: DBOS forces `postgresql+psycopg` when given a
+  URL alone, and its SQL fails on CockroachDB under psycopg 3 (typed
+  parameters, `float * int`). `system_engine` builds a `cockroachdb+psycopg2`
+  engine for the worker and the client (`use_listen_notify=False`), and
+  `DBOS.migrate()` takes no engine, so `migrate` only creates the database:
+  the worker applies DBOS' migrations on launch (`django_dbos.E005`).
+- **Never patch `django.conf.settings` attributes directly** (lazy object +
+  pytest-django `settings` fixture teardown = state leaks between tests).
+  Patch the module's own `settings` reference instead (see
+  `test_no_usable_django_database_raises` in `tests/test_settings.py`) or
+  override via the `settings` fixture for plain settings.
+  Overriding `DATABASES` through the fixture also raises a `UserWarning`
+  (fatal with `filterwarnings = ["error"]`).
+- No private SDK import (`dbos._*`): workflow functions are kept in
+  `tasks_registry._workflows`, errors come from the public `dbos.error`
+  alias (`from dbos import error as dbos_error` — `from dbos.error import`
+  fails, it is an attribute, not a module), capacity lists active workflows
+  through `DBOSClient.list_workflows`. `DBOS.get_schedule` returns a
+  **dict**; the synchronous `retrieve_workflow()` refuses to run inside a
+  running event loop — use the `*_async` variants in async paths.
+- `django.tasks` validates task construction (module-level function, declared
+  queue) at decoration time: build "rogue" tasks inside tests with
+  `dataclasses.replace` after overriding `TASKS`, not at module import.
+- Admin URLs must be **prepended** to the admin's URL list (`dbos_urls + urls`)
+  or the admin's generic patterns swallow them; URL names are bare (`django_dbos_workflow_changelist`), the `admin:`
+  namespace is added by the
+  inclusion.
+- DBOS/structlog log on stdout: in tests, capture a command's output with
+  `call_command(..., stdout=StringIO())` rather than `capsys`.

django_dbos-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [0.1.0] - 2026-11-08
+
+### Added
+
+- `DBOSBackend`, a backend for Django's `django.tasks` framework: every task runs as a durable DBOS workflow that survives crashes and restarts, with configurable queues (concurrency, rate limits) and pluggable serializers.
+- Access to DBOS durable primitives (steps, sleep, events, messages) from inside a task through `get_dbos_context()`.
+- `@cron` scheduling of tasks, with optional Sentry cron monitors.
+- A `dbos` management command: `dbos worker` to run tasks, `dbos migrate` to set up the system database (also applied by `manage.py migrate`), and `dbos status` for a worker-capacity report with pluggable advice.
+- Admin pages, restricted to superusers, to browse, cancel, resume and fork workflows and to manage schedules.
+- PostgreSQL, SQLite and CockroachDB support for the DBOS system database.
+- A pytest plugin (`django-dbos[test]` extra) with `dbos_inline` and `dbos_system` fixtures, to run tasks inline or against a real system database.

django_dbos-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

django_dbos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Tewouda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_dbos-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.5
+Name: django-dbos
+Version: 0.1.0
+Summary: DBOS-backed backend for Django's tasks framework: durable background tasks, cron scheduling and optional Sentry monitoring.
+Project-URL: Homepage, https://github.com/lewoudar/django-dbos
+Project-URL: Repository, https://github.com/lewoudar/django-dbos
+Project-URL: Changelog, https://github.com/lewoudar/django-dbos/blob/main/CHANGELOG.md
+Author-email: Kevin Tewouda <rollandkev@yahoo.fr>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: asgiref>=3.8
+Requires-Dist: croniter>=6.0
+Requires-Dist: dbos<4,>=3.0
+Requires-Dist: django-click>=2.5.0
+Requires-Dist: django<7,>=6.0
+Requires-Dist: sqlalchemy<3,>=2.0
+Requires-Dist: structlog>=25.1
+Provides-Extra: cockroachdb
+Requires-Dist: psycopg2-binary>=2.9; extra == 'cockroachdb'
+Requires-Dist: sqlalchemy-cockroachdb>=2.0; extra == 'cockroachdb'
+Provides-Extra: metrics
+Requires-Dist: psutil>=7.0; extra == 'metrics'
+Provides-Extra: msgspec
+Requires-Dist: msgspec>=0.21; extra == 'msgspec'
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk>=2.19; extra == 'sentry'
+Provides-Extra: test
+Requires-Dist: pytest>=8.4; extra == 'test'
+Requires-Dist: testcontainers[postgres]>=4.13; extra == 'test'
+Description-Content-Type: text/markdown
+
+# django-dbos
+
+**⚠️ Experimental project. Do not use in production.**
+
+A [DBOS](https://docs.dbos.dev/)-backed backend for Django's
+[tasks framework](https://docs.djangoproject.com/en/stable/topics/tasks/):
+background tasks that survive a worker crash, cron scheduling, optional
+Sentry monitoring, an admin UI to inspect and operate on tasks, and a worker
+capacity report to drive autoscaling.
+
+## At a glance
+
+If you know Django's tasks API, you already know django-dbos:
+
+```python
+from django.tasks import task
+
+
+@task
+def send_welcome_email(user_id: int) -> None: ...
+
+
+result = send_welcome_email.enqueue(user_id)  # durable by default
+result.status  # READY, RUNNING, SUCCESSFUL, FAILED — standard Django TaskResult
+```
+
+Each enqueued task is recorded in a database before it runs. If the worker
+executing it crashes, the task is not lost: it runs again once a worker is
+back.
+
+## Why DBOS
+
+Say you send a newsletter to 10,000 users:
+
+```python
+from django.tasks import task
+
+
+@task
+def send_newsletter(campaign_id: int) -> None:
+    for user_id in User.objects.values_list('id', flat=True):
+        send_one_email(user_id, campaign_id)
+```
+
+With most task backends, if the worker is killed at email #6,000 — a deploy,
+an OOM, a spot instance reclaimed — the retry restarts the task from #1.
+6,000 people get the same email twice.
+
+With django-dbos, one option and one call per email turn the loop into a
+durable, checkpointed workflow:
+
+```python
+from django.tasks import task
+from django_dbos import dbos_params, get_dbos_context
+
+
+@dbos_params(durable_operations=True)
+@task
+def send_newsletter(campaign_id: int) -> None:
+    ctx = get_dbos_context()
+    for user_id in User.objects.values_list('id', flat=True):
+        ctx.run_step(send_one_email, user_id, campaign_id, name=f'email-{user_id}')
+```
+
+Each `run_step` call is recorded in the system database as it completes.
+Kill the worker at #6,000, restart it, and the task resumes from there: the
+5,999 emails already sent are skipped, and only the one in flight at the
+moment of the crash may go out again. No external state to reconcile, no
+idempotency keys to invent yourself.
+
+Cron schedules are just `@task`s with a firing time attached — same
+durability, same retries, same admin page:
+
+```python
+from django_dbos import cron
+
+
+@cron('0 3 * * *')  # every day at 3am
+@dbos_params(workflow_timeout=3600, step_retries_allowed=True)
+@task
+def nightly_report() -> None: ...
+```
+
+Schedules are stored in the system database, so they keep firing across
+restarts and deploys — and with the `sentry` extra installed, each firing
+checks in with [Sentry Crons](https://docs.sentry.io/product/crons/)
+automatically.
+
+## What you get
+
+- **Durable tasks** — every `.enqueue()` becomes a DBOS workflow: automatic
+  recovery after a crash, step retries with backoff, deferred execution
+  (`run_after`), deduplication, priorities and workflow timeouts, all through
+  Django's own `Task` / `TaskResult` API.
+- **Durable workflows** *(opt-in)* — checkpointed steps, durable sleeps that
+  survive restarts, progress events, messages between workflows and child
+  workflows, from inside a task.
+- **Cron scheduling** — `@cron('0 3 * * *')` on top of `@task`. Every worker
+  fires the schedules, each firing runs once, and no separate scheduler
+  process is needed.
+- **Sentry cron monitoring** *(optional)* — scheduled tasks check in with
+  [Sentry Crons](https://docs.sentry.io/product/crons/) automatically, no
+  monitor to configure by hand.
+- **Admin pages** — inspect every workflow (inputs, outputs, errors, step
+  history), and cancel, resume, fork or delete them; manage schedules; see
+  which workers are alive. Superuser-only.
+- **Worker capacity report** — `dbos status` (or `capacity.collect()` from
+  Python) reports backlog, running count and per-worker load per queue, with
+  a scale up/down/OK verdict you can plug into an autoscaler.
+- **Structured logging** — everything goes through
+  [structlog](https://www.structlog.org/) under the `django_dbos` logger.
+- **A pytest plugin** — `dbos_inline` runs enqueued tasks synchronously for
+  fast unit tests; `dbos_system` launches a real DBOS system database
+  (SQLite or a Postgres testcontainer) when you need real semantics.
+
+## Requirements
+
+- Python 3.12+
+- Django 6.0+
+- A DBOS system database: PostgreSQL (recommended) or SQLite
+
+## Installation
+
+```bash
+uv add django-dbos
+# or
+pip install django-dbos
+```
+
+Poetry and PDM work too, see
+[Installation](https://github.com/lewoudar/django-dbos/blob/main/docs/index.md#installation).
+Add the `msgspec` extra (`uv add "django-dbos[msgspec]"` or
+`pip install "django-dbos[msgspec]"`) for fast, safe serialization of task data; see
+[Serialization](https://github.com/lewoudar/django-dbos/blob/main/docs/configuration.md#serialization).
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'django_dbos',
+]
+
+TASKS = {
+    'default': {
+        'BACKEND': 'django_dbos.backends.DBOSBackend',
+        'QUEUES': ['default', 'emails'],
+        # other django-dbos settings go in 'OPTIONS', see the configuration docs
+    },
+}
+```
+
+```bash
+python manage.py migrate       # Django's migrations, then the DBOS system database
+python manage.py dbos worker   # start executing tasks
+```
+
+Put your tasks in a `tasks.py` module of an installed app: that is where the
+worker looks for them. Your web processes only ever talk to the system
+database — they enqueue tasks, they never execute them.
+
+New to background tasks? [Your first task](https://github.com/lewoudar/django-dbos/blob/main/docs/first-task.md) walks through
+writing, running and checking one, step by step.
+
+## Using an AI coding agent
+
+django-dbos ships an [agent skill](https://github.com/lewoudar/django-dbos/tree/main/skills/django-dbos)
+that teaches AI coding agents (Claude Code, Codex, Cursor, OpenCode, Pi...)
+how to write tasks, workflows and cron schedules with it. Install it with the
+[`skills`](https://github.com/vercel-labs/skills) CLI:
+
+```bash
+npx skills add lewoudar/django-dbos --skill django-dbos
+```
+
+[AI agents](https://github.com/lewoudar/django-dbos/blob/main/docs/ai-agents.md) has the command for each agent
+and how to install the skill by hand.
+
+## Examples
+
+Two runnable projects in [`examples/`](https://github.com/lewoudar/django-dbos/tree/main/examples/), each a standalone `uv`
+project you can `uv sync` and run on its own:
+
+- [`ninja_api`](https://github.com/lewoudar/django-dbos/tree/main/examples/ninja_api) — a [Django Ninja](https://django-ninja.dev/)
+  API that enqueues a task and polls its status until it's done.
+- [`cron_report`](https://github.com/lewoudar/django-dbos/tree/main/examples/cron_report) — a `@cron` task that fires on its
+  own once a worker is running, no external scheduler needed.
+
+## Documentation
+
+The full documentation lives in [`docs/`](https://github.com/lewoudar/django-dbos/tree/main/docs/) (a hosted version is coming
+once the repository goes public). Good places to start:
+
+- [Your first task](https://github.com/lewoudar/django-dbos/blob/main/docs/first-task.md) — a hands-on walkthrough.
+- [Tasks](https://github.com/lewoudar/django-dbos/blob/main/docs/tasks.md) and [Workflows](https://github.com/lewoudar/django-dbos/blob/main/docs/workflows.md) — options,
+  retries, durable primitives.
+- [Cron scheduling](https://github.com/lewoudar/django-dbos/blob/main/docs/cron.md) — schedules and Sentry monitors.
+- [Deployment](https://github.com/lewoudar/django-dbos/blob/main/docs/deployment.md) — what to settle before production.
+- [Troubleshooting](https://github.com/lewoudar/django-dbos/blob/main/docs/troubleshooting.md) — the errors you are most
+  likely to meet.
+
+## License
+
+MIT