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

flock/cli/execute_flock.py

@@ -142,7 +142,7 @@ def execute_flock(flock: Flock):
 
         # Run the Flock
         result = flock.run(
-            start_agent=start_agent_name,
+            agent=start_agent_name,
             input=input_data,
         )
 

flock/cli/manage_agents.py

@@ -105,7 +105,7 @@ def _list_agents(flock: Flock):
         model = agent.model or flock.model or "Default"
 
         # Format description (truncate if too long)
-        description = agent.resolved_description
+        description = agent.description
         if description and len(description) > 30:
             description = description[:27] + "..."
         elif not description:
@@ -165,11 +165,11 @@ def _view_agent_details(agent: FlockAgent):
 
     basic_info.add_row("Name", agent.name)
     basic_info.add_row("Model", str(agent.model or "Default"))
-    basic_info.add_row("Description", agent.resolved_description if agent.resolved_description else "N/A")
+    basic_info.add_row("Description", agent.description if agent.description else "N/A")
     basic_info.add_row("Input", str(agent.input))
     basic_info.add_row("Output", str(agent.output))
-    basic_info.add_row("Write to File", str(agent.write_to_file))
-    basic_info.add_row("Wait for input", str(agent.wait_for_input))
+    basic_info.add_row("Write to File", str(agent.config.write_to_file))
+    basic_info.add_row("Wait for input", str(agent.config.wait_for_input))
 
     console.print(Panel(basic_info, title="Basic Information"))
 
@@ -180,7 +180,7 @@ def _view_agent_details(agent: FlockAgent):
     console.print(Panel(evaluator_info, title="Evaluator"))
 
     # Router info
-    router_info = f"Type: {type(agent.handoff_router).__name__ if agent.handoff_router else 'None'}"
+    router_info = f"Type: {type(agent.router).__name__ if agent.router else 'None'}"
     console.print(Panel(router_info, title="Router"))
 
     # Tools
@@ -339,7 +339,7 @@ def _edit_agent(flock: Flock):
     console.print(f"\n[bold underline]Details for Agent: {agent.name}[/]")
     basic_info = Table(show_header=False, box=Box.ROUNDED, padding=(0, 2))
     basic_info.add_row("Name", agent.name)
-    description = agent.resolved_description
+    description = agent.description
     basic_info.add_row("Description", description if description else "N/A")
     basic_info.add_row("Model", agent.model or "Flock Default")
     basic_info.add_row("Input Signature", str(agent.input))

flock/components/__init__.py

@@ -0,0 +1,30 @@
+# src/flock/components/__init__.py
+"""Unified component implementations for Flock agents."""
+
+# Evaluation components
+from .evaluation.declarative_evaluation_component import (
+    DeclarativeEvaluationComponent,
+)
+
+# Routing components
+from .routing.conditional_routing_component import ConditionalRoutingComponent
+from .routing.default_routing_component import DefaultRoutingComponent
+from .routing.llm_routing_component import LLMRoutingComponent
+
+# Utility components
+from .utility.memory_utility_component import MemoryUtilityComponent
+from .utility.metrics_utility_component import MetricsUtilityComponent
+from .utility.output_utility_component import OutputUtilityComponent
+
+__all__ = [
+    # Routing
+    "ConditionalRoutingComponent",
+    # Evaluation
+    "DeclarativeEvaluationComponent",
+    "DefaultRoutingComponent",
+    "LLMRoutingComponent",
+    # Utility
+    "MemoryUtilityComponent",
+    "MetricsUtilityComponent",
+    "OutputUtilityComponent",
+]

flock/components/evaluation/__init__.py

@@ -0,0 +1,9 @@
+# src/flock/components/evaluation/__init__.py
+"""Evaluation components for the unified component system."""
+
+from .declarative_evaluation_component import DeclarativeEvaluationComponent, DeclarativeEvaluationConfig
+
+__all__ = [
+    "DeclarativeEvaluationComponent",
+    "DeclarativeEvaluationConfig",
+]

flock/components/evaluation/declarative_evaluation_component.py

