flock-core 0.5.9__py3-none-any.whl → 0.5.11__py3-none-any.whl

flock/store.py

@@ -227,7 +227,9 @@ class InMemoryBlackboardStore(BlackboardStore):
         self._lock = Lock()
         self._by_id: dict[UUID, Artifact] = {}
         self._by_type: dict[str, list[Artifact]] = defaultdict(list)
-        self._consumptions_by_artifact: dict[UUID, list[ConsumptionRecord]] = defaultdict(list)
+        self._consumptions_by_artifact: dict[UUID, list[ConsumptionRecord]] = (
+            defaultdict(list)
+        )
         self._agent_snapshots: dict[str, AgentSnapshotRecord] = {}
 
     async def publish(self, artifact: Artifact) -> None:
@@ -254,7 +256,9 @@ class InMemoryBlackboardStore(BlackboardStore):
             artifacts = self._by_type.get(canonical, [])
             return [artifact_type(**artifact.payload) for artifact in artifacts]  # type: ignore
 
-    async def extend(self, artifacts: Iterable[Artifact]) -> None:  # pragma: no cover - helper
+    async def extend(
+        self, artifacts: Iterable[Artifact]
+    ) -> None:  # pragma: no cover - helper
         for artifact in artifacts:
             await self.publish(artifact)
 
@@ -280,7 +284,9 @@ class InMemoryBlackboardStore(BlackboardStore):
         filters = filters or FilterConfig()
         canonical: set[str] | None = None
         if filters.type_names:
-            canonical = {type_registry.resolve_name(name) for name in filters.type_names}
+            canonical = {
+                type_registry.resolve_name(name) for name in filters.type_names
+            }
 
         visibility_filter = filters.visibility or set()
 
@@ -347,7 +353,9 @@ class InMemoryBlackboardStore(BlackboardStore):
             if not isinstance(artifact, Artifact):
                 raise TypeError("Expected Artifact instance")
             by_type[artifact.type] = by_type.get(artifact.type, 0) + 1
-            by_producer[artifact.produced_by] = by_producer.get(artifact.produced_by, 0) + 1
+            by_producer[artifact.produced_by] = (
+                by_producer.get(artifact.produced_by, 0) + 1
+            )
             kind = getattr(artifact.visibility, "kind", "Unknown")
             by_visibility[kind] = by_visibility.get(kind, 0) + 1
             for tag in artifact.tags:
@@ -476,7 +484,9 @@ class SQLiteBlackboardStore(BlackboardStore):
                 "version": artifact.version,
                 "visibility": visibility_json,
                 "tags": tags_json,
-                "correlation_id": str(artifact.correlation_id) if artifact.correlation_id else None,
+                "correlation_id": str(artifact.correlation_id)
+                if artifact.correlation_id
+                else None,
                 "partition_key": artifact.partition_key,
                 "created_at": created_at,
             }
