{
  "markdown": "# Rakaia\n\n**Rakaia** is a Python implementation of the [Durable Streams protocol](docs/protocol.md) —\nan HTTP-based protocol for append-only, ordered, durable byte streams.\n\nIt ships two installable packages:\n\n- **`rakaia`** — A zero-dependency ASGI app implementing the protocol. Run it\n  standalone (`uvicorn`/`daphne`/`granian`) or mount it inside Django/FastAPI/Starlette.\n- **`django_rakaia`** — A Django app with normalized stream models, a\n  `@stream_model` decorator, Channels-based SSE broadcasting, and an admin\n  interface.\n\n## Install\n\n```bash\npip install rakaia-streams                 # core protocol server\npip install \"rakaia-streams[django]\"       # + Django integration\npip install \"rakaia-streams[django,prod]\"  # + channels-redis + hypercorn for prod\n```\n\nThe distribution is named `rakaia-streams` on PyPI (plain `rakaia` was already\ntaken); the import names are unchanged — `import rakaia`, `import django_rakaia`.\n\nAlready using rakaia from a pinned git revision? See\n[`UPGRADING.md`](UPGRADING.md) before bumping the pin — the distribution rename\nabove is itself a breaking change for a `[tool.uv.sources]` entry spelled\n`rakaia`.\n\n## Quick start (standalone)\n\n```bash\npip install rakaia-streams uvicorn\nuvicorn rakaia:app --port 4437\n```\n\n```python\nfrom rakaia import create_app, StreamStore\n\napp = create_app()  # in-memory store\napp = create_app(store=StreamStore())\n```\n\n## Quick start (Django)\n\n```python\n# models.py\nfrom dataclasses import dataclass\nfrom django.db import models\nfrom django_rakaia.decorators import stream_model\n\n\n@dataclass\nclass RoomData:\n    id: int\n    name: str\n\n\n@stream_model(\n    stream_paths=lambda obj: f\"room:{obj.id}:messages\",\n    to_dataclass=lambda obj: RoomData(id=obj.id, name=obj.name),\n)\nclass ChatRoom(models.Model):\n    name = models.CharField(max_length=100)\n```\n\nEvery save/delete now emits a stream event you can subscribe to over SSE.\n\n## Documentation\n\nThe documentation site is built with [Zensical](https://zensical.org/).\n\n```bash\nuv sync --extra docs\nuv run zensical serve   # live preview at http://localhost:8000\nuv run zensical build   # static build into ./site\n```\n\nPages live in [`docs/`](docs/) and the site config is in\n[`zensical.toml`](zensical.toml):\n\n- [Overview & quick start](docs/index.md)\n- [**What's new — a guided tour**](docs/whats-new.md) — start here to see the recent features, each with a one-command demo\n- [Glossary](docs/glossary.md) — plain-language definitions of the event-sourcing terms\n- [Django integration](docs/django-integration.md)\n- [Versioned handlers](docs/versioned-handlers.md)\n- [Projections & fan-out](docs/projections-and-fan-out.md)\n- [Dry-run & executors](docs/dry-run-and-executors.md)\n- [Translations](docs/translations.md) (example)\n- [Deployment](docs/deployment.md)\n- [Protocol specification](docs/protocol.md) · [Backend storage](docs/streams-backend-storage.md)\n\n## Versioned handlers (event replay with history)\n\nRakaia ships a subsystem for replaying a stream through handlers whose\n*current* and *historical* versions are both kept in source. Handlers are\npure — they return `Effect` descriptions that an executor applies via\nidempotent `update_or_create`, so replay can be re-run safely.\n\n```python\nfrom rakaia import Upsert, register_handler, register_upcaster\n\n\n@register_handler(\n    name=\"mogrify\", event_match=\"room:*:messages\", effective_from=0, effective_to=10_000\n)\ndef mogrify_v1(event):\n    return Upsert(\n        model_label=\"myapp.Room\",\n        lookup={\"id\": event[\"room_id\"]},\n        defaults={\"name\": event[\"name\"]},\n    )\n\n\n@register_handler(name=\"mogrify\", event_match=\"room:*:messages\", effective_from=10_000)\ndef mogrify_v2(event):  # bugfix only for events from seq 10_000 onward\n    ...\n\n\n@register_upcaster(event_match=\"room:*:messages\", from_version=1)\ndef upcast_v1_to_v2(event):  # schema-shape change handled separately\n    return {**event, \"currency\": \"USD\"}\n```\n\n`python manage.py replay room:5:messages --from 0` then runs every event\nthrough its time-correct handler version, with drift detection (`--strict-drift`)\nand dry-run (`--dry-run`) modes.\n\nSee [`docs/versioned-handlers.md`](docs/versioned-handlers.md) for the\nfull story, including a worked example based on Partisipa's submissions\npipeline.\n\n## Sample applications\n\nEach example demonstrates one feature area end-to-end. Most are standalone Django\nprojects; two are zero-dependency scripts (no Django). Run them all with\n`just demo`, or individually:\n\n| Example | Demonstrates | Run |\n|---|---|---|\n| [`examples/orders/`](examples/orders/) | Versioned handlers, upcasters, replay, dry-run | `just orders-demo` |\n| [`examples/formkit_submissions/`](examples/formkit_submissions/) | Projections/fan-out, `reconcile_children`, migration parity | `just formkit-demo` |\n| [`examples/protocol_streams/`](examples/protocol_streams/) | Protocol layer (no Django): producer fencing, close, `poll` cursors | `just protocol-demo` |\n| [`examples/multi_owner/`](examples/multi_owner/) | Effect primitives (no Django): `Ref`, `reconcile_aggregate(owns=)` | `just multi-owner-demo` |\n| [`examples/chat/`](examples/chat/) | `@stream_model`, multi-stream events, live SSE | `just dev` |\n| [`examples/polyglot/`](examples/polyglot/) | Language-scoped streams, live-editable translations | `just polyglot-dev` |\n\nFor the full catalog with a concept-coverage matrix, see\n[`docs/examples.md`](docs/examples.md) (human) or the machine-readable\n[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog)\nbundle in [`okf/`](okf/) (agents/tools). For a narrated walkthrough, see\n[`docs/whats-new.md`](docs/whats-new.md).\n\n## Running it\n\nIf you have [`just`](https://github.com/casey/just) and `podman`:\n\n```bash\njust install\njust dev      # single-worker dev server\njust serve    # production-style: 4 hypercorn workers + Redis (podman)\n```\n\n`just --list` shows everything. The full guide is in\n[`docs/deployment.md`](docs/deployment.md).\n\n## Development\n\n```bash\njust install\njust check   # lint + format + types + tests + docs build\n```\n\nOr by hand:\n\n```bash\nuv sync --extra dev --extra django\nuv run pytest\nuv run ruff check src/\nuv run pyright src/\n```\n\n### Protocol conformance\n\nBeyond the pytest suite, rakaia is checked against the upstream, language-agnostic\n[`@durable-streams/server-conformance-tests`](https://github.com/durable-streams/durable-streams/tree/main/packages/server-conformance-tests)\ncompliance suite:\n\n```bash\njust conformance   # starts rakaia, runs the suite against it, tears it down (needs node/npm)\n```\n\nThis runs in CI as a non-blocking check (`.github/workflows/conformance.yml`).\nrakaia passes the full protocol surface today except the stream **forking**\nfamily, which is not yet implemented. See [`conformance/README.md`](conformance/README.md).\n\n## License\n\nMIT.\n",
  "bytes": 6825,
  "sha": "3d9cc7c6ea821b17de27c935190380a74e32b31a73263d0082ec3d9f0f3fec37",
  "repo_slug": "joshbrooks/rakaia",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_joshbrooks_rakaia_okf_index_md_6af0f22d/readme"
}