[FEAT]: Dapr-Backed Blackboard State Store

docs/examples/index.md

@@ -11,9 +11,9 @@ Learn by example! Explore working code samples demonstrating Flock's features an
 
 Explore the numbered example folders in this repository:
 
-- **01 — The Declarative Way** (`examples/01-the-declarative-way`) — minimal and focused
-- **02 — The Blackboard** (`examples/02-the-blackboard`) — architecture overview
-- **03 — The Dashboard** (`examples/03-the-dashboard`) — real-time monitoring
+- **01 — Getting Started** (`examples/01-getting-started`) — minimal and focused
+- **02 — Patterns** (`examples/02-patterns`) — architecture and flow patterns
+- **04 — Misc** (`examples/04-misc`) — dashboard and persistence demos
 
 ### Component Examples
 **Learn to build custom components and engines**
@@ -44,12 +44,19 @@ These examples show how to extend Flock with custom logic:
 ### Feature Examples
 **Focused examples for specific capabilities**
 
-Feature-focused examples are integrated into the folders above (e.g., dashboard edge cases). Additional feature demos may be added over time.
+Feature-focused examples are integrated into the folders above (for example dashboard edge cases). Additional feature demos may be added over time.
+
+### Dapr Examples
+**Run Flock with Dapr-backed state stores**
+
+- **12 — Dapr** (`examples/12-dapr`) — in-memory, Redis encrypted, and PostgreSQL state-store setups
+
+Start here for setup details: `examples/12-dapr/README.md`
 
 ### Dashboard Examples
 **Interactive dashboard demonstrations**
 
-Check out `examples/03-the-dashboard` to explore:
+Check out `examples/04-misc` to explore:
 
 - **Declarative Pizza** - Single-agent dashboard demo
 - **Edge Cases** - Multi-agent cascades and filtering
@@ -108,10 +115,10 @@ git clone https://github.com/whiteducksoftware/flock.git
 cd flock
 
 # Run a minimal example
-python examples/01-the-declarative-way/01_declarative_pizza.py
+python examples/01-getting-started/01_declarative_pizza.py
 
 # Run with dashboard
-python examples/03-the-dashboard/01_declarative_pizza.py
+python examples/04-misc/02-dashboard-edge-cases.py
 ```
 
 ---
@@ -151,15 +158,15 @@ async def main():
 asyncio.run(main())
 ```
 
-Run it locally: `python examples/01-the-declarative-way/01_declarative_pizza.py`
+Run it locally: `python examples/01-getting-started/01_declarative_pizza.py`
 
 ---
 
 ### 2. Dashboard Edge Cases
 
 **What it demonstrates:** Agent cascades, filtering, and real-time updates
 
-Run: `python examples/03-the-dashboard/02-dashboard-edge-cases.py`
+Run: `python examples/04-misc/02-dashboard-edge-cases.py`
 
 ---
 
@@ -180,7 +187,7 @@ await orchestrator.serve(
 )
 ```
 
-Run: `python examples/03-the-dashboard/01_declarative_pizza.py`
+Run: `python examples/04-misc/02-dashboard-edge-cases.py`
 
 ---
 

docs/getting-started/index.md

@@ -40,6 +40,14 @@ Welcome to Flock! This section will help you get up and running quickly with the
 
     [:octicons-arrow-right-24: Server Components Concepts](server-components-concepts.md)
 
+-   **🧱 Dapr State Store**
+
+    ---
+
+    Optional distributed persistence with Dapr-backed state stores.
+
+    [:octicons-arrow-right-24: Dapr State Store Guide](../guides/dapr-state-store.md)
+
 </div>
 
 ---

docs/getting-started/quick-start.md

@@ -30,6 +30,8 @@ export DEFAULT_MODEL="openai/gpt-4.1"
 
 **That's it.** Flock works with any LiteLLM-supported model (OpenAI, Anthropic, Azure, local models, etc.).
 
+Need distributed blackboard persistence? See [Dapr State Store Integration](../guides/dapr-state-store.md).
+
 ---
 
 ## Your First Agent (60 Seconds)

docs/guides/blackboard.md

@@ -531,20 +531,26 @@ await flock.store.clear()
 
 ### Memory Management
 
-**Current limitation:** Blackboard is in-memory only (v0.5.0)
+Flock supports multiple blackboard storage backends depending on your deployment needs.
 
 ```python
-# ⚠️ In-memory only
-# After 10,000 artifacts, memory usage grows
-# Restart required to clear
+# In-memory store (default)
+flock = Flock("openai/gpt-4.1")
+
+# SQLite store (local durable history)
+from flock.store import SQLiteBlackboardStore
+flock = Flock("openai/gpt-4.1", store=SQLiteBlackboardStore(".flock/history.db"))
 
