livingai 0.4.0__tar.gz

livingai-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    defaults:
+      run:
+        working-directory: livingai_runtime
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install mypy
+
+      - name: Type check (mypy --strict)
+        run: mypy --strict livingai
+
+      - name: Run tests with coverage
+        run: |
+          coverage run -m pytest -q
+          coverage report -m --include="*/livingai/*" --fail-under=100
+
+  benchmark:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: livingai_runtime
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e .
+      - name: Run benchmarks
+        run: python benchmarks/benchmark.py --json

livingai-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: livingai_runtime
+    permissions:
+      id-token: write  # trusted publishing (OIDC), no API token needed
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: livingai_runtime/dist

livingai-0.4.0/.gitignore

@@ -0,0 +1,17 @@
+# Python caches / build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Local databases produced by SQLiteStore
+*.db
+*.sqlite
+*.sqlite3

livingai-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to Living AI Runtime
+
+Thanks for your interest in contributing! This is an infrastructure project, so
+the bar is **correctness and reliability first**. Boring, well-tested code wins.
+
+## Development setup
+
+```bash
+cd livingai_runtime
+python -m venv .venv && . .venv/bin/activate    # or your preferred env
+pip install -e ".[dev]"
+pip install mypy
+```
+
+The core has **zero runtime dependencies** — only the standard library. Do not
+add a runtime dependency to `livingai/` without discussion; it undermines the
+zero-config promise.
+
+## Running the checks locally
+
+Everything CI runs, you can run locally:
+
+```bash
+# Tests
+python -m pytest -q
+
+# Coverage (must stay at 100%)
+python -m coverage run -m pytest -q
+python -m coverage report -m --include="*/livingai/*" --fail-under=100
+
+# Strict type checking (must pass clean)
+python -m mypy --strict livingai
+
+# Benchmarks (sanity check performance)
+python benchmarks/benchmark.py
+```
+
+## Standards
+
+- **100% test coverage** on `livingai/`. New code needs new tests.
+- **`mypy --strict` clean.** Full type hints; the package ships `py.typed`.
+- **Async-first.** All I/O is `async`; provide sync wrappers only when needed.
+- **Append-only.** Never mutate stored records; write a new node version.
+- **No global state.** Engines and stores are independent instances.
+- Tests use plain `asyncio.run(...)` (no `pytest-asyncio` dependency).
+
+## Adding a new framework adapter
+
+Adapters are thin translation layers. Subclass
+[`BaseAdapter`](livingai/adapters/_base.py) and set three attributes:
+
+```python
+from livingai.adapters._base import BaseAdapter
+
+class MyFrameworkAdapter(BaseAdapter):
+    framework = "myframework"          # metadata["framework"] tag
+    node_key = "mf_node"               # metadata key for the node name
+    tool_hints = ("tool", "call", ...) # names that mark side-effecting TOOL nodes
+```
+
+Rules:
+
+- **Do not import the framework package.** Consume events as plain data so the
+  adapter runs anywhere and the core stays dependency-free.
+- Mark side-effecting steps as `TOOL` (auto non-idempotent) so recovery never
+  re-runs them. Allow explicit `idempotent=` overrides.
+- Add tests mirroring [`tests/test_more_adapters.py`](tests/test_more_adapters.py).
+- Export it from `livingai/adapters/__init__.py` and the top-level `livingai`.
+
+## Extending the storage protocol
+
+New backends (Redis, Postgres, ...) implement the
+[`CheckpointStore`](livingai/storage/__init__.py) protocol:
+
+```python
+async def write(node) -> None            # append-only
+async def read(node_id) -> ExecutionNode | None
+async def list_by_execution(execution_id) -> list[ExecutionNode]
+async def get_latest_checkpoint(execution_id) -> ExecutionNode | None
+```
+
+A new backend must pass the **same** test suite as `SQLiteStore`
+([`tests/test_sqlite_store.py`](tests/test_sqlite_store.py)) — parametrize the
+store fixture rather than duplicating tests.
+
+## Pull request checklist
+
+- [ ] Tests added/updated; `pytest` green.
+- [ ] Coverage at 100%.
+- [ ] `mypy --strict` clean.
+- [ ] Public API changes reflected in `docs/` and the top-level `__all__`.
+- [ ] No new runtime dependency in `livingai/` (unless discussed).
+- [ ] Commit messages are clear and scoped.
+
+## Reporting bugs
+
+Prefer a minimal reproduction using the in-memory `SQLiteStore()`. Include the
+Python version and the exact steps. For anything involving data loss or
+corruption, please flag it clearly — that is the highest-priority class of bug.

