flock-core 0.4.528__py3-none-any.whl → 0.5.0b0__py3-none-any.whl

flock/core/component/evaluation_component.py

@@ -0,0 +1,56 @@
+# src/flock/core/component/evaluation_component_base.py
+"""Base class for evaluation components in the unified component system."""
+
+from abc import abstractmethod
+from typing import Any
+
+from flock.core.context.context import FlockContext
+
+from .agent_component_base import AgentComponent
+
+
+class EvaluationComponent(AgentComponent):
+    """Base class for evaluation components.
+    
+    Evaluation components implement the core intelligence/logic of an agent.
+    They are responsible for taking inputs and producing outputs using some
+    evaluation strategy (e.g., DSPy, direct LLM calls, deterministic logic).
+    
+    Each agent should have exactly one primary evaluation component.
+    
+    Example implementations:
+    - DeclarativeEvaluationComponent (DSPy-based)
+    - ScriptEvaluationComponent (Python script-based)
+    - LLMEvaluationComponent (direct LLM API)
+    """
+
+    @abstractmethod
+    async def evaluate_core(
+        self,
+        agent: Any,
+        inputs: dict[str, Any],
+        context: FlockContext | None = None,
+        tools: list[Any] | None = None,
+        mcp_tools: list[Any] | None = None,
+    ) -> dict[str, Any]:
+        """Core evaluation logic - MUST be implemented by concrete classes.
+        
+        This is the heart of the agent's intelligence. It takes the processed
+        inputs (after all on_pre_evaluate hooks) and produces the agent's output.
+        
+        Args:
+            agent: The agent being executed
+            inputs: Input data for evaluation (after pre-processing)
+            context: Execution context with variables, history, etc.
+            tools: Available callable tools for the agent
+            mcp_tools: Available MCP server tools
+            
+        Returns:
+            Evaluation result as a dictionary
+            
+        Raises:
+            NotImplementedError: Must be implemented by concrete classes
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement evaluate_core()"
+        )

flock/core/component/routing_component.py

@@ -0,0 +1,74 @@
+# src/flock/core/component/routing_component_base.py
+"""Base class for routing components in the unified component system."""
+
+from abc import abstractmethod
+from typing import Any
+
+from flock.core.context.context import FlockContext
+
+from .agent_component_base import AgentComponent
+
+
+class RoutingComponent(AgentComponent):
+    """Base class for routing components.
+    
+    Routing components determine the next step in a workflow based on the
+    current agent's output. They implement workflow orchestration logic
+    and can enable complex multi-agent patterns.
+    
+    Each agent should have at most one routing component. If no routing
+    component is present, the workflow ends after this agent.
+    
+    Example implementations:
+    - ConditionalRoutingModule (rule-based routing)
+    - LLMRoutingModule (AI-powered routing decisions)
+    - DefaultRoutingModule (simple next-agent routing)
+    - ListGeneratorRoutingModule (dynamic agent creation)
+    """
+
+    @abstractmethod
+    async def determine_next_step(
+        self,
+        agent: Any,
+        result: dict[str, Any],
+        context: FlockContext | None = None,
+    ) -> str | Any | None:
+        """Determine the next agent in the workflow - MUST be implemented.
+        
+        This method analyzes the agent's result and determines what agent
+        should execute next. The result will be stored in agent.next_agent
+        for the orchestrator to process.
+        
+        Args:
+            agent: The agent that just completed execution
+            result: Result from the agent's evaluation (after post-processing)
+            context: Execution context with workflow state
+            
+        Returns:
+            String (agent name), FlockAgent instance, or None to end workflow
+            
+        Raises:
+            NotImplementedError: Must be implemented by concrete classes
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} must implement determine_next_step()"
+        )
+
+    async def evaluate_core(
+        self,
+        agent: Any,
+        inputs: dict[str, Any],
+        context: FlockContext | None = None,
+        tools: list[Any] | None = None,
+        mcp_tools: list[Any] | None = None,
+    ) -> dict[str, Any]:
+        """Routing components typically don't modify evaluation - pass through.
+        
+        Routing components usually don't implement core evaluation logic,
+        they focus on workflow decisions. This default implementation
+        passes inputs through unchanged.
+        
+        Override this if your routing component also needs to modify
+        the evaluation process.
+        """
+        return inputs

flock/core/component/utility_component.py

@@ -0,0 +1,69 @@
+# src/flock/core/component/utility_component_base.py
+"""Base class for utility components in the unified component system."""
+
+from typing import Any
+
+from flock.core.context.context import FlockContext
+
+# HandOffRequest removed - using agent.next_agent directly
+from .agent_component_base import AgentComponent
+
+
+class UtilityComponent(AgentComponent):
+    """Base class for utility/enhancement components.
+    
+    Utility components add cross-cutting concerns to agents without being
+    the primary evaluation or routing logic. They typically use the standard
+    lifecycle hooks to enhance agent behavior.
+    
+    These components focus on concerns like:
+    - Memory management  
+    - Output formatting
+    - Metrics collection
+    - Logging and tracing
+    - Input validation
+    - Error handling
+    - Caching
+    - Rate limiting
+    
+    Example implementations:
+    - MemoryUtilityModule (memory persistence)
+    - OutputUtilityModule (result formatting)  
+    - MetricsUtilityModule (performance tracking)
+    - AssertionUtilityModule (result validation)
+    """
+
+    async def evaluate_core(
+        self,
+        agent: Any,
+        inputs: dict[str, Any],
+        context: FlockContext | None = None,
+        tools: list[Any] | None = None,
+        mcp_tools: list[Any] | None = None,
+    ) -> dict[str, Any]:
+        """Utility components typically don't implement core evaluation.
+        
+        This default implementation passes inputs through unchanged.
+        Utility components usually enhance behavior through the standard
+        lifecycle hooks (on_pre_evaluate, on_post_evaluate, etc.).
+        
+        Override this only if your utility component needs to participate
+        in the core evaluation process.
+        """
+        return inputs
+
+    async def determine_next_step(
+        self,
+        agent: Any,
+        result: dict[str, Any],
+        context: FlockContext | None = None,
+    ) -> None:
+        """Utility components typically don't implement routing logic.
+        
+        This default implementation does nothing, as utility components
+        usually enhance behavior through other lifecycle hooks.
+        
+        Override this only if your utility component needs to influence
+        workflow routing decisions by setting agent.next_agent.
+        """
+        pass

