flock-core 0.5.1__tar.gz → 0.5.3__tar.gz

{flock_core-0.5.1 → flock_core-0.5.3}/.gitignore

@@ -2,7 +2,7 @@
 __pycache__/
 *.py[codz]
 *$py.class
-
+.tmp/
 # C extensions
 *.so
 .claude-flow/

{flock_core-0.5.1 → flock_core-0.5.3}/AGENTS.md

@@ -92,7 +92,16 @@ uv run python examples/02-dashboard/03_code_detective.py
 
 For deep dives into specific topics, see:
 
+**Core Architecture:**
 - **[Architecture & Blackboard](docs/guides/blackboard.md)** - Core pattern, structure, and behavior
+- **[Agent Guide](docs/guides/agents.md)** - Complete agent development reference
+
+**Logic Operations (Advanced Subscriptions):**
+- **[Predicates](docs/guides/predicates.md)** - Conditional consumption with `where=` filters
+- **[Join Operations](docs/guides/join-operations.md)** - Correlate related artifacts with JoinSpec
+- **[Batch Processing](docs/guides/batch-processing.md)** - Efficient bulk operations with BatchSpec
+
+**Development & Operations:**
 - **[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

{flock_core-0.5.1 → flock_core-0.5.3}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.1
+Version: 0.5.3
 Summary: Flock: A declrative framework for building and orchestrating AI agents.
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
+License: MIT
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: aiosqlite>=0.20.0
@@ -34,10 +35,10 @@ Description-Content-Type: text/markdown
   <img alt="Flock Banner" src="docs/assets/images/flock.png" width="800">
 </p>
 <p align="center">
-  <a href="https://docs.flock.whiteduck.de" target="_blank"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge&logo=readthedocs"></a>
+  <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">
-  <a href="LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/pypi/l/flock-core?style=for-the-badge"></a>
+  <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>
   <img alt="Test Coverage" src="https://img.shields.io/badge/coverage-77%25-green?style=for-the-badge">
   <img alt="Tests" src="https://img.shields.io/badge/tests-743%20passing-brightgreen?style=for-the-badge">
@@ -51,14 +52,14 @@ Description-Content-Type: text/markdown
 
 Flock is a production-focused framework for orchestrating AI agents through **declarative type contracts** and **blackboard architecture**—proven patterns from distributed systems, decades of experience with microservice architectures, and classical AI—now applied to modern LLMs.
 
-**📖 [Read the full documentation →](https://docs.flock.whiteduck.de)**
+**📖 [Read the full documentation →](https://whiteducksoftware.github.io/flock)**
 
 **Quick links:**
-- **[Getting Started](https://docs.flock.whiteduck.de/getting-started/installation/)** - Installation and first steps
-- **[Tutorials](https://docs.flock.whiteduck.de/tutorials/)** - Step-by-step learning path
-- **[User Guides](https://docs.flock.whiteduck.de/guides/)** - In-depth feature documentation
-- **[API Reference](https://docs.flock.whiteduck.de/reference/api/)** - Complete API documentation
-- **[Roadmap](https://docs.flock.whiteduck.de/about/roadmap/)** - What's coming in v1.0
+- **[Getting Started](https://whiteducksoftware.github.io/flock/getting-started/installation/)** - Installation and first steps
+- **[Tutorials](https://whiteducksoftware.github.io/flock/tutorials/)** - Step-by-step learning path
+- **[User Guides](https://whiteducksoftware.github.io/flock/guides/)** - In-depth feature documentation
+- **[API Reference](https://whiteducksoftware.github.io/flock/reference/api/)** - Complete API documentation
+- **[Roadmap](https://whiteducksoftware.github.io/flock/about/roadmap/)** - What's coming in v1.0
 
 ---
 
@@ -265,7 +266,7 @@ flock = Flock(os.getenv("DEFAULT_MODEL", "openai/gpt-4.1"))
 bug_detector = flock.agent("bug_detector").consumes(CodeSubmission).publishes(BugAnalysis)
 security_auditor = flock.agent("security_auditor").consumes(CodeSubmission).publishes(SecurityAnalysis)
 
-# This agent AUTOMATICALLY waits for both analyses
+# AND gate: This agent AUTOMATICALLY waits for BOTH analyses before triggering
 final_reviewer = flock.agent("final_reviewer").consumes(BugAnalysis, SecurityAnalysis).publishes(FinalReview)
 
 # 4. Run with real-time dashboard
@@ -342,29 +343,77 @@ analyzer = (
 )
 ```
 
-**Advanced subscriptions:**
+**Logic Operations (AND/OR Gates):**
+
+Flock provides intuitive syntax for coordinating multiple input types:
 
 ```python
-# Conditional consumption - only high-severity cases
+# AND gate: Wait for BOTH types before triggering
+diagnostician = flock.agent("diagnostician").consumes(XRayAnalysis, LabResults).publishes(Diagnosis)
+# Agent triggers only when both XRayAnalysis AND LabResults are available
+
+# OR gate: Trigger on EITHER type (via chaining)
+alert_handler = flock.agent("alerts").consumes(SystemAlert).consumes(UserAlert).publishes(Response)
+# Agent triggers when SystemAlert OR UserAlert is published
+
+# Count-based AND gate: Wait for MULTIPLE instances of the same type
+aggregator = flock.agent("aggregator").consumes(Order, Order, Order).publishes(BatchSummary)
+# Agent triggers when THREE Order artifacts are available
+
+# Mixed counts: Different requirements per type
+validator = flock.agent("validator").consumes(Image, Image, Metadata).publishes(ValidationResult)
+# Agent triggers when TWO Images AND ONE Metadata are available
+```
+
+**What just happened:**
+- ✅ **Natural syntax** - Code clearly expresses intent ("wait for 3 orders")
+- ✅ **Order-independent** - Artifacts can arrive in any sequence
+- ✅ **Latest wins** - If 4 As arrive but need 3, uses the 3 most recent
+- ✅ **Zero configuration** - No manual coordination logic needed
+
+**Advanced subscriptions unlock crazy powerful patterns:**
+
+```python
+# 🎯 Predicates - Smart filtering (only process critical cases)
 urgent_care = flock.agent("urgent").consumes(
     Diagnosis,
-    where=lambda d: d.severity in ["Critical", "High"]
+    where=lambda d: d.severity in ["Critical", "High"]  # Conditional routing!
 )
 
-# Batch processing - wait for 10 items
-batch_processor = flock.agent("batch").consumes(
-    Event,
-    batch=BatchSpec(size=10, timeout=timedelta(seconds=30))
+# 📦 BatchSpec - Cost optimization (process 10 at once = 90% cheaper API calls)
+payment_processor = flock.agent("payments").consumes(
+    Transaction,
+    batch=BatchSpec(size=25, timeout=timedelta(seconds=30))  # $5 saved per batch!
 )
 
-# Join operations - wait for multiple types within time window
-correlator = flock.agent("correlator").consumes(
-    SignalA,
-    SignalB,
-    join=JoinSpec(within=timedelta(minutes=5))
+# 🔗 JoinSpec - Data correlation (match orders + shipments by ID)
+customer_service = flock.agent("notifications").consumes(
+    Order,
+    Shipment,
+    join=JoinSpec(by=lambda x: x.order_id, within=timedelta(hours=24))  # Correlated!
+)
+
+# 🏭 Combined Features - Correlate sensors, THEN batch for analysis
+quality_control = flock.agent("qc").consumes(
+    TemperatureSensor,
+    PressureSensor,
+    join=JoinSpec(by=lambda x: x.device_id, within=timedelta(seconds=30)),
+    batch=BatchSpec(size=5, timeout=timedelta(seconds=45))  # IoT at scale!
 )
 ```
 
+**What just happened:**
+- ✅ **Predicates** route work by business rules ("only critical severity")
+- ✅ **BatchSpec** optimizes costs (25 transactions = 1 API call instead of 25)
+- ✅ **JoinSpec** correlates related data (orders ↔ shipments, sensors ↔ readings)
+- ✅ **Combined** delivers production-grade multi-stage pipelines
+
+**Real-world impact:**
+- 💰 E-commerce: Save $5 per batch on payment processing fees
+- 🏥 Healthcare: Correlate patient scans + lab results for diagnosis
+- 🏭 Manufacturing: Monitor 1000+ IoT sensors with efficient batching
+- 📊 Finance: Match trades + confirmations within 5-minute windows
+
 ### Visibility Controls (The Security)
 
 **Unlike other frameworks, Flock has zero-trust security built-in:**
@@ -890,14 +939,14 @@ uv run python examples/02-dashboard/01_declarative_pizza.py
 - 📚 [Examples README](examples/README.md) - 12-step learning path from basics to advanced
 - 🖥️ [CLI Examples](examples/01-cli/) - Detailed console output examples (01-12)
 - 📊 [Dashboard Examples](examples/02-dashboard/) - Interactive visualization examples (01-12)
-- 📖 [Documentation](https://docs.flock.whiteduck.de) - Complete online documentation
+- 📖 [Documentation](https://whiteducksoftware.github.io/flock) - Complete online documentation
 - 📘 [AGENTS.md](AGENTS.md) - Development guide
 
 ---
 
 ## Contributing
 
-We're building Flock in the open. See **[Contributing Guide](https://docs.flock.whiteduck.de/about/contributing/)** for development setup, or check [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) locally.
+We're building Flock in the open. See **[Contributing Guide](https://whiteducksoftware.github.io/flock/about/contributing/)** for development setup, or check [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) locally.
 
 **We welcome:**
 - Bug reports and feature requests
@@ -960,7 +1009,7 @@ We're calling this 0.5 to signal:
 
 **"Declarative contracts eliminate prompt hell. Blackboard architecture eliminates graph spaghetti. Proven patterns applied to modern LLMs."**
 
-[⭐ Star on GitHub](https://github.com/whiteducksoftware/flock-flow) | [📖 Documentation](https://docs.flock.whiteduck.de) | [🚀 Try Examples](examples/) | [💼 Enterprise Support](mailto:support@whiteduck.de)
+[⭐ Star on GitHub](https://github.com/whiteducksoftware/flock-flow) | [📖 Documentation](https://whiteducksoftware.github.io/flock) | [🚀 Try Examples](examples/) | [💼 Enterprise Support](mailto:support@whiteduck.de)
 
 </div>
 

{flock_core-0.5.1 → flock_core-0.5.3}/README.md

@@ -2,10 +2,10 @@
   <img alt="Flock Banner" src="docs/assets/images/flock.png" width="800">
 </p>
 <p align="center">
-  <a href="https://docs.flock.whiteduck.de" target="_blank"><img alt="Documentation" src="https://img.shields.io/badge/docs-online-blue?style=for-the-badge&logo=readthedocs"></a>
+  <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">
-  <a href="LICENSE" target="_blank"><img alt="License" src="https://img.shields.io/pypi/l/flock-core?style=for-the-badge"></a>
+  <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>
   <img alt="Test Coverage" src="https://img.shields.io/badge/coverage-77%25-green?style=for-the-badge">
   <img alt="Tests" src="https://img.shields.io/badge/tests-743%20passing-brightgreen?style=for-the-badge">
@@ -19,14 +19,14 @@
 
 Flock is a production-focused framework for orchestrating AI agents through **declarative type contracts** and **blackboard architecture**—proven patterns from distributed systems, decades of experience with microservice architectures, and classical AI—now applied to modern LLMs.
 
-**📖 [Read the full documentation →](https://docs.flock.whiteduck.de)**
+**📖 [Read the full documentation →](https://whiteducksoftware.github.io/flock)**
 
 **Quick links:**
-- **[Getting Started](https://docs.flock.whiteduck.de/getting-started/installation/)** - Installation and first steps
-- **[Tutorials](https://docs.flock.whiteduck.de/tutorials/)** - Step-by-step learning path
-- **[User Guides](https://docs.flock.whiteduck.de/guides/)** - In-depth feature documentation
-- **[API Reference](https://docs.flock.whiteduck.de/reference/api/)** - Complete API documentation
-- **[Roadmap](https://docs.flock.whiteduck.de/about/roadmap/)** - What's coming in v1.0
+- **[Getting Started](https://whiteducksoftware.github.io/flock/getting-started/installation/)** - Installation and first steps
+- **[Tutorials](https://whiteducksoftware.github.io/flock/tutorials/)** - Step-by-step learning path
+- **[User Guides](https://whiteducksoftware.github.io/flock/guides/)** - In-depth feature documentation
+- **[API Reference](https://whiteducksoftware.github.io/flock/reference/api/)** - Complete API documentation
+- **[Roadmap](https://whiteducksoftware.github.io/flock/about/roadmap/)** - What's coming in v1.0
 
 ---
 
@@ -233,7 +233,7 @@ flock = Flock(os.getenv("DEFAULT_MODEL", "openai/gpt-4.1"))
 bug_detector = flock.agent("bug_detector").consumes(CodeSubmission).publishes(BugAnalysis)
 security_auditor = flock.agent("security_auditor").consumes(CodeSubmission).publishes(SecurityAnalysis)
 
-# This agent AUTOMATICALLY waits for both analyses
+# AND gate: This agent AUTOMATICALLY waits for BOTH analyses before triggering
 final_reviewer = flock.agent("final_reviewer").consumes(BugAnalysis, SecurityAnalysis).publishes(FinalReview)
 
 # 4. Run with real-time dashboard
@@ -310,29 +310,77 @@ analyzer = (
 )
 ```
 
-**Advanced subscriptions:**
+**Logic Operations (AND/OR Gates):**
+
+Flock provides intuitive syntax for coordinating multiple input types:
 
 ```python
-# Conditional consumption - only high-severity cases
+# AND gate: Wait for BOTH types before triggering
+diagnostician = flock.agent("diagnostician").consumes(XRayAnalysis, LabResults).publishes(Diagnosis)
+# Agent triggers only when both XRayAnalysis AND LabResults are available
+
+# OR gate: Trigger on EITHER type (via chaining)
+alert_handler = flock.agent("alerts").consumes(SystemAlert).consumes(UserAlert).publishes(Response)
+# Agent triggers when SystemAlert OR UserAlert is published
+
+# Count-based AND gate: Wait for MULTIPLE instances of the same type
+aggregator = flock.agent("aggregator").consumes(Order, Order, Order).publishes(BatchSummary)
+# Agent triggers when THREE Order artifacts are available
+
+# Mixed counts: Different requirements per type
+validator = flock.agent("validator").consumes(Image, Image, Metadata).publishes(ValidationResult)
+# Agent triggers when TWO Images AND ONE Metadata are available
+```
+
+**What just happened:**
+- ✅ **Natural syntax** - Code clearly expresses intent ("wait for 3 orders")
+- ✅ **Order-independent** - Artifacts can arrive in any sequence
+- ✅ **Latest wins** - If 4 As arrive but need 3, uses the 3 most recent
+- ✅ **Zero configuration** - No manual coordination logic needed
+
+**Advanced subscriptions unlock crazy powerful patterns:**
+
+```python
+# 🎯 Predicates - Smart filtering (only process critical cases)
 urgent_care = flock.agent("urgent").consumes(
     Diagnosis,
-    where=lambda d: d.severity in ["Critical", "High"]
+    where=lambda d: d.severity in ["Critical", "High"]  # Conditional routing!
 )
 
-# Batch processing - wait for 10 items
-batch_processor = flock.agent("batch").consumes(
-    Event,
-    batch=BatchSpec(size=10, timeout=timedelta(seconds=30))
+# 📦 BatchSpec - Cost optimization (process 10 at once = 90% cheaper API calls)
+payment_processor = flock.agent("payments").consumes(
+    Transaction,
+    batch=BatchSpec(size=25, timeout=timedelta(seconds=30))  # $5 saved per batch!
 )
 
-# Join operations - wait for multiple types within time window
-correlator = flock.agent("correlator").consumes(
-    SignalA,
-    SignalB,
-    join=JoinSpec(within=timedelta(minutes=5))
+# 🔗 JoinSpec - Data correlation (match orders + shipments by ID)
+customer_service = flock.agent("notifications").consumes(
+    Order,
+    Shipment,
+    join=JoinSpec(by=lambda x: x.order_id, within=timedelta(hours=24))  # Correlated!
+)
+
+# 🏭 Combined Features - Correlate sensors, THEN batch for analysis
+quality_control = flock.agent("qc").consumes(
+    TemperatureSensor,
+    PressureSensor,
+    join=JoinSpec(by=lambda x: x.device_id, within=timedelta(seconds=30)),
+    batch=BatchSpec(size=5, timeout=timedelta(seconds=45))  # IoT at scale!
 )
 ```
 
+**What just happened:**
+- ✅ **Predicates** route work by business rules ("only critical severity")
+- ✅ **BatchSpec** optimizes costs (25 transactions = 1 API call instead of 25)
+- ✅ **JoinSpec** correlates related data (orders ↔ shipments, sensors ↔ readings)
+- ✅ **Combined** delivers production-grade multi-stage pipelines
+
+**Real-world impact:**
+- 💰 E-commerce: Save $5 per batch on payment processing fees
+- 🏥 Healthcare: Correlate patient scans + lab results for diagnosis
+- 🏭 Manufacturing: Monitor 1000+ IoT sensors with efficient batching
+- 📊 Finance: Match trades + confirmations within 5-minute windows
+
 ### Visibility Controls (The Security)
 
 **Unlike other frameworks, Flock has zero-trust security built-in:**
@@ -858,14 +906,14 @@ uv run python examples/02-dashboard/01_declarative_pizza.py
 - 📚 [Examples README](examples/README.md) - 12-step learning path from basics to advanced
 - 🖥️ [CLI Examples](examples/01-cli/) - Detailed console output examples (01-12)
 - 📊 [Dashboard Examples](examples/02-dashboard/) - Interactive visualization examples (01-12)
-- 📖 [Documentation](https://docs.flock.whiteduck.de) - Complete online documentation
+- 📖 [Documentation](https://whiteducksoftware.github.io/flock) - Complete online documentation
 - 📘 [AGENTS.md](AGENTS.md) - Development guide
 
 ---
 
 ## Contributing
 
-We're building Flock in the open. See **[Contributing Guide](https://docs.flock.whiteduck.de/about/contributing/)** for development setup, or check [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) locally.
+We're building Flock in the open. See **[Contributing Guide](https://whiteducksoftware.github.io/flock/about/contributing/)** for development setup, or check [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) locally.
 
 **We welcome:**
 - Bug reports and feature requests
@@ -928,7 +976,7 @@ We're calling this 0.5 to signal:
 
 **"Declarative contracts eliminate prompt hell. Blackboard architecture eliminates graph spaghetti. Proven patterns applied to modern LLMs."**
 
-[⭐ Star on GitHub](https://github.com/whiteducksoftware/flock-flow) | [📖 Documentation](https://docs.flock.whiteduck.de) | [🚀 Try Examples](examples/) | [💼 Enterprise Support](mailto:support@whiteduck.de)
+[⭐ Star on GitHub](https://github.com/whiteducksoftware/flock-flow) | [📖 Documentation](https://whiteducksoftware.github.io/flock) | [🚀 Try Examples](examples/) | [💼 Enterprise Support](mailto:support@whiteduck.de)
 
 </div>
 

{flock_core-0.5.1 → flock_core-0.5.3}/docs/getting-started/concepts.md

@@ -433,6 +433,107 @@ analyzer = (
 
 ---
 
+## Logic Operations (AND/OR Gates)
+
+**Control how agents wait for multiple artifacts with declarative logic gates.**
+
+Flock Flow supports three coordination patterns for multi-artifact subscriptions:
+
+### AND Gates: Wait for ALL Types
+
+**Syntax:** `.consumes(TypeA, TypeB)` in a single call
+
+```python
+# Diagnostician waits for BOTH X-ray AND lab results
+diagnostician = (
+    flock.agent("diagnostician")
+    .consumes(XRayAnalysis, LabResults)  # AND gate: waits for both
+    .publishes(Diagnosis)
+)
+```
+
+**Timeline:**
+```
+t0: XRayAnalysis published → diagnostician WAITS (needs LabResults too)
+t1: LabResults published → diagnostician TRIGGERS with both artifacts
+```
+
+### OR Gates: Trigger on ANY Type
+
+**Syntax:** Chain multiple `.consumes()` calls
+
+```python
+# Alert handler triggers on EITHER system OR user alert
+alert_handler = (
+    flock.agent("alert_handler")
+    .consumes(SystemAlert)      # OR
+    .consumes(UserAlert)        # OR
+    .publishes(AlertResponse)
+)
+```
+
+**Timeline:**
+```
+t0: SystemAlert published → alert_handler TRIGGERS (doesn't need UserAlert)
+t1: UserAlert published → alert_handler TRIGGERS AGAIN (independent subscription)
+```
+
+### Count-Based AND Gates: Wait for MULTIPLE Instances
+
+**Syntax:** `.consumes(TypeA, TypeA, TypeA)` (repeat type N times)
+
+```python
+# Batch processor waits for THREE orders
+batch_processor = (
+    flock.agent("batch_processor")
+    .consumes(Order, Order, Order)  # AND gate: waits for 3 Orders
+    .publishes(BatchSummary)
+)
+```
+
+**Timeline:**
+```
+t0: Order #1 published → batch_processor WAITS (needs 2 more)
+t1: Order #2 published → batch_processor WAITS (needs 1 more)
+t2: Order #3 published → batch_processor TRIGGERS with all 3 Orders
+```
+
+**Mixed Counts:**
+```python
+# Wait for 2 images AND 1 metadata document
+validator = (
+    flock.agent("validator")
+    .consumes(Image, Image, Metadata)  # 2 Images + 1 Metadata
+    .publishes(ValidationResult)
+)
+```
+
+### Combining AND/OR Logic
+
+**AND + OR Pattern:**
+```python
+# Trigger on (TypeA AND TypeB) OR TypeC
+agent = (
+    flock.agent("flexible_agent")
+    .consumes(TypeA, TypeB)    # AND gate (waits for both)
+    .consumes(TypeC)           # OR (independent trigger)
+    .publishes(Result)
+)
+```
+
+**Timeline:**
+```
+Scenario 1: TypeA + TypeB published → agent TRIGGERS
+Scenario 2: TypeC published alone → agent TRIGGERS
+Scenario 3: TypeA alone → agent WAITS (needs TypeB for AND gate)
+```
+
+**Key Principle:** Each `.consumes()` call creates a separate subscription (OR). Multiple types in one call create an AND gate.
+
+[**👉 See complete AND/OR gate examples**](../guides/agents.md#logic-operations-andor-gates)
+
+---
+
 ## Visibility Controls (Zero-Trust Security)
 
 **Unlike other frameworks, Flock has zero-trust security built-in.** Control who sees what on the blackboard.
@@ -611,13 +712,35 @@ editor = flock.agent("editor").consumes(Draft).publishes(EditedDraft)
 publisher = flock.agent("publisher").consumes(EditedDraft).publishes(Article)
 ```
 
-**Parallel-Then-Join (A+B → C):**
+**Parallel-Then-Join with AND Gate (A+B → C):**
 ```python
 bugs = flock.agent("bugs").consumes(Code).publishes(BugReport)
 security = flock.agent("security").consumes(Code).publishes(SecurityReport)
+# AND gate: reviewer waits for BOTH BugReport AND SecurityReport
 reviewer = flock.agent("reviewer").consumes(BugReport, SecurityReport).publishes(FinalReview)
 ```
 
+**OR Gate via Chaining (A OR B → C):**
+```python
+# OR gate: handler triggers on EITHER SystemAlert OR UserAlert
+alert_handler = (
+    flock.agent("alert_handler")
+    .consumes(SystemAlert)      # Triggers on SystemAlert
+    .consumes(UserAlert)        # OR triggers on UserAlert
+    .publishes(AlertResponse)
+)
+```
+
+**Count-Based AND Gate (3× A → B):**
+```python
+# Wait for THREE Order artifacts before triggering
+batch_processor = (
+    flock.agent("batch_processor")
+    .consumes(Order, Order, Order)  # AND gate: waits for 3 Orders
+    .publishes(BatchSummary)
+)
+```
+
 **Fan-Out (A → B1, B2, ..., Bn):**
 ```python
 editor = flock.agent("editor").consumes(Topic).publishes(StoryIdea)

{flock_core-0.5.1 → flock_core-0.5.3}/docs/guides/agents.md

@@ -152,6 +152,148 @@ code_reviewer = (
 
 ---
 
+## Logic Operations (AND/OR Gates)
+
+Flock provides intuitive syntax for coordinating multiple input types through **AND gates**, **OR gates**, and **count-based logic**. This enables powerful coordination patterns without manual wiring.
+
+### AND Gates: Wait for ALL types
+
+**Use `.consumes(A, B)` to wait for multiple types before triggering:**
+
+```python
+# Diagnostician waits for BOTH inputs
+diagnostician = (
+    flock.agent("diagnostician")
+    .consumes(XRayAnalysis, LabResults)  # AND gate: waits for both
+    .publishes(Diagnosis)
+)
+```
+
+**How it works:**
+- Agent collects artifacts as they arrive
+- Triggers only when **ALL required types** are present
+- Order-independent: `XRay → Lab` or `Lab → XRay` both work
+- After triggering, the waiting pool clears for next cycle
+
+**Example timeline:**
+```
+Time 0: XRayAnalysis published → diagnostician waits...
+Time 1: LabResults published   → diagnostician triggers! ✅
+Time 2: Agent executes with BOTH artifacts
+```
+
+**Use cases:**
+- Multi-modal fusion (images + text + metadata)
+- Parallel analysis aggregation (multiple perspectives → final decision)
+- Dependency coordination (wait for prerequisites)
+
+### OR Gates: Trigger on ANY type
+
+**Use chained `.consumes()` to trigger on multiple types independently:**
+
+```python
+# Alert handler triggers on EITHER alert type
+alert_handler = (
+    flock.agent("alert_handler")
+    .consumes(SystemAlert)      # OR
+    .consumes(UserAlert)        # OR
+    .consumes(SecurityAlert)    # OR
+    .publishes(AlertResponse)
+)
+```
+
+**How it works:**
+- Each `.consumes()` creates a **separate subscription**
+- Agent triggers independently for each type
+- Single artifact per trigger (not accumulated)
+
+**Example timeline:**
+```
+Time 0: SystemAlert published   → alert_handler triggers ✅
+Time 1: UserAlert published     → alert_handler triggers AGAIN ✅
+Time 2: SystemAlert published   → alert_handler triggers AGAIN ✅
+```
+
+**Use cases:**
+- Polymorphic handling (multiple input types, same logic)
+- Event routing (different triggers, same response)
+- Flexible inputs (accept various formats)
+
+### Count-Based AND Gates: Wait for MULTIPLE instances
+
+**Use duplicate types to wait for multiple instances:**
+
+```python
+# Wait for THREE orders before processing
+batch_processor = (
+    flock.agent("batch_processor")
+    .consumes(Order, Order, Order)  # Waits for 3 Orders
+    .publishes(BatchSummary)
+)
+
+# Mixed counts: 2 Images + 1 Metadata
+validator = (
+    flock.agent("validator")
+    .consumes(Image, Image, Metadata)  # Waits for 2 Images AND 1 Metadata
+    .publishes(ValidationResult)
+)
+```
+
+**How it works:**
+- Flock counts required instances per type
+- Artifacts collected until counts satisfied
+- Order-independent (any arrival sequence works)
+- **Latest wins**: If 4 Orders arrive but need 3, uses 3 most recent
+
+**Example timeline:**
+```
+Time 0: Order #1 published → batch_processor waits... (need 3)
+Time 1: Order #2 published → batch_processor waits... (need 1 more)
+Time 2: Order #3 published → batch_processor triggers! ✅
+Time 3: Agent executes with all 3 Orders
+```
+
+**Use cases:**
+- Batch aggregation ("wait for 10 reviews before analyzing")
+- Quorum logic ("need 3 validator approvals")
+- Data fusion ("need 5 sensor readings before prediction")
+
+### Combining Logic Operations
+
+**Mix AND, OR, and count-based logic:**
+
+```python
+# Complex: (2 Images AND 1 Metadata) OR (3 Scans)
+processor = (
+    flock.agent("processor")
+    .consumes(Image, Image, Metadata)  # AND gate with counts
+    .consumes(Scan, Scan, Scan)        # OR gate: separate trigger path
+    .publishes(ProcessedData)
+)
+```
+
+**How it works:**
+- First `.consumes()` creates AND gate waiting for 2 Images + 1 Metadata
+- Second `.consumes()` creates OR gate waiting for 3 Scans
+- Agent triggers when **either condition** satisfied
+
+### Best Practices
+
+**✅ Do:**
+- Use AND gates for multi-modal fusion
+- Use OR gates for polymorphic inputs
+- Use count-based logic for batch operations
+- Choose syntax that matches your intent
+
+**❌ Don't:**
+- Mix AND/OR without understanding separate subscriptions
+- Forget that OR gates create independent triggers
+- Assume specific artifact ordering
+
+[**👉 See AND/OR gates in action: Debate Club**](https://github.com/whiteducksoftware/flock/blob/main/examples/02-dashboard/09_debate_club.py)
+
+---
+
 ## Advanced Subscriptions
 
 ### Conditional Consumption (Filtering)