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

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

@@ -40,7 +40,10 @@ 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)
-- **Components:** Pluggable utilities (metrics, budgets, guards) + engines (DSPy, custom)
+- **Components:** Three levels of extensibility:
+  - **Orchestrator Components:** Global lifecycle hooks (monitoring, metrics, coordination)
+  - **Agent Components:** Per-agent behavior (quality gates, retry logic, validation)
+  - **Engines:** Custom processing logic (DSPy, regex, deterministic rules)
 - **Real-time Dashboard:** React/TypeScript interface for live monitoring
 
 ---
@@ -90,6 +93,8 @@ uv run python examples/05-engines/emoji_mood_engine.py
 uv run python examples/05-engines/potion_batch_engine.py
 uv run python examples/06-agent-components/plot_twist_component.py
 uv run python examples/06-agent-components/cheer_meter_component.py
+uv run python examples/07-orchestrator-components/quest_tracker_component.py
+uv run python examples/07-orchestrator-components/kitchen_monitor_component.py
 ```
 
 ---
@@ -102,12 +107,20 @@ For deep dives into specific topics, see:
 - **[Architecture & Blackboard](docs/guides/blackboard.md)** - Core pattern, structure, and behavior
 - **[Agent Guide](docs/guides/agents.md)** - Complete agent development reference
 
+**Components & Extensibility:**
+- **[Agent Components](docs/guides/components.md)** - Extend agent behavior with lifecycle hooks
+- **[Orchestrator Components](docs/guides/orchestrator-components.md)** - Extend orchestrator behavior with lifecycle hooks (NEW!)
+
 **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/guides/testing.md)** - Testing, quality, versioning, pre-commit
+- **[Frontend/Dashboard](docs/guides/dashboard.md)** - Dashboard usage and development
+- **[Configuration & Dependencies](CONTRIBUTING.md)** - Environment and setup
+- **[Patterns & Common Tasks](docs/guides/patterns.md)** - Recipes, performance, security
 - **[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
@@ -404,28 +417,28 @@ Before creating a PR, verify:
 - [ ] Frontend version bumped in `package.json` (if any UI changes)
 - [ ] Version bump committed (separate commit is fine)
 - [ ] Pre-commit hooks pass
-- [ ] **PR targets `0.5.0b` branch (NOT `main`!)** ⚠️
+- [ ] **PR targets `main` branch** ✅
 
 #### ⚠️ CRITICAL: PR Base Branch
 
-**ALL pull requests MUST target the `0.5.0b` branch, NOT `main`!**
+**ALL pull requests MUST target the `main` branch!**
 
 ```bash
-# ✅ CORRECT: PR into 0.5.0b branch
-gh pr create --base 0.5.0b --title "..." --body "..."
-
-# ❌ WRONG: PR into main branch
+# ✅ CORRECT: PR into main branch
 gh pr create --base main --title "..." --body "..."
