flock-core 0.5.0b62__tar.gz → 0.5.0b65__tar.gz

{flock_core-0.5.0b62 → flock_core-0.5.0b65}/AGENTS.md

@@ -4,7 +4,7 @@
 
 This is Flock Flow, a production-grade blackboard-first AI agent orchestration framework. This guide gets you up to speed quickly on the current project state and development patterns.
 
-**Current Version:** Backend: 0.5.0b62 • Frontend: 0.1.4
+**Current Version:** Backend: 0.5.0b63 • Frontend: 0.1.4
 **Architecture:** Hybrid Python/TypeScript with real-time dashboard
 **Package Manager:** UV (NOT pip!)
 **Status:** Production-ready with comprehensive monitoring

{flock_core-0.5.0b62 → flock_core-0.5.0b65}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b62
+Version: 0.5.0b65
 Summary: Add your description here
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -9,6 +9,7 @@ Requires-Dist: devtools>=0.12.2
 Requires-Dist: dspy==3.0.0
 Requires-Dist: duckdb>=1.1.0
 Requires-Dist: fastapi>=0.117.1
+Requires-Dist: hanging-threads>=2.0.7
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: litellm==1.75.3
 Requires-Dist: loguru>=0.7.3
@@ -178,7 +179,7 @@ agent.consumes(BugReport).publishes(BugDiagnosis)
 ```
 
 <p align="center">
-  <img alt="Flock Banner" src="docs/img/bug_diagnosis.png" width="1000">
+  <img alt="Flock Banner" src="docs/assets/images/bug_diagnosis.png" width="1000">
 </p>
 
 **Why this matters:**
@@ -437,7 +438,7 @@ await flock.serve(dashboard=True)
 The dashboard provides comprehensive real-time visibility into your agent system with professional UI/UX:
 
 <p align="center">
-  <img alt="Flock Agent View" src="docs/img/flock_ui_agent_view.png" width="1000">
+  <img alt="Flock Agent View" src="docs/assets/images/flock_ui_agent_view.png" width="1000">
   <i>Agent View: See agent communication patterns and message flows in real-time</i>
 </p>
 
@@ -448,7 +449,7 @@ The dashboard provides comprehensive real-time visibility into your agent system
   - **Blackboard View** - Messages as nodes with data transformations as edges
 
 <p align="center">
-  <img alt="Flock Blackboard View" src="docs/img/flock_ui_blackboard_view.png" width="1000">
+  <img alt="Flock Blackboard View" src="docs/assets/images/flock_ui_blackboard_view.png" width="1000">
   <i>Blackboard View: Track data lineage and transformations across the system</i>
 </p>
 
@@ -488,7 +489,7 @@ The dashboard provides comprehensive real-time visibility into your agent system
 The dashboard includes a **Jaeger-style trace viewer** with 7 powerful visualization modes:
 
 <p align="center">
-  <img alt="Trace Viewer" src="docs/img/trace_1.png" width="1000">
+  <img alt="Trace Viewer" src="docs/assets/images/trace_1.png" width="1000">
   <i>Trace Viewer: Timeline view showing span hierarchies and execution flow</i>
 </p>
 
@@ -511,7 +512,7 @@ The dashboard includes a **Jaeger-style trace viewer** with 7 powerful visualiza
 - **CSV Export** - Download query results for offline analysis
 
 <p align="center">
-  <img alt="Trace Viewer" src="docs/img/trace_2.png" width="1000">
+  <img alt="Trace Viewer" src="docs/assets/images/trace_2.png" width="1000">
   <i>Trace Viewer: Dependency Analysis</i>
 </p>
 
@@ -565,7 +566,7 @@ AI: [queries DuckDB]
 **Why DuckDB?** 10-100x faster than SQLite for analytical queries. Zero configuration. AI agents can debug your AI agents.
 
 <p align="center">
-  <img alt="Trace Viewer" src="docs/img/trace_3.png" width="1000">
+  <img alt="Trace Viewer" src="docs/assets/images/trace_3.png" width="1000">
   <i>Trace Viewer: DuckDB Query</i>
 </p>
 
@@ -677,83 +678,18 @@ All planned for v1.0
 
 ## Roadmap to 1.0
 
-We're not building a toy framework. We're building enterprise infrastructure for AI agents.
-
-**See [ROADMAP.md](ROADMAP.md) for the complete roadmap with detailed code examples.**
-
-### Flock 1.0 - Q4 2025 Release
-
-**We're confident we can deliver all enterprise features by Q4 2025:**
-
-**🏢 Enterprise Persistence**
-- Redis and PostgreSQL backends for durable blackboard state
-- Agent crashes? State persists, agents resume automatically
-- Multi-region deployments with shared blackboard
-- SQL queries on artifact history for analytics and compliance
-
-**🔄 Advanced Error Handling**
-- Exponential backoff with jitter for transient failures
-- Dead letter queues for poison messages
-- Per-agent circuit breakers with auto-recovery
-- Full observability of all failure modes
-
-**🤝 Aggregation Patterns**
-- Map-reduce pattern for parallel processing → aggregation
-- Voting/consensus for multi-agent decision making
-- Best-result selection with custom scoring functions
-
-**📨 Kafka Event Backbone**
-- Event replay for debugging production issues in development
-- Time-travel debugging with checkpoint restoration
-- Immutable audit logs for regulatory compliance
-- Backfill new agents with historical data
-
-**☸️ Kubernetes-Native Deployment**
-- Helm charts for production deployments
-- Horizontal auto-scaling based on blackboard queue depth
-- Zero-downtime deployments with health checks
-- Production-grade readiness probes
-
-**🔐 OAuth/RBAC**
-- OAuth2/OIDC authentication for multi-tenant SaaS
-- API key authentication for programmatic access
-- Role-based access control with agent-level permissions
-- Complete audit trails for compliance (SOC2, HIPAA)
-
-**👤 Human-in-the-Loop**
-- Approval patterns for high-value transactions
-- Dashboard integration for pending approvals
-- Slack/email notifications with audit trails
-- Training mode with review-before-automation
-
-**🔀 Fan-Out/Fan-In Patterns**
-- Dynamic work distribution based on runtime data
-- Result collection and aggregation
-- Map-reduce over LLM operations
-- Sharding for horizontal scale
-
-**⏰ Time-Based Scheduling**
-- Cron-like triggers for periodic workflows
-- Sliding window patterns for real-time analytics
-- Hybrid event+time based triggers
-- SLA monitoring and data freshness checks
-
-### Release Criteria for v1.0
-
-**v1.0 will ship when all of these are complete:**
-1. ✅ Production persistence (Redis + Postgres backends stable)
-2. ✅ Advanced error handling (retry, circuit breakers, DLQ working)
-3. ✅ Aggregation patterns (map-reduce, voting, consensus implemented)
-4. ✅ Kafka event backbone (replay and time-travel debugging)
-5. ✅ Kubernetes native (Helm chart with auto-scaling)
-6. ✅ Authentication (OAuth/OIDC + API key auth)
-7. ✅ Human-in-the-loop (approval patterns implemented)
-8. ✅ Fan-out/fan-in (distributed processing patterns)
-9. ✅ Time-based scheduling (cron + sliding windows)
-10. ✅ 85%+ test coverage (1000+ tests passing)
-11. ✅ Production validation (deployed at 3+ companies)
-
-**Target Date:** Q4 2025
+We're building enterprise infrastructure for AI agents and tracking the work publicly. Check [ROADMAP.md](ROADMAP.md) for deep dives and status updates.
+
+### 0.5.0 Beta (In Flight)
+- **Core data & governance:** [#271](https://github.com/whiteducksoftware/flock/issues/271), [#274](https://github.com/whiteducksoftware/flock/issues/274), [#273](https://github.com/whiteducksoftware/flock/issues/273), [#281](https://github.com/whiteducksoftware/flock/issues/281)
+- **Execution patterns & scheduling:** [#282](https://github.com/whiteducksoftware/flock/issues/282), [#283](https://github.com/whiteducksoftware/flock/issues/283)
+- **REST access & integrations:** [#286](https://github.com/whiteducksoftware/flock/issues/286), [#287](https://github.com/whiteducksoftware/flock/issues/287), [#288](https://github.com/whiteducksoftware/flock/issues/288), [#289](https://github.com/whiteducksoftware/flock/issues/289), [#290](https://github.com/whiteducksoftware/flock/issues/290), [#291](https://github.com/whiteducksoftware/flock/issues/291), [#292](https://github.com/whiteducksoftware/flock/issues/292), [#293](https://github.com/whiteducksoftware/flock/issues/293)
+- **Docs & onboarding:** [#270](https://github.com/whiteducksoftware/flock/issues/270), [#269](https://github.com/whiteducksoftware/flock/issues/269)
+
+### 1.0 Release Goals (Target Q4 2025)
+- **Reliability & operations:** [#277](https://github.com/whiteducksoftware/flock/issues/277), [#278](https://github.com/whiteducksoftware/flock/issues/278), [#279](https://github.com/whiteducksoftware/flock/issues/279), [#294](https://github.com/whiteducksoftware/flock/issues/294)
+- **Platform validation & quality:** [#275](https://github.com/whiteducksoftware/flock/issues/275), [#276](https://github.com/whiteducksoftware/flock/issues/276), [#284](https://github.com/whiteducksoftware/flock/issues/284), [#285](https://github.com/whiteducksoftware/flock/issues/285)
+- **Security & access:** [#280](https://github.com/whiteducksoftware/flock/issues/280)
 
 ---
 

{flock_core-0.5.0b62 → flock_core-0.5.0b65}/README.md

@@ -148,7 +148,7 @@ agent.consumes(BugReport).publishes(BugDiagnosis)
 ```
 
 <p align="center">
