flock-core 0.5.0b61__tar.gz → 0.5.0b63__tar.gz

{flock_core-0.5.0b61 → flock_core-0.5.0b63}/.pre-commit-config.yaml

@@ -79,7 +79,7 @@ repos:
         name: frontend build check
         entry: bash -c 'cd src/flock/frontend && npm run build'
         language: system
-        files: ^frontend/
+        files: ^src/flock/frontend/
         pass_filenames: false
         stages: [pre-push]  # Only on push, not on every commit
 

{flock_core-0.5.0b61 → flock_core-0.5.0b63}/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:** 0.1.16
+**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
@@ -51,7 +51,7 @@ A blackboard architecture framework where specialized AI agents collaborate thro
 
 - **Python 3.10+** (we use modern async features)
 - **UV package manager** (faster than pip, handles virtual envs)
-- **Node.js 22+** (for dashboard frontend)
+- **Node.js 18+** (22+ recommended) for dashboard frontend
 - **OpenAI API key** (for running examples)
 
 ### Installation
@@ -66,7 +66,7 @@ poe install  # Equivalent to: uv sync --dev --all-groups --all-extras
 
 # Set up environment
 export OPENAI_API_KEY="sk-..."
-export DEFAULT_MODEL="openai/gpt-4o-mini"
+export DEFAULT_MODEL="openai/gpt-4.1"
 
 # Verify installation
 uv run python -c "from flock import Flock; print('✅ Ready!')"
@@ -75,14 +75,14 @@ uv run python -c "from flock import Flock; print('✅ Ready!')"
 ### Run Examples
 
 ```bash
-# Showcase examples (workshops & demos)
-uv run python examples/showcase/01_hello_flock.py
-uv run python examples/showcase/02_blog_review.py
-uv run python examples/showcase/04_dashboard.py
-
-# Feature examples (with assertions)
-uv run python examples/features/feedback_prevention.py
-uv run python examples/features/visibility/public_visibility.py
+# Core examples
+uv run python examples/01-the-declarative-way/01_declarative_pizza.py
+uv run python examples/01-the-declarative-way/02_input_and_output.py
+
+# Dashboard examples
+uv run python examples/03-the-dashboard/01_declarative_pizza.py
+uv run python examples/03-the-dashboard/02-dashboard-edge-cases.py
+uv run python examples/03-the-dashboard/03-scale-test-100-agents.py
 ```
 
 ---
@@ -91,45 +91,37 @@ uv run python examples/features/visibility/public_visibility.py
 
 For deep dives into specific topics, see:
 
-- **[Architecture Guide](docs/ai-agents/architecture.md)** - Core architecture, project structure, code style
-- **[Development Workflow](docs/ai-agents/development.md)** - Testing, quality standards, versioning, pre-commit hooks
-- **[Frontend Guide](docs/ai-agents/frontend.md)** - Dashboard usage, frontend development, React/TypeScript
-- **[Dependencies Guide](docs/ai-agents/dependencies.md)** - Package management, UV commands, adding dependencies
-- **[Common Tasks](docs/ai-agents/common-tasks.md)** - Adding agents/components, performance tips, security
+- **[Architecture & Blackboard](docs/guides/blackboard.md)** - Core pattern, structure, and behavior
+- **[Development Workflow](docs/about/contributing.md)** - Testing, quality, versioning, pre-commit
+- **[Frontend/Dashboard](docs/guides/dashboard.md)** - Dashboard usage and development
+- **[Configuration & Dependencies](docs/reference/configuration.md)** - Environment and setup
+- **[Patterns & Common Tasks](docs/guides/patterns.md)** - Recipes, performance, security
 
 ---
 
 ## 🚨 CRITICAL PATTERNS (Learn from Our Experience)
 
-### ⚡ invoke() vs run_until_idle() - The Double Execution Trap
+### ⚡ invoke() vs run_until_idle() - Execution Control (no double-run by default)
 
 **This pattern cost us hours of debugging - learn from our pain!**
 
-#### The Problem
-After API migration from `arun()` to `invoke()`, tests started executing component hooks **twice**:
-
-```python
-# Expected: ['A', 'B', 'C']
-# Actual: ['A', 'B', 'C', 'A', 'B', 'C']  # Double execution!
-```
+#### The Goal
+Choose between isolated agent execution and event-driven cascades.
 
