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

{flock_core-0.5.8 → flock_core-0.5.9}/.github/workflows/quality.yml

@@ -51,12 +51,29 @@ jobs:
           export PATH="$HOME/.cargo/bin:$PATH"
           uv run pytest --cov=src/flock --cov-branch --cov-report=xml --cov-report=term --cov-fail-under=75
 
+      - name: Extract test metrics
+        id: test-metrics
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+
+          # Count total tests
+          TEST_COUNT=$(uv run pytest --collect-only -q | tail -n 1 | awk '{print $1}')
+          echo "test_count=$TEST_COUNT" >> $GITHUB_OUTPUT
+          echo "📊 Total tests: $TEST_COUNT"
+
+          # Extract coverage percentage from XML
+          COVERAGE=$(python -c "import xml.etree.ElementTree as ET; tree = ET.parse('coverage.xml'); root = tree.getroot(); print(f\"{float(root.attrib['line-rate']) * 100:.0f}\")")
+          echo "coverage=$COVERAGE" >> $GITHUB_OUTPUT
+          echo "📈 Coverage: $COVERAGE%"
+
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4
         with:
+          token: ${{ secrets.CODECOV_TOKEN }}
           file: ./coverage.xml
           flags: backend
           name: backend-coverage
+          fail_ci_if_error: true
 
       - name: Backend build check
         run: |

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.5.8
+Version: 0.5.9
 Summary: Flock: A declrative framework for building and orchestrating AI agents.
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License: MIT
@@ -40,8 +40,8 @@ Description-Content-Type: text/markdown
   <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/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">
+  <a href="https://codecov.io/gh/whiteducksoftware/flock" target="_blank"><img alt="Test Coverage" src="https://codecov.io/gh/whiteducksoftware/flock/branch/main/graph/badge.svg?token=YOUR_TOKEN_HERE&style=for-the-badge"></a>
+  <img alt="Tests" src="https://img.shields.io/badge/tests-1300+-brightgreen?style=for-the-badge">
 </p>
 
 ---

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

@@ -7,8 +7,8 @@
   <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/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">
+  <a href="https://codecov.io/gh/whiteducksoftware/flock" target="_blank"><img alt="Test Coverage" src="https://codecov.io/gh/whiteducksoftware/flock/branch/main/graph/badge.svg?token=YOUR_TOKEN_HERE&style=for-the-badge"></a>
+  <img alt="Tests" src="https://img.shields.io/badge/tests-1300+-brightgreen?style=for-the-badge">
 </p>
 
 ---

{flock_core-0.5.8/examples/09-patterms → flock_core-0.5.9/examples/00-patterns}/02-multi_publish.py

@@ -11,12 +11,18 @@ class Idea(BaseModel):
     story_idea: str
 
 
+@flock_type
+class Character(BaseModel):
+    name: str
+    potential_actors: dict[str, str] = Field(..., description="Potential actors and reasons why they are a good fit")
+    backstory: str
+
 @flock_type
 class Movie(BaseModel):
     title: str
     genre: str
     director: str
-    cast: list[str]
+    characters: list[Character]
     plot_summary: str
 
 

{flock_core-0.5.8/examples/09-patterms → flock_core-0.5.9/examples/00-patterns}/03-multi-artifact-multi-publish.py

@@ -11,12 +11,18 @@ class Idea(BaseModel):
     story_idea: str
 
 
+@flock_type
+class Character(BaseModel):
+    name: str
+    potential_actors: dict[str, str] = Field(..., description="Potential actors and reasons why they are a good fit")
+    backstory: str
+
 @flock_type
 class Movie(BaseModel):
     title: str
     genre: str
     director: str
-    cast: list[str]
+    characters: list[Character]
     plot_summary: str
 
 

{flock_core-0.5.8/examples/09-patterms → flock_core-0.5.9/examples/00-patterns}/05-multi-fan-out.py

@@ -11,12 +11,18 @@ class Idea(BaseModel):
     story_idea: str
 
 
+@flock_type
+class Character(BaseModel):
+    name: str
+    potential_actors: dict[str, str] = Field(..., description="Potential actors and reasons why they are a good fit")
+    backstory: str
+
 @flock_type
 class Movie(BaseModel):
     title: str
     genre: str
     director: str
-    cast: list[str]
+    characters: list[Character]
     plot_summary: str
 
 