flock/core/config/flock_agent_config.py

@@ -1,11 +1,58 @@
+"""Configuration settings for FlockAgent."""
 
+from typing import Literal
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class FlockAgentConfig(BaseModel):
     """FlockAgentConfig is a class that holds the configuration for a Flock agent.
+    
     It is used to store various settings and parameters that can be accessed throughout the agent's lifecycle.
     """
 
-    pass
+    write_to_file: bool = Field(
+        default=False,
+        description="Write the agent's output to a file.",
+    )
+    wait_for_input: bool = Field(
+        default=False,
+        description="Wait for user input after the agent's output is displayed.",
+    )
+
+    handoff_strategy: Literal["append", "override", "static", "map"] = Field(
+        default="static",
+        description="""Strategy for passing data to the next agent.
+        
+        example:
+        ReviewAgent.next_agent = SummaryAgent
+        ReviewAgent(output = "text:str, keywords:list[str], rating:int")
+        SummaryAgent(input = "text:str, title:str")
+
+        'append' means the difference in signature is appended to the next agent's input signature.
+        SummaryAgent(input = "text:str, title:str, keywords:list[str], rating:int")
+
+        'override' means the target agent's signature is getting overriden.
+        SummaryAgent(input = "text:str, keywords:list[str], rating:int")
+
+        'static' means the the target agent's signature is not changed at all.
+        If source agent has no output fields that match the target agent's input,
+        there will be no data passed to the next agent.
+        SummaryAgent(input = "text:str, title:str")
+        
+        'map' means the source agent's output is mapped to the target agent's input
+        based on 'handoff_map' configuration.
+
+        """,
+    )
+
+    handoff_map: dict[str, str] | None = Field(
+        default=None,
+        description="""Mapping of source agent output fields to target agent input fields.
+        
+        Used with 'handoff_strategy' = 'map'.
+        Example: {"text": "text", "keywords": "title"}
+        
+        If a field is not mapped, it will not be passed to the next agent.
+        """,
+    )

flock/core/evaluation/utils.py

@@ -17,7 +17,8 @@ from opik.evaluation import evaluate
 
 from flock.core.flock import Flock
 from flock.core.flock_agent import FlockAgent
-from flock.core.flock_evaluator import FlockEvaluator
+
+# Legacy FlockEvaluator import removed
 from flock.core.logging.logging import get_logger
 
 # Potentially import metrics libraries like rouge_score, nltk, sentence_transformers
@@ -58,7 +59,7 @@ def evaluate_with_opik(
 
         # Use the shared Flock instance instead of creating a new one
         result_flock = shared_flock.run(
-            start_agent=start_agent, input=agent_input, box_result=False
+            agent=start_agent, input=agent_input, box_result=False
         )
 
         # agent_output = result_flock.get(answer_mapping[key], "No answer found")

flock/core/execution/batch_executor.py

@@ -228,7 +228,7 @@ class BatchProcessor:
             try:
                 # Use the synchronous wrapper to avoid nested event-loop issues inside threads
                 result = self.flock.run(
-                    start_agent=start_agent,
+                    agent=start_agent,
                     input=full_input,
                     box_result=box_results,
                 )

flock/core/execution/evaluation_executor.py

@@ -43,7 +43,7 @@ from flock.core.logging.logging import get_logger
 if TYPE_CHECKING:
     from flock.core.flock import Flock
     from flock.core.flock_agent import FlockAgent
-    from flock.core.flock_evaluator import FlockEvaluator
+    # Legacy FlockEvaluator import removed
     # Conditional types
 
 
@@ -188,7 +188,7 @@ class EvaluationExecutor:
                 try:
                     # Run the agent/flock for this item
                     agent_output = await self.flock.run_async(
-                        start_agent=start_agent,  # Name or instance
+                        agent=start_agent,  # Name or instance
                         input=agent_inputs_with_static,
                         box_result=True,  # Use Box for easier access via dot notation
                         # context=... # Assuming isolated context for now

flock/core/execution/opik_executor.py

@@ -64,7 +64,7 @@ class OpikExecutor:
 
         # Evaluation task
         def evaluation_task(dataset_item):
-          flock_result = self.flock.run(start_agent=start_agent, input=dataset_item, box_result=False)
+          flock_result = self.flock.run(agent=start_agent, input=dataset_item, box_result=False)
 
           result = {
               "input": dataset_item.get("test"),