@@ -816,7 +826,8 @@ class SQLiteBlackboardStore(BlackboardStore):
         by_visibility_rows = await cursor.fetchall()
         await cursor.close()
         by_visibility = {
-            (row["visibility_kind"] or "Unknown"): row["count"] for row in by_visibility_rows
+            (row["visibility_kind"] or "Unknown"): row["count"]
+            for row in by_visibility_rows
         }
 
         tag_query = f"""
@@ -839,7 +850,9 @@ class SQLiteBlackboardStore(BlackboardStore):
         cursor = await conn.execute(range_query, params_tuple)
         range_row = await cursor.fetchone()
         await cursor.close()
-        earliest = range_row["earliest"] if range_row and range_row["earliest"] else None
+        earliest = (
+            range_row["earliest"] if range_row and range_row["earliest"] else None
+        )
         latest = range_row["latest"] if range_row and range_row["latest"] else None
 
         return {
@@ -902,7 +915,9 @@ class SQLiteBlackboardStore(BlackboardStore):
         consumption_rows = await cursor.fetchall()
         await cursor.close()
 
-        consumed_by_type = {row["canonical_type"]: row["count"] for row in consumption_rows}
+        consumed_by_type = {
+            row["canonical_type"]: row["count"] for row in consumption_rows
+        }
         consumed_total = sum(consumed_by_type.values())
 
         return {
@@ -1156,7 +1171,9 @@ class SQLiteBlackboardStore(BlackboardStore):
         params: list[Any] = []
 
         if filters.type_names:
-            canonical = {type_registry.resolve_name(name) for name in filters.type_names}
+            canonical = {
+                type_registry.resolve_name(name) for name in filters.type_names
+            }
             placeholders = ", ".join("?" for _ in canonical)
             conditions.append(f"{prefix}canonical_type IN ({placeholders})")
             params.extend(sorted(canonical))
@@ -1172,7 +1189,9 @@ class SQLiteBlackboardStore(BlackboardStore):
 
         if filters.visibility:
             placeholders = ", ".join("?" for _ in filters.visibility)
-            conditions.append(f"json_extract({prefix}visibility, '$.kind') IN ({placeholders})")
+            conditions.append(
+                f"json_extract({prefix}visibility, '$.kind') IN ({placeholders})"
+            )
             params.extend(sorted(filters.visibility))
 
         if filters.start is not None:

flock/subscription.py

@@ -102,7 +102,7 @@ class Subscription:
         where: Sequence[Predicate] | None = None,
         text_predicates: Sequence[TextPredicate] | None = None,
         from_agents: Iterable[str] | None = None,
-        channels: Iterable[str] | None = None,
+        tags: Iterable[str] | None = None,
         join: JoinSpec | None = None,
         batch: BatchSpec | None = None,
         delivery: str = "exclusive",
@@ -116,7 +116,9 @@ class Subscription:
 
         # Register all types and build counts (supports duplicates for count-based AND gates)
         type_name_list = [type_registry.register(t) for t in types]
-        self.type_names: set[str] = set(type_name_list)  # Unique type names (for matching)
+        self.type_names: set[str] = set(
+            type_name_list
+        )  # Unique type names (for matching)
 
         # Count-based AND gate: Track how many of each type are required
         # Example: .consumes(A, A, B) → {"TypeA": 2, "TypeB": 1}
@@ -127,7 +129,7 @@ class Subscription:
         self.where = list(where or [])
         self.text_predicates = list(text_predicates or [])
         self.from_agents = set(from_agents or [])
-        self.channels = set(channels or [])
+        self.tags = set(tags or [])
         self.join = join
         self.batch = batch
         self.delivery = delivery
@@ -145,7 +147,7 @@ class Subscription:
             return False
         if self.from_agents and artifact.produced_by not in self.from_agents:
             return False
-        if self.channels and not artifact.tags.intersection(self.channels):
+        if self.tags and not artifact.tags.intersection(self.tags):
             return False
 
         # Evaluate where predicates on typed payloads

flock/system_artifacts.py

@@ -0,0 +1,33 @@
+"""System-level artifact types published by the Flock orchestrator.
+
+These artifacts provide workflow telemetry and error tracking.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from flock.registry import flock_type
+
+
+@flock_type
+class WorkflowError(BaseModel):
+    """Error artifact published when an agent execution fails.
+
+    This artifact is automatically published by the orchestrator when an agent
+    raises an exception during execution. It includes the correlation_id to enable
+    error tracking for workflows.
+
+    The workflow continues execution for other branches even when this is published.
+    """
+
+    failed_agent: str = Field(description="Name of the agent that failed")
+    error_type: str = Field(description="Type of exception that occurred")
+    error_message: str = Field(description="Error message from the exception")
+    timestamp: datetime = Field(description="When the error occurred")
+    task_id: str | None = Field(
+        default=None, description="Task ID of the failed execution"
+    )
+
+
+__all__ = ["WorkflowError"]

flock/utilities.py

@@ -31,7 +31,9 @@ class MetricsUtility(AgentComponent):
 
     name: str | None = "metrics"
 
-    async def on_pre_evaluate(self, agent, ctx: Context, inputs: EvalInputs) -> EvalInputs:
+    async def on_pre_evaluate(
+        self, agent, ctx: Context, inputs: EvalInputs
+    ) -> EvalInputs:
         ctx.state.setdefault("metrics", {})[f"{agent.name}:start"] = time.perf_counter()
         return inputs
 
