flock-core 0.4.0b27__tar.gz → 0.4.0b28__tar.gz

flock_core-0.4.0b28/.gitmodules

@@ -0,0 +1,4 @@
+[submodule "examples"]
+	path = examples
+	url = https://github.com/whiteducksoftware/flock-showcase.git
+	branch = master

{flock_core-0.4.0b27 → flock_core-0.4.0b28}/.vscode/settings.json

@@ -15,10 +15,10 @@
     "editor.smoothScrolling": true,
     "terminal.integrated.fontFamily": "'Jetbrains Mono', 'FiraCode Nerd Font', 'Hack Nerd Font', 'monospace'",
     "editor.renderWhitespace": "none",
-    //"terminal.integrated.lineHeight": 1.5,
+    "terminal.integrated.lineHeight": 1.5,
     "editor.fontSize": 15.5,
     "editor.fontLigatures": true,
-    //"editor.lineHeight": 1.5,
+    "editor.lineHeight": 1.5,
     "editor.minimap.enabled": true,
     "editor.tabSize": 2,
     "editor.semanticTokenColorCustomizations": {
@@ -29,15 +29,53 @@
     // prevent VSCode from modifying the terminal colors
     "terminal.integrated.minimumContrastRatio": 1,
     "cSpell.words": [
+        "asyncio",
+        "chromadb",
+        "cloudpickle",
         "deptry",
+        "docling",
+        "dotenv",
+        "dspy",
+        "duckduckgo",
+        "fastapi",
+        "fasthtml",
         "gradio",
+        "htmlcov",
+        "httpx",
+        "ipywidgets",
+        "isort",
+        "litellm",
+        "loguru",
+        "markdownify",
+        "matplotlib",
+        "minversion",
         "mkdocs",
+        "mkdocstrings",
+        "msgpack",
         "msgspec",
         "mypy",
+        "nltk",
         "packb",
+        "poethepoet",
+        "psutil",
+        "pycache",
+        "pycodestyle",
+        "pydantic",
+        "pydocstyle",
+        "pyflakes",
         "pyinstrument",
         "pytest",
-        "unpackb"
+        "pyupgrade",
+        "pyyaml",
+        "Ratzenberger",
+        "respx",
+        "tavily",
+        "temporalio",
+        "testpaths",
+        "tiktoken",
+        "tqdm",
+        "unpackb",
+        "uvicorn"
     ],
     "yaml.schemas": {
         "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"

{flock_core-0.4.0b27 → flock_core-0.4.0b28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.4.0b27
+Version: 0.4.0b28
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -126,7 +126,7 @@ Flock's power comes from a few key ideas (Learn more in the [Full Documentation]
 6. **Tool Integration:** Equip agents with standard or custom Python functions (`@flock_tool`) registered via the `FlockRegistry`.
 7. **Registry:** A central place (`@flock_component`, `@flock_type`, `@flock_tool`) to register your custom classes, types, and functions, enabling robust serialization and dynamic loading.
 
-## 💾 Installation
+## 💾 Installation - Use Flock in your project
 
 Get started with the core Flock library:
 
@@ -148,7 +148,27 @@ uv pip install flock-core[tools]
 uv pip install flock-core[all]
 ```
 
-Environment Setup:
+## 🔑 Installation - Develop Flock
+
+```bash
+git clone https://github.com/whiteducksoftware/flock.git
+cd flock
+
+# One-liner dev setup after cloning
+pip install poethepoet && poe install
+```
+
+Additional provided `poe` tasks and commands:
+
+```bash
+poe install # Install the project
+poe build # Build the project
+poe docs # Serve the docs
+poe format # Format the code
+poe lint # Lint the code
+```
+
+## 🔑 Environment Setup
 
 Flock uses environment variables (typically in a .env file) for configuration, especially API keys. Create a .env file in your project root:
 
@@ -173,7 +193,7 @@ DEFAULT_MODEL="openai/gpt-4o" # Default LLM if agent doesn't specify
 # VARS_PER_PAGE="20"
 ```
 
-Remember to add .env to your .gitignore!
+Be sure that the .env file is added to your .gitignore!
 
 ## ⚡ Quick Start Syntax
 
@@ -223,18 +243,32 @@ Version 0.4.0 brings significant enhancements focused on usability, deployment,
 
 Easily deploy your Flock agents as scalable REST API endpoints. Interact with your agent workflows via standard HTTP requests.
 
+--------------------------------
+
 ### 🖥️ Web UI - Test Flock Agents in the Browser
 
 Test and interact with your Flock agents directly in your browser through an integrated web interface.
 
+--------------------------------
+
 ### ⌨️ CLI Tool - Manage Flock Agents via the Command Line
 
 Manage Flock configurations, run agents, and inspect results directly from your command line.
 
+--------------------------------
+
 ### 💾 Enhanced Serialization - Share, Deploy, and Run Flock Agents by human readable yaml files
 
 Define and share entire Flock configurations, including agents and components, using human-readable YAML files. Load flocks directly from these files for easy deployment and versioning.
 
+--------------------------------
+
+### 💾 New execution flows
+
+Run Flock in batch mode to process multiple inputs at once or in evaluation mode to test agents with different inputs.
+
+--------------------------------
+
 ### ⏱️ Robust Temporal Integration
 
 Flock 0.4.0 introduces first-class support for Temporal.io, enabling you to build truly production-grade, reliable, and scalable agent workflows. Move beyond simple local execution and leverage Temporal's power for:
@@ -249,6 +283,51 @@ Flock makes this easy with:
 *   **Declarative Configuration:** Define Temporal timeouts, retry policies, and task queues directly within your `Flock` and `FlockAgent` configurations (YAML or Python).
 *   **Correct Patterns:** Uses Temporal's recommended granular activity execution for better control and visibility.
 *   **Clear Worker Separation:** Provides guidance and flags for running dedicated Temporal workers, separating development convenience from production best practices.
+  
+Visit the [Temporal Documentation](https://learn.temporal.io/python/workflows/) for more information on how to use Temporal.
+
+Or check out the [Flock Showcase](https://github.com/whiteducksoftware/flock-showcase) for a complete example of a Flock that uses Temporal or our [docs](https://whiteducksoftware.github.io/flock/guides/temporal-configuration/) for more information.
+
+Here's an example of how to configure a Flock to use Temporal:
+
+```python
+from flock.core import Flock, FlockFactory
+
+from flock.workflow.temporal_config import (
+    TemporalActivityConfig,
+    TemporalRetryPolicyConfig,
+    TemporalWorkflowConfig,
+)
+
+# Flock-scoped temporal config
+flock = Flock(
+    enable_temporal=True,
+    temporal_config=TemporalWorkflowConfig(
+        task_queue="flock-test-queue",
+        workflow_execution_timeout=timedelta(minutes=10),
+        default_activity_retry_policy=TemporalRetryPolicyConfig(
+            maximum_attempts=2
+        ),
+    ),
+)
+
+# Agent-scoped temporal config
+content_agent = FlockFactory.create_default_agent(
+    name="content_agent",
+    input="funny_title, funny_slide_headers",
+    output="funny_slide_content",
+    temporal_activity_config=TemporalActivityConfig(
+        start_to_close_timeout=timedelta(minutes=1),
+        retry_policy=TemporalRetryPolicyConfig(
+            maximum_attempts=4,
+            initial_interval=timedelta(seconds=2),
+            non_retryable_error_types=["ValueError"],
+        ),
+    ),
+)
+```
+
+--------------------------------
 
 ### ✨ Utility: @flockclass Hydrator
 
@@ -281,6 +360,8 @@ async def create_character():
 # asyncio.run(create_character())
 ```
 
+--------------------------------
+
 ## 📚 Examples & Tutorials
 
 For a comprehensive set of examples, ranging from basic usage to complex projects and advanced features, please visit our dedicated showcase repository:

{flock_core-0.4.0b27 → flock_core-0.4.0b28}/README.md

@@ -65,7 +65,7 @@ Flock's power comes from a few key ideas (Learn more in the [Full Documentation]
 6. **Tool Integration:** Equip agents with standard or custom Python functions (`@flock_tool`) registered via the `FlockRegistry`.
 7. **Registry:** A central place (`@flock_component`, `@flock_type`, `@flock_tool`) to register your custom classes, types, and functions, enabling robust serialization and dynamic loading.
 
-## 💾 Installation
+## 💾 Installation - Use Flock in your project
 
 Get started with the core Flock library:
 
@@ -87,7 +87,27 @@ uv pip install flock-core[tools]
 uv pip install flock-core[all]
 ```
 
-Environment Setup:
+## 🔑 Installation - Develop Flock
+
+```bash
+git clone https://github.com/whiteducksoftware/flock.git
+cd flock
+
+# One-liner dev setup after cloning
+pip install poethepoet && poe install
+```
+
+Additional provided `poe` tasks and commands:
+
+```bash
+poe install # Install the project
+poe build # Build the project
+poe docs # Serve the docs
+poe format # Format the code
+poe lint # Lint the code
+```
+
+## 🔑 Environment Setup
 
 Flock uses environment variables (typically in a .env file) for configuration, especially API keys. Create a .env file in your project root:
 
@@ -112,7 +132,7 @@ DEFAULT_MODEL="openai/gpt-4o" # Default LLM if agent doesn't specify
 # VARS_PER_PAGE="20"
 ```
 
-Remember to add .env to your .gitignore!
+Be sure that the .env file is added to your .gitignore!
 
 ## ⚡ Quick Start Syntax
 
@@ -162,18 +182,32 @@ Version 0.4.0 brings significant enhancements focused on usability, deployment,
 
 Easily deploy your Flock agents as scalable REST API endpoints. Interact with your agent workflows via standard HTTP requests.
 
+--------------------------------
+
 ### 🖥️ Web UI - Test Flock Agents in the Browser
 
 Test and interact with your Flock agents directly in your browser through an integrated web interface.
 
+--------------------------------
+
 ### ⌨️ CLI Tool - Manage Flock Agents via the Command Line
 
 Manage Flock configurations, run agents, and inspect results directly from your command line.
 
+--------------------------------
+
 ### 💾 Enhanced Serialization - Share, Deploy, and Run Flock Agents by human readable yaml files
 
 Define and share entire Flock configurations, including agents and components, using human-readable YAML files. Load flocks directly from these files for easy deployment and versioning.
 
+--------------------------------
+
+### 💾 New execution flows
+
+Run Flock in batch mode to process multiple inputs at once or in evaluation mode to test agents with different inputs.
+
+--------------------------------
+
 ### ⏱️ Robust Temporal Integration
 
 Flock 0.4.0 introduces first-class support for Temporal.io, enabling you to build truly production-grade, reliable, and scalable agent workflows. Move beyond simple local execution and leverage Temporal's power for:
@@ -188,6 +222,51 @@ Flock makes this easy with:
 *   **Declarative Configuration:** Define Temporal timeouts, retry policies, and task queues directly within your `Flock` and `FlockAgent` configurations (YAML or Python).
 *   **Correct Patterns:** Uses Temporal's recommended granular activity execution for better control and visibility.
 *   **Clear Worker Separation:** Provides guidance and flags for running dedicated Temporal workers, separating development convenience from production best practices.
+  
+Visit the [Temporal Documentation](https://learn.temporal.io/python/workflows/) for more information on how to use Temporal.
+
+Or check out the [Flock Showcase](https://github.com/whiteducksoftware/flock-showcase) for a complete example of a Flock that uses Temporal or our [docs](https://whiteducksoftware.github.io/flock/guides/temporal-configuration/) for more information.
+
+Here's an example of how to configure a Flock to use Temporal:
+
+```python
+from flock.core import Flock, FlockFactory
+
+from flock.workflow.temporal_config import (
+    TemporalActivityConfig,
+    TemporalRetryPolicyConfig,
+    TemporalWorkflowConfig,
+)
+
+# Flock-scoped temporal config
+flock = Flock(
+    enable_temporal=True,
+    temporal_config=TemporalWorkflowConfig(
+        task_queue="flock-test-queue",
+        workflow_execution_timeout=timedelta(minutes=10),
+        default_activity_retry_policy=TemporalRetryPolicyConfig(
+            maximum_attempts=2
+        ),
+    ),
+)
+
+# Agent-scoped temporal config
+content_agent = FlockFactory.create_default_agent(
+    name="content_agent",
+    input="funny_title, funny_slide_headers",
+    output="funny_slide_content",
+    temporal_activity_config=TemporalActivityConfig(
+        start_to_close_timeout=timedelta(minutes=1),
+        retry_policy=TemporalRetryPolicyConfig(
+            maximum_attempts=4,
+            initial_interval=timedelta(seconds=2),
+            non_retryable_error_types=["ValueError"],
+        ),
+    ),
+)
+```
+
+--------------------------------
 
 ### ✨ Utility: @flockclass Hydrator
 
@@ -220,6 +299,8 @@ async def create_character():
 # asyncio.run(create_character())
 ```
 
+--------------------------------
+
 ## 📚 Examples & Tutorials
 
 For a comprehensive set of examples, ranging from basic usage to complex projects and advanced features, please visit our dedicated showcase repository:

{flock_core-0.4.0b27 → flock_core-0.4.0b28}/docs/assets/drawio/architecture.drawio

@@ -1,6 +1,6 @@
 <mxfile host="65bd71144e">
     <diagram id="iQ7YuHOuaVDECIdskFDT" name="Page-1">
-        <mxGraphModel dx="88" dy="620" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF, #d8cfb1)" math="0" shadow="1">
+        <mxGraphModel dx="1089" dy="498" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF, #d8cfb1)" math="0" shadow="1">
             <root>
                 <mxCell id="0"/>
                 <mxCell id="1" parent="0"/>
@@ -11,18 +11,18 @@
         </mxGraphModel>
     </diagram>
     <diagram id="mQwFuZfSuTjpqv4SXbYC" name="Page-2">
-        <mxGraphModel dx="354" dy="259" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF, #ffffde)" math="0" shadow="1">
+        <mxGraphModel dx="1089" dy="498" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF, #ffffde)" math="0" shadow="1">
             <root>
                 <mxCell id="0"/>
                 <mxCell id="1" parent="0"/>
-                <mxCell id="gh-ZxXSGDDD0mwRwWCxR-1" value="graph TD&#xa;    subgraph Client Application&#xa;        client[Client Code]&#xa;    end&#xa;&#xa;    subgraph Flock Framework&#xa;        orchestrator[Flock Orchestrator]&#xa;        registry[Agent Registry]&#xa;        context[Context Manager]&#xa;        &#xa;        subgraph Agents&#xa;            base[FlockAgent Base]&#xa;&#xa;        end&#xa;        &#xa;        subgraph Execution&#xa;            local[Local Executor]&#xa;            temporal[Temporal Executor]&#xa;        end&#xa;        &#xa;        subgraph Core Services&#xa;            logging[Logging System]&#xa;            tools[Tool Registry]&#xa;            formatter[Output Formatters]&#xa;        end&#xa;    end&#xa;&#xa;    subgraph External Services&#xa;        llm[Language Models]&#xa;        temporal_server[Temporal Server]&#xa;    end&#xa;&#xa;    %% Client interactions&#xa;    client --&gt; orchestrator&#xa;    &#xa;    %% Orchestrator relations&#xa;    orchestrator --&gt; registry&#xa;    orchestrator --&gt; context&#xa;    orchestrator --&gt; local&#xa;    orchestrator --&gt; temporal&#xa;    &#xa;    %% Agent relations&#xa;    base --&gt; tools&#xa;    base --&gt; logging&#xa;    base --&gt; formatter&#xa;&#xa;    &#xa;    %% Execution relations&#xa;    local --&gt; llm&#xa;    temporal --&gt; temporal_server&#xa;    temporal_server --&gt; llm&#xa;    &#xa;    %% Registry relations&#xa;    registry --&gt; base&#xa;    registry --&gt; tools&#xa;&#xa;    %% Style&#xa;    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px;&#xa;    classDef external fill:#e1f5fe,stroke:#0288d1,stroke-width:2px;&#xa;    classDef core fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;&#xa;    &#xa;    class llm,temporal_server external;&#xa;    class orchestrator,registry,context,base,local,temporal core;" style="shadow=0;dashed=0;align=left;strokeWidth=1;shape=mxgraph.mermaid.abstract.mermaid;labelBackgroundColor=#ffffff;noLabel=1;theme=default;" vertex="1" parent="1">
+                <mxCell id="gh-ZxXSGDDD0mwRwWCxR-1" value="graph TD&#xa;    subgraph Client Application&#xa;        client[Client Code]&#xa;    end&#xa;&#xa;    subgraph Flock Framework&#xa;        orchestrator[Flock Orchestrator]&#xa;        registry[Agent Registry]&#xa;        context[Context Manager]&#xa;        &#xa;        subgraph Agents&#xa;            base[FlockAgent Base]&#xa;&#xa;        end&#xa;        &#xa;        subgraph Execution&#xa;            local[Local Executor]&#xa;            temporal[Temporal Executor]&#xa;        end&#xa;        &#xa;        subgraph Core Services&#xa;            logging[Logging System]&#xa;            tools[Tool Registry]&#xa;            formatter[Output Formatters]&#xa;        end&#xa;    end&#xa;&#xa;    subgraph External Services&#xa;        llm[Language Models]&#xa;        temporal_server[Temporal Server]&#xa;    end&#xa;&#xa;    %% Client interactions&#xa;    client --&gt; orchestrator&#xa;    &#xa;    %% Orchestrator relations&#xa;    orchestrator --&gt; registry&#xa;    orchestrator --&gt; context&#xa;    orchestrator --&gt; local&#xa;    orchestrator --&gt; temporal&#xa;    &#xa;    %% Agent relations&#xa;    base --&gt; tools&#xa;    base --&gt; logging&#xa;    base --&gt; formatter&#xa;&#xa;    &#xa;    %% Execution relations&#xa;    local --&gt; llm&#xa;    temporal --&gt; temporal_server&#xa;    temporal_server --&gt; llm&#xa;    &#xa;    %% Registry relations&#xa;    registry --&gt; base&#xa;    registry --&gt; tools&#xa;&#xa;    %% Style&#xa;    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px;&#xa;    classDef external fill:#e1f5fe,stroke:#0288d1,stroke-width:2px;&#xa;    classDef core fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;&#xa;    &#xa;    class llm,temporal_server external;&#xa;    class orchestrator,registry,context,base,local,temporal core;" style="shadow=0;dashed=0;align=left;strokeWidth=1;shape=mxgraph.mermaid.abstract.mermaid;labelBackgroundColor=#ffffff;noLabel=1;theme=default;" parent="1" vertex="1">
                     <mxGeometry x="274" y="325" width="300" height="300" as="geometry"/>
                 </mxCell>
             </root>
         </mxGraphModel>
     </diagram>
     <diagram id="sh9ImpPZNdK_Mo0HMCRx" name="Page-3">
-        <mxGraphModel dx="1237" dy="800" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF,#E8E8E8)" math="0" shadow="0">
+        <mxGraphModel dx="1489" dy="898" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF,#E8E8E8)" math="0" shadow="0">
             <root>
                 <mxCell id="0"/>
                 <mxCell id="1" parent="0"/>

flock_core-0.4.0b28/docs/guides/chaining-agents.md

@@ -0,0 +1,232 @@
+---
+hide: # Optional: Hide table of contents on simple pages
+  - toc
+---
+
+# ⛓️ Chaining Agents: Building Workflows with Routers
+
+In Flock, individual agents are powerful, but the real magic happens when you connect them to form sophisticated workflows. Chaining allows the output of one agent to become the input for another, enabling complex tasks to be broken down into manageable, specialized steps.
+
+The key to chaining lies in **Routers**. Every `FlockAgent` can have a `handoff_router` attached. After an agent successfully completes its `evaluate` step, its router is called to decide what happens next.
+
+## How Routers Work: The `HandOffRequest`
+
+A `FlockRouter`'s primary job is to execute its `route` method. This method receives:
+
+1.  `current_agent`: The agent instance that just finished.
+2.  `result`: The dictionary output produced by the `current_agent`.
+3.  `context`: The shared `FlockContext` object containing the overall workflow state and history.
+
+Based on these inputs, the router returns a `HandOffRequest` object. This object tells the Flock workflow engine:
+
+*   `next_agent` (str): The `name` of the agent to execute next. If empty or `None`, the workflow typically terminates.
+*   `output_to_input_merge_strategy` (Literal["match", "add"]): How the `result` from the current agent should be incorporated into the context for the next agent.
+    *   `"match"` (Default): Fields in the `result` update corresponding fields in the context.
+    *   `"add"`: The entire `result` dictionary is added to the context, often under a specific key (useful for feedback or passing complex objects).
+*   Optional Overrides: The `HandOffRequest` can also potentially carry information to override aspects of the next agent's execution or update the context directly (though specific router implementations vary in how they use this).
+
+Flock provides several built-in router types to handle different chaining scenarios:
+
+## 1. Static Chaining: `DefaultRouter`
+
+The simplest way to chain agents. The `DefaultRouter` routes to a predetermined next agent specified in its configuration.
+
+```python
+# --- In your agent definition ---
+from flock.core import FlockFactory
+from flock.routers.default import DefaultRouter, DefaultRouterConfig
+
+# Agent A always hands off to Agent B
+agent_a = FlockFactory.create_default_agent(
+    name="agent_a",
+    input="topic",
+    output="summary",
+    router=DefaultRouter(
+        config=DefaultRouterConfig(hand_off="agent_b") # Always go to agent_b
+    )
+)
+
+agent_b = FlockFactory.create_default_agent(
+    name="agent_b",
+    input="summary", # Expects output from agent_a
+    output="final_report"
+)
+
+flock.add_agent(agent_a)
+flock.add_agent(agent_b)
+
+# Run starting with agent_a
+flock.run(start_agent=agent_a, input={"topic": "AI Agents"})
+```
+
+The `hand_off` value in `DefaultRouterConfig` can also be a callable function that dynamically returns a `HandOffRequest` based on the context or result.
+
+## 2. Dynamic Chaining: Making Decisions
+
+For more complex workflows, you need routers that can make decisions based on the current state.
+
+### LLM-Powered Routing: `LLMRouter` 🧠
+
+This router leverages a Large Language Model (LLM) to decide the next best agent.
+
+*   **How it works:** It constructs a prompt containing the current agent's details, its output, and information about all other available agents (their names, descriptions, inputs/outputs). It asks the LLM to choose the most suitable next agent, provide a confidence score, and explain its reasoning.
+*   **Configuration:** You can set the LLM `model`, `temperature`, `max_tokens`, a `confidence_threshold` (to only proceed if the LLM is confident enough), and even provide a custom prompt template.
+*   **Use Case:** Ideal for workflows where the next step depends on nuanced understanding of the previous agent's output and the capabilities of potential next agents.
+
+```python
+# --- Conceptual Example ---
+from flock.routers.llm import LLMRouter, LLMRouterConfig
+
+smart_router = LLMRouter(
+    config=LLMRouterConfig(
+        confidence_threshold=0.7, # Only route if LLM score is >= 0.7
+        temperature=0.1
+    )
+)
+
+agent_with_llm_routing = FlockFactory.create_default_agent(
+    name="decision_point_agent",
+    # ... inputs/outputs ...
+    router=smart_router
+)
+```
+
+### Agent-Powered Routing: `AgentRouter` 🤖
+
+This router delegates the routing decision to *another* specialized `FlockAgent` called the `HandoffAgent`.
+
+*   **How it works:** The `AgentRouter` gathers information about the current agent, its result, and the available next agents. It packages this information and feeds it to the internal `HandoffAgent`. The `HandoffAgent` (which typically uses a `DeclarativeEvaluator`) analyzes the situation and outputs its decision (next agent name, confidence, reasoning). The `AgentRouter` then uses this decision.
+*   **Configuration:** Includes a `confidence_threshold`.
+*   **Use Case:** Useful when the routing logic itself is complex enough to warrant its own dedicated agent. It allows the routing logic to be developed and potentially improved independently.
+
+```python
+# --- Conceptual Example ---
+from flock.routers.agent import AgentRouter, AgentRouterConfig
+
+agent_powered_router = AgentRouter(
+    config=AgentRouterConfig(
+        confidence_threshold=0.6
+    )
+)
+
+agent_with_agent_routing = FlockFactory.create_default_agent(
+    name="complex_routing_agent",
+    # ... inputs/outputs ...
+    router=agent_powered_router
+)
+```
+
+## 3. Conditional Routing & Retries
+
+Sometimes, the workflow needs to branch or repeat based on specific conditions or feedback.
+
+### Condition-Based Branching: `ConditionalRouter` 🤔
+
+This router evaluates a condition based on a value stored in the `FlockContext` and routes accordingly.
+
+*   **How it works:** You configure it to check a specific `condition_context_key`. It supports various checks:
+    *   String comparison (equals, contains, regex, etc.)
+    *   Number comparison (<, ==, >, etc.)
+    *   List size checks (min/max items)
+    *   Type checking (`isinstance`)
+    *   Boolean checks
+    *   Existence checks (does the key exist?)
+    *   Custom logic via a registered callable function.
+*   **Routing Paths:** It routes to `success_agent` if the condition passes, or `failure_agent` if it fails.
+*   **Retry Logic:** Optionally, if the condition fails, it can route back to a `retry_agent` (often the *same* agent) up to `max_retries` times before finally giving up and going to the `failure_agent`. This is useful for self-correction loops.
+*   **Use Case:** Implementing if/else logic, validation checks, or simple retry loops within your workflow.
+
+```python
+# --- Conceptual Example ---
+from flock.routers.conditional import ConditionalRouter, ConditionalRouterConfig
+
+# Assume an agent 'validator_agent' puts its result in context.state['validation_status']
+conditional_router = ConditionalRouter(
+    config=ConditionalRouterConfig(
+        condition_context_key="validation_status", # Check this context variable
+        expected_string="PASS", # Condition: Does it equal "PASS"?
+        string_mode="equals",
+        ignore_case=True,
+        success_agent="publish_agent", # If "PASS", go to publish
+        failure_agent="human_review_agent" # If not "PASS", go to review
+    )
+)
+
+validator_agent = FlockFactory.create_default_agent(
+    name="validator_agent",
+    # ... inputs/outputs ...
+    # Assume it sets context.state['validation_status'] = "PASS" or "FAIL"
+    router=conditional_router
+)
+```
+
+### Feedback-Driven Retries: `FeedbackRetryRouter` 🔁
+
+This router is specifically designed to handle retries based on feedback, often generated by assertion modules.
+
+*   **How it works:** It checks a configured `feedback_context_key`. If feedback is present (indicating a failure or issue detected, perhaps by an `AssertionCheckerModule`), and `max_retries` hasn't been exceeded, it routes back to the *current agent*. Crucially, it uses `output_to_input_merge_strategy="add"` and `add_input_fields` to inject the feedback message (and potentially the previous result) into the context, making it available for the agent's next attempt. If retries are exhausted, it routes to a `fallback_agent` or stops.
+*   **Use Case:** Implementing self-correction loops where an agent attempts a task, an assertion module checks the result, and if issues are found, the agent retries with specific feedback on what went wrong.
+
+```python
+# --- Conceptual Example ---
+from flock.routers.feedback import FeedbackRetryRouter, FeedbackRetryRouterConfig
+# Assume AssertionCheckerModule puts feedback in context.state['flock.assertion_feedback']
+
+retry_router = FeedbackRetryRouter(
+    config=FeedbackRetryRouterConfig(
+        max_retries=2, # Allow 2 retries
+        feedback_context_key="flock.assertion_feedback", # Check this key
+        fallback_agent="error_handler_agent" # Go here if retries fail
+    )
+)
+
+# Agent that might fail assertions
+correctable_agent = FlockFactory.create_default_agent(
+    name="correctable_agent",
+    input="task_description, flock.assertion_feedback | Optional feedback", # Agent needs to accept feedback
+    output="result_data",
+    # Assume AssertionCheckerModule runs after evaluate
+    router=retry_router
+)
+```
+
+## 4. Iterative Generation: `IterativeListGeneratorRouter` 🔄
+
+This router facilitates scenarios where an agent needs to be called repeatedly to build up a list of items.
+
+*   **How it works:** It routes back to the *same agent* multiple times. It manages the growing list of generated items and the current iteration count within the `FlockContext`. On each subsequent run, it provides the list of previously generated items back to the agent (via a configured `context_input_field`). It stops once `max_iterations` is reached.
+*   **Complexity:** This pattern can be complex because the agent ideally needs slightly different inputs (the growing list) and might only need to produce *one* new item per iteration, rather than the full final list. The router attempts to manage this state, but careful agent and signature design is required.
+*   **Use Case:** Generating list items one by one, like chapters for a book outline, steps in a plan, or ideas in a brainstorm, where each new item might depend on the previous ones.
+
+```python
+# --- Conceptual Example ---
+from flock.routers.list_generator import IterativeListGeneratorRouter, IterativeListGeneratorRouterConfig
+
+list_router = IterativeListGeneratorRouter(
+    config=IterativeListGeneratorRouterConfig(
+        target_list_field="chapters", # The final list output name
+        item_output_field="chapter", # The output field for a single item
+        context_input_field="previous_chapters", # How the list is passed back
+        max_iterations=5 # Generate up to 5 chapters
+    )
+)
+
+chapter_agent = FlockFactory.create_default_agent(
+    name="chapter_agent",
+    input="book_topic, previous_chapters | List of previously generated chapters",
+    output="chapter | The next chapter details", # Agent generates one item
+    router=list_router
+)
+# Note: The final result containing the full 'chapters' list is typically
+# assembled from the context after the iterations complete.
+```
+
+## Combining Routers
+
+For truly advanced workflows, you might even chain routers themselves (though this requires careful design). For example, a `FeedbackRetryRouter` could handle immediate retries, and if no feedback is present (success), it could hand off to an `LLMRouter` to decide the *next different* agent.
+
+Just create a new router which is calling both routers in sequence! And even more wild shenanigans are possible!
+
+---
+
+By understanding and utilizing these different router types, you can move beyond simple linear sequences and build dynamic, intelligent, and robust agent workflows with Flock! 🚀

flock_core-0.4.0b28/docs/guides/index.md

@@ -0,0 +1,17 @@
+---
+hide: # Optional: Hide table of contents on simple pages
+  - toc
+---
+
+# 📚 Guides: Practical Recipes for Flock
+
+Welcome to the Flock Guides! This section provides practical, step-by-step walkthroughs for accomplishing specific tasks and implementing common patterns with Flock.
+
+Whether you're looking to build complex workflows, integrate specific tools, or optimize your agents, these guides offer focused instructions and examples.
+
+## Available Guides
+
+*   **[Chaining Agents: Building Workflows with Routers](chaining-agents.md):** Learn how to connect multiple agents together using different routing strategies, from simple static handoffs to dynamic, LLM-powered decisions.
+*   **[Configuring Temporal Execution](temporal-configuration.md):** Learn how to configure Temporal settings like task queues, timeouts, and retries for your workflows and agents.
+
+*(More guides coming soon!)*