-# ✅ v1.0 will support:
-# - Redis backend (distributed state)
-# - PostgreSQL backend (persistent history)
-# - Automatic artifact expiration
-# - Query by time range
+# Dapr store (distributed backend)
+from flock.storage import DaprStateBlackboardStore, DaprStateBlackboardConfig
+flock = Flock(
+    "openai/gpt-4.1",
+    store=DaprStateBlackboardStore(DaprStateBlackboardConfig(store_name="flockstate")),
+)
 ```
 
+For backend-specific guidance, see the [Persistent Blackboard guide](persistent-blackboard.md) and the [Dapr State Store guide](dapr-state-store.md).
+
 ### Observability
 
 **Enable tracing to see artifact flow:**

docs/guides/dapr-state-store.md

@@ -0,0 +1,184 @@
+---
+title: Dapr State Store Integration
+description: Use Dapr-supported state stores as an optional distributed blackboard backend for Flock.
+tags:
+  - blackboard
+  - persistence
+  - dapr
+  - integrations
+search:
+  boost: 1.4
+---
+
+# Dapr State Store Integration
+
+Flock includes Dapr-backed blackboard storage as an optional feature. This lets you keep your existing agent and artifact model while switching the backend from local storage to any Dapr-supported state store.
+
+Use Dapr storage when you need distributed state, backend-level encryption, or backend-specific TTL and query capabilities.
+
+---
+
+## Install
+
+For this repository:
+
+```bash
+uv sync --extra dapr
+```
+
+For external projects using Flock:
+
+```bash
+uv add "flock-core[dapr]"
+```
+
+If you only need local durable history in a single process, prefer SQLite via [Persistent Blackboard History](persistent-blackboard.md).
+
+---
+
+## Quick Start
+
+```python
+from flock import Flock
+from flock.storage import (
+    DaprStateBlackboardConfig,
+    DaprStateBlackboardStore,
+    DaprStateBlackboardStoreClientConfig,
+)
+
+client_config = DaprStateBlackboardStoreClientConfig(
+    dapr_grpc_endpoint="localhost:50001",
+)
+
+store_config = DaprStateBlackboardConfig(
+    store_name="flockstate",       # must match Dapr component metadata.name
+    supports_transactions=True,
+    supports_etag=True,
+    consistency="strong",          # eventual | strong | unspecified
+    client_config=client_config,
+)
+
+store = DaprStateBlackboardStore(config=store_config)
+
+flock = Flock(
+    model="openai/gpt-4.1",
+    store=store,
+)
+```
+
+The rest of your agent setup stays unchanged.
+
+### Backend Capability Notes
+
+- `supports_transactions=True` is recommended for unencrypted Redis/PostgreSQL backends.
+- For encrypted Redis (`encrypted_backend=True`), transactions are automatically disabled by the store implementation because of a Dapr runtime limitation.
+- Enable `supports_dapr_query_lang=True` only when your selected state store/component actually supports Dapr query API.
+
+---
+
+## Backend Matrix
+
+The examples in this repository include three reference Dapr setups:
+
+| Backend | Example Directory | Encryption | Transactions | Query API | TTL |
+| --- | --- | --- | --- | --- | --- |
+| In-memory | `examples/12-dapr/inmemory/` | No | No | No | No |
+| Redis (encrypted) | `examples/12-dapr/redis_encrypted/` | Yes | Yes | Yes | Yes |
+| PostgreSQL 17 | `examples/12-dapr/postgresql_unencrypted/` | No | Yes | No | No |
+
+---
+
+## Configuration Reference
+
+### DaprStateBlackboardConfig
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| store_name | str | statestore | Dapr component name (metadata.name) |
+| supports_ttl | bool | False | Enable TTL-based expiration if backend supports TTL |
+| encrypted_backend | bool | False | Use Dapr encryption metadata path |
+| backend_encryption_key | str \| None | None | Optional encryption key when encrypted backend is enabled |
+| supports_transactions | bool | False | Use execute_state_transaction for atomic writes |
+| supports_dapr_query_lang | bool | False | Enable Dapr query API paths |
+| supports_etag | bool | False | Enable optimistic concurrency with ETags |
+| etag_max_retries | int | 3 | Retries on ETag conflict |
+| consistency | str | unspecified | eventual, strong, or unspecified |
+| entries_ttl_seconds | int \| None | None | TTL in seconds when supports_ttl is enabled |
+| client_config | DaprStateBlackboardStoreClientConfig \| None | None | Optional Dapr client settings |
+
+### DaprStateBlackboardStoreClientConfig
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| dapr_grpc_endpoint | str \| None | None | Dapr gRPC endpoint, for example localhost:50001 |
+| headers_callback | Callable \| None | None | Request headers callback |
+| interceptors | list \| None | None | gRPC interceptors |
+| http_timeout_seconds | int \| None | None | HTTP timeout for Dapr SDK calls |
+| max_grpc_message_length | int \| None | None | Max gRPC message size |
+| retry_policy | RetryPolicy \| None | None | Dapr SDK retry policy |
+
+---
+
+## Known Limitations
+
+- Encryption and transactions cannot be combined due to a Dapr runtime transaction serialization issue; Flock automatically falls back to non-transactional writes for encrypted backends.
+- Dapr query support depends on the selected state store and component implementation.
+- TTL support depends on backend capabilities.
+- Distributed writes can still race across multiple Flock instances; use ETags where supported.
+
+---
+
+## Run The Example Stacks
+
+Only run one backend stack at a time because they share host ports.
+
+1. In-memory backend:
+
+```bash
+cd examples/12-dapr/inmemory
+cp secrets.example.json secrets.json
+docker compose up -d
+```
+
+2. Redis encrypted backend:
+
+```bash
+cd examples/12-dapr/redis_encrypted
+cp secrets.example.json secrets.json
+docker compose up -d
+```
+
+3. PostgreSQL backend:
+
+```bash
+cd examples/12-dapr/postgresql_unencrypted
+cp secrets.example.json secrets.json
+docker compose up -d
+```
+
+For all three setups, copy `secrets.example.json` to `secrets.json` and fill in required keys before running.
+
+Then run the matching example script from repository root:
+
+```bash
+export DAPR_GRPC_ENDPOINT="localhost:50001"
+
+uv run python examples/12-dapr/inmemory/flock_dapr_inmemory.py
+# or
+uv run python examples/12-dapr/redis_encrypted/flock_dapr_redis.py
+# or
+uv run python examples/12-dapr/postgresql_unencrypted/flock_dapr_postgresql.py
+```
+
+---
+
+## Choosing SQLite vs Dapr
+
+- Choose SQLite for single-node durable history and simple local operations.
+- Choose Dapr for shared distributed state, pluggable backend infrastructure, and backend-specific capabilities.
+
+For SQLite-focused persistence and dashboard history workflows, see the [Persistent Blackboard guide](persistent-blackboard.md).
+
+For full Dapr example details, see [examples/12-dapr/README.md](https://github.com/whiteducksoftware/flock/tree/main/examples/12-dapr/README.md).
+
+You can also browse runnable setup variants in [Examples Index](../examples/index.md).

docs/guides/index.md

@@ -80,6 +80,14 @@ Comprehensive guides for building production-ready multi-agent systems with Floc
 
 <div class="grid cards" markdown>
 
+-   **🧱 Dapr State Store Integration**
+
+    ---
+
+    Plug Redis, PostgreSQL, or other Dapr-supported state stores into Flock's blackboard backend.
+
+    [:octicons-arrow-right-24: Dapr State Store Guide](dapr-state-store.md)
+
 -   **🦞 OpenClaw Integration**
 
     ---

docs/guides/persistent-blackboard.md

@@ -21,7 +21,7 @@ The in-memory blackboard is perfect for local prototyping, but production teams
 - **Replay & Audits** — Inspect any published artifact (including payloads, tags, visibility, version, correlation IDs) even after the orchestrator restarts.
 - **Lifecycle Analytics** — Summaries and agent history endpoints expose production/consumption counts, visibility breakdowns, and tag trends over arbitrary windows.
 - **Operator Experience** — Dashboard users can scroll back through previous runs, inspect payload details, and view retention banners that explain how far history goes.
-- **Future Backends** — The updated store interface (`FilterConfig`, `ArtifactEnvelope`) paves the way for Postgres, DuckDB, or cloud warehouses with identical semantics.
+- **Alternative Backends** — The same store contract also supports distributed backends via Dapr state stores.
 
 ---
 
@@ -48,6 +48,23 @@ Key capabilities:
 
 ---
 
+## Choosing SQLite vs Dapr
+
+Use this quick matrix when deciding which store to use:
+
+| Option | Best For | Persistence Scope | Tradeoffs |
+| --- | --- | --- | --- |
+| In-memory (default) | Local prototyping and tests | Process lifetime only | Fastest setup, but data is lost on restart |
+| SQLiteBlackboardStore | Single-node durable history | Local file persistence | Simple operations, but not a shared distributed backend |
+| DaprStateBlackboardStore | Shared/distributed blackboard workloads | Depends on chosen Dapr state store | Flexible backend choice, but requires Dapr sidecar + component setup |
+
+- Use SQLite when you want local durable history for a single-node deployment.
+- Use Dapr-backed storage when you need shared/distributed state or backend-specific capabilities such as store-managed encryption and TTL.
+
+See [Dapr State Store Integration](dapr-state-store.md) for distributed setup options.
+
+---
+
 ## Historical APIs
 
 Once the SQLite store is active, the HTTP control plane exposes richer endpoints:

docs/index.md

@@ -120,6 +120,14 @@ await flock.serve(dashboard=True)
 
     [Guides →](guides/index.md){ .md-button }
 
+-   :material-database: **Dapr State Store**
+
+    ---
+
+    Use Redis, PostgreSQL, or other Dapr-supported state stores as distributed blackboard backends.
+
+    [Dapr Guide →](guides/dapr-state-store.md){ .md-button }
+
 -   :material-api: **API Reference**
 
     ---