@@ -0,0 +1,222 @@
+# src/flock/components/evaluation/declarative_evaluation_component.py
+"""DeclarativeEvaluationComponent - DSPy-based evaluation using the unified component system."""
+
+from collections.abc import Generator
+from typing import Any
+
+from temporalio import workflow
+
+with workflow.unsafe.imports_passed_through():
+    import dspy
+
+from pydantic import Field, PrivateAttr
+
+from flock.core.component.agent_component_base import AgentComponentConfig
+from flock.core.component.evaluation_component import EvaluationComponent
+from flock.core.context.context import FlockContext
+from flock.core.logging.logging import get_logger
+from flock.core.mixin.dspy_integration import DSPyIntegrationMixin
+from flock.core.mixin.prompt_parser import PromptParserMixin
+from flock.core.registry import flock_component
+
+logger = get_logger("components.evaluation.declarative")
+
+
+class DeclarativeEvaluationConfig(AgentComponentConfig):
+    """Configuration for the DeclarativeEvaluationComponent."""
+
+    override_evaluator_type: str | None = None
+    model: str | None = "openai/gpt-4o"
+    use_cache: bool = True
+    temperature: float = 0.0
+    max_tokens: int = 4096
+    max_retries: int = 3
+    max_tool_calls: int = 10
+    stream: bool = Field(
+        default=False,
+        description="Enable streaming output from the underlying DSPy program.",
+    )
+    include_thought_process: bool = Field(
+        default=False,
+        description="Include the thought process in the output.",
+    )
+    include_reasoning: bool = Field(
+        default=False,
+        description="Include the reasoning in the output.",
+    )
+    kwargs: dict[str, Any] = Field(default_factory=dict)
+
+
+@flock_component(config_class=DeclarativeEvaluationConfig)
+class DeclarativeEvaluationComponent(
+    EvaluationComponent, DSPyIntegrationMixin, PromptParserMixin
+):
+    """Evaluation component that uses DSPy for generation.
+    
+    This component provides the core intelligence for agents using DSPy's
+    declarative programming model. It handles LLM interactions, tool usage,
+    and prompt management through DSPy's framework.
+    """
+
+    config: DeclarativeEvaluationConfig = Field(
+        default_factory=DeclarativeEvaluationConfig,
+        description="Evaluation configuration",
+    )
+
+    _cost: float = PrivateAttr(default=0.0)
+    _lm_history: list = PrivateAttr(default_factory=list)
+
+    def __init__(self, **data):
+        super().__init__(**data)
+
+    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 using DSPy - migrated from DeclarativeEvaluator."""
+        logger.debug(f"Starting declarative evaluation for component '{self.name}'")
+
+        # Setup DSPy context with LM (directly from original implementation)
+        with dspy.context(
+            lm=dspy.LM(
+                model=self.config.model or agent.model,
+                cache=self.config.use_cache,
+                temperature=self.config.temperature,
+                max_tokens=self.config.max_tokens,
+                num_retries=self.config.max_retries,
+            )
+        ):
+            try:
+                from rich.console import Console
+                console = Console()
+
+                # Create DSPy signature from agent definition
+                _dspy_signature = self.create_dspy_signature_class(
+                    agent.name,
+                    agent.description,
+                    f"{agent.input} -> {agent.output}",
+                )
+
+                # Get output field names for streaming
+                output_field_names = list(_dspy_signature.output_fields.keys())
+                if not output_field_names:
+                    logger.warning(
+                        f"DSPy signature for agent '{agent.name}' has no defined output fields. Streaming might not produce text."
+                    )
+
+                # Select appropriate DSPy task
+                agent_task = self._select_task(
+                    _dspy_signature,
+                    override_evaluator_type=self.config.override_evaluator_type,
+                    tools=tools or [],
+                    max_tool_calls=self.config.max_tool_calls,
+                    mcp_tools=mcp_tools or [],
+                    kwargs=self.config.kwargs,
+                )
+
+            except Exception as setup_error:
+                logger.error(
+                    f"Error setting up DSPy task for agent '{agent.name}': {setup_error}",
+                    exc_info=True,
+                )
+                raise RuntimeError(
+                    f"DSPy task setup failed: {setup_error}"
+                ) from setup_error
+
+            # Execute with streaming or non-streaming
+            if self.config.stream:
+                return await self._execute_streaming(agent_task, inputs, agent, console)
+            else:
+                return await self._execute_standard(agent_task, inputs, agent)
+
+    async def _execute_streaming(self, agent_task, inputs: dict[str, Any], agent: Any, console) -> dict[str, Any]:
+        """Execute DSPy program in streaming mode (from original implementation)."""
+        logger.info(f"Evaluating agent '{agent.name}' with async streaming.")
+
+        if not callable(agent_task):
+            logger.error("agent_task is not callable, cannot stream.")
+            raise TypeError("DSPy task could not be created or is not callable.")
+
+        streaming_task = dspy.streamify(agent_task, is_async_program=True)
+        stream_generator: Generator = streaming_task(**inputs)
+        delta_content = ""
+
+        console.print("\n")
+        async for chunk in stream_generator:
+            if (
+                hasattr(chunk, "choices")
+                and chunk.choices
+                and hasattr(chunk.choices[0], "delta")
+                and chunk.choices[0].delta
+                and hasattr(chunk.choices[0].delta, "content")
+            ):
+                delta_content = chunk.choices[0].delta.content
+
+            if delta_content:
+                console.print(delta_content, end="")
+
+            result_dict, cost, lm_history = self._process_result(chunk, inputs)
+            self._cost = cost
+            self._lm_history = lm_history
+
+        console.print("\n")
+        result_dict = self.filter_reasoning(
+                    result_dict, self.config.include_reasoning
+                )
+        return self.filter_thought_process(
+            result_dict, self.config.include_thought_process
+        )
+
+    async def _execute_standard(self, agent_task, inputs: dict[str, Any], agent: Any) -> dict[str, Any]:
+        """Execute DSPy program in standard mode (from original implementation)."""
+        logger.info(f"Evaluating agent '{agent.name}' without streaming.")
+
+        try:
+            # Ensure the call is awaited if the underlying task is async
+            result_obj = await agent_task.acall(**inputs)
+            result_dict, cost, lm_history = self._process_result(result_obj, inputs)
+            self._cost = cost
+            self._lm_history = lm_history
+            result_dict = self.filter_reasoning(
+                    result_dict, self.config.include_reasoning
+                )
+            return self.filter_thought_process(
+                result_dict, self.config.include_thought_process
+            )
+        except Exception as e:
+            logger.error(
+                f"Error during non-streaming evaluation for agent '{agent.name}': {e}",
+                exc_info=True,
+            )
+            raise RuntimeError(f"Evaluation failed: {e}") from e
+
+    def filter_thought_process(
+        self, result_dict: dict[str, Any], include_thought_process: bool
+    ) -> dict[str, Any]:
+        """Filter out thought process from the result dictionary (from original implementation)."""
+        if include_thought_process:
+            return result_dict
+        else:
+            return {
+                k: v
+                for k, v in result_dict.items()
+                if not (k.startswith("reasoning") or k.startswith("trajectory"))
+            }
+
+    def filter_reasoning(
+        self, result_dict: dict[str, Any], include_reasoning: bool
+    ) -> dict[str, Any]:
+        """Filter out reasoning from the result dictionary."""
+        if include_reasoning:
+            return result_dict
+        else:
+            return {
+                k: v
+                for k, v in result_dict.items()
+                if not (k.startswith("reasoning"))
+            }
+

flock/components/routing/__init__.py

@@ -0,0 +1,15 @@
+# src/flock/components/routing/__init__.py
+"""Routing components for the Flock framework."""
+
+from .conditional_routing_component import ConditionalRoutingComponent, ConditionalRoutingConfig
+from .default_routing_component import DefaultRoutingComponent, DefaultRoutingConfig
+from .llm_routing_component import LLMRoutingComponent, LLMRoutingConfig
+
+__all__ = [
+    "ConditionalRoutingComponent",
+    "ConditionalRoutingConfig",
+    "DefaultRoutingComponent", 
+    "DefaultRoutingConfig",
+    "LLMRoutingComponent",
+    "LLMRoutingConfig",
+]

flock/{routers/conditional/conditional_router.py → components/routing/conditional_routing_component.py}

@@ -1,26 +1,28 @@
-# src/flock/routers/conditional/conditional_router.py
+# src/flock/components/routing/conditional_routing_component.py
+"""Conditional routing component implementation for the unified component architecture."""
 
 import re
 from collections.abc import Callable
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 from pydantic import Field, model_validator
 
+from flock.core.component.agent_component_base import AgentComponentConfig
+from flock.core.component.routing_component import RoutingComponent
 from flock.core.context.context import FlockContext
-from flock.core.flock_agent import FlockAgent
-from flock.core.flock_registry import flock_component, get_registry
-from flock.core.flock_router import (
-    FlockRouter,
-    FlockRouterConfig,
-    HandOffRequest,
-)
+
+# HandOffRequest removed - using agent.next_agent directly
 from flock.core.logging.logging import get_logger
+from flock.core.registry import flock_component, get_registry
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
 
-logger = get_logger("router.conditional")
+logger = get_logger("components.routing.conditional")
 
 
-class ConditionalRouterConfig(FlockRouterConfig):
-    """Configuration for the ConditionalRouter."""
+class ConditionalRoutingConfig(AgentComponentConfig):
+    """Configuration for the ConditionalRoutingComponent."""
 
     condition_context_key: str = Field(
         default="flock.condition",
@@ -115,10 +117,6 @@ class ConditionalRouterConfig(FlockRouterConfig):
         default="flock.assertion_feedback",  # Useful if paired with AssertionCheckerModule
         description="Optional context key containing feedback message to potentially include when retrying.",
     )
-    feedback_on_failure: str | None = Field(
-        default=None,
-        description="Default feedback message to use when condition evaluation fails.",
-    )
     retry_count_context_key_prefix: str = Field(
         default="flock.conditional_retry_count_",
         description="Internal prefix for context key storing retry attempts per agent.",
@@ -126,7 +124,7 @@ class ConditionalRouterConfig(FlockRouterConfig):
 
     # --- Validator to ensure only one condition type is set ---
     @model_validator(mode="after")
-    def check_exclusive_condition(self) -> "ConditionalRouterConfig":
+    def check_exclusive_condition(self) -> "ConditionalRoutingConfig":
         conditions_set = [
             self.condition_callable is not None,
             self.expected_string is not None
@@ -141,27 +139,37 @@ class ConditionalRouterConfig(FlockRouterConfig):
         ]
         if sum(conditions_set) > 1:
             raise ValueError(
-                "Only one type of condition (callable, string/length, number, list size, type, boolean, exists) can be configured per ConditionalRouter."
+                "Only one type of condition (callable, string/length, number, list size, type, boolean, exists) can be configured per ConditionalRoutingComponent."
             )
         if sum(conditions_set) == 0:
             raise ValueError(
-                "At least one condition type must be configured for ConditionalRouter."
+                "At least one condition type must be configured for ConditionalRoutingComponent."
             )
         return self
 
 
-@flock_component(config_class=ConditionalRouterConfig)
-class ConditionalRouter(FlockRouter):
+@flock_component(config_class=ConditionalRoutingConfig)
+class ConditionalRoutingComponent(RoutingComponent):
     """Routes workflow based on evaluating a condition against a value in the FlockContext.