@@ -42,7 +44,9 @@ class MetricsUtility(AgentComponent):
         start = metrics.get(f"{agent.name}:start")
         if start:
             metrics[f"{agent.name}:duration_ms"] = (time.perf_counter() - start) * 1000
-        result.metrics.update({k: v for k, v in metrics.items() if k.endswith("duration_ms")})
+        result.metrics.update({
+            k: v for k, v in metrics.items() if k.endswith("duration_ms")
+        })
         return result
 
 
@@ -78,11 +82,15 @@ class LoggingUtility(AgentComponent):
 
     async def on_pre_consume(self, agent, ctx: Context, inputs: list[Any]):
         summary = ", ".join(self._summarize_artifact(art) for art in inputs) or "<none>"
-        self._console.log(f"[{agent.name}] consume n={len(inputs)} artifacts -> {summary}")
+        self._console.log(
+            f"[{agent.name}] consume n={len(inputs)} artifacts -> {summary}"
+        )
         self._render_artifacts(agent.name, inputs, role="input")
         return await super().on_pre_consume(agent, ctx, inputs)
 
-    async def on_pre_evaluate(self, agent, ctx: Context, inputs: EvalInputs) -> EvalInputs:
+    async def on_pre_evaluate(
+        self, agent, ctx: Context, inputs: EvalInputs
+    ) -> EvalInputs:
         if self._stream_tokens:
             self._maybe_start_stream(agent, ctx)
         return await super().on_pre_evaluate(agent, ctx, inputs)
@@ -91,7 +99,9 @@ class LoggingUtility(AgentComponent):
         self, agent, ctx: Context, inputs: EvalInputs, result: EvalResult
     ) -> EvalResult:
         self._render_metrics(agent.name, result.metrics)
-        self._render_artifacts(agent.name, result.artifacts or inputs.artifacts, role="output")
+        self._render_artifacts(
+            agent.name, result.artifacts or inputs.artifacts, role="output"
+        )
         if result.logs:
             self._render_logs(agent.name, result.logs)
         awaited = await super().on_post_evaluate(agent, ctx, inputs, result)
@@ -102,7 +112,9 @@ class LoggingUtility(AgentComponent):
     async def on_post_publish(self, agent, ctx: Context, artifact):
         visibility = getattr(artifact.visibility, "kind", "Public")
         subtitle = f"visibility={visibility}"
-        panel = self._build_artifact_panel(artifact, role="published", subtitle=subtitle)
+        panel = self._build_artifact_panel(
+            artifact, role="published", subtitle=subtitle
+        )
         self._console.print(panel)
         await super().on_post_publish(agent, ctx, artifact)
 
@@ -121,7 +133,9 @@ class LoggingUtility(AgentComponent):
     # ------------------------------------------------------------------
     # Rendering helpers
 
-    def _render_artifacts(self, agent_name: str, artifacts: Sequence[Any], *, role: str) -> None:
+    def _render_artifacts(
+        self, agent_name: str, artifacts: Sequence[Any], *, role: str
+    ) -> None:
         for artifact in artifacts:
             panel = self._build_artifact_panel(artifact, role=role)
             self._console.print(panel)
@@ -189,7 +203,9 @@ class LoggingUtility(AgentComponent):
             else:
                 textual.append(line)
         for payload in json_sections:
-            panel = Panel(payload, title=f"{agent_name} ▸ dspy.output", border_style="green")
+            panel = Panel(
+                payload, title=f"{agent_name} ▸ dspy.output", border_style="green"
+            )
             self._console.print(panel)
         if textual:
             body = Text("\n".join(textual) + "\n")
@@ -244,7 +260,9 @@ class LoggingUtility(AgentComponent):
         with contextlib.suppress(asyncio.CancelledError):
             await task
 
-    async def _consume_stream(self, agent_name: str, stream_key: str, queue: asyncio.Queue) -> None:
+    async def _consume_stream(
+        self, agent_name: str, stream_key: str, queue: asyncio.Queue
+    ) -> None:
         body = Text()
         live: Live | None = None
         try:
@@ -254,7 +272,9 @@ class LoggingUtility(AgentComponent):
                     break
                 kind = event.get("kind")
                 if live is None:
