flock-core 0.5.2__tar.gz → 0.5.4__tar.gz

{flock_core-0.5.2 → flock_core-0.5.4}/.gitignore

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

{flock_core-0.5.2 → flock_core-0.5.4}/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.2 → flock_core-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.2
+Version: 0.5.4
 Summary: Flock: A declrative framework for building and orchestrating AI agents.
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License: MIT
@@ -266,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
@@ -343,29 +343,85 @@ 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:**
+
+<p align="center">
+  <img alt="Event Join" src="docs/assets/images/join.png" width="800">
+</p>
+
+```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
+
+<p align="center">
+  <img alt="Event Batch" src="docs/assets/images/batch.png" width="800">
+</p>
+
 ### Visibility Controls (The Security)
 
 **Unlike other frameworks, Flock has zero-trust security built-in:**

{flock_core-0.5.2 → flock_core-0.5.4}/README.md

@@ -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,85 @@ 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:**
+
+<p align="center">
+  <img alt="Event Join" src="docs/assets/images/join.png" width="800">
+</p>
+
+```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
+
+<p align="center">
+  <img alt="Event Batch" src="docs/assets/images/batch.png" width="800">
+</p>
+
 ### Visibility Controls (The Security)
 
 **Unlike other frameworks, Flock has zero-trust security built-in:**

{flock_core-0.5.2 → flock_core-0.5.4}/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.2 → flock_core-0.5.4}/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)