-  <img alt="Flock Banner" src="docs/img/bug_diagnosis.png" width="1000">
+  <img alt="Flock Banner" src="docs/assets/images/bug_diagnosis.png" width="1000">
 </p>
 
 **Why this matters:**
@@ -407,7 +407,7 @@ await flock.serve(dashboard=True)
 The dashboard provides comprehensive real-time visibility into your agent system with professional UI/UX:
 
 <p align="center">
-  <img alt="Flock Agent View" src="docs/img/flock_ui_agent_view.png" width="1000">
+  <img alt="Flock Agent View" src="docs/assets/images/flock_ui_agent_view.png" width="1000">
   <i>Agent View: See agent communication patterns and message flows in real-time</i>
 </p>
 
@@ -418,7 +418,7 @@ The dashboard provides comprehensive real-time visibility into your agent system
   - **Blackboard View** - Messages as nodes with data transformations as edges
 
 <p align="center">
-  <img alt="Flock Blackboard View" src="docs/img/flock_ui_blackboard_view.png" width="1000">
+  <img alt="Flock Blackboard View" src="docs/assets/images/flock_ui_blackboard_view.png" width="1000">
   <i>Blackboard View: Track data lineage and transformations across the system</i>
 </p>
 
@@ -458,7 +458,7 @@ The dashboard provides comprehensive real-time visibility into your agent system
 The dashboard includes a **Jaeger-style trace viewer** with 7 powerful visualization modes:
 
 <p align="center">