-                    live_panel = Panel(body, title=f"{agent_name} ▸ streaming", border_style="cyan")
+                    live_panel = Panel(
+                        body, title=f"{agent_name} ▸ streaming", border_style="cyan"
+                    )
                     live = Live(
                         live_panel,
                         console=self._console,
@@ -274,19 +294,27 @@ class LoggingUtility(AgentComponent):
                     message = event.get("message") or ""
                     body.append(f"\n⚠ {message}\n", style="bold red")
                 if live is not None:
-                    live.update(Panel(body, title=f"{agent_name} ▸ streaming", border_style="cyan"))
+                    live.update(
+                        Panel(
+                            body, title=f"{agent_name} ▸ streaming", border_style="cyan"
+                        )
+                    )
         finally:
             if live is not None:
                 live.__exit__(None, None, None)
         if body.plain:
             self._console.print(
-                Panel(body, title=f"{agent_name} ▸ stream transcript", border_style="cyan")
+                Panel(
+                    body, title=f"{agent_name} ▸ stream transcript", border_style="cyan"
+                )
             )
 
     def _stream_key(self, agent, ctx: Context) -> str:
         return f"{ctx.task_id}:{agent.name}"
 
-    def _attach_stream_queue(self, state: MutableMapping[str, Any], queue: asyncio.Queue) -> None:
+    def _attach_stream_queue(
+        self, state: MutableMapping[str, Any], queue: asyncio.Queue
+    ) -> None:
         state.setdefault("_logging", {})["stream_queue"] = queue
 
     def _detach_stream_queue(self, state: MutableMapping[str, Any]) -> None:

flock/utility/output_utility_component.py

@@ -28,8 +28,12 @@ class OutputUtilityConfig(AgentComponentConfig):
     theme: OutputTheme = Field(
         default=OutputTheme.catppuccin_mocha, description="Theme for output formatting"
     )
-    render_table: bool = Field(default=True, description="Whether to render output as a table")
-    max_length: int = Field(default=1000, description="Maximum length for displayed output")
+    render_table: bool = Field(
+        default=True, description="Whether to render output as a table"
+    )
+    max_length: int = Field(
+        default=1000, description="Maximum length for displayed output"
+    )
     truncate_long_values: bool = Field(
         default=True, description="Whether to truncate long values in display"
     )
@@ -61,7 +65,9 @@ class OutputUtilityComponent(AgentComponent):
         default_factory=OutputUtilityConfig, description="Output configuration"
     )
 
-    def __init__(self, name: str = "output", config: OutputUtilityConfig | None = None, **data):
+    def __init__(
+        self, name: str = "output", config: OutputUtilityConfig | None = None, **data
+    ):
         if config is None:
             config = OutputUtilityConfig()
         super().__init__(name=name, config=config, **data)
@@ -96,7 +102,11 @@ class OutputUtilityComponent(AgentComponent):
         items = []
         prefix = "  " * indent
         for key, value in d.items():
-            if self.config.truncate_long_values and isinstance(value, str) and len(value) > 100:
+            if (
+                self.config.truncate_long_values
+                and isinstance(value, str)
+                and len(value) > 100
+            ):
                 value = value[:97] + "..."
             formatted_value = self._format_value(value, key)
             items.append(f"{prefix}  {key}: {formatted_value}")
@@ -125,7 +135,9 @@ class OutputUtilityComponent(AgentComponent):
             return f"[CODE:{language}]\n{code}\n[/CODE]"
 
         # Replace markdown-style code blocks