@@ -48,7 +54,6 @@ multi_master = (
 
 
 async def main():
-    await flock.serve(dashboard=True)
     idea = Idea(story_idea="An action thriller set in space")
     await flock.publish(idea)
     await flock.run_until_idle()

flock_core-0.5.9/examples/00-patterns/README.md

@@ -0,0 +1,162 @@
+# 📐 Publishing Patterns
+
+This folder demonstrates the various ways agents can publish artifacts to the blackboard—one of Flock's most powerful features.
+
+## 🎯 What You'll Learn
+
+These examples show the evolution from simple single-output agents to advanced fan-out patterns that generate multiple artifacts in one execution:
+
+- **Single Publish** - One agent, one artifact type
+- **Multi Publish** - One agent, multiple artifact types
+- **Fan-Out** - One agent, multiple instances of the same type
+- **Multi Fan-Out** - One agent, multiple instances of multiple types
+
+## 📚 Examples
+
+### 01 - Single Publish
+**Pattern:** `consumes(Idea).publishes(Movie)`
+
+The most basic pattern - one input artifact produces one output artifact. Each execution creates exactly one Movie from one Idea.
+
+```bash
+uv run 00-patterns/01-single_publish.py
+```
+
+**Use Case:** Simple 1:1 transformations
+
+---
+
+### 02 - Multi Publish
+**Pattern:** `consumes(Idea).publishes(Movie, MovieScript, MovieCampaign)`
+
+One agent execution produces multiple different artifact types. The agent outputs a Movie, a MovieScript, AND a MovieCampaign all in a single LLM call!
+
+```bash
+uv run 00-patterns/02-multi_publish.py
+```
+
+**Use Case:** When you need multiple perspectives or outputs from the same input
+
+**💡 Key Benefit:** 3 artifacts in 1 LLM call = 67% cost savings vs 3 separate agents!
+
+---
+
+### 03 - Multi-Artifact Multi-Publish
+**Pattern:** Multiple agents, each publishing multiple types
+
+Complex orchestration where different agents produce multiple artifact types, creating rich blackboard interactions.
+
+```bash
+uv run 00-patterns/03-multi-artifact-multi-publish.py
+```
+
+**Use Case:** Complex workflows with multiple agents each producing varied outputs
+
+---
+
+### 04 - Fan-Out
+**Pattern:** `consumes(Idea).publishes(Movie, fan_out=4)`
+
+Generate multiple variations of the same type! One Idea produces 4 different Movie concepts—perfect for creative brainstorming.
+
+```bash
+uv run 00-patterns/04-fan-out.py
+```
+
+**Use Case:**
+- Generate multiple alternatives
+- A/B testing scenarios
+- Creative exploration
+- Portfolio diversification
+
+**⭐ NEW in Flock 0.5**
+
+---
+
+### 05 - Multi Fan-Out
+**Pattern:** `consumes(Idea).publishes(Movie, MovieScript, MovieCampaign, fan_out=3)`
+
+The ultimate publishing pattern! Generate 3 instances of EACH type = 9 total artifacts from one execution:
+- 3 Movies
+- 3 MovieScripts
+- 3 MovieCampaigns
+
+```bash
+uv run 00-patterns/05-multi-fan-out.py
+```
+
+**Use Case:** Maximum creative output with perfect context alignment
+
+**💡 Cost Optimization:** 9 artifacts in 1 LLM call = 89% savings vs 9 separate calls!
+
+**⭐ NEW in Flock 0.5**
+
+---
+
+## 🎓 Learning Path
+
+Work through these examples in order:
+
+1. **Start with 01** - Understand basic publishing
+2. **Try 02** - See how multi-publish works
+3. **Move to 04** - Learn fan-out for same-type generation
+4. **Master 05** - Combine everything for maximum output
+
+## 🔑 Key Concepts
+
+### Why Fan-Out?
+
+Traditional approach (without fan-out):
+```python
+# ❌ OLD WAY: 4 separate LLM calls
+for i in range(4):
+    await flock.invoke(movie_agent, idea)  # 4x the cost!
+```
+
+Fan-out approach:
+```python
+# ✅ NEW WAY: 1 LLM call, 4 outputs
+agent.publishes(Movie, fan_out=4)
+await flock.publish(idea)  # Generates 4 movies at once!
+```
+
+### Advanced Fan-Out Features
+
+You can enhance fan-out with filtering and validation:
+
+```python
+# Filter low-quality outputs
+agent.publishes(Movie, fan_out=10, where=lambda m: m.rating >= 8.0)
+
+# Validate outputs
+agent.publishes(Movie, fan_out=5, validate=lambda m: m.budget > 0)
+
+# Dynamic visibility per artifact
+agent.publishes(
+    Movie,
+    fan_out=3,
+    visibility=lambda m: PrivateVisibility(agents=[m.target_audience])
+)
+```
+
+## 💡 When to Use Each Pattern
+
+| Pattern | Use When | Example |
+|---------|----------|---------|
+| **Single Publish** | Simple 1:1 transformations | Bug report → Diagnosis |
+| **Multi Publish** | Need multiple outputs per input | Order → Invoice + Receipt + Tracking |
+| **Fan-Out** | Want multiple variations | Idea → 5 different movie concepts |
+| **Multi Fan-Out** | Need comprehensive output set | Idea → 3 Movies + 3 Scripts + 3 Campaigns |
+
+## 🚀 Next Steps
+
+After mastering these patterns, explore:
+- **01-cli/** - See these patterns in complete workflows
+- **02-dashboard/** - Visualize publishing patterns
+- **03-claudes-workshop/** - Production patterns and best practices
+
+## 📖 Additional Resources
+
+- [Fan-Out Publishing Guide](https://github.com/whiteducksoftware/flock-flow/blob/main/docs/guides/fan-out.md)
+- [Agent Guide](https://github.com/whiteducksoftware/flock-flow/blob/main/docs/guides/agents.md)
+- AGENTS.md - Section on "Fan-Out Publishing"

flock_core-0.5.9/examples/01-cli/README.md

@@ -0,0 +1,290 @@
+# 💻 CLI Examples
+
+Command-line interface examples for Flock—perfect for learning, debugging, and understanding what's happening under the hood. Each example runs in your terminal with detailed console output.
+
+## 🎯 Why CLI Examples?
+
+- **See detailed logs** - Watch agent execution in real-time
+- **Understand behavior** - Console output shows exactly what's happening
+- **Easy debugging** - Add print statements, inspect data
+- **Fast iteration** - No browser startup time
+- **Perfect for learning** - Follow along with code and output together
+
+## 🎓 Learning Path
+
+The examples are ordered by complexity. Start at 01 and work your way up!
+
+### 🔰 Beginner Track (Examples 01-04)
+
+#### 01 - Declarative Pizza 🍕
+Your first Flock agent! One agent, one task, pure magic.
+
+```bash
+uv run 01-cli/01_declarative_pizza.py
+```
+
+**Concepts:** Agent creation, basic publishing, type-safe contracts
+
+---
+
+#### 02 & 04 - Input and Output 📝
+Learn structured data with Pydantic models.
+
+```bash
+uv run 01-cli/02_input_and_output.py
+uv run 01-cli/04_input_and_output.py  # Advanced version
+```
+
+**Concepts:** Custom message types, validation, structured transformation
+
+---
+
+#### 03 - Code Detective 🔍
+Complex structured outputs with rich nested data.
+
+```bash
+uv run 01-cli/03_code_detective.py
+```
+
+**Concepts:** Complex Pydantic models, real-world structured analysis
+
+---
+
+### 🛠️ Tool Integration (Examples 05-07)
+
+#### 05 - MCP and Tools 🛠️
+Connect agents to external tools via Model Context Protocol.
+
+```bash
+uv run 01-cli/05_mcp_and_tools.py
+```
+
+**Concepts:** MCP integration, tool usage, extending agent capabilities
+
+---
+
+#### 06 - MCP Roots 📂
+Control filesystem access boundaries for security.
+
+```bash
+uv run 01-cli/06_mcp_roots.py
+```
+
+**Concepts:** MCP configuration, security boundaries, custom server options
+
+---
+
+#### 07 - Web Detective 🌐
+Multi-tool research agent combining web search and file operations.
+
+```bash
+uv run 01-cli/07_web_detective.py
+```
+
+**Concepts:** Multiple MCP servers, tool orchestration, research workflows
+
+---
+
+### 🔄 Multi-Agent Workflows (Examples 08-10)
+
+#### 08 - Band Formation 🎸
+Linear pipeline: recruiter → audition → band manager.
+
+```bash
+uv run 01-cli/08_band_formation.py
+```
+
+**Concepts:** Agent chaining, linear workflows, message passing
+
+---
+
+#### 09 - Debate Club 🗣️
+Parallel execution with pro, con, and judge agents.
+
+```bash
+uv run 01-cli/09_debate_club.py
+```
+
+**Concepts:** Parallel agents, consensus building, multiple consumers
+
+---
+
+#### 10 - News Agency 📰
+Complex coordination with reporter, editor, and publisher.
+
+```bash
+uv run 01-cli/10_news_agency.py
+```
+
+**Concepts:** Multi-input agents, complex workflows, real-world modeling
+
+---
+
+### 🔬 Advanced Features (Examples 11-12)
+
+#### 11 - Tracing Detective 🔬
+Observability and debugging with traced runs.
+
+```bash
+uv run 01-cli/11_tracing_detective.py
+```
+
+**Concepts:** `traced_run()`, execution tracing, debugging multi-agent systems
+
+**After running:** Explore `.flock/traces.duckdb` to see captured execution data!
+
+---
+
+#### 12 - Secret Agents 🕵️
+Security controls with visibility boundaries.
+
+```bash
+uv run 01-cli/12_secret_agents.py
+```
+
+**Concepts:** `Visibility.PRIVATE`, `Visibility.PUBLIC`, security boundaries, classified data
+
+---
+
+### 🚀 Expert Track - Logic Operations (Examples 13-15)
+
+#### 13 - Medical Diagnostics (JoinSpec) 🏥
+Correlate related artifacts before processing.
+
+```bash
+uv run 01-cli/13_medical_diagnostics_joinspec.py
+```
+
+**Concepts:**
+- **JoinSpec** - Correlate artifacts by common key
+- Time-windowed matching (`within=timedelta(minutes=5)`)
+- AND-gate pattern (wait for multiple inputs)
+- Order-independent correlation
+
+**Real-world use case:** Hospital system correlating X-rays with lab results by patient ID
+
+---
+
+#### 14 - E-commerce Batch Processing 📦
+Efficient batch operations for performance.
+
+```bash
+uv run 01-cli/14_ecommerce_batch_processing.py
+```
+
+**Concepts:**
+- **BatchSpec** - Collect and process artifacts in batches
+- Size-based triggers (`max_size=10`)
+- Time-based triggers (`max_wait=timedelta(seconds=30)`)
+- Cost optimization through batching
+
+**Real-world use case:** Payment processing system batching transactions for efficiency
+
+---
+
+#### 15 - IoT Sensor Batching 📡
+Combine JoinSpec + BatchSpec for production-grade patterns.
+
+```bash
+uv run 01-cli/15_iot_sensor_batching.py
+```
+
+**Concepts:**
+- **Combined operations** - JoinSpec + BatchSpec together
+- Multi-stage correlation and batching
+- IoT sensor monitoring at scale
+- Production-ready patterns
+
+**Real-world use case:** Smart factory correlating temperature/pressure/vibration sensors, then batching for analysis
+
+---
+
+## 🎯 Quick Reference
+
+### Run All Examples
+```bash
+# Basic examples
+uv run 01-cli/01_declarative_pizza.py
+uv run 01-cli/02_input_and_output.py
+uv run 01-cli/03_code_detective.py
+
+# Tool integration
+uv run 01-cli/05_mcp_and_tools.py
+uv run 01-cli/06_mcp_roots.py
+uv run 01-cli/07_web_detective.py
+
+# Multi-agent
+uv run 01-cli/08_band_formation.py
+uv run 01-cli/09_debate_club.py
+uv run 01-cli/10_news_agency.py
+
+# Advanced
+uv run 01-cli/11_tracing_detective.py
+uv run 01-cli/12_secret_agents.py
+
+# Expert - Logic Operations
+uv run 01-cli/13_medical_diagnostics_joinspec.py
+uv run 01-cli/14_ecommerce_batch_processing.py
+uv run 01-cli/15_iot_sensor_batching.py
+```
+
+## 💡 Tips
+
+1. **Read the source code** - Each example is intentionally minimal and well-commented
+2. **Run in order** - Each builds on concepts from previous examples
+3. **Experiment** - Modify examples to understand behavior
+4. **Enable tracing** - Set `FLOCK_AUTO_TRACE=true` to see execution details
+5. **Check output** - Pay attention to console logs showing agent execution
+
+## 🔍 Debugging Tips
+
+### Enable Detailed Tracing
+```bash
+# Before running examples
+export FLOCK_AUTO_TRACE=true
+export FLOCK_TRACE_FILE=true
+
+# Run example
+uv run 01-cli/11_tracing_detective.py
+
+# Query traces
+python -c "
+import duckdb
+conn = duckdb.connect('.flock/traces.duckdb', read_only=True)
+traces = conn.execute('''
+    SELECT name, duration_ms, status_code
+    FROM spans ORDER BY start_time DESC LIMIT 10
+''').fetchall()
+for t in traces:
+    print(f'{t[0]}: {t[1]:.0f}ms - {t[2]}')
+"
+```
+
+## 📊 Complexity Progression
+
+```
+Simple → Complex
+Single Agent → Multi-Agent
+Synchronous → Parallel
+Basic → Tool Integration
+Local → Secured
+Sequential → Correlated → Batched
+```
+
+## 🎓 Next Steps
+
+After completing CLI examples:
+1. **Try Dashboard versions** in `02-dashboard/` - Visualize the same workflows
+2. **Take the Workshop** in `03-claudes-workshop/` - Structured learning path
+3. **Explore Advanced** - Check `05-engines/`, `06-agent-components/`, `07-orchestrator-components/`
+
+## 📚 Related Resources
+
+- **02-dashboard/** - Same examples with visual interface
+- **03-claudes-workshop/** - Structured course with detailed lessons
+- **00-patterns/** - Publishing pattern reference
+- **AGENTS.md** - Complete development guide
+
+---
+
+**Happy learning! 🦆**