+
+# ❌ WRONG: PR into other branches without discussion
+gh pr create --base some-other-branch --title "..." --body "..."
 ```
 
 **Why this matters:**
-- The `0.5.0b` branch is the active development branch for the 0.5.0 beta release
-- PRs into `main` bypass the beta testing process
-- Features need to be validated in beta before reaching `main`
+- The `main` branch is the active development branch
+- All features should be validated through PR review before merging
+- Keeps the project history clean and linear
 
-**If you accidentally create a PR against `main`:**
+**If you accidentally create a PR against the wrong branch:**
 1. Close the incorrect PR: `gh pr close <number>`
-2. Recreate against `0.5.0b`: `gh pr create --base 0.5.0b ...`
+2. Recreate against `main`: `gh pr create --base main ...`
 
 **Remember: It's better to increment versions too often than too rarely. Each meaningful change should get a version bump!**
 

{flock_core-0.5.5 → flock_core-0.5.7}/CONTRIBUTING.md

@@ -123,7 +123,7 @@ poe version-check  # See what would be bumped
 poe version-minor  # Bump version
 
 # 7. Commit version bump
-git add pyproject.toml frontend/package.json
+git add pyproject.toml src/flock/frontend/package.json
 git commit -m "chore: bump version to 0.2.0"
 
 # 8. Push (build checks run)

flock_core-0.5.5/README.md → flock_core-0.5.7/PKG-INFO

@@ -1,3 +1,36 @@
+Metadata-Version: 2.4
+Name: flock-core
+Version: 0.5.7
+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
+Requires-Dist: devtools>=0.12.2
+Requires-Dist: dspy==3.0.3
+Requires-Dist: duckdb>=1.1.0
+Requires-Dist: fastapi>=0.117.1
+Requires-Dist: hanging-threads>=2.0.7
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: litellm==1.78.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mcp>=1.7.1
+Requires-Dist: opentelemetry-api>=1.30.0
+Requires-Dist: opentelemetry-exporter-jaeger-proto-grpc>=1.21.0
+Requires-Dist: opentelemetry-exporter-jaeger>=1.21.0
+Requires-Dist: opentelemetry-exporter-otlp>=1.30.0
+Requires-Dist: opentelemetry-instrumentation-logging>=0.51b0
+Requires-Dist: opentelemetry-sdk>=1.30.0
+Requires-Dist: poethepoet>=0.30.0
+Requires-Dist: pydantic[email]>=2.11.9
+Requires-Dist: rich>=14.1.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: typer>=0.19.2
+Requires-Dist: uvicorn>=0.37.0
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
 <p align="center">
   <img alt="Flock Banner" src="docs/assets/images/flock.png" width="800">
 </p>
@@ -451,13 +484,77 @@ await flock.run_until_idle()
 # Total time: ~1x single execution (parallel)
 ```
 