-  <img alt="Trace Viewer" src="docs/img/trace_1.png" width="1000">
+  <img alt="Trace Viewer" src="docs/assets/images/trace_1.png" width="1000">
   <i>Trace Viewer: Timeline view showing span hierarchies and execution flow</i>
 </p>
 
@@ -481,7 +481,7 @@ The dashboard includes a **Jaeger-style trace viewer** with 7 powerful visualiza
 - **CSV Export** - Download query results for offline analysis
 
 <p align="center">
-  <img alt="Trace Viewer" src="docs/img/trace_2.png" width="1000">
+  <img alt="Trace Viewer" src="docs/assets/images/trace_2.png" width="1000">
   <i>Trace Viewer: Dependency Analysis</i>
 </p>
 
@@ -535,7 +535,7 @@ AI: [queries DuckDB]
 **Why DuckDB?** 10-100x faster than SQLite for analytical queries. Zero configuration. AI agents can debug your AI agents.
 
 <p align="center">
-  <img alt="Trace Viewer" src="docs/img/trace_3.png" width="1000">
+  <img alt="Trace Viewer" src="docs/assets/images/trace_3.png" width="1000">
   <i>Trace Viewer: DuckDB Query</i>
 </p>
 
@@ -647,83 +647,18 @@ All planned for v1.0
 
 ## Roadmap to 1.0
 