-        return re.sub(r"```(\w+)?\n(.*?)\n```", replace_code_block, text, flags=re.DOTALL)
+        return re.sub(
+            r"```(\w+)?\n(.*?)\n```", replace_code_block, text, flags=re.DOTALL
+        )
 
     async def on_post_evaluate(
         self, agent: "Agent", ctx: Context, inputs: EvalInputs, result: EvalResult
@@ -138,7 +150,9 @@ class OutputUtilityComponent(AgentComponent):
         streamed_artifact_id = None
 
         if ctx:
-            streaming_live_handled = bool(ctx.get_variable("_flock_stream_live_active", False))
+            streaming_live_handled = bool(
+                ctx.get_variable("_flock_stream_live_active", False)
+            )
             output_queued = bool(ctx.get_variable("_flock_output_queued", False))
             streamed_artifact_id = ctx.get_variable("_flock_streamed_artifact_id")
 
@@ -162,20 +176,24 @@ class OutputUtilityComponent(AgentComponent):
 
         # Skip output if streaming already handled it (and no ID to update)
         if streaming_live_handled:
-            logger.debug("Skipping static table because streaming rendered live output.")
+            logger.debug(
+                "Skipping static table because streaming rendered live output."
+            )
             return result
 
         # If output was queued due to concurrent stream, wait and then display
         if output_queued:
             # Wait for active streams to complete
-            orchestrator = getattr(ctx, "orchestrator", None)
-            if orchestrator:
+            # Phase 6+7 Security Fix: Use Agent class variable instead of ctx.state
+            if ctx:
                 import asyncio
 
+                from flock.agent import Agent
+
                 # Wait until no streams are active
                 max_wait = 30  # seconds
                 waited = 0
-                while getattr(orchestrator, "_active_streams", 0) > 0 and waited < max_wait:
+                while Agent._streaming_counter > 0 and waited < max_wait:
                     await asyncio.sleep(0.1)
                     waited += 0.1
                 logger.debug(
@@ -189,7 +207,9 @@ class OutputUtilityComponent(AgentComponent):
             try:
                 # Create a copy or select relevant parts to avoid modifying original result dict directly
                 display_result = result.copy()
-                display_result["context_snapshot"] = ctx.to_dict()  # Potential performance hit
+                display_result["context_snapshot"] = (
+                    ctx.to_dict()
+                )  # Potential performance hit
             except Exception:
                 display_result = result.copy()
                 display_result["context_snapshot"] = "[Error serializing context]"

{flock_core-0.5.9.dist-info → flock_core-0.5.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.9
+Version: 0.5.11
 Summary: Flock: A declrative framework for building and orchestrating AI agents.
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License: MIT
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 <p align="center">
   <a href="https://whiteducksoftware.github.io/flock/" target="_blank"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge&logo=readthedocs"></a>
   <a href="https://pypi.org/project/flock-core/" target="_blank"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/flock-core?style=for-the-badge&logo=pypi&label=pip%20version"></a>
-  <img alt="Python Version" src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python">
+  <img alt="Python Version" src="https://img.shields.io/badge/python-3.12%2B-blue?style=for-the-badge&logo=python">
   <a href="LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/github/license/whiteducksoftware/flock?style=for-the-badge"></a>
   <a href="https://whiteduck.de" target="_blank"><img alt="Built by white duck" src="https://img.shields.io/badge/Built%20by-white%20duck%20GmbH-white?style=for-the-badge&labelColor=black"></a>
   <a href="https://codecov.io/gh/whiteducksoftware/flock" target="_blank"><img alt="Test Coverage" src="https://codecov.io/gh/whiteducksoftware/flock/branch/main/graph/badge.svg?token=YOUR_TOKEN_HERE&style=for-the-badge"></a>
@@ -287,30 +287,6 @@ asyncio.run(main())
 
 ---
 
-## Persistent Blackboard History
-
-The in-memory store is still great for local tinkering, but production teams now have a durable option. Plugging in `SQLiteBlackboardStore` turns the blackboard into a persistent event log with first-class ergonomics:
-
-- **Long-lived artifacts** — every field (payload, tags, partition keys, visibility) is stored for replay, audits, and postmortems
-- **Historical APIs** — `/api/v1/artifacts`, `/summary`, and `/agents/{agent_id}/history-summary` expose pagination, filtering, and consumption counts
-- **Dashboard module** — the new **Historical Blackboard** experience preloads persisted history, enriches the graph with consumer metadata, and highlights retention windows
-- **Operational tooling** — CLI helpers (`init-sqlite-store`, `sqlite-maintenance --delete-before ... --vacuum`) make schema setup and retention policies scriptable
-
-Quick start:
-
-```python
-from flock import Flock
-from flock.store import SQLiteBlackboardStore
-
-store = SQLiteBlackboardStore(".flock/blackboard.db")
-await store.ensure_schema()
-flock = Flock("openai/gpt-4.1", store=store)
-```
-
-Run `examples/02-the-blackboard/01_persistent_pizza.py` to generate history, then launch `examples/03-the-dashboard/04_persistent_pizza_dashboard.py` and explore previous runs, consumption trails, and retention banners inside the dashboard.
-
----
-
 ## Core Concepts
 
 ### Typed Artifacts (The Vocabulary)
@@ -541,8 +517,127 @@ artifact.visibility = AfterVisibility(ttl=timedelta(hours=24), then=PublicVisibi
 agent.publishes(PublicReport, visibility=PublicVisibility())
 ```
 
+**Visibility has a dual purpose:** It controls both which agents can be **triggered** by an artifact AND which artifacts agents can **see** in their context. This ensures consistent security across agent execution and data access—agents cannot bypass visibility controls through subscription filters or context providers.
+
 **Why this matters:** Financial services, healthcare, defense, SaaS platforms all need this for compliance. Other frameworks make you build it yourself.
 
+---
+
+### 🔒 Architecturally Impossible to Bypass Security
+
+**Here's what makes Flock different:** In most frameworks, security is something you remember to add. In Flock, **it's architecturally impossible to forget.**
+
+Every context provider in Flock inherits from `BaseContextProvider`, which enforces visibility filtering **automatically**. You literally cannot create a provider that forgets to check permissions—the security logic is baked into the base class and executes before your custom code even runs.
+
+**What this means in practice:**
+
+```python
+# ❌ Other frameworks: Security is your responsibility (easy to forget!)
+class MyProvider:
+    async def get_context(self, agent):
+        artifacts = store.get_all()  # OOPS! Forgot to check visibility!
+        return artifacts  # 🔥 Security vulnerability
+
+# ✅ Flock: Security is enforced automatically (impossible to bypass!)
+class MyProvider(BaseContextProvider):
+    async def get_artifacts(self, request):
+        artifacts = await store.query_artifacts(...)
+        return artifacts  # ✨ Visibility filtering happens automatically!
+        # BaseContextProvider calls .visibility.allows() for you
+        # You CANNOT bypass this - it's enforced by the architecture
+```
+
+**Built-in providers (all inherit BaseContextProvider):**
+- `DefaultContextProvider` - Full blackboard access (visibility-filtered)
+- `CorrelatedContextProvider` - Workflow isolation (visibility-filtered)
+- `RecentContextProvider` - Token cost control (visibility-filtered)
+- `TimeWindowContextProvider` - Time-based filtering (visibility-filtered)
+- `EmptyContextProvider` - Stateless agents (zero context)
+- `FilteredContextProvider` - Custom filtering (visibility-filtered)
+
+**Every single one enforces visibility automatically. Zero chance of accidentally leaking data.**
+
+This isn't just convenient—it's **security by design**. When you're building HIPAA-compliant healthcare systems or SOC2-certified SaaS platforms, "impossible to bypass even by accident" is the only acceptable standard.
+
+---
+
+### Context Providers (The Smart Filter)
+
+**Control what agents see with custom Context Providers:**
+
+```python
+from flock.context_provider import FilteredContextProvider, PasswordRedactorProvider
+from flock.store import FilterConfig
+
+# Global filtering - all agents see only urgent items
+flock = Flock(
+    "openai/gpt-4.1",
+    context_provider=FilteredContextProvider(FilterConfig(tags={"urgent"}))
+)
+
+# Per-agent overrides - specialized context per agent
+error_agent = flock.agent("errors").consumes(Log).publishes(Alert)
+error_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR"}))
+
+# Production-ready password filtering
+from examples.context_provider import PasswordRedactorProvider
+flock = Flock(
+    "openai/gpt-4.1",
+    context_provider=PasswordRedactorProvider()  # Auto-redacts sensitive data!
+)
+```
+
+**What just happened:**
+- ✅ **Filtered context** - Agents see only relevant artifacts (save tokens, improve performance)
+- ✅ **Security boundary** - Visibility enforcement + custom filtering (mandatory, cannot bypass)
+- ✅ **Sensitive data protection** - Auto-redact passwords, API keys, credit cards, SSN, JWT tokens
+- ✅ **Per-agent specialization** - Different agents, different context rules
+
+**Production patterns:**
+```python
+# Password/secret redaction (copy-paste ready!)
+provider = PasswordRedactorProvider(
+    custom_patterns={"internal_id": r"ID-\d{6}"},
+    redaction_text="[REDACTED]"
+)
+
+# Role-based access control
+junior_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR"}))
+senior_agent.context_provider = FilteredContextProvider(FilterConfig(tags={"ERROR", "WARN"}))
+admin_agent.context_provider = None  # See everything (uses default)
+
+# Multi-tenant isolation
+agent.context_provider = FilteredContextProvider(
+    FilterConfig(tags={"tenant:customer_123"})
+)
+```
+
+**Why this matters:** Reduce token costs (90%+ with smart filtering), protect sensitive data (auto-redact secrets), improve performance (agents see only what they need).
+
+**📖 [Learn more: Context Providers Guide](https://whiteducksoftware.github.io/flock/guides/context-providers/) | [Steal production code →](examples/08-context-provider/)**
+
+### Persistent Blackboard History
+
+The in-memory store is great for local development, but production teams need durability. The `SQLiteBlackboardStore` turns the blackboard into a persistent event log with first-class ergonomics:
+
+**What you get:**
+- **Long-lived artifacts** — Every field (payload, tags, partition keys, visibility) stored for replay, audits, and postmortems
+- **Historical APIs** — `/api/v1/artifacts`, `/summary`, and `/agents/{agent_id}/history-summary` expose pagination, filtering, and consumption counts
+- **Dashboard integration** — The **Historical Blackboard** view preloads persisted history, enriches the graph with consumer metadata, and highlights retention windows
+- **Operational tooling** — CLI helpers (`init-sqlite-store`, `sqlite-maintenance --delete-before ... --vacuum`) make schema setup and retention policies scriptable
+
+**Quick start:**
+```python
+from flock import Flock
+from flock.store import SQLiteBlackboardStore
+
+store = SQLiteBlackboardStore(".flock/blackboard.db")
+await store.ensure_schema()
+flock = Flock("openai/gpt-4.1", store=store)
+```
+
+**Try it:** Run `examples/02-the-blackboard/01_persistent_pizza.py` to generate history, then launch `examples/03-the-dashboard/04_persistent_pizza_dashboard.py` to explore previous runs, consumption trails, and retention banners.
+
 ### Batching Pattern: Parallel Execution Control
 
 **A key differentiator:** The separation of `publish()` and `run_until_idle()` enables parallel execution.
@@ -670,6 +765,35 @@ agent.best_of(150, ...)  # ⚠️ Warns: "best_of(150) is very high - high LLM c
 
 ## Production-Ready Observability
 
+### Sophisticated REST API
+
+**Production-ready HTTP endpoints with comprehensive OpenAPI documentation:**
+
+Flock includes a fully-featured REST API for programmatic access to the blackboard, agents, and workflow orchestration. Perfect for integration with external systems, building custom UIs, or monitoring production deployments.
+
+**Key endpoints:**
+- `POST /api/v1/artifacts` - Publish artifacts to the blackboard
+- `GET /api/v1/artifacts` - Query artifacts with filtering, pagination, and consumption metadata
+- `POST /api/v1/agents/{name}/run` - Direct agent invocation
+- `GET /api/v1/correlations/{correlation_id}/status` - Workflow completion tracking
+- `GET /api/v1/agents` - List all registered agents with subscriptions
+- `GET /health` and `GET /metrics` - Production monitoring
+
+**Start the API server:**
+```python
+await flock.serve(dashboard=True)  # API + Dashboard on port 8344
+# API docs: http://localhost:8344/docs
+```
+
+**Features:**
+- ✅ **OpenAPI 3.0** - Interactive documentation at `/docs`
+- ✅ **Pydantic validation** - Type-safe request/response models
+- ✅ **Correlation tracking** - Monitor workflow completion with polling
+- ✅ **Consumption metadata** - Full artifact lineage and agent execution trails
+- ✅ **Production monitoring** - Health checks and Prometheus-compatible metrics
+
+**📖 [Explore the API →](http://localhost:8344/docs)** (start the server first!)
+
 ### Real-Time Dashboard
 
 **Start the dashboard with one line:**