+    
     Supports various built-in checks (string, number, list, type, bool, existence)
     or a custom callable. Can optionally retry the current agent on failure.
     """
 
-    name: str = "conditional_router"
-    config: ConditionalRouterConfig = Field(
-        default_factory=ConditionalRouterConfig
+    config: ConditionalRoutingConfig = Field(
+        default_factory=ConditionalRoutingConfig
     )
 
+    def __init__(
+        self,
+        name: str = "conditional_router",
+        config: ConditionalRoutingConfig | None = None,
+        **data,
+    ):
+        if config is None:
+            config = ConditionalRoutingConfig()
+        super().__init__(name=name, config=config, **data)
+
     def _evaluate_condition(self, value: Any) -> tuple[bool, str | None]:
         """Evaluates the condition based on the router's configuration.
 
@@ -172,7 +180,7 @@ class ConditionalRouter(FlockRouter):
         """
         cfg = self.config
         condition_passed = False
-        feedback = cfg.feedback_on_failure  # Default feedback
+        feedback = None  # Default feedback
         condition_type = "unknown"
 
         try:
@@ -377,12 +385,17 @@ class ConditionalRouter(FlockRouter):
                 feedback,
             )  # Treat evaluation errors as condition failure
 
-    async def route(
+    async def determine_next_step(
         self,
-        current_agent: FlockAgent,
+        agent: "FlockAgent",
         result: dict[str, Any],
-        context: FlockContext,
-    ) -> HandOffRequest:
+        context: FlockContext | None = None,
+    ) -> None:
+        """Determine next step based on evaluating a condition against context value."""
+        if not context:
+            logger.warning("No context provided for conditional routing")
+            return
+
         cfg = self.config
         condition_value = context.get_variable(cfg.condition_context_key, None)
         feedback_value = context.get_variable(cfg.feedback_context_key, None)
@@ -399,17 +412,17 @@ class ConditionalRouter(FlockRouter):
         if condition_passed:
             # --- Success Path ---
             logger.info(
-                f"Condition PASSED for agent '{current_agent.name}'. Routing to success path."
+                f"Condition PASSED for agent '{agent.name}'. Routing to success path."
             )
             # Reset retry count if applicable
             if cfg.retry_on_failure:
                 retry_key = (
-                    f"{cfg.retry_count_context_key_prefix}{current_agent.name}"
+                    f"{cfg.retry_count_context_key_prefix}{agent.name}"
                 )
                 if retry_key in context.state:
                     del context.state[retry_key]
                     logger.debug(
-                        f"Reset retry count for agent '{current_agent.name}'."
+                        f"Reset retry count for agent '{agent.name}'."
                     )
 
             # Clear feedback from context on success
@@ -422,20 +435,21 @@ class ConditionalRouter(FlockRouter):
                     f"Cleared feedback key '{cfg.feedback_context_key}' on success."
                 )
 
-            next_agent = cfg.success_agent or ""  # Stop chain if None
+            next_agent = cfg.success_agent or None  # Stop chain if None
             logger.debug(f"Success route target: '{next_agent}'")
-            return HandOffRequest(next_agent=next_agent)
+
+            agent.next_agent = next_agent  # Set directly on agent
 
         else:
             # --- Failure Path ---
             logger.warning(
-                f"Condition FAILED for agent '{current_agent.name}'. Reason: {feedback_msg}"
+                f"Condition FAILED for agent '{agent.name}'. Reason: {feedback_msg}"
             )
 
             if cfg.retry_on_failure:
                 # --- Retry Logic ---
                 retry_key = (
-                    f"{cfg.retry_count_context_key_prefix}{current_agent.name}"
+                    f"{cfg.retry_count_context_key_prefix}{agent.name}"
                 )
                 retry_count = context.get_variable(retry_key, 0)
 
@@ -443,44 +457,38 @@ class ConditionalRouter(FlockRouter):
                     next_retry_count = retry_count + 1
                     context.set_variable(retry_key, next_retry_count)
                     logger.info(
-                        f"Routing back to agent '{current_agent.name}' for retry #{next_retry_count}/{cfg.max_retries}."
+                        f"Routing back to agent '{agent.name}' for retry #{next_retry_count}/{cfg.max_retries}."
                     )
 
                     # Add specific feedback to context if retry is enabled
                     if cfg.feedback_context_key:
                         context.set_variable(
                             cfg.feedback_context_key,
-                            feedback_msg or cfg.feedback_on_failure,
+                            feedback_msg or "Condition failed",
                         )
                         logger.debug(
-                            f"Set feedback key '{cfg.feedback_context_key}': {feedback_msg or cfg.feedback_on_failure}"
+                            f"Set feedback key '{cfg.feedback_context_key}': {feedback_msg or 'Condition failed'}"
                         )
 
-                    return HandOffRequest(
-                        next_agent=current_agent.name,  # Route back to self
-                        output_to_input_merge_strategy="add",  # Make feedback available
-                    )
+                    agent.next_agent = agent.name  # Route back to self
                 else:
                     # --- Max Retries Exceeded ---
                     logger.error(
-                        f"Max retries ({cfg.max_retries}) exceeded for agent '{current_agent.name}'."
+                        f"Max retries ({cfg.max_retries}) exceeded for agent '{agent.name}'."
                     )
                     if retry_key in context.state:
                         del context.state[retry_key]  # Reset count
-                    # Clear feedback before final failure route? Optional.
-                    # if cfg.feedback_context_key in context.state: del context.state[cfg.feedback_context_key]
-                    next_agent = cfg.failure_agent or ""
+                    next_agent = cfg.failure_agent or None
                     logger.debug(
                         f"Failure route target (after retries): '{next_agent}'"
                     )
-                    return HandOffRequest(next_agent=next_agent)
+
+                    agent.next_agent = next_agent
             else:
                 # --- No Retry Logic ---
                 next_agent = (
-                    cfg.failure_agent or ""
+                    cfg.failure_agent or None
                 )  # Use failure agent or stop
                 logger.debug(f"Failure route target (no retry): '{next_agent}'")
-                # Optionally add feedback even if not retrying?
-                # if cfg.feedback_context_key:
-                #     context.set_variable(cfg.feedback_context_key, feedback_msg or cfg.feedback_on_failure)
-                return HandOffRequest(next_agent=next_agent)
+
+                agent.next_agent = next_agent

flock/components/routing/default_routing_component.py

@@ -0,0 +1,103 @@
+# src/flock/components/routing/default_routing_component.py
+"""Default routing component implementation for the unified component architecture."""
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from pydantic import Field
+
+from flock.core.component.agent_component_base import AgentComponentConfig
+from flock.core.component.routing_component import RoutingComponent
+from flock.core.context.context import FlockContext
+from flock.core.logging.logging import get_logger
+from flock.core.registry import flock_component
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+
+logger = get_logger("components.routing.default")
+
+
+class DefaultRoutingConfig(AgentComponentConfig):
+    """Configuration for the default routing component."""
+
+    next_agent: str | Callable[..., str] = Field(
+        default="", description="Next agent to hand off to"
+    )
+
+
+@flock_component(config_class=DefaultRoutingConfig)
+class DefaultRoutingComponent(RoutingComponent):
+    """Default routing component implementation.
+
+    This router simply uses the configured hand_off property to determine the next agent.
+    It does not perform any dynamic routing based on agent results.
+
+    Configuration can be:
+    - A string: Simple agent name to route to
+    - A callable: Function that takes (context, result) and returns agent name
+    """
+
+    config: DefaultRoutingConfig = Field(
+        default_factory=DefaultRoutingConfig,
+        description="Default routing configuration",
+    )
+
+    def __init__(
+        self,
+        name: str = "default_router",
+        config: DefaultRoutingConfig | None = None,
+        **data,
+    ):
+        """Initialize the DefaultRoutingComponent.
+
+        Args:
+            name: The name of the routing component
+            config: The routing configuration
+        """
+        if config is None:
+            config = DefaultRoutingConfig()
+        super().__init__(name=name, config=config, **data)
+
+    async def determine_next_step(
+        self,
+        agent: "FlockAgent",
+        result: dict[str, Any],
+        context: FlockContext | None = None,
+    ) -> str | None:
+        """Determine the next agent to hand off to based on configuration.
+
+        Args:
+            agent: The agent that just completed execution
+            result: The output from the current agent
+            context: The global execution context
+
+        Returns:
+            String agent name to route to, or None to end workflow
+        """
+        handoff = self.config.next_agent
+
+        # If empty string, end the workflow
+        if handoff == "":
+            logger.debug("No handoff configured, ending workflow")
+            return None
+
+        # If callable, invoke it with context and result
+        if callable(handoff):
+            logger.debug("Invoking handoff callable")
+            try:
+                handoff = handoff(context, result)
+            except Exception as e:
+                logger.error("Error invoking handoff callable: %s", e)
+                return None
+
+        # Validate it's a string
+        if not isinstance(handoff, str):
+            logger.error(
+                "Invalid handoff type: %s. Expected str or callable returning str",
+                type(handoff),
+            )
+            return None
+
+        logger.debug("Routing to agent: %s", handoff)
+        return handoff