-#### Root Cause Analysis
-`invoke()` method behavior depends on `publish_outputs` parameter:
+#### How it works
+`invoke()` behavior depends on `publish_outputs`:
 
 ```python
-# invoke() with default publish_outputs=True:
-await orchestrator.invoke(agent, input_artifact)
-await orchestrator.run_until_idle()  # ❌ Triggers SECOND execution!
-
-# invoke() with publish_outputs=False:
+# Isolated: execute agent only (no cascade)
 await orchestrator.invoke(agent, input_artifact, publish_outputs=False)
-# ✅ No double execution - just direct agent execution
+
+# Cascading: execute and publish outputs, then run downstream agents
+await orchestrator.invoke(agent, input_artifact, publish_outputs=True)
+await orchestrator.run_until_idle()  # processes downstream agents
 ```
 
-**Why this happens:**
-1. `invoke(..., publish_outputs=True)` executes agent AND publishes results to blackboard
-2. `run_until_idle()` processes published artifacts, triggering agent execution again
-3. Component hooks fire on BOTH executions → double execution
+Notes:
+- By default, agents have `prevent_self_trigger=True`, so an agent will not re-run on its own outputs when you call `run_until_idle()`. Downstream agents that subscribe to the output types will run.
 
 #### When to Use Which Pattern
 
@@ -161,12 +153,12 @@ assert len(output_artifacts) == 3
 #### Quick Reference
 
 | Scenario | invoke() call | run_until_idle() | Result |
-|----------|---------------|------------------|---------|
-| Unit test | `invoke(..., publish_outputs=False)` | No | ✅ Single execution |
-| Integration test | `invoke(..., publish_outputs=True)` | Yes | ✅ Cascade execution |
-| Bug we fixed | `invoke(..., publish_outputs=True)` | Yes | ❌ Double execution |
+|----------|---------------|------------------|--------|
+| Unit test | `invoke(..., publish_outputs=False)` | No | Single execution |
+| Integration test | `invoke(..., publish_outputs=True)` | Yes | Cascade to downstream agents |
+| Common mistake | `invoke(..., publish_outputs=True)` | Yes | Not a double-run; downstream agents run |
 
-**Rule of thumb:** Start with `publish_outputs=False` for tests, only enable publication if you specifically need cascade behavior.
+Rule of thumb: start with `publish_outputs=False` for unit tests; enable publication only when you want cascades.
 
 ---
 
@@ -297,7 +289,7 @@ The automated PyPI release pipeline checks if the version in `pyproject.toml` ha
 
 #### What to Bump
 
-**Backend version (REQUIRED for ALL changes):**
+**Backend version (REQUIRED for backend code changes):**
 ```toml
 # pyproject.toml
 [project]
@@ -317,14 +309,15 @@ version = "0.5.0b56"  # Increment this! e.g., "0.5.0b57"
 **✅ ALWAYS bump backend version for:**
 - Any Python code changes in `src/flock/`
 - Bug fixes, features, refactors
-- Documentation changes (increment patch)
-- Any commit that will be pushed to a branch
+- Commits that modify backend behavior
+
+Docs-only changes (in `docs/`, `README.md`) do not require a version bump.
 
 **✅ ALWAYS bump frontend version for:**
 - Dashboard UI changes
 - React/TypeScript component updates
 - CSS/styling changes
-- Any changes in `src/flock/frontend/src/`
+- Any changes in `src/flock/frontend/`
 
 #### Versioning Pattern
 
@@ -940,7 +933,7 @@ Always use the appropriate subdirectory:
 - **Source Code**: `/src/flock` - Production code only
 - **Documentation**: `/docs` - Documentation only
 - **Examples**: `/examples` - Example scripts only
-- **Frontend**: `/frontend/src` - React components and frontend code
+- **Frontend**: `src/flock/frontend/src` - React components and frontend code
 
 **Never create files in the root directory** - it should only contain configuration files like `pyproject.toml`, `README.md`, etc.
 

{flock_core-0.5.0b61 → flock_core-0.5.0b63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.0b61
+Version: 0.5.0b63
 Summary: Add your description here
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -178,7 +178,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 +437,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 +448,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 +488,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 +511,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 +565,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 +677,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.0b61 → flock_core-0.5.0b63}/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.0b63/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)
+```