-We're not building a toy framework. We're building enterprise infrastructure for AI agents.
-
-**See [ROADMAP.md](ROADMAP.md) for the complete roadmap with detailed code examples.**
-
-### Flock 1.0 - Q4 2025 Release
-
-**We're confident we can deliver all enterprise features by Q4 2025:**
-
-**🏢 Enterprise Persistence**
-- Redis and PostgreSQL backends for durable blackboard state
-- Agent crashes? State persists, agents resume automatically
-- Multi-region deployments with shared blackboard
-- SQL queries on artifact history for analytics and compliance
-
-**🔄 Advanced Error Handling**
-- Exponential backoff with jitter for transient failures
-- Dead letter queues for poison messages
-- Per-agent circuit breakers with auto-recovery
-- Full observability of all failure modes
-
-**🤝 Aggregation Patterns**
-- Map-reduce pattern for parallel processing → aggregation
-- Voting/consensus for multi-agent decision making
-- Best-result selection with custom scoring functions
-
-**📨 Kafka Event Backbone**
-- Event replay for debugging production issues in development
-- Time-travel debugging with checkpoint restoration
-- Immutable audit logs for regulatory compliance
-- Backfill new agents with historical data
-
-**☸️ Kubernetes-Native Deployment**
-- Helm charts for production deployments
-- Horizontal auto-scaling based on blackboard queue depth
-- Zero-downtime deployments with health checks
-- Production-grade readiness probes
-
-**🔐 OAuth/RBAC**
-- OAuth2/OIDC authentication for multi-tenant SaaS
-- API key authentication for programmatic access
-- Role-based access control with agent-level permissions
-- Complete audit trails for compliance (SOC2, HIPAA)
-
-**👤 Human-in-the-Loop**
-- Approval patterns for high-value transactions
-- Dashboard integration for pending approvals
-- Slack/email notifications with audit trails
-- Training mode with review-before-automation
-
-**🔀 Fan-Out/Fan-In Patterns**
-- Dynamic work distribution based on runtime data
-- Result collection and aggregation
-- Map-reduce over LLM operations
-- Sharding for horizontal scale
-
-**⏰ Time-Based Scheduling**
-- Cron-like triggers for periodic workflows
-- Sliding window patterns for real-time analytics
-- Hybrid event+time based triggers
-- SLA monitoring and data freshness checks
-
-### Release Criteria for v1.0
-
-**v1.0 will ship when all of these are complete:**
-1. ✅ Production persistence (Redis + Postgres backends stable)
-2. ✅ Advanced error handling (retry, circuit breakers, DLQ working)
-3. ✅ Aggregation patterns (map-reduce, voting, consensus implemented)
-4. ✅ Kafka event backbone (replay and time-travel debugging)
-5. ✅ Kubernetes native (Helm chart with auto-scaling)
-6. ✅ Authentication (OAuth/OIDC + API key auth)
-7. ✅ Human-in-the-loop (approval patterns implemented)
-8. ✅ Fan-out/fan-in (distributed processing patterns)
-9. ✅ Time-based scheduling (cron + sliding windows)
-10. ✅ 85%+ test coverage (1000+ tests passing)
-11. ✅ Production validation (deployed at 3+ companies)
-
-**Target Date:** Q4 2025
+We're building enterprise infrastructure for AI agents and tracking the work publicly. Check [ROADMAP.md](ROADMAP.md) for deep dives and status updates.
+
+### 0.5.0 Beta (In Flight)
+- **Core data & governance:** [#271](https://github.com/whiteducksoftware/flock/issues/271), [#274](https://github.com/whiteducksoftware/flock/issues/274), [#273](https://github.com/whiteducksoftware/flock/issues/273), [#281](https://github.com/whiteducksoftware/flock/issues/281)
+- **Execution patterns & scheduling:** [#282](https://github.com/whiteducksoftware/flock/issues/282), [#283](https://github.com/whiteducksoftware/flock/issues/283)
+- **REST access & integrations:** [#286](https://github.com/whiteducksoftware/flock/issues/286), [#287](https://github.com/whiteducksoftware/flock/issues/287), [#288](https://github.com/whiteducksoftware/flock/issues/288), [#289](https://github.com/whiteducksoftware/flock/issues/289), [#290](https://github.com/whiteducksoftware/flock/issues/290), [#291](https://github.com/whiteducksoftware/flock/issues/291), [#292](https://github.com/whiteducksoftware/flock/issues/292), [#293](https://github.com/whiteducksoftware/flock/issues/293)
+- **Docs & onboarding:** [#270](https://github.com/whiteducksoftware/flock/issues/270), [#269](https://github.com/whiteducksoftware/flock/issues/269)
+
+### 1.0 Release Goals (Target Q4 2025)
+- **Reliability & operations:** [#277](https://github.com/whiteducksoftware/flock/issues/277), [#278](https://github.com/whiteducksoftware/flock/issues/278), [#279](https://github.com/whiteducksoftware/flock/issues/279), [#294](https://github.com/whiteducksoftware/flock/issues/294)
+- **Platform validation & quality:** [#275](https://github.com/whiteducksoftware/flock/issues/275), [#276](https://github.com/whiteducksoftware/flock/issues/276), [#284](https://github.com/whiteducksoftware/flock/issues/284), [#285](https://github.com/whiteducksoftware/flock/issues/285)
+- **Security & access:** [#280](https://github.com/whiteducksoftware/flock/issues/280)
 
 ---
 

flock_core-0.5.0b65/ROADMAP.md

@@ -0,0 +1,165 @@
+# 🗺️ Flock Roadmap to 1.0
+
+**Building Enterprise Infrastructure for AI Agents**
+
+This roadmap outlines Flock's path from v0.5.0 (production-ready core) to v1.0 (enterprise-complete) by Q4 2025.
+
+We're confident to deliver all enterprise features in a single release: **Flock 1.0 in Q4 2025**.
+
+---
+
+## ✅ What's Already Production-Ready (v0.5.0)
+
+### Core Framework
+- [x] Blackboard orchestrator with typed artifacts
+- [x] Declarative agent subscriptions (no graph wiring)
+- [x] Parallel + sequential execution (automatic)
+- [x] Zero-trust security (5 visibility types)
+- [x] Circuit breakers and feedback loop prevention
+- [x] 743 tests with 77.65% coverage (86-100% on critical paths)
+- [x] Type-safe retrieval API (`get_by_type()`)
+
+### Observability
+- [x] OpenTelemetry distributed tracing
+- [x] DuckDB trace storage (AI-queryable)
+- [x] Real-time dashboard with WebSocket streaming
+- [x] 7-mode trace viewer (Timeline, RED metrics, Dependencies, SQL)
+- [x] Service filtering and CSV export
+- [x] Full I/O capture with JSON viewer
+
+### Developer Experience
+- [x] MCP integration (Model Context Protocol)
+- [x] Best-of-N execution
+- [x] Exclusive delivery (exactly-once)
+- [x] Batch processing and join operations
+- [x] Conditional consumption (`where=lambda`)
+- [x] Rich console output and FastAPI service
+- [x] Keyboard shortcuts (WCAG 2.1 AA compliant)
+
+---
+
+## 🧱 0.5.0 Beta Initiatives (In Flight)
+
+These are the features we are actively building for the 0.5.0 beta. Follow the linked GitHub issues to track progress:
+
+### Core data & governance
+- [#271](https://github.com/whiteducksoftware/flock/issues/271) — Durable blackboard persistence backends.
+- [#274](https://github.com/whiteducksoftware/flock/issues/274) — Serialization/export of blackboard state and registered agents.
+- [#273](https://github.com/whiteducksoftware/flock/issues/273) — Structured feedback channel for agent outputs.
+- [#281](https://github.com/whiteducksoftware/flock/issues/281) — Human-in-the-loop approval flow.
+
+### Execution patterns & scheduling
+- [#282](https://github.com/whiteducksoftware/flock/issues/282) — Fan-out / fan-in workflow helpers.
+- [#283](https://github.com/whiteducksoftware/flock/issues/283) — Time-based scheduling primitives.
+
+### REST access & integrations
+- [#286](https://github.com/whiteducksoftware/flock/issues/286) — Custom REST endpoint DSL.
+- [#287](https://github.com/whiteducksoftware/flock/issues/287) — Synchronous publish endpoint (single and batch).
+- [#288](https://github.com/whiteducksoftware/flock/issues/288) — Correlation-aware status endpoint.
+- [#289](https://github.com/whiteducksoftware/flock/issues/289) — Webhook notifications for published artifacts.
+- [#290](https://github.com/whiteducksoftware/flock/issues/290) — Schema discovery endpoints.
+- [#291](https://github.com/whiteducksoftware/flock/issues/291) — REST idempotency keys and error model.
+- [#292](https://github.com/whiteducksoftware/flock/issues/292) — Artifact listing and filtering API.
+- [#293](https://github.com/whiteducksoftware/flock/issues/293) — OpenAPI specification generation.
+
+### Documentation & onboarding
+- [#270](https://github.com/whiteducksoftware/flock/issues/270) — MkDocs-powered documentation site.
+- [#269](https://github.com/whiteducksoftware/flock/issues/269) — Revamped example catalog.
+
+---
+
+## 🚀 Flock 1.0 (Target Q4 2025)
+
+Once the 0.5.0 beta ships, we will focus on the remaining enterprise capabilities before the 1.0 release.
+
+### Reliability & operations
+- [#277](https://github.com/whiteducksoftware/flock/issues/277) — Advanced retry strategy, dead-letter queues, per-agent circuit breakers.
+- [#278](https://github.com/whiteducksoftware/flock/issues/278) — Kafka-backed event backbone with replay and time-travel debugging.
+- [#279](https://github.com/whiteducksoftware/flock/issues/279) — Kubernetes deployment tooling (Helm charts, auto-scaling).
+- [#294](https://github.com/whiteducksoftware/flock/issues/294) — Workflow lifecycle controls (pause, resume, cancel).
+
+### Platform validation & quality
+- [#275](https://github.com/whiteducksoftware/flock/issues/275) — Benchmarking suite against industry workloads.
+- [#276](https://github.com/whiteducksoftware/flock/issues/276) — Automated evaluation harness for datasets/metrics.
+- [#284](https://github.com/whiteducksoftware/flock/issues/284) — Test coverage expansion to 85%+ with 1,000 tests.
+- [#285](https://github.com/whiteducksoftware/flock/issues/285) — Production validation pilots with launch partners.
+
+### Security & access
+- [#280](https://github.com/whiteducksoftware/flock/issues/280) — Authentication & authorization (OAuth/OIDC, API keys).
+
+Stay tuned to the issue tracker for milestone updates. We'll publish detailed release notes as each cluster of features lands.
+
+---
+
+## Example: Multi-Modal Clinical Decision Support
+
+```python
+import os
+from flock import Flock, flock_type
+from flock.visibility import PrivateVisibility, TenantVisibility, LabelledVisibility
+from flock.identity import AgentIdentity
+from pydantic import BaseModel
+
+@flock_type
+class PatientScan(BaseModel):
+    patient_id: str
+    scan_type: str
+    image_data: bytes
+
+@flock_type
+class XRayAnalysis(BaseModel):
+    findings: list[str]
+    confidence: float
+
+@flock_type
+class LabResults(BaseModel):
+    markers: dict[str, float]
+
+@flock_type
+class Diagnosis(BaseModel):
+    condition: str
+    reasoning: str
+    confidence: float
+
+# Create HIPAA-compliant blackboard
+flock = Flock(os.getenv("DEFAULT_MODEL", "openai/gpt-4.1"))
+
+# Radiologist with privacy controls
+radiologist = (
+    flock.agent("radiologist")
+    .consumes(PatientScan)
+    .publishes(
+        XRayAnalysis,
+        visibility=PrivateVisibility(agents={"diagnostician"})  # HIPAA!
+    )
+)
+
+# Lab tech with multi-tenancy
+lab_tech = (
+    flock.agent("lab_tech")
+    .consumes(PatientScan)
+    .publishes(
+        LabResults,
+        visibility=TenantVisibility(tenant_id="patient_123")  # Isolation!
+    )
+)
+
+# Diagnostician with explicit access
+diagnostician = (
+    flock.agent("diagnostician")
+    .identity(AgentIdentity(name="diagnostician", labels={"role:physician"}))
+    .consumes(XRayAnalysis, LabResults)  # Waits for BOTH
+    .publishes(
+        Diagnosis,
+        visibility=LabelledVisibility(required_labels={"role:physician"})
+    )
+)
+
+# Run with tracing
+async with flock.traced_run("patient_123_diagnosis"):
+    await flock.publish(PatientScan(patient_id="123", ...))
+    await flock.run_until_idle()
+
+    # Get diagnosis (type-safe retrieval)
+    diagnoses = await flock.store.get_by_type(Diagnosis)
+```

flock_core-0.5.0b65/docs/about/roadmap.md

@@ -0,0 +1,108 @@
+---
+title: Product Roadmap
+description: Flock's path from v0.5.0 to v1.0 - enterprise features, production readiness, and future vision
+tags:
+  - roadmap
+  - future
+  - community
+search:
+  boost: 1.2
+---
+
+# 🗺️ Flock Roadmap to 1.0
+
+**Building Enterprise Infrastructure for AI Agents**
+
+This roadmap outlines Flock's path from v0.5.0 (production-ready core) to v1.0 (enterprise-complete) by Q4 2025. We're confident we can deliver the remaining enterprise features by **Q4 2025**.
+
+---
+
+## ✅ What's Already Production-Ready (v0.5.0)
+
+### Core Framework
+- Blackboard orchestrator with typed artifacts
+- Declarative agent subscriptions (no graph wiring)
+- Automatic parallel + sequential execution
+- Zero-trust visibility model (5 visibility types)
+- Circuit breakers and self-trigger prevention
+- 743 tests with 77.65% coverage (86-100% on critical paths)
+- Type-safe retrieval API (`get_by_type()`)
+
+### Observability
+- OpenTelemetry distributed tracing
+- DuckDB trace storage (AI-queryable)
+- Real-time dashboard with WebSocket streaming
+- 7-mode trace viewer (Timeline, RED metrics, Dependencies, SQL)
+- Service filtering and CSV export
+- Full I/O capture with JSON viewer
+
+### Developer Experience
+- MCP integration (Model Context Protocol)
+- Best-of-N execution
+- Exclusive delivery (exactly-once)
+- Batch processing and join operations
+- Conditional consumption (`where=lambda`)
+- Rich console output and FastAPI service
+- Keyboard shortcuts (WCAG 2.1 AA compliant)
+
+---
+
+## 🧱 0.5.0 Beta Initiatives (In Flight)
+
+These are the features we are actively building for the 0.5.0 beta. Follow the linked GitHub issues to track progress:
+
+### Core data & governance
+- [#271](https://github.com/whiteducksoftware/flock/issues/271) — Durable blackboard persistence backends.
+- [#274](https://github.com/whiteducksoftware/flock/issues/274) — Serialization/export of blackboard state and registered agents.
+- [#273](https://github.com/whiteducksoftware/flock/issues/273) — Structured feedback channel for agent outputs.
+- [#281](https://github.com/whiteducksoftware/flock/issues/281) — Human-in-the-loop approval flow.
+
+### Execution patterns & scheduling
+- [#282](https://github.com/whiteducksoftware/flock/issues/282) — Fan-out / fan-in workflow helpers.
+- [#283](https://github.com/whiteducksoftware/flock/issues/283) — Time-based scheduling primitives.
+
+### REST access & integrations
+- [#286](https://github.com/whiteducksoftware/flock/issues/286) — Custom REST endpoint DSL.
+- [#287](https://github.com/whiteducksoftware/flock/issues/287) — Synchronous publish endpoint (single and batch).
+- [#288](https://github.com/whiteducksoftware/flock/issues/288) — Correlation-aware status endpoint.
+- [#289](https://github.com/whiteducksoftware/flock/issues/289) — Webhook notifications for published artifacts.
+- [#290](https://github.com/whiteducksoftware/flock/issues/290) — Schema discovery endpoints.
+- [#291](https://github.com/whiteducksoftware/flock/issues/291) — REST idempotency keys and error model.
+- [#292](https://github.com/whiteducksoftware/flock/issues/292) — Artifact listing and filtering API.
+- [#293](https://github.com/whiteducksoftware/flock/issues/293) — OpenAPI specification generation.
+
+### Documentation & onboarding
+- [#270](https://github.com/whiteducksoftware/flock/issues/270) — MkDocs-powered documentation site.
+- [#269](https://github.com/whiteducksoftware/flock/issues/269) — Revamped example catalog.
+
+---
+
+## 🚀 Flock 1.0 (Target Q4 2025)
+
+Once the 0.5.0 beta ships, we will focus on the remaining enterprise capabilities before the 1.0 release.
+
+### Reliability & operations
+- [#277](https://github.com/whiteducksoftware/flock/issues/277) — Advanced retry strategy, dead-letter queues, per-agent circuit breakers.
+- [#278](https://github.com/whiteducksoftware/flock/issues/278) — Kafka-backed event backbone with replay and time-travel debugging.
+- [#279](https://github.com/whiteducksoftware/flock/issues/279) — Kubernetes deployment tooling (Helm charts, auto-scaling).
+- [#294](https://github.com/whiteducksoftware/flock/issues/294) — Workflow lifecycle controls (pause, resume, cancel).
+
+### Platform validation & quality
+- [#275](https://github.com/whiteducksoftware/flock/issues/275) — Benchmarking suite against industry workloads.
+- [#276](https://github.com/whiteducksoftware/flock/issues/276) — Automated evaluation harness for datasets/metrics.
+- [#284](https://github.com/whiteducksoftware/flock/issues/284) — Test coverage expansion to 85%+ with 1,000 tests.
+- [#285](https://github.com/whiteducksoftware/flock/issues/285) — Production validation pilots with launch partners.
+
+### Security & access
+- [#280](https://github.com/whiteducksoftware/flock/issues/280) — Authentication & authorization (OAuth/OIDC, API keys).
+
+---
+
+## 📌 Staying in the Loop
+
+- ⭐ Star the [GitHub repository](https://github.com/whiteducksoftware/flock)
+- 🗓️ Join community calls and roadmap discussions (announced in Discord/Slack)
+- 💬 Open issues or discussions to influence priorities
+- 📨 Contact [support@whiteduck.de](mailto:support@whiteduck.de) for enterprise questions
+
+We’ll publish release notes as each milestone lands and keep this document in sync with the public issue tracker.