+### Agent Components (Agent Lifecycle Hooks)
+
+**Extend agent behavior through composable lifecycle hooks:**
+
+Agent components let you inject custom logic at specific points in an agent's execution without modifying core agent code:
+
+```python
+from flock.components import AgentComponent
+
+# Custom component: Log inputs/outputs
+class LoggingComponent(AgentComponent):
+    async def on_pre_evaluate(self, agent, ctx, inputs):
+        logger.info(f"Agent {agent.name} evaluating: {inputs}")
+        return inputs  # Pass through unchanged
+    
+    async def on_post_evaluate(self, agent, ctx, inputs, result):
+        logger.info(f"Agent {agent.name} produced: {result}")
+        return result
+
+# Attach to any agent
+analyzer = (
+    flock.agent("analyzer")
+    .consumes(Data)
+    .publishes(Report)
+    .with_utilities(LoggingComponent())
+)
+```
+
+**Built-in components**: Rate limiting, caching, metrics collection, budget tracking, guardrails
+
+**📖 [Learn more: Agent Components Guide](https://whiteducksoftware.github.io/flock/guides/components/)**
+
+---
+
+### Orchestrator Components (Orchestrator Lifecycle Hooks)
+
+**Extend orchestrator behavior through composable lifecycle hooks:**
+
+Orchestrator components let you inject custom logic into the orchestrator's scheduling pipeline:
+
+```python
+from flock.orchestrator_component import OrchestratorComponent, ScheduleDecision
+
+# Custom component: Skip scheduling during maintenance window
+class MaintenanceWindowComponent(OrchestratorComponent):
+    async def on_before_schedule(self, orch, artifact, agent, subscription):
+        if self.is_maintenance_window():
+            logger.info(f"Deferring {agent.name} during maintenance")
+            return ScheduleDecision.DEFER
+        return ScheduleDecision.CONTINUE
+
+# Add to orchestrator
+flock = Flock("openai/gpt-4.1")
+flock.add_component(MaintenanceWindowComponent())
+```
+
+**Built-in components**: 
+- `CircuitBreakerComponent` - Prevent runaway agent execution
+- `DeduplicationComponent` - Skip duplicate artifact/agent processing
+
+**8 Lifecycle Hooks**: Artifact publication, scheduling decisions, artifact collection, agent scheduling, idle/shutdown
+
+---
+
 ### Production Safety Features
 
 **Built-in safeguards prevent common production failures:**
 
 ```python
-# Circuit breakers prevent runaway costs
-flock = Flock("openai/gpt-4.1", max_agent_iterations=1000)
+# Circuit breakers prevent runaway costs (via OrchestratorComponent)
+flock = Flock("openai/gpt-4.1")  # Auto-adds CircuitBreakerComponent(max_iterations=1000)
 
 # Feedback loop protection
 critic = (

flock_core-0.5.5/PKG-INFO → flock_core-0.5.7/README.md

@@ -1,36 +1,3 @@
-Metadata-Version: 2.4
-Name: flock-core
-Version: 0.5.5
-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
-Requires-Dist: devtools>=0.12.2
-Requires-Dist: dspy==3.0.4b1
-Requires-Dist: duckdb>=1.1.0
-Requires-Dist: fastapi>=0.117.1
-Requires-Dist: hanging-threads>=2.0.7
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: litellm==1.75.3
-Requires-Dist: loguru>=0.7.3
-Requires-Dist: mcp>=1.7.1
-Requires-Dist: opentelemetry-api>=1.30.0
-Requires-Dist: opentelemetry-exporter-jaeger-proto-grpc>=1.21.0
-Requires-Dist: opentelemetry-exporter-jaeger>=1.21.0
-Requires-Dist: opentelemetry-exporter-otlp>=1.30.0
-Requires-Dist: opentelemetry-instrumentation-logging>=0.51b0
-Requires-Dist: opentelemetry-sdk>=1.30.0
-Requires-Dist: poethepoet>=0.30.0
-Requires-Dist: pydantic[email]>=2.11.9
-Requires-Dist: rich>=14.1.0
-Requires-Dist: toml>=0.10.2
-Requires-Dist: typer>=0.19.2
-Requires-Dist: uvicorn>=0.37.0
-Requires-Dist: websockets>=15.0.1
-Description-Content-Type: text/markdown
-
 <p align="center">
   <img alt="Flock Banner" src="docs/assets/images/flock.png" width="800">
 </p>
@@ -484,13 +451,77 @@ await flock.run_until_idle()
 # Total time: ~1x single execution (parallel)
 ```
 
+### Agent Components (Agent Lifecycle Hooks)
+
+**Extend agent behavior through composable lifecycle hooks:**
+
+Agent components let you inject custom logic at specific points in an agent's execution without modifying core agent code:
+
+```python
+from flock.components import AgentComponent
+
+# Custom component: Log inputs/outputs
+class LoggingComponent(AgentComponent):
+    async def on_pre_evaluate(self, agent, ctx, inputs):
+        logger.info(f"Agent {agent.name} evaluating: {inputs}")
+        return inputs  # Pass through unchanged
+    
+    async def on_post_evaluate(self, agent, ctx, inputs, result):
+        logger.info(f"Agent {agent.name} produced: {result}")
+        return result
+
+# Attach to any agent
+analyzer = (
+    flock.agent("analyzer")
+    .consumes(Data)
+    .publishes(Report)
+    .with_utilities(LoggingComponent())
+)
+```
+
+**Built-in components**: Rate limiting, caching, metrics collection, budget tracking, guardrails
+
+**📖 [Learn more: Agent Components Guide](https://whiteducksoftware.github.io/flock/guides/components/)**
+
+---
+
+### Orchestrator Components (Orchestrator Lifecycle Hooks)
+
+**Extend orchestrator behavior through composable lifecycle hooks:**
+
+Orchestrator components let you inject custom logic into the orchestrator's scheduling pipeline:
+
+```python
+from flock.orchestrator_component import OrchestratorComponent, ScheduleDecision
+
+# Custom component: Skip scheduling during maintenance window
+class MaintenanceWindowComponent(OrchestratorComponent):
+    async def on_before_schedule(self, orch, artifact, agent, subscription):
+        if self.is_maintenance_window():
+            logger.info(f"Deferring {agent.name} during maintenance")
+            return ScheduleDecision.DEFER
+        return ScheduleDecision.CONTINUE
+
+# Add to orchestrator
+flock = Flock("openai/gpt-4.1")
+flock.add_component(MaintenanceWindowComponent())
+```
+
+**Built-in components**: 
+- `CircuitBreakerComponent` - Prevent runaway agent execution
+- `DeduplicationComponent` - Skip duplicate artifact/agent processing
+
+**8 Lifecycle Hooks**: Artifact publication, scheduling decisions, artifact collection, agent scheduling, idle/shutdown
+
+---
+
 ### Production Safety Features
 
 **Built-in safeguards prevent common production failures:**
 
 ```python
-# Circuit breakers prevent runaway costs
-flock = Flock("openai/gpt-4.1", max_agent_iterations=1000)
+# Circuit breakers prevent runaway costs (via OrchestratorComponent)
+flock = Flock("openai/gpt-4.1")  # Auto-adds CircuitBreakerComponent(max_iterations=1000)
 
 # Feedback loop protection
 critic = (

{flock_core-0.5.5 → flock_core-0.5.7}/docs/examples/index.md

@@ -15,6 +15,27 @@ Explore the numbered example folders in this repository:
 - **02 — The Blackboard** (`examples/02-the-blackboard`) — architecture overview
 - **03 — The Dashboard** (`examples/03-the-dashboard`) — real-time monitoring
 
+### Component Examples
+**Learn to build custom components and engines**
+
+- **05 — Custom Engines** (`examples/05-engines`) — deterministic logic engines
+- **06 — Agent Components** (`examples/06-agent-components`) — per-agent behavior patterns
+- **07 — Orchestrator Components** (`examples/07-orchestrator-components`) — global coordination patterns
+
+These examples show how to extend Flock with custom logic:
+
+**Custom Engines** - Replace LLM calls with deterministic logic:
+- `emoji_mood_engine.py` - Pattern-based mood detection
+- `potion_batch_engine.py` - Batch processing rules
+
+**Agent Components** - Add per-agent behavior:
+- `cheer_meter_component.py` - Track agent-specific metrics
+- `plot_twist_component.py` - Dynamic agent state
+
+**Orchestrator Components** - Global coordination:
+- `quest_tracker_component.py` - Real-time quest scoring system
+- `kitchen_monitor_component.py` - Restaurant performance monitoring
+
 ### Feature Examples
 **Focused examples for specific capabilities**
 
@@ -29,6 +50,36 @@ Check out `examples/03-the-dashboard` to explore:
 - **Edge Cases** - Multi-agent cascades and filtering
 - **Real-time Updates** - WebSocket streaming
 
+### Claude's Workshop
+**🎓 Interactive learning course from beginner to expert**
+
+Complete hands-on workshop: `examples/03-claudes-workshop`
+
+**Beginner Track:**
+- Lesson 01: Code Detective - Your first agent
+- Lesson 02: Band Formation - Multi-agent chaining
+
+**Intermediate Track:**
+- Lesson 03: Quality Gates - Conditional consumption
+- Lesson 04: Debate Club - Feedback loops
+- Lesson 05: Debugging Detective - Unified tracing
+
+**Advanced Track:**
+- Lesson 06: Secret Agent Network - Visibility controls
+- Lesson 07: News Agency - Parallel execution
+
+**Expert Track:**
+- Lesson 08: The Matchmaker - JoinSpec correlation
+- Lesson 09: Batch Optimizer - BatchSpec patterns
+- Lesson 10: Smart Factory - Combined features
+
+**Architecture Track:**
+- Lesson 11: Performance Monitor - Orchestrator components
+- Lesson 12: Confidence Booster - Agent components
+- Lesson 13: Regex Matcher - Custom engines
+
+Each lesson is self-contained with detailed comments and runnable code!
+
 ---
 
 ## 🚀 Running Examples

{flock_core-0.5.5 → flock_core-0.5.7}/docs/guides/components.md

@@ -111,6 +111,7 @@ class RateLimiter(AgentComponent):
 
     max_calls: int = 10
     window_seconds: int = 60
+    priority: int = 0  # Lower = earlier execution (defaults to registration order)
 
     def __init__(self, max_calls: int = 10, window: int = 60):
         super().__init__(name="rate_limiter")
@@ -136,6 +137,14 @@ class RateLimiter(AgentComponent):
         return inputs
 ```
 
+**Execution order & logging.** Agent utilities now support a `priority` field that mirrors
+the orchestrator component system. Components run in ascending priority order
+(default `0` preserves registration order thanks to stable sorting), and every
+hook invocation is logged with component name, priority, and agent context. This
+makes it easy to slot in cross-cutting utilities (e.g., telemetry collectors with
+`priority=-100`) without rewriting existing agents, while still getting detailed
+traceable logs for each lifecycle stage.
+
 ### EngineComponent (Replacing the Execution Engine)
 
 **EngineComponents are special**: They replace the agent's evaluation logic entirely. By default, agents use `DSPyEngine` for LLM-based processing, but you can swap it out for: