flock-core 0.5.7__tar.gz → 0.5.8__tar.gz

{flock_core-0.5.7 → flock_core-0.5.8}/.github/workflows/deploy-whiteduck-pypi.yml

@@ -6,7 +6,6 @@ on:
   push:
     branches:
       - main # Replace with your default branch
-      - 0.5.0b
     paths:
       - 'pyproject.toml'  # Only trigger on changes to pyproject.toml (version number)
 
@@ -15,8 +14,6 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.10"
-          - "3.11"
           - "3.12"
           - "3.13"
     runs-on: ubuntu-latest

{flock_core-0.5.7 → flock_core-0.5.8}/AGENTS.md

@@ -40,6 +40,7 @@ A blackboard architecture framework where specialized AI agents collaborate thro
 - **Artifacts:** Typed data (Pydantic models) published to blackboard
 - **Subscriptions:** Declarative rules for when agents react
 - **Visibility:** Built-in access control (Public/Private/Tenant/Label-based/Time-based)
+- **Fan-Out Publishing:** Produce multiple artifacts from single agent execution with filtering/validation
 - **Components:** Three levels of extensibility:
   - **Orchestrator Components:** Global lifecycle hooks (monitoring, metrics, coordination)
   - **Agent Components:** Per-agent behavior (quality gates, retry logic, validation)
@@ -116,6 +117,9 @@ For deep dives into specific topics, see:
 - **[Join Operations](docs/guides/join-operations.md)** - Correlate related artifacts with JoinSpec
 - **[Batch Processing](docs/guides/batch-processing.md)** - Efficient bulk operations with BatchSpec
 
+**Publishing Patterns:**
+- **[Fan-Out Publishing](docs/guides/fan-out.md)** - Generate multiple outputs with filtering/validation ⭐ **NEW in 0.5**
+
 **Development & Operations:**
 - **[Development Workflow](docs/guides/testing.md)** - Testing, quality, versioning, pre-commit
 - **[Frontend/Dashboard](docs/guides/dashboard.md)** - Dashboard usage and development
@@ -1394,6 +1398,42 @@ agent = (
 await orchestrator.arun(agent, input_data)
 ```
 
+**Fan-out publishing (multiple outputs):**
+```python
+# Single-type fan-out: Generate 10 outputs per execution
+agent = (
+    orchestrator.agent("generator")
+    .consumes(InputType)
+    .publishes(OutputType, fan_out=10)
+)
+
+# Multi-output fan-out: Generate 3 of EACH type = 9 total artifacts in ONE LLM call!
+multi_master = (
+    orchestrator.agent("multi_master")
+    .consumes(Idea)
+    .publishes(Movie, MovieScript, MovieCampaign, fan_out=3)
+)
+# Result: 3 Movies + 3 MovieScripts + 3 MovieCampaigns = 9 artifacts
+# 89% cost savings vs 9 separate calls + perfect context alignment!
+
+# With filtering (reduce noise)
+agent.publishes(OutputType, fan_out=20, where=lambda o: o.score >= 8.0)
+
+# With validation (enforce quality)
+agent.publishes(
+    OutputType,
+    fan_out=10,
+    validate=lambda o: o.field in ["valid", "values"]
+)
+
+# With dynamic visibility (per-artifact access control)
+agent.publishes(
+    OutputType,
+    fan_out=5,
+    visibility=lambda o: PrivateVisibility(agents=[o.recipient])
+)
+```
+
 **Unified tracing:**
 ```python
 # Wrap workflow in single trace

{flock_core-0.5.7 → flock_core-0.5.8}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.7
+Version: 0.5.8
 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-Python: >=3.12
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: devtools>=0.12.2
 Requires-Dist: dspy==3.0.3
@@ -424,6 +424,101 @@ quality_control = flock.agent("qc").consumes(
   <img alt="Event Batch" src="docs/assets/images/batch.png" width="800">
 </p>
 
+### 🌟 Fan-Out Publishing (New in 0.5)
+
+**Produce multiple outputs from a single agent execution:**
+
+```python
+# Generate 10 diverse product ideas from one brief
+idea_generator = (
+    flock.agent("generator")
+    .consumes(ProductBrief)
+    .publishes(ProductIdea, fan_out=10)  # Produces 10 ideas per brief!
+)
+
+# With WHERE filtering - only publish high-quality ideas
+idea_generator = (
+    flock.agent("generator")
+    .consumes(ProductBrief)
+    .publishes(
+        ProductIdea,
+        fan_out=20,  # Generate 20 candidates
+        where=lambda idea: idea.score >= 8.0  # Only publish score >= 8
+    )
+)
+
+# With VALIDATE - enforce quality standards
+code_reviewer = (
+    flock.agent("reviewer")
+    .consumes(CodeSubmission)
+    .publishes(
+        BugReport,
+        fan_out=5,
+        validate=lambda bug: bug.severity in ["Critical", "High", "Medium", "Low"]
+    )
+)
+
+# With Dynamic Visibility - control access per artifact
+notification_agent = (
+    flock.agent("notifier")
+    .consumes(Alert)
+    .publishes(
+        Notification,
+        fan_out=3,
+        visibility=lambda n: PrivateVisibility(agents=[n.recipient])  # Dynamic!
+    )
+)
+```
+
+**What just happened:**
+- ✅ **fan_out=N** - Agent produces N artifacts per execution (not just 1!)
+- ✅ **where** - Filter outputs before publishing (reduce noise, save costs)
+- ✅ **validate** - Enforce quality standards (fail-fast on bad outputs)
+- ✅ **Dynamic visibility** - Control access per artifact based on content
+
+**Real-world impact:**
+- 🎯 **Content Generation** - Generate 10 blog post ideas, filter to top 3 by score
+- 🐛 **Code Review** - Produce 5 potential bugs, validate severity levels
+- 📧 **Notifications** - Create 3 notification variants, target specific agents
+- 🧪 **A/B Testing** - Generate N variations, filter by quality metrics
+
+**🤯 Multi-Output Fan-Out (New in 0.5)**
+
+**The truly mind-blowing part:** Fan-out works across **multiple output types**:
+
+```python
+# Generate 3 of EACH type = 9 total artifacts in ONE LLM call!
+multi_master = (
+    flock.agent("multi_master")
+    .consumes(Idea)
+    .publishes(Movie, MovieScript, MovieCampaign, fan_out=3)
+)
+
+# Single execution produces:
+# - 3 complete Movie artifacts (with title, genre, cast, plot)
+# - 3 complete MovieScript artifacts (with characters, scenes, pages)
+# - 3 complete MovieCampaign artifacts (with taglines, poster descriptions)
+# = 9 complex artifacts, ~100+ fields total, full Pydantic validation, ONE LLM call!
+
+await flock.publish(Idea(story_idea="An action thriller set in space"))
+await flock.run_until_idle()
+
+# Result: 9 artifacts on the blackboard, all validated, all ready
+movies = await flock.store.get_by_type(Movie)  # 3 movies
+scripts = await flock.store.get_by_type(MovieScript)  # 3 scripts
+campaigns = await flock.store.get_by_type(MovieCampaign)  # 3 campaigns
+```
+
+**Why this is revolutionary:**
+- ⚡ **Massive efficiency** - 1 LLM call generates 9 production-ready artifacts
+- ✅ **Full validation** - All 100+ fields validated with Pydantic constraints
+- 🎯 **Coherent generation** - Movie/Script/Campaign are thematically aligned (same LLM context)
+- 💰 **Cost optimized** - 9 artifacts for the price of 1 API call
+
+**Can any other agent framework do this?** We haven't found one. 🚀
+
+**📖 [Full Fan-Out Guide →](https://whiteducksoftware.github.io/flock/guides/fan-out/)**
+
 ### Visibility Controls (The Security)
 
 **Unlike other frameworks, Flock has zero-trust security built-in:**

{flock_core-0.5.7 → flock_core-0.5.8}/README.md

@@ -391,6 +391,101 @@ quality_control = flock.agent("qc").consumes(
   <img alt="Event Batch" src="docs/assets/images/batch.png" width="800">
 </p>
 
+### 🌟 Fan-Out Publishing (New in 0.5)
+
+**Produce multiple outputs from a single agent execution:**
+
+```python
+# Generate 10 diverse product ideas from one brief
+idea_generator = (
+    flock.agent("generator")
+    .consumes(ProductBrief)
+    .publishes(ProductIdea, fan_out=10)  # Produces 10 ideas per brief!
+)
+
+# With WHERE filtering - only publish high-quality ideas
+idea_generator = (
+    flock.agent("generator")
+    .consumes(ProductBrief)
+    .publishes(
+        ProductIdea,
+        fan_out=20,  # Generate 20 candidates
+        where=lambda idea: idea.score >= 8.0  # Only publish score >= 8
+    )
+)
+
+# With VALIDATE - enforce quality standards
+code_reviewer = (
+    flock.agent("reviewer")
+    .consumes(CodeSubmission)
+    .publishes(
+        BugReport,
+        fan_out=5,
+        validate=lambda bug: bug.severity in ["Critical", "High", "Medium", "Low"]
+    )
+)
+
+# With Dynamic Visibility - control access per artifact
+notification_agent = (
+    flock.agent("notifier")
+    .consumes(Alert)
+    .publishes(
+        Notification,
+        fan_out=3,
+        visibility=lambda n: PrivateVisibility(agents=[n.recipient])  # Dynamic!
+    )
+)
+```
+
+**What just happened:**
+- ✅ **fan_out=N** - Agent produces N artifacts per execution (not just 1!)
+- ✅ **where** - Filter outputs before publishing (reduce noise, save costs)
+- ✅ **validate** - Enforce quality standards (fail-fast on bad outputs)
+- ✅ **Dynamic visibility** - Control access per artifact based on content
+
+**Real-world impact:**
+- 🎯 **Content Generation** - Generate 10 blog post ideas, filter to top 3 by score
+- 🐛 **Code Review** - Produce 5 potential bugs, validate severity levels
+- 📧 **Notifications** - Create 3 notification variants, target specific agents
+- 🧪 **A/B Testing** - Generate N variations, filter by quality metrics
+
+**🤯 Multi-Output Fan-Out (New in 0.5)**
+
+**The truly mind-blowing part:** Fan-out works across **multiple output types**:
+
+```python
+# Generate 3 of EACH type = 9 total artifacts in ONE LLM call!
+multi_master = (
+    flock.agent("multi_master")
+    .consumes(Idea)
+    .publishes(Movie, MovieScript, MovieCampaign, fan_out=3)
+)
+
+# Single execution produces:
+# - 3 complete Movie artifacts (with title, genre, cast, plot)
+# - 3 complete MovieScript artifacts (with characters, scenes, pages)
+# - 3 complete MovieCampaign artifacts (with taglines, poster descriptions)
+# = 9 complex artifacts, ~100+ fields total, full Pydantic validation, ONE LLM call!
+
+await flock.publish(Idea(story_idea="An action thriller set in space"))
+await flock.run_until_idle()
+
+# Result: 9 artifacts on the blackboard, all validated, all ready
+movies = await flock.store.get_by_type(Movie)  # 3 movies
+scripts = await flock.store.get_by_type(MovieScript)  # 3 scripts
+campaigns = await flock.store.get_by_type(MovieCampaign)  # 3 campaigns
+```
+
+**Why this is revolutionary:**
+- ⚡ **Massive efficiency** - 1 LLM call generates 9 production-ready artifacts
+- ✅ **Full validation** - All 100+ fields validated with Pydantic constraints
+- 🎯 **Coherent generation** - Movie/Script/Campaign are thematically aligned (same LLM context)
+- 💰 **Cost optimized** - 9 artifacts for the price of 1 API call
+
+**Can any other agent framework do this?** We haven't found one. 🚀
+
+**📖 [Full Fan-Out Guide →](https://whiteducksoftware.github.io/flock/guides/fan-out/)**
+
 ### Visibility Controls (The Security)
 
 **Unlike other frameworks, Flock has zero-trust security built-in:**