livingai-0.4.0/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 Living AI
+
+   A full copy of the Apache 2.0 license text is available at the URL above.

livingai-0.4.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: livingai
+Version: 0.4.0
+Summary: Checkpoint, recovery, and replay infrastructure for AI agents.
+Project-URL: Homepage, https://github.com/livingai/livingai
+Project-URL: Repository, https://github.com/livingai/livingai
+Project-URL: Documentation, https://github.com/livingai/livingai#readme
+Author: Living AI
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,checkpoint,llm,observability,recovery,replay
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: coverage>=7; extra == 'dev'
+Requires-Dist: fakeredis; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: redis>=4.2; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.28; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=4.2; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# Living AI
+
+**Crash recovery, checkpointing, and replay for AI agents — one runtime that works across LangGraph, CrewAI, and OpenAI Agents.**
+
+[![CI](https://img.shields.io/badge/CI-py3.9–3.12-brightgreen)](.github/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](#quality)
+[![Types](https://img.shields.io/badge/mypy-strict-blue)](#quality)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![Runtime deps](https://img.shields.io/badge/runtime%20deps-0-blueviolet)](pyproject.toml)
+
+---
+
+## The problem
+
+AI agents crash. A process dies mid-workflow — after the LLM reasoned, after the
+tool charged a card, three steps into a ten-step plan — and all of that work is
+gone. You restart from zero, pay for the tokens again, and hope the tool doesn't
+fire its side effects twice. And when something goes wrong, you can't replay what
+happened to understand *why*.
+
+## The solution
+
+Living AI records every step of an agent execution to an **append-only log**, so
+any run can be:
+
+- **Recovered** — resume from the last durable checkpoint after a crash, replaying
+  only the *idempotent* work and never re-running side-effecting tool calls
+  (payments, emails, API writes).
+- **Replayed** — re-run a recorded execution for debugging, with `MOCK_TOOLS` mode
+  returning recorded tool responses so you can iterate on reasoning without real
+  API calls.
+- **Audited** — inspect cost, latency, and the full node graph of any run.
+
+## Why it's different
+
+Most observability and checkpointing tools lock you into one framework. Living AI
+ships a **framework-agnostic core** with thin adapters for all three major agent
+frameworks — the same recovery guarantees whether you use LangGraph, CrewAI, or
+the OpenAI Agents SDK:
+
+```python
+from livingai.adapters import LangGraphAdapter, CrewAIAdapter, OpenAIAgentsAdapter
+```
+
+And the core has **zero runtime dependencies** — it's pure standard library.
+
+## Install
+
+```bash
+pip install livingai
+```
+
+## Crash recovery in 18 lines
+
+```python
+import asyncio
+from livingai import (
+    CheckpointEngine, ExecutionNode, NodeType, RecoveryEngine, SQLiteStore, Status,
+)
+
+
+async def main():
+    engine = CheckpointEngine(SQLiteStore("agent.db"))
+
+    # Your agent checkpoints after an expensive step.
+    step = ExecutionNode(execution_id="run-1", type=NodeType.PROMPT,
+                         status=Status.SUCCESS, output="plan ready")
+    await engine.save(step, state=b"...serialized agent state...")
+
+    # A tool with real side effects runs (e.g. charging a card).
+    charge = ExecutionNode(execution_id="run-1", type=NodeType.TOOL,
+                           status=Status.SUCCESS, output={"receipt": "R-1"})
+    await engine.save(charge)
+
+    # 💥 The process crashes. On restart, recover from the durable log:
+    recovery = RecoveryEngine(CheckpointEngine(SQLiteStore("agent.db")))
+    plan = await recovery.plan("run-1")
+    print("resume from :", plan.resume_node_id)        # last durable checkpoint
+    print("replay safe :", len(plan.replay_nodes))     # idempotent work to redo
+    print("skip effects:", len(plan.skipped_nodes))    # card is NOT re-charged
+
+
+asyncio.run(main())
+```
+
+```
+resume from : d482c31e-...
+replay safe : 0
+skip effects: 1          # the card is never charged twice
+```
+
+The [`examples/`](examples/README.md) directory has five runnable demos (crash
+recovery, `MOCK_TOOLS` debugging, cost tracking, and the LangGraph adapter) — none
+require an LLM or network.
+
+## Performance
+
+Checkpointing is on the hot path of every agent step, so it has to be fast. It is.
+
+| Metric | Result | Notes |
+| --- | --- | --- |
+| Checkpoint write (p50) | **~0.3 ms** | 50 KB compressed state blob |
+| Checkpoint write (p95) | **~0.8 ms** | |
+| Checkpoint write (p99) | **~1 ms** | ~50× under the 50 ms budget |
+| Hot recovery read | **~4 µs** | vs ~190 µs cold — ~40× faster |
+| Compression | **60–99%** | typical agent state (histories, docs) |
+
+Measured on a dev laptop with the **default 50 ms overhead budget**, 50 KB blobs,
+2000 writes — the same configuration you get out of the box. Reproduce with
+`python benchmarks/benchmark.py`.
+
+The overhead budget is enforced *in code*: a checkpoint write that would exceed it
+is dropped and logged as *missed* rather than ever blocking your agent thread.
+
+## How it works
+
+```
+ExecutionNode ──► CheckpointStore (Tier 2: durable, append-only)
+      ▲                  ▲
+      │                  │
+ Adapters          CheckpointEngine ──► HotCache (Tier 1: LRU + TTL)
+ (LangGraph/             │
+  CrewAI/           RecoveryEngine ──► RecoveryPlan (replay vs. skip)
+  OpenAI)           ReplaySession  ──► FULL / FROM_NODE / MOCK_TOOLS / COUNTERFACTUAL
+```
+
+Every execution is a DAG of `ExecutionNode` records. The log is never mutated,
+only appended to — so any point in time can be reconstructed deterministically.
+`TOOL` nodes default to **non-idempotent**, which is how recovery knows never to
+re-run side effects. See [docs/concepts.md](docs/concepts.md) for the full model.
+
+## CLI
+
+```bash
+livingai list   --db agent.db          # execution ids
+livingai show   run-1 --db agent.db    # the node graph
+livingai replay run-1 --db agent.db --mode MOCK_TOOLS
+```
+
+## Documentation
+
+[Quickstart](docs/quickstart.md) ·
+[Concepts](docs/concepts.md) ·
+[Checkpointing](docs/checkpointing.md) ·
+[Recovery](docs/recovery.md) ·
+[Replay](docs/replay.md) ·
+[CLI](docs/cli.md) ·
+[Adapters](docs/adapters.md) ·
+[Migrating from other checkpointers](docs/migration.md) ·
+[API Reference](docs/api-reference.md)
+
+## Quality
+
+- **108 tests, 100% line coverage** — including crash-simulation and stress tests
+  (10k-node graphs, concurrent writers, write contention).
+- **`mypy --strict` clean** across all source files; ships `py.typed`.
+- **CI matrix** on Python 3.9–3.12 with a 100%-coverage gate.
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q                    # run the suite
+mypy --strict livingai                 # type check
+python benchmarks/benchmark.py         # reproduce the numbers above
+```
+
+## Design principles
+
+| Principle | How |
+| --- | --- |
+| Zero-dependency core | Standard library only (`sqlite3`, `asyncio`, `zlib`, `dataclasses`, `uuid`). |
+| Append-only log | Every write inserts a new row; nothing is mutated or deleted. |
+| Framework-agnostic | No framework imports in the core; framework data lives in `metadata`. |
+| Async-first I/O | Storage is `async`; sync SQLite runs off the event loop. |
+| Bounded overhead | Cold writes run under `asyncio.wait_for`; overruns are dropped, never blocking the agent. |
+
+## Roadmap
+
+Shipped: core data model, checkpoint engine, recovery engine, replay engine, CLI,
+LangGraph / CrewAI / OpenAI adapters, benchmarks, docs, Redis store, PostgreSQL store.
+
+**Optional backends** — swap the default SQLite store for Redis or PostgreSQL
+with a single import (no core changes required):
+
+```bash
+pip install "livingai[redis]"     # hot Redis store
+pip install "livingai[postgres]"  # PostgreSQL cold store
+```
+
+```python
+from livingai.stores.redis import RedisStore
+from livingai.stores.postgres import PostgresStore
+
+# Redis
+engine = CheckpointEngine(RedisStore(url="redis://localhost:6379"))
+
+# PostgreSQL
+store = PostgresStore(dsn="postgresql://user:pass@localhost/livingai")
+await store.initialize()          # creates tables once
+engine = CheckpointEngine(store)
+```
+
+A **Docker Compose** dev stack (Postgres + Redis) ships with the repo:
+
+```bash
+docker compose up -d    # starts postgres:5432 + redis:6379
+```
+
+Next: FastAPI cloud backend (5 endpoints), cloud client (`CloudSync`), web replay dashboard.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, running tests, code
+style, and how to add a new framework adapter or storage backend.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

livingai-0.4.0/README.md

@@ -0,0 +1,217 @@
+# Living AI
+
+**Crash recovery, checkpointing, and replay for AI agents — one runtime that works across LangGraph, CrewAI, and OpenAI Agents.**
+
+[![CI](https://img.shields.io/badge/CI-py3.9–3.12-brightgreen)](.github/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](#quality)
+[![Types](https://img.shields.io/badge/mypy-strict-blue)](#quality)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![Runtime deps](https://img.shields.io/badge/runtime%20deps-0-blueviolet)](pyproject.toml)
+
+---
+
+## The problem
+
+AI agents crash. A process dies mid-workflow — after the LLM reasoned, after the
+tool charged a card, three steps into a ten-step plan — and all of that work is
+gone. You restart from zero, pay for the tokens again, and hope the tool doesn't
+fire its side effects twice. And when something goes wrong, you can't replay what
+happened to understand *why*.
+
+## The solution
+
+Living AI records every step of an agent execution to an **append-only log**, so
+any run can be:
+
+- **Recovered** — resume from the last durable checkpoint after a crash, replaying
+  only the *idempotent* work and never re-running side-effecting tool calls
+  (payments, emails, API writes).
+- **Replayed** — re-run a recorded execution for debugging, with `MOCK_TOOLS` mode
+  returning recorded tool responses so you can iterate on reasoning without real
+  API calls.
+- **Audited** — inspect cost, latency, and the full node graph of any run.
+
+## Why it's different
+
+Most observability and checkpointing tools lock you into one framework. Living AI
+ships a **framework-agnostic core** with thin adapters for all three major agent
+frameworks — the same recovery guarantees whether you use LangGraph, CrewAI, or
+the OpenAI Agents SDK:
+
+```python
+from livingai.adapters import LangGraphAdapter, CrewAIAdapter, OpenAIAgentsAdapter
+```
+
+And the core has **zero runtime dependencies** — it's pure standard library.
+
+## Install
+
+```bash
+pip install livingai
+```
+
+## Crash recovery in 18 lines
+
+```python
+import asyncio
+from livingai import (
+    CheckpointEngine, ExecutionNode, NodeType, RecoveryEngine, SQLiteStore, Status,
+)
+
+
+async def main():
+    engine = CheckpointEngine(SQLiteStore("agent.db"))
+
+    # Your agent checkpoints after an expensive step.
+    step = ExecutionNode(execution_id="run-1", type=NodeType.PROMPT,
+                         status=Status.SUCCESS, output="plan ready")
+    await engine.save(step, state=b"...serialized agent state...")
+
+    # A tool with real side effects runs (e.g. charging a card).
+    charge = ExecutionNode(execution_id="run-1", type=NodeType.TOOL,
+                           status=Status.SUCCESS, output={"receipt": "R-1"})
+    await engine.save(charge)
+
+    # 💥 The process crashes. On restart, recover from the durable log:
+    recovery = RecoveryEngine(CheckpointEngine(SQLiteStore("agent.db")))
+    plan = await recovery.plan("run-1")
+    print("resume from :", plan.resume_node_id)        # last durable checkpoint
+    print("replay safe :", len(plan.replay_nodes))     # idempotent work to redo
+    print("skip effects:", len(plan.skipped_nodes))    # card is NOT re-charged
+
+
+asyncio.run(main())
+```
+
+```
+resume from : d482c31e-...
+replay safe : 0
+skip effects: 1          # the card is never charged twice
+```
+
+The [`examples/`](examples/README.md) directory has five runnable demos (crash
+recovery, `MOCK_TOOLS` debugging, cost tracking, and the LangGraph adapter) — none
+require an LLM or network.
+
+## Performance
+
+Checkpointing is on the hot path of every agent step, so it has to be fast. It is.
+
+| Metric | Result | Notes |
+| --- | --- | --- |
+| Checkpoint write (p50) | **~0.3 ms** | 50 KB compressed state blob |
+| Checkpoint write (p95) | **~0.8 ms** | |
+| Checkpoint write (p99) | **~1 ms** | ~50× under the 50 ms budget |
+| Hot recovery read | **~4 µs** | vs ~190 µs cold — ~40× faster |
+| Compression | **60–99%** | typical agent state (histories, docs) |
+
+Measured on a dev laptop with the **default 50 ms overhead budget**, 50 KB blobs,
+2000 writes — the same configuration you get out of the box. Reproduce with
+`python benchmarks/benchmark.py`.
+
+The overhead budget is enforced *in code*: a checkpoint write that would exceed it
+is dropped and logged as *missed* rather than ever blocking your agent thread.
+
+## How it works
+
+```
+ExecutionNode ──► CheckpointStore (Tier 2: durable, append-only)
+      ▲                  ▲
+      │                  │
+ Adapters          CheckpointEngine ──► HotCache (Tier 1: LRU + TTL)
+ (LangGraph/             │
+  CrewAI/           RecoveryEngine ──► RecoveryPlan (replay vs. skip)
+  OpenAI)           ReplaySession  ──► FULL / FROM_NODE / MOCK_TOOLS / COUNTERFACTUAL
+```
+
+Every execution is a DAG of `ExecutionNode` records. The log is never mutated,
+only appended to — so any point in time can be reconstructed deterministically.
+`TOOL` nodes default to **non-idempotent**, which is how recovery knows never to
+re-run side effects. See [docs/concepts.md](docs/concepts.md) for the full model.
+
+## CLI
+
+```bash
+livingai list   --db agent.db          # execution ids
+livingai show   run-1 --db agent.db    # the node graph
+livingai replay run-1 --db agent.db --mode MOCK_TOOLS
+```
+
+## Documentation
+
+[Quickstart](docs/quickstart.md) ·
+[Concepts](docs/concepts.md) ·
+[Checkpointing](docs/checkpointing.md) ·
+[Recovery](docs/recovery.md) ·
+[Replay](docs/replay.md) ·
+[CLI](docs/cli.md) ·
+[Adapters](docs/adapters.md) ·
+[Migrating from other checkpointers](docs/migration.md) ·
+[API Reference](docs/api-reference.md)
+
+## Quality
+
+- **108 tests, 100% line coverage** — including crash-simulation and stress tests
+  (10k-node graphs, concurrent writers, write contention).
+- **`mypy --strict` clean** across all source files; ships `py.typed`.
+- **CI matrix** on Python 3.9–3.12 with a 100%-coverage gate.
+
+```bash
+pip install -e ".[dev]"
+python -m pytest -q                    # run the suite
+mypy --strict livingai                 # type check
+python benchmarks/benchmark.py         # reproduce the numbers above
+```
+
+## Design principles
+
+| Principle | How |
+| --- | --- |
+| Zero-dependency core | Standard library only (`sqlite3`, `asyncio`, `zlib`, `dataclasses`, `uuid`). |
+| Append-only log | Every write inserts a new row; nothing is mutated or deleted. |
+| Framework-agnostic | No framework imports in the core; framework data lives in `metadata`. |
+| Async-first I/O | Storage is `async`; sync SQLite runs off the event loop. |
+| Bounded overhead | Cold writes run under `asyncio.wait_for`; overruns are dropped, never blocking the agent. |
+
+## Roadmap
+
+Shipped: core data model, checkpoint engine, recovery engine, replay engine, CLI,
+LangGraph / CrewAI / OpenAI adapters, benchmarks, docs, Redis store, PostgreSQL store.
+
+**Optional backends** — swap the default SQLite store for Redis or PostgreSQL
+with a single import (no core changes required):
+
+```bash
+pip install "livingai[redis]"     # hot Redis store
+pip install "livingai[postgres]"  # PostgreSQL cold store
+```
+
+```python
+from livingai.stores.redis import RedisStore
+from livingai.stores.postgres import PostgresStore
+
+# Redis
+engine = CheckpointEngine(RedisStore(url="redis://localhost:6379"))
+
+# PostgreSQL
+store = PostgresStore(dsn="postgresql://user:pass@localhost/livingai")
+await store.initialize()          # creates tables once
+engine = CheckpointEngine(store)
+```
+
+A **Docker Compose** dev stack (Postgres + Redis) ships with the repo:
+
+```bash
+docker compose up -d    # starts postgres:5432 + redis:6379
+```
+
+Next: FastAPI cloud backend (5 endpoints), cloud client (`CloudSync`), web replay dashboard.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, running tests, code
+style, and how to add a new framework adapter or storage backend.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).