flock-core 0.3.6__py3-none-any.whl → 0.3.8__py3-none-any.whl

flock/cli/assets/release_notes.md

@@ -1,4 +1,3 @@
-
 # Flock v0.3 - Hummingbird  
 
 We're excited to announce Flock v0.3, codenamed **"Hummingbird"**! This release brings a fundamental redesign of Flock's core architecture, introducing **unprecedented modularity and flexibility** to AI agent development.  
@@ -13,17 +12,17 @@ Like a hummingbird, modules are small and nimble code packages. Put enough of th
 
 ### Other notable additions:  
 - **CLI Interface** – Flock now has a command-line interface  
+- **REST API Server** – Expose your agents via HTTP endpoints
 - **Color-coded logging** – Better debugging experience  
 - **New examples**  
 - ...and much more!  
 
 ---
 
-## Core Changes  
+## Core Changes   
 
-### New Module System  
-- **Complete redesign** of the module architecture  
-- Simple yet powerful lifecycle hooks: `initialize`, `pre_evaluate`, `post_evaluate`, `terminate`  
+### New Module System   
+- **Pluggable modules system á la FastAPI**   
 - **Easy-to-implement** module interface  
 - **Configuration system** for clean parameter management  
 
@@ -32,15 +31,44 @@ Like a hummingbird, modules are small and nimble code packages. Put enough of th
 - Built-in support for multiple evaluation strategies:  
   - **Declarative Evaluator** – The default way Flock is designed  
   - **Natural Language Evaluator** – Use "classic" prompting  
+  - **Zep Evaluator** – Add or query data
 - **Easily extendable** with custom evaluation approaches  
 
-### FlockFactory  
+### New Router System
+- **Pluggable router system** for dynamic agent chaining
+- Built-in support for multiple routing strategies:
+  - **Default Router** – Uses the agent's hand_off property
+  - **LLM Router** – Uses an LLM to determine the next agent
+  - **Agent Router** – Uses a dedicated agent to make routing decisions
+- **Easily extendable** with custom routing approaches
+
+### REST API Server
+- **FastAPI-based** HTTP server for exposing agents
+- **Synchronous and asynchronous** execution modes
+- **Run status tracking** with unique run IDs
+- **Agent discovery** endpoint to list available agents
+- **Simple integration** with existing Flock instances
+
+### Auto-Handoff Feature
+- **Dynamic agent chaining** without explicit handoff definitions
+- **LLM-powered routing** to determine the best next agent
+- **Emergent behavior** in multi-agent systems
+- **Simple to use** with the "auto_handoff" string value
+
+### New high end examples like the Repository Analyzer
+- **Automatic documentation generation** for any codebase
+- **Rule-based version** using custom evaluators
+- **LLM-based version** for more flexible and powerful analysis
+- **Comprehensive documentation** including overview, architecture, components, and more
+
+### FlockFactory    
 - Provides **pre-configured agents**, so you don't have to manage modules and evaluators manually!  
 
 ### Built-in Modules  
 - **Memory Module** – Persistent agent memory  
 - **Output Module** – Advanced output formatting and storage  
 - **Metrics Module** – Detailed performance tracking  
+- **Zep Module** – Uses Zep for Knowledge Graphs
 
 ---
 
@@ -99,7 +127,7 @@ See? **Basically nothing changed!** Just more modular and flexible.
 
 ---
 
-## 🛠 Installation  
+## Installation  
 
 ```bash
 pip install flock-core>=0.3.0
@@ -107,5 +135,5 @@ pip install flock-core>=0.3.0
 
 ---  
 
-**Full documentation**: [docs.flock.ai](https://docs.flock.ai)  
-**GitHub**: [github.com/flock-ai](https://github.com/flock-ai)  
+**Full documentation**: [https://whiteducksoftware.github.io/flock](https://whiteducksoftware.github.io/flock)  
+**GitHub**: [https://github.com/whiteducksoftware/flock](https://github.com/whiteducksoftware/flock)

flock/core/flock_agent.py

@@ -5,15 +5,15 @@ import json
 import os
 from abc import ABC
 from collections.abc import Callable
-from typing import Any, TypeVar, Union
+from typing import Any, TypeVar
 
 import cloudpickle
 from opentelemetry import trace
 from pydantic import BaseModel, Field
 
-from flock.core.context.context import FlockContext
 from flock.core.flock_evaluator import FlockEvaluator
 from flock.core.flock_module import FlockModule
+from flock.core.flock_router import FlockRouter
 from flock.core.logging.logging import get_logger
 
 logger = get_logger("agent")
@@ -23,21 +23,6 @@ tracer = trace.get_tracer(__name__)
 T = TypeVar("T", bound="FlockAgent")
 
 
-class HandOff(BaseModel):
-    """Base class for handoff returns."""
-
-    next_agent: Union[str, "FlockAgent"] = Field(
-        default="", description="Next agent to invoke"
-    )
-    input: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Input data for the next agent",
-    )
-    context: FlockContext = Field(
-        default=None, descrio="Override context parameters"
-    )
-
-
 class FlockAgent(BaseModel, ABC):
     name: str = Field(..., description="Unique identifier for the agent.")
     model: str | None = Field(
@@ -72,12 +57,9 @@ class FlockAgent(BaseModel, ABC):
         description="Set to True to enable caching of the agent's results.",
     )
 
-    hand_off: str | HandOff | Callable[..., HandOff] | None = Field(
-        None,
-        description=(
-            "Specifies the next agent in the workflow or a callable that determines the handoff. "
-            "This allows chaining of agents."
-        ),
+    handoff_router: FlockRouter | None = Field(
+        default=None,
+        description="Router to use for determining the next agent in the workflow.",
     )
 
     evaluator: FlockEvaluator = Field(

flock/core/flock_factory.py

@@ -3,14 +3,17 @@
 from collections.abc import Callable
 from typing import Any
 
-from flock.core.flock_agent import FlockAgent, HandOff
+from flock.core.flock_agent import FlockAgent
 from flock.core.logging.formatters.themes import OutputTheme
 from flock.evaluators.declarative.declarative_evaluator import (
     DeclarativeEvaluator,
     DeclarativeEvaluatorConfig,
 )
-from flock.modules.performance.metrics_module import MetricsModule, MetricsModuleConfig
 from flock.modules.output.output_module import OutputModule, OutputModuleConfig
+from flock.modules.performance.metrics_module import (
+    MetricsModule,
+    MetricsModuleConfig,
+)
 
 
 class FlockFactory:
@@ -24,7 +27,6 @@ class FlockFactory:
         input: str | Callable[..., str] | None = None,
         output: str | Callable[..., str] | None = None,
         tools: list[Callable[..., Any] | Any] | None = None,
-        hand_off: str | HandOff | Callable[..., HandOff] | None = None,
         use_cache: bool = True,
         enable_rich_tables: bool = False,
         output_theme: OutputTheme = OutputTheme.abernathy,
@@ -53,7 +55,6 @@ class FlockFactory:
             input=input,
             output=output,
             tools=tools,
-            hand_off=hand_off,
             model=model,
             description=description,
             evaluator=evaluator,
@@ -65,7 +66,9 @@ class FlockFactory:
         )
         output_module = OutputModule("output", config=output_config)
 
-        metrics_config = MetricsModuleConfig(latency_threshold_ms=alert_latency_threshold_ms)
+        metrics_config = MetricsModuleConfig(
+            latency_threshold_ms=alert_latency_threshold_ms
+        )
         metrics_module = MetricsModule("metrics", config=metrics_config)
 
         agent.add_module(output_module)

flock/core/flock_module.py

@@ -43,7 +43,9 @@ class FlockModule(BaseModel, ABC):
     2. Using FlockModuleConfig.with_fields() to create a config class
     """
 
-    name: str = Field(..., description="Unique identifier for the module")
+    name: str = Field(
+        default="", description="Unique identifier for the module"
+    )
     config: FlockModuleConfig = Field(
         default_factory=FlockModuleConfig, description="Module configuration"
     )

flock/core/flock_router.py

@@ -0,0 +1,70 @@
+"""Base router class for the Flock framework."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from flock.core.context.context import FlockContext
+
+
+class HandOffRequest(BaseModel):
+    """Base class for handoff returns."""
+
+    next_agent: str = Field(default="", description="Next agent to invoke")
+    # match = use the output fields of the current agent that also exists as input field of the next agent
+    # add = add the output of the current agent to the input of the next agent
+    hand_off_mode: Literal["match", "add"] = Field(default="match")
+    override_next_agent: Any | None = Field(
+        default=None,
+        description="Override the next agent to hand off to",
+    )
+    override_context: FlockContext | None = Field(
+        default=None, descrio="Override context parameters"
+    )
+
+
+class FlockRouterConfig(BaseModel):
+    """Configuration for a router.
+
+    This class defines the configuration parameters for a router.
+    Subclasses can extend this to add additional parameters.
+    """
+
+    enabled: bool = Field(
+        default=True, description="Whether the router is enabled"
+    )
+    agents: list[str] | None = Field(
+        default=None,
+        description="List of agents to choose from",
+    )
+
+
+class FlockRouter(BaseModel, ABC):
+    """Base class for all routers.
+
+    A router is responsible for determining the next agent in a workflow
+    based on the current agent's output.
+    """
+
+    name: str = Field(..., description="Name of the router")
+    config: FlockRouterConfig = Field(default_factory=FlockRouterConfig)
+
+    @abstractmethod
+    async def route(
+        self,
+        current_agent: Any,
+        result: dict[str, Any],
+        context: FlockContext,
+    ) -> HandOffRequest:
+        """Determine the next agent to hand off to based on the current agent's output.
+
+        Args:
+            current_agent: The agent that just completed execution
+            result: The output from the current agent
+            context: The global execution context
+
+        Returns:
+            A HandOff object containing the next agent and input data
+        """
+        pass

flock/evaluators/zep/zep_evaluator.py

@@ -40,6 +40,8 @@ class ZepEvaluator(FlockEvaluator, DSPyIntegrationMixin, PromptParserMixin):
                 zep_api_key=self.config.zep_api_key,
                 zep_url=self.config.zep_url,
                 min_fact_rating=self.config.min_fact_rating,
+                enable_read=True,
+                enable_write=True,
             ),
         )
         client = zep.get_client()

flock/routers/__init__.py

@@ -0,0 +1 @@
+"""Routers for the Flock framework."""

flock/routers/agent/__init__.py

@@ -0,0 +1 @@
+"""Agent-based router implementation for the Flock framework."""

flock/routers/agent/agent_router.py

@@ -0,0 +1,234 @@
+"""Agent-based router implementation for the Flock framework."""
+
+from typing import Any
+
+from flock.core.context.context import FlockContext
+from flock.core.flock_agent import FlockAgent
+from flock.core.flock_router import (
+    FlockRouter,
+    FlockRouterConfig,
+    HandOffRequest,
+)
+from flock.core.logging.formatters.themes import OutputTheme
+from flock.core.logging.logging import get_logger
+from flock.evaluators.declarative.declarative_evaluator import (
+    DeclarativeEvaluator,
+    DeclarativeEvaluatorConfig,
+)
+from flock.modules.output.output_module import OutputModule, OutputModuleConfig
+from flock.routers.agent.handoff_agent import (
+    AgentInfo,
+    HandoffAgent,
+)
+
+logger = get_logger("agent_router")
+
+
+class AgentRouterConfig(FlockRouterConfig):
+    """Configuration for the agent router.
+
+    This class extends FlockRouterConfig with parameters specific to the agent router.
+    """
+
+    with_output: bool = False
+    confidence_threshold: float = 0.5  # No additional parameters needed for now
+
+
+class AgentRouter(FlockRouter):
+    """Router that uses a FlockAgent to determine the next agent in a workflow.
+
+    This class is responsible for:
+    1. Creating and managing a HandoffAgent
+    2. Analyzing available agents in the registry
+    3. Using the HandoffAgent to determine the best next agent
+    4. Creating a HandOff object with the selected agent
+    """
+
+    def __init__(
+        self,
+        name: str = "agent_router",
+        config: AgentRouterConfig | None = None,
+    ):
+        """Initialize the AgentRouter.
+
+        Args:
+            registry: The agent registry containing all available agents
+            name: The name of the router
+            config: The router configuration
+        """
+        super().__init__(
+            name=name, config=config or AgentRouterConfig(name=name)
+        )
+
+    async def route(
+        self,
+        current_agent: FlockAgent,
+        result: dict[str, Any],
+        context: FlockContext,
+    ) -> HandOffRequest:
+        """Determine the next agent to hand off to based on the current agent's output.
+
+        Args:
+            current_agent: The agent that just completed execution
+            result: The output from the current agent
+            context: The global execution context
+
+        Returns:
+            A HandOff object containing the next agent and input data
+        """
+        # Get all available agents from context.agent_definitions
+        agent_definitions = context.agent_definitions
+        handoff_agent = HandoffAgent(model=current_agent.model)
+        handoff_agent.evaluator = DeclarativeEvaluator(
+            name="evaluator",
+            config=DeclarativeEvaluatorConfig(
+                model=current_agent.model,
+                use_cache=True,
+                max_tokens=1000,
+                temperature=0.0,
+            ),
+        )
+        if self.config.with_output:
+            handoff_agent.add_module(
+                OutputModule(
+                    name="output",
+                    config=OutputModuleConfig(
+                        theme=OutputTheme.abernathy,
+                    ),
+                )
+            )
+        available_agents = self._get_available_agents(
+            agent_definitions, current_agent.name
+        )
+
+        if not available_agents:
+            logger.warning("No available agents for agent-based routing")
+            return HandOffRequest(
+                next_agent="",
+                hand_off_mode="add",
+                override_next_agent=None,
+                override_context=None,
+            )
+
+        # Prepare input for the handoff agent
+        handoff_input = {
+            "current_agent_name": current_agent.name,
+            "current_agent_description": current_agent.description,
+            "current_agent_input": current_agent.input,
+            "current_agent_output": current_agent.output,
+            "current_result": result,
+            "available_agents": available_agents,
+        }
+
+        try:
+            # Run the handoff agent to determine the next agent
+            handoff_result = await handoff_agent.run_async(handoff_input)
+
+            # Extract the decision
+            next_agent_name = handoff_result.get("agent_name")
+            confidence = handoff_result.get("confidence")
+            reasoning = handoff_result.get("reasoning")
+            logger.info(
+                f"Agent router selected agent '{next_agent_name}' with confidence {confidence} and reasoning: {reasoning}"
+            )
+
+            if confidence < self.config.confidence_threshold:
+                logger.info(
+                    f"No suitable next agent found (best score: {confidence})"
+                )
+                return HandOffRequest(
+                    next_agent="",
+                    hand_off_mode="add",
+                    override_next_agent=None,
+                    override_context=None,
+                )
+
+            next_agent = agent_definitions.get(next_agent_name)
+            if not next_agent:
+                logger.error(
+                    f"Selected agent '{next_agent_name}' not found in agent definitions"
+                )
+                return HandOffRequest(
+                    next_agent="",
+                    hand_off_mode="add",
+                    override_next_agent=None,
+                    override_context=None,
+                )
+
+            logger.info(
+                f"Agent router selected agent '{next_agent_name}' with confidence {confidence}"
+            )
+            return HandOffRequest(
+                next_agent=next_agent_name,
+                hand_off_mode="add",
+                override_next_agent=None,
+                override_context=None,
+            )
+
+        except Exception as e:
+            logger.error(f"Error in agent-based routing: {e}")
+            return HandOffRequest(
+                next_agent="",
+                hand_off_mode="add",
+                override_next_agent=None,
+                override_context=None,
+            )
+
+    def _get_available_agents(
+        self, agent_definitions: dict[str, Any], current_agent_name: str
+    ) -> list[AgentInfo]:
+        """Get all available agents except the current one and the handoff agent.
+
+        Args:
+            agent_definitions: Dictionary of available agents
+            current_agent_name: Name of the current agent to exclude
+
+        Returns:
+            List of available agents as AgentInfo objects
+        """
+        agents = []
+        for agent_name in agent_definitions:
+            if agent_name != current_agent_name:
+                agent = agent_definitions[agent_name]
+                agent_info = AgentInfo(
+                    name=agent_name,
+                    description=agent.agent_data["description"]
+                    if agent.agent_data["description"]
+                    else "",
+                    input_schema=agent.agent_data["input"],
+                    output_schema=agent.agent_data["output"],
+                )
+                agents.append(agent_info)
+        return agents
+
+    def _get_schema_from_agent(
+        self, agent: Any, schema_type: str
+    ) -> dict[str, Any]:
+        """Extract input or output schema from an agent.
+
+        Args:
+            agent: The agent to extract schema from
+            schema_type: Either "input" or "output"
+
+        Returns:
+            Dictionary representation of the schema
+        """
+        schema = {}
+        schema_str = agent.agent_data.get(schema_type, "")
+
+        # Parse the schema string to extract field names, types, and descriptions
+        if schema_str:
+            fields = schema_str.split(",")
+            for field in fields:
+                field = field.strip()
+                if ":" in field:
+                    name, rest = field.split(":", 1)
+                    name = name.strip()
+                    schema[name] = rest.strip()
+                else:
+                    schema[field] = "Any"
+
+        return schema
+
+    # The _create_next_input method is no longer needed since we're using hand_off_mode="add"
+    # instead of manually preparing inputs for the next agent

flock/routers/agent/handoff_agent.py

@@ -0,0 +1,58 @@
+"""Handoff agent for the agent-based router."""
+
+from pydantic import BaseModel
+
+from flock.core.flock_agent import FlockAgent
+
+
+class AgentInfo(BaseModel):
+    """Information about an agent for handoff decisions."""
+
+    name: str
+    description: str = ""
+    input_schema: str = ""
+    output_schema: str = ""
+
+
+class HandoffDecision(BaseModel):
+    """Decision about which agent to hand off to."""
+
+    agent_name: str
+    confidence: float
+    reasoning: str
+
+
+class HandoffAgent(FlockAgent):
+    """Agent that decides which agent to hand off to next.
+
+    This agent analyzes the current agent's output and available agents
+    to determine the best next agent in the workflow.
+    """
+
+    def __init__(
+        self,
+        name: str = "handoff_agent",
+        model: str | None = None,
+        description: str = "Decides which agent to hand off to next",
+    ):
+        """Initialize the HandoffAgent.
+
+        Args:
+            name: The name of the agent
+            model: The model to use (e.g., 'openai/gpt-4o')
+            description: A human-readable description of the agent
+        """
+        super().__init__(
+            name=name,
+            model=model,
+            description=description,
+            input=(
+                "current_agent_name: str | Name of the current agent, "
+                "current_agent_description: str | Description of the current agent, "
+                "current_agent_input: str | Input schema of the current agent, "
+                "current_agent_output: str | Output schema of the current agent, "
+                "current_result: dict | Output from the current agent, "
+                "available_agents: list[AgentInfo] | List of available agents"
+            ),
+            output="agent_name: str | Name of the agent to hand off to, confidence: float | Confidence in the decision, reasoning: str | Reasoning for the decision",
+        )

flock/routers/default/__init__.py

@@ -0,0 +1 @@
+"""Default router implementation for the Flock framework."""

flock/routers/default/default_router.py

@@ -0,0 +1,76 @@
+"""Default router implementation for the Flock framework."""
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import Field
+
+from flock.core.context.context import FlockContext
+from flock.core.flock_agent import FlockAgent
+from flock.core.flock_router import (
+    FlockRouter,
+    FlockRouterConfig,
+    HandOffRequest,
+)
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("default_router")
+
+
+class DefaultRouterConfig(FlockRouterConfig):
+    """Configuration for the default router."""
+
+    hand_off: str | HandOffRequest | Callable[..., HandOffRequest] = Field(
+        default="", description="Next agent to hand off to"
+    )
+
+
+class DefaultRouter(FlockRouter):
+    """Default router implementation.
+
+    This router simply uses the agent's hand_off property to determine the next agent.
+    It does not perform any dynamic routing.
+    """
+
+    name: str = "default_router"
+    config: DefaultRouterConfig = Field(
+        default_factory=DefaultRouterConfig, description="Output configuration"
+    )
+
+    def __init__(
+        self,
+        name: str = "default_router",
+        config: DefaultRouterConfig | None = None,
+    ):
+        """Initialize the DefaultRouter.
+
+        Args:
+            name: The name of the router
+            config: The router configuration
+        """
+        super().__init__(
+            name=name, config=config or DefaultRouterConfig(name=name)
+        )
+
+    async def route(
+        self,
+        current_agent: FlockAgent,
+        result: dict[str, Any],
+        context: FlockContext,
+    ) -> HandOffRequest:
+        """Determine the next agent to hand off to based on the current agent's output.
+
+        Args:
+            current_agent: The agent that just completed execution
+            result: The output from the current agent
+            context: The global execution context
+
+        Returns:
+            A HandOff object containing the next agent and input data
+        """
+        handoff = self.config.hand_off
+        if callable(handoff):
+            handoff = handoff(context, result)
+        if isinstance(handoff, str):
+            handoff = HandOffRequest(next_agent=handoff, hand_off_mode="match")
+        return handoff

flock/routers/llm/__init__.py

@@ -0,0 +1 @@
+"""LLM-based router implementation for the Flock framework."""

flock/routers/llm/llm_router.py

@@ -0,0 +1,363 @@
+"""LLM-based router implementation for the Flock framework."""
+
+import json
+from typing import Any
+
+import litellm
+
+from flock.core.context.context import FlockContext
+from flock.core.flock_agent import FlockAgent
+from flock.core.flock_router import (
+    FlockRouter,
+    FlockRouterConfig,
+    HandOffRequest,
+)
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("llm_router")
+
+
+class LLMRouterConfig(FlockRouterConfig):
+    """Configuration for the LLM router.
+
+    This class extends FlockRouterConfig with parameters specific to the LLM router.
+    """
+
+    temperature: float = 0.2
+    max_tokens: int = 500
+    confidence_threshold: float = 0.5
+    prompt: str = ""
+
+
+class LLMRouter(FlockRouter):
+    """Router that uses an LLM to determine the next agent in a workflow.
+
+    This class is responsible for:
+    1. Analyzing available agents in the registry
+    2. Using an LLM to score each agent's suitability as the next step
+    3. Selecting the highest-scoring agent
+    4. Creating a HandOff object with the selected agent
+    """
+
+    def __init__(
+        self,
+        name: str = "llm_router",
+        config: LLMRouterConfig | None = None,
+    ):
+        """Initialize the LLMRouter.
+
+        Args:
+            registry: The agent registry containing all available agents
+            name: The name of the router
+            config: The router configuration
+        """
+        logger.info(f"Initializing LLM Router '{name}'")
+        super().__init__(name=name, config=config or LLMRouterConfig(name=name))
+        logger.debug(
+            "LLM Router configuration",
+            temperature=self.config.temperature,
+            max_tokens=self.config.max_tokens,
+        )
+
+    async def route(
+        self,
+        current_agent: FlockAgent,
+        result: dict[str, Any],
+        context: FlockContext,
+    ) -> HandOffRequest:
+        """Determine the next agent to hand off to based on the current agent's output.
+
+        Args:
+            current_agent: The agent that just completed execution
+            result: The output from the current agent
+            context: The global execution context
+
+        Returns:
+            A HandOff object containing the next agent and input data
+        """
+        logger.info(
+            f"Routing from agent '{current_agent.name}'",
+            current_agent=current_agent.name,
+        )
+        logger.debug("Current agent result", result=result)
+
+        agent_definitions = context.agent_definitions
+        # Get all available agents from the registry
+        available_agents = self._get_available_agents(
+            agent_definitions, current_agent.name
+        )
+        logger.debug(
+            "Available agents for routing",
+            count=len(available_agents),
+            agents=[a.agent_data["name"] for a in available_agents],
+        )
+
+        if not available_agents:
+            logger.warning(
+                "No available agents for routing",
+                current_agent=current_agent.name,
+            )
+            return HandOffRequest(
+                next_agent="", override_next_agent={}, override_context=None
+            )
+
+        # Use LLM to determine the best next agent
+        next_agent_name, score = await self._select_next_agent(
+            current_agent, result, available_agents
+        )
+        logger.info(
+            "Agent selection result",
+            next_agent=next_agent_name,
+            score=score,
+        )
+
+        if not next_agent_name or score < self.config.confidence_threshold:
+            logger.warning(
+                "No suitable next agent found",
+                best_score=score,
+            )
+            return HandOffRequest(
+                next_agent="", override_next_agent={}, override_context=None
+            )
+
+        # Get the next agent from the registry
+        next_agent = agent_definitions.get(next_agent_name)
+        if not next_agent:
+            logger.error(
+                "Selected agent not found in registry",
+                agent_name=next_agent_name,
+            )
+            return HandOffRequest(
+                next_agent="", override_next_agent={}, override_context=None
+            )
+
+        # Create input for the next agent
+
+        logger.success(
+            f"Successfully routed to agent '{next_agent_name}'",
+            score=score,
+            from_agent=current_agent.name,
+        )
+        return HandOffRequest(
+            next_agent=next_agent_name,
+            hand_off_mode="add",
+            override_next_agent=None,
+            override_context=None,
+        )
+
+    def _get_available_agents(
+        self, agent_definitions: dict[str, Any], current_agent_name: str
+    ) -> list[FlockAgent]:
+        """Get all available agents except the current one.
+
+        Args:
+            current_agent_name: Name of the current agent to exclude
+
+        Returns:
+            List of available agents
+        """
+        logger.debug(
+            "Getting available agents",
+            total_agents=len(agent_definitions),
+            current_agent=current_agent_name,
+        )
+        agents = []
+        for agent in agent_definitions:
+            if agent != current_agent_name:
+                agents.append(agent_definitions.get(agent))
+        return agents
+
+    async def _select_next_agent(
+        self,
+        current_agent: FlockAgent,
+        result: dict[str, Any],
+        available_agents: list[FlockAgent],
+    ) -> tuple[str, float]:
+        """Use an LLM to select the best next agent.
+
+        Args:
+            current_agent: The agent that just completed execution
+            result: The output from the current agent
+            available_agents: List of available agents to choose from
+
+        Returns:
+            Tuple of (selected_agent_name, confidence_score)
+        """
+        logger.debug(
+            "Selecting next agent",
+            current_agent=current_agent.name,
+            available_count=len(available_agents),
+        )
+
+        # Prepare the prompt for the LLM
+        prompt = self._create_selection_prompt(
+            current_agent, result, available_agents
+        )
+        logger.debug("Generated selection prompt", prompt_length=len(prompt))
+
+        try:
+            logger.info(
+                "Calling LLM for agent selection",
+                model=current_agent.model,
+                temperature=self.config.temperature,
+            )
+            # Call the LLM to get the next agent
+            response = await litellm.acompletion(
+                model=current_agent.model,
+                messages=[{"role": "user", "content": prompt}],
+                temperature=self.config.temperature
+                if isinstance(self.config, LLMRouterConfig)
+                else 0.2,
+                max_tokens=self.config.max_tokens
+                if isinstance(self.config, LLMRouterConfig)
+                else 500,
+            )
+
+            content = response.choices[0].message.content
+            # Parse the response to get the agent name and score
+            try:
+                # extract the json object from the response
+                content = content.split("```json")[1].split("```")[0]
+                data = json.loads(content)
+                next_agent = data.get("next_agent", "")
+                score = float(data.get("score", 0))
+                reasoning = data.get("reasoning", "")
+                logger.info(
+                    "Successfully parsed LLM response",
+                    next_agent=next_agent,
+                    score=score,
+                    reasoning=reasoning,
+                )
+                return next_agent, score
+            except (json.JSONDecodeError, ValueError) as e:
+                logger.error(
+                    "Failed to parse LLM response",
+                    error=str(e),
+                    raw_response=content,
+                )
+                logger.debug("Attempting fallback parsing")
+
+                # Fallback: try to extract the agent name from the text
+                for agent in available_agents:
+                    if agent.agent_data["name"] in content:
+                        logger.info(
+                            "Found agent name in response using fallback",
+                            agent=agent.agent_data["name"],
+                        )
+                        return agent.agent_data[
+                            "name"
+                        ], 0.6  # Default score for fallback
+
+                return "", 0.0
+
+        except Exception as e:
+            logger.error(
+                "Error calling LLM for agent selection",
+                error=str(e),
+                current_agent=current_agent.name,
+            )
+            return "", 0.0
+
+    def _create_selection_prompt(
+        self,
+        current_agent: FlockAgent,
+        result: dict[str, Any],
+        available_agents: list[FlockAgent],
+    ) -> str:
+        """Create a prompt for the LLM to select the next agent.
+
+        Args:
+            current_agent: The agent that just completed execution
+            result: The output from the current agent
+            available_agents: List of available agents to choose from
+
+        Returns:
+            Prompt string for the LLM
+        """
+        # Format the current agent's output
+        result_str = json.dumps(result, indent=2)
+
+        # Format the available agents' information
+        agents_info = []
+        for agent in available_agents:
+            agent_info = {
+                "name": agent.agent_data["name"],
+                "description": agent.agent_data["description"]
+                if agent.agent_data["description"]
+                else "",
+                "input": agent.agent_data["input"],
+                "output": agent.agent_data["output"],
+            }
+            agents_info.append(agent_info)
+
+        agents_str = json.dumps(agents_info, indent=2)
+
+        # Create the prompt
+        if self.config.prompt:
+            prompt = self.config.prompt
+        else:
+            prompt = f"""
+You are a workflow router that determines the next agent to execute in a multi-agent system.
+
+CURRENT AGENT:
+Name: {current_agent.name}
+Description: {current_agent.description}
+Input: {current_agent.input}
+Output: {current_agent.output}
+
+CURRENT AGENT'S OUTPUT:
+{result_str}
+
+AVAILABLE AGENTS:
+{agents_str}
+
+Based on the current agent's output and the available agents, determine which agent should be executed next.
+Consider the following:
+1. Which agent's input requirements best match the current agent's output?
+2. Which agent's purpose and description make it the most logical next step?
+3. Which agent would provide the most value in continuing the workflow?
+
+Respond with a JSON object containing:
+1. "next_agent": The name of the selected agent
+2. "score": A confidence score between 0 and 1 indicating how suitable this agent is
+3. "reasoning": A brief explanation of why this agent was selected
+
+If no agent is suitable, set "next_agent" to an empty string and "score" to 0.
+
+JSON Response:
+"""
+        return prompt
+
+    def _create_next_input(
+        self,
+        current_agent: FlockAgent,
+        result: dict[str, Any],
+        next_agent: FlockAgent,
+    ) -> dict[str, Any]:
+        """Create the input for the next agent, including the previous agent's output.
+
+        Args:
+            current_agent: The agent that just completed execution
+            result: The output from the current agent
+            next_agent: The next agent to execute
+
+        Returns:
+            Input dictionary for the next agent
+        """
+        # Start with an empty input
+        next_input = {}
+
+        # Add a special field for the previous agent's output
+        next_input["previous_agent_output"] = {
+            "agent_name": current_agent.name,
+            "result": result,
+        }
+
+        # Try to map the current agent's output to the next agent's input
+        # This is a simple implementation that could be enhanced with more sophisticated mapping
+        for key in result:
+            # If the next agent expects this key, add it directly
+            if key in next_agent.input:
+                next_input[key] = result[key]
+
+        return next_input

flock/workflow/activities.py

@@ -7,7 +7,8 @@ from temporalio import activity
 
 from flock.core.context.context import FlockContext
 from flock.core.context.context_vars import FLOCK_CURRENT_AGENT
-from flock.core.flock_agent import FlockAgent, HandOff
+from flock.core.flock_agent import FlockAgent
+from flock.core.flock_router import HandOffRequest
 from flock.core.logging.logging import get_logger
 from flock.core.registry.agent_registry import Registry
 from flock.core.util.input_resolver import resolve_inputs
@@ -74,49 +75,83 @@ async def run_agent(context: FlockContext) -> dict:
                         exec_span.record_exception(e)
                         raise
 
-                # If there is no handoff, record the result and finish.
-                if not agent.hand_off:
-                    context.record(
-                        agent.name,
-                        result,
-                        timestamp=datetime.now().isoformat(),
-                        hand_off=None,
-                        called_from=previous_agent_name,
-                    )
+                # Determine the next agent using the handoff router if available
+                handoff_data = HandOffRequest()
+
+                if agent.handoff_router:
                     logger.info(
-                        "No handoff defined, completing chain", agent=agent.name
+                        f"Using handoff router: {agent.handoff_router.__class__.__name__}",
+                        agent=agent.name,
                     )
-                    iter_span.add_event("chain completed")
-                    return result
-
-                # Determine the next agent.
-                handoff_data = HandOff()
-                if callable(agent.hand_off):
-                    logger.debug("Executing handoff function", agent=agent.name)
                     try:
-                        handoff_data = agent.hand_off(context, result)
-                        if isinstance(handoff_data.next_agent, FlockAgent):
+                        # Route to the next agent
+                        handoff_data = await agent.handoff_router.route(
+                            agent, result, context
+                        )
+
+                        if callable(handoff_data):
+                            logger.debug(
+                                "Executing handoff function", agent=agent.name
+                            )
+                            try:
+                                handoff_data = handoff_data(context, result)
+                                if isinstance(
+                                    handoff_data.next_agent, FlockAgent
+                                ):
+                                    handoff_data.next_agent = (
+                                        handoff_data.next_agent.name
+                                    )
+                            except Exception as e:
+                                logger.error(
+                                    "Handoff function error {} {}",
+                                    agent=agent.name,
+                                    error=str(e),
+                                )
+                                iter_span.record_exception(e)
+                                return {"error": f"Handoff function error: {e}"}
+                        elif isinstance(handoff_data.next_agent, FlockAgent):
                             handoff_data.next_agent = (
                                 handoff_data.next_agent.name
                             )
+
+                        if not handoff_data.next_agent:
+                            logger.info(
+                                "Router found no suitable next agent",
+                                agent=agent.name,
+                            )
+                            context.record(
+                                agent.name,
+                                result,
+                                timestamp=datetime.now().isoformat(),
+                                hand_off=None,
+                                called_from=previous_agent_name,
+                            )
+                            logger.info("Completing chain", agent=agent.name)
+                            iter_span.add_event("chain completed")
+                            return result
                     except Exception as e:
                         logger.error(
-                            "Handoff function error",
-                            agent=agent.name,
-                            error=str(e),
+                            "Router error {} {}",
+                            agent.name,
+                            str(e),
                         )
                         iter_span.record_exception(e)
-                        return {"error": f"Handoff function error: {e}"}
-                elif isinstance(agent.hand_off, str | FlockAgent):
-                    handoff_data.next_agent = (
-                        agent.hand_off
-                        if isinstance(agent.hand_off, str)
-                        else agent.hand_off.name
-                    )
+                        return {"error": f"Router error: {e}"}
                 else:
-                    logger.error("Unsupported hand_off type", agent=agent.name)
-                    iter_span.add_event("unsupported hand_off type")
-                    return {"error": "Unsupported hand_off type."}
+                    # No router, so no handoff
+                    logger.info(
+                        "No handoff router defined, completing chain",
+                        agent=agent.name,
+                    )
+                    context.record(
+                        agent.name,
+                        result,
+                        timestamp=datetime.now().isoformat(),
+                        hand_off=None,
+                        called_from=previous_agent_name,
+                    )
+                    iter_span.add_event("chain completed")
+                    return result
 
                 # Record the agent run in the context.
                 context.record(
@@ -127,10 +162,15 @@ async def run_agent(context: FlockContext) -> dict:
                     called_from=previous_agent_name,
                 )
                 previous_agent_name = agent.name
+                previous_agent_output = agent.output
+                if handoff_data.override_context:
+                    context.update(handoff_data.override_context)
 
                 # Prepare the next agent.
                 try:
                     agent = registry.get_agent(handoff_data.next_agent)
+                    if handoff_data.hand_off_mode == "add":
+                        agent.input = previous_agent_output + ", " + agent.input
                     agent.resolve_callables(context=context)
                     if not agent:
                         logger.error(
@@ -147,6 +187,7 @@ async def run_agent(context: FlockContext) -> dict:
                         }
 
                     context.set_variable(FLOCK_CURRENT_AGENT, agent.name)
+
                     logger.info("Handing off to next agent", next=agent.name)
                     iter_span.set_attribute("next.agent", agent.name)
                 except Exception as e:

{flock_core-0.3.6.dist-info → flock_core-0.3.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.3.6
+Version: 0.3.8
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE

{flock_core-0.3.6.dist-info → flock_core-0.3.8.dist-info}/RECORD

@@ -8,14 +8,15 @@ flock/cli/load_examples.py,sha256=DkeLUlrb7rGx3nZ04aADU9HXXu5mZTf_DBwT0xhzIv4,7
 flock/cli/load_flock.py,sha256=3JdECvt5X7uyOG2vZS3-Zk5C5SI_84_QZjcsB3oJmfA,932
 flock/cli/load_release_notes.py,sha256=qFcgUrMddAE_TP6x1P-6ZywTUjTknfhTDW5LTxtg1yk,599
 flock/cli/settings.py,sha256=DkeLUlrb7rGx3nZ04aADU9HXXu5mZTf_DBwT0xhzIv4,7
-flock/cli/assets/release_notes.md,sha256=K-upUm5vuUuRSSU2FkMdgDfai_YlDk_vTCp0s4s2WO0,3419
+flock/cli/assets/release_notes.md,sha256=-RuE-G9Sn8z1LWEdr9iqjuQN7N1K_JMaCzHYoyLR42U,4793
 flock/core/__init__.py,sha256=mPlvKc0SxC2qCvSlgYeP_7EyV8ptmdn24NO8mlQoCSo,559
 flock/core/flock.py,sha256=1LPMblsvT90Na35LXx0w3Us66yIaTzsokL7lF5fsVX8,19228
-flock/core/flock_agent.py,sha256=RzKX0GRrRJz16YbQFheMo8TqJPXOZSHWNloTbp35zwI,12229
+flock/core/flock_agent.py,sha256=LjSuAYRFh4UWV8Z4_mguMme2GnMQwteNFyion4Memt8,11705
 flock/core/flock_api.py,sha256=SKQVKgFCaNCqHtwvIcksnpqG6ajHodVhs3oaKUw-d8c,7192
 flock/core/flock_evaluator.py,sha256=j7riJj_KsWoBnKmLiGp-U0CRhxDyJbgEdLGN26tfKm8,1588
-flock/core/flock_factory.py,sha256=vyDq0eyFT4MyE_n2JyNU7YaFx2ljmjSDmZ07OIsmIOE,2694
-flock/core/flock_module.py,sha256=VWFlBiY2RHZLTlGYfcchuT41M3m_JrZcmzw07u7KayM,2581
+flock/core/flock_factory.py,sha256=xTz2VqcLjaHn60b3Oaz8JCJdcIQra0vc5NHqh3Dy44s,2617
+flock/core/flock_module.py,sha256=3DmxOc39gQS-tiJcgUCjMaLr8QDDJR4acV_M76Xcf6I,2602
+flock/core/flock_router.py,sha256=A5GaxcGvtiFlRLHBTW7okh5RDm3BdKam2uXvRHRaj7k,2187
 flock/core/context/context.py,sha256=AW0qKIAkgZucVroGsulrPVPc4WmWuqWIrVPHf2qaOLI,6380
 flock/core/context/context_manager.py,sha256=qMySVny_dbTNLh21RHK_YT0mNKIOrqJDZpi9ZVdBsxU,1103
 flock/core/context/context_vars.py,sha256=0Hn6fM2iNc0_jIIU0B7KX-K2o8qXqtZ5EYtwujETQ7U,272
@@ -46,7 +47,7 @@ flock/core/util/hydrator.py,sha256=6qNwOwCZB7r6y25BZ--0PGofrAlfMaXbDKFQeP5NLts,1
 flock/core/util/input_resolver.py,sha256=g9vDPdY4OH-G7qjas5ksGEHueokHGFPMoLOvC-ngeLo,5984
 flock/evaluators/declarative/declarative_evaluator.py,sha256=f8ldgZZp94zC4CoGzBufKvbvtckCGBe9EHTOoAZfZK0,1695
 flock/evaluators/natural_language/natural_language_evaluator.py,sha256=6nVEeh8_uwv_h-d3FWlA0GbzDzRtdhvxCGKirHtyvOU,2012
-flock/evaluators/zep/zep_evaluator.py,sha256=hEHQdgIwGsbC4ci9RvtdA2k7f4M0yznIok4v4XltNwg,1885
+flock/evaluators/zep/zep_evaluator.py,sha256=9NOELl7JAuUcx_FQrxY6b-_vN3MjwDyW7ZppPIGeCFc,1954
 flock/modules/callback/callback_module.py,sha256=hCCw-HNYjK4aHnUQfvw26ZP1Q_jdlKb9kDh3BHzbCQA,2916
 flock/modules/memory/memory_module.py,sha256=2grdmvw7FJWZvz0IjgASbDPCfyS1w4gWkRzOWtK7BFM,8214
 flock/modules/memory/memory_parser.py,sha256=2S7CmVEsm22gD7-MiFj4318FTg8wd_jB-RKMwXI14WM,4369
@@ -56,6 +57,14 @@ flock/modules/performance/metrics_module.py,sha256=K5z5bizIjA4ZEUjBk5ShwTR9ZElR-
 flock/modules/zep/zep_module.py,sha256=BIJ5K-hg2bLeJmGKoDcVY1rVN7_0yYETiSaVrO-gtMI,5830
 flock/platform/docker_tools.py,sha256=fpA7-6rJBjPOUBLdQP4ny2QPgJ_042nmqRn5GtKnoYw,1445
 flock/platform/jaeger_install.py,sha256=MyOMJQx4TQSMYvdUJxfiGSo3YCtsfkbNXcAcQ9bjETA,2898
+flock/routers/__init__.py,sha256=w9uL34Auuo26-q_EGlE8Z9iHsw6S8qutTAH_ZI7pn7M,39
+flock/routers/agent/__init__.py,sha256=0ZOYpR8BMnR5iCGfcUiv99g7aT_g13xvm2Shl-XzybY,65
+flock/routers/agent/agent_router.py,sha256=9s3AwcBqpyhpPXOTqyMSVtS8Bcme1RDdqSUfWIqEBfc,8139
+flock/routers/agent/handoff_agent.py,sha256=p-0XEPXIyv1T3DGAhhXg2SYXmrwEaJ5pnuLgRSvbiZg,1903
+flock/routers/default/__init__.py,sha256=DOatGX_aE2DWvf55a0Tv7qDK05QFD-hL3sm7g58hmLU,61
+flock/routers/default/default_router.py,sha256=D9TCAAeNfzt3Se6QduGO2TmZ6038XlQLV6Y1u5IGI-0,2232
+flock/routers/llm/__init__.py,sha256=OV89ebq8RPWZwCJTS2_P46Q0yKD_03rwq_fBOsETd08,63
+flock/routers/llm/llm_router.py,sha256=3WXUK2TqZENYXSFb7o_WtpONq0SsebaZZpytCRr1daw,12217
 flock/themes/3024-day.toml,sha256=uOVHqEzSyHx0WlUk3D0lne4RBsNBAPCTy3C58yU7kEY,667
 flock/themes/3024-night.toml,sha256=qsXUwd6ZYz6J-R129_Ao2TKlvvK60svhZJJjB5c8Tfo,1667
 flock/themes/aardvark-blue.toml,sha256=5ZgsxP3pWLPN3yJ2Wd9ErCo7fy_VJpIfje4kriDKlqo,1667
@@ -393,12 +402,12 @@ flock/themes/zenburned.toml,sha256=UEmquBbcAO3Zj652XKUwCsNoC2iQSlIh-q5c6DH-7Kc,1
 flock/themes/zenwritten-dark.toml,sha256=To5l6520_3UqAGiEumpzGWsHhXxqu9ThrMildXKgIO0,1669
 flock/themes/zenwritten-light.toml,sha256=G1iEheCPfBNsMTGaVpEVpDzYBHA_T-MV27rolUYolmE,1666
 flock/workflow/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-flock/workflow/activities.py,sha256=2zcYyDoCuYs9oQbnhLjCzBUdEi7d5IEIemKJ7TV_B8w,6932
+flock/workflow/activities.py,sha256=PqUc1jecg-7qq4KQr0Gr2XLNCABZ79fvD1MqazT--YU,8866
 flock/workflow/agent_activities.py,sha256=NhBZscflEf2IMfSRa_pBM_TRP7uVEF_O0ROvWZ33eDc,963
 flock/workflow/temporal_setup.py,sha256=VWBgmBgfTBjwM5ruS_dVpA5AVxx6EZ7oFPGw4j3m0l0,1091
 flock/workflow/workflow.py,sha256=I9MryXW_bqYVTHx-nl2epbTqeRy27CAWHHA7ZZA0nAk,1696
-flock_core-0.3.6.dist-info/METADATA,sha256=-TPh-D8HF2et5uEyksY7uwhl9Fgc0b_RRf0PMe1B2hg,20494
-flock_core-0.3.6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-flock_core-0.3.6.dist-info/entry_points.txt,sha256=rWaS5KSpkTmWySURGFZk6PhbJ87TmvcFQDi2uzjlagQ,37
-flock_core-0.3.6.dist-info/licenses/LICENSE,sha256=iYEqWy0wjULzM9GAERaybP4LBiPeu7Z1NEliLUdJKSc,1072
-flock_core-0.3.6.dist-info/RECORD,,
+flock_core-0.3.8.dist-info/METADATA,sha256=0ImaV46N5uSNlZPP4kF2q-pjfY3nsLLHzDvicvv7_gA,20494
+flock_core-0.3.8.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+flock_core-0.3.8.dist-info/entry_points.txt,sha256=rWaS5KSpkTmWySURGFZk6PhbJ87TmvcFQDi2uzjlagQ,37
+flock_core-0.3.8.dist-info/licenses/LICENSE,sha256=iYEqWy0wjULzM9GAERaybP4LBiPeu7Z1NEliLUdJKSc,1072
+flock_core-0.3.8.dist-info/RECORD,,