flock-core 0.5.0b28__py3-none-any.whl → 0.5.56b0__py3-none-any.whl

flock/core/component/agent_component_base.py

@@ -1,309 +0,0 @@
-# src/flock/core/component/agent_component_base.py
-"""Base classes for the unified Flock component system."""
-
-from abc import ABC
-from typing import Any, TypeVar
-
-from pydantic import BaseModel, Field, create_model
-
-from flock.core.context.context import FlockContext
-
-# HandOffRequest removed - using agent.next_agent directly
-
-T = TypeVar("T", bound="AgentComponentConfig")
-
-
-class AgentComponentConfig(BaseModel):
-    """Base configuration class for all Flock agent components.
-    
-    This unified config class replaces FlockModuleConfig, FlockEvaluatorConfig, 
-    and FlockRouterConfig, providing common functionality for all component types.
-    """
-
-    enabled: bool = Field(
-        default=True,
-        description="Whether this component is currently enabled"
-    )
-
-    model: str | None = Field(
-        default=None,
-        description="Model to use for this component (if applicable)"
-    )
-
-    @classmethod
-    def with_fields(cls: type[T], **field_definitions) -> type[T]:
-        """Create a new config class with additional fields.
-        
-        This allows dynamic config creation for components with custom configuration needs.
-        
-        Example:
-            CustomConfig = AgentComponentConfig.with_fields(
-                temperature=Field(default=0.7, description="LLM temperature"),
-                max_tokens=Field(default=1000, description="Max tokens to generate")
-            )
-        """
-        return create_model(
-            f"Dynamic{cls.__name__}",
-            __base__=cls,
-            **field_definitions
-        )
-
-
-class AgentComponent(BaseModel, ABC):
-    """Base class for all Flock agent components.
-    
-    This unified base class replaces the separate FlockModule, FlockEvaluator, 
-    and FlockRouter base classes. All agent extensions now inherit from this 
-    single base class and use the unified lifecycle hooks.
-    
-    Components can specialize by:
-    - EvaluationComponentBase: Implements evaluate_core() for agent intelligence
-    - RoutingComponentBase: Implements determine_next_step() for workflow routing  
-    - UtilityComponentBase: Uses standard lifecycle hooks for cross-cutting concerns
-    """
-
-    name: str = Field(
-        ...,
-        description="Unique identifier for this component"
-    )
-
-    config: AgentComponentConfig = Field(
-        default_factory=AgentComponentConfig,
-        description="Component configuration"
-    )
-
-    def __init__(self, **data):
-        super().__init__(**data)
-
-    # --- Standard Lifecycle Hooks ---
-    # These are called for ALL components during agent execution
-
-    async def on_initialize(
-        self,
-        agent: Any,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-    ) -> None:
-        """Called when the agent starts running.
-        
-        Use this for component initialization, resource setup, etc.
-        """
-        pass
-
-    async def on_pre_evaluate(
-        self,
-        agent: Any,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-    ) -> dict[str, Any]:
-        """Called before agent evaluation, can modify inputs.
-        
-        Args:
-            agent: The agent being executed
-            inputs: Current input data
-            context: Execution context
-            
-        Returns:
-            Modified input data (or original if no changes)
-        """
-        return inputs
-
-    async def on_post_evaluate(
-        self,
-        agent: Any,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-        result: dict[str, Any] | None = None,
-    ) -> dict[str, Any] | None:
-        """Called after agent evaluation, can modify results.
-        
-        Args:
-            agent: The agent that was executed  
-            inputs: Original input data
-            context: Execution context
-            result: Evaluation result
-            
-        Returns:
-            Modified result data (or original if no changes)
-        """
-        return result
-
-    async def on_terminate(
-        self,
-        agent: Any,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-        result: dict[str, Any] | None = None,
-    ) -> dict[str, Any] | None:
-        """Called when the agent finishes running.
-        
-        Use this for cleanup, final result processing, etc.
-        """
-        return result
-
-    async def on_error(
-        self,
-        agent: Any,
-        inputs: dict[str, Any],
-        context: FlockContext | None = None,
-        error: Exception | None = None,
-    ) -> None:
-        """Called when an error occurs during agent execution.
-        
-        Use this for error handling, logging, recovery, etc.
-        """
-        pass
-
-    # --- Specialized Hooks ---
-    # These are overridden by specialized component types
-
-    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 - override in EvaluationComponentBase.
-        
-        This is where the main "intelligence" of the agent happens.
-        Only one component per agent should implement this meaningfully.
-        
-        Args:
-            agent: The agent being executed
-            inputs: Input data for evaluation
-            context: Execution context  
-            tools: Available tools for the agent
-            mcp_tools: Available MCP tools
-            
-        Returns:
-            Evaluation result
-        """
-        # Default implementation is pass-through
-        return inputs
-
-    async def determine_next_step(
-        self,
-        agent: Any,
-        result: dict[str, Any],
-        context: FlockContext | None = None,
-    ) -> None:
-        """Determine the next step in the workflow - override in RoutingComponentBase.
-        
-        This is where routing decisions are made. Sets agent.next_agent directly.
-        
-        Args:
-            agent: The agent that just completed
-            result: Result from the agent's evaluation
-            context: Execution context
-            
-        Returns:
-            None - routing components set agent.next_agent directly
-        """
-        # Default implementation provides no routing
-        pass
-
-    # --- MCP Server Lifecycle Hooks ---
-    # For components that interact directly with MCP servers
-
-    async def on_pre_server_init(self, server: Any) -> None:
-        """Called before a server initializes."""
-        pass
-
-    async def on_post_server_init(self, server: Any) -> None:
-        """Called after a server initializes."""
-        pass
-
-    async def on_pre_server_terminate(self, server: Any) -> None:
-        """Called before a server terminates."""
-        pass
-
-    async def on_post_server_terminate(self, server: Any) -> None:
-        """Called after a server terminates."""
-        pass
-
-    async def on_server_error(self, server: Any, error: Exception) -> None:
-        """Called when a server errors."""
-        pass
-
-    async def on_connect(
-        self,
-        server: Any,
-        additional_params: dict[str, Any],
-    ) -> dict[str, Any]:
-        """Called before a connection is being established to a mcp server.
-
-        use `server` (type FlockMCPServer) to modify the core behavior of the server.
-        use `additional_params` to 'tack_on' additional configurations (for example additional headers for sse-clients.)
-
-        (For example: modify the server's config)
-        new_config = NewConfigObject(...)
-        server.config = new_config
-
-        Warning:
-            Be very careful when modifying a server's internal state.
-            If you just need to 'tack on' additional information (such as headers)
-            or want to temporarily override certain configurations (such as timeouts)
-            use `additional_params` instead if you can.
-
-        (Or pass additional values downstream:)
-        additional_params["headers"] = { "Authorization": "Bearer 123" }
-        additional_params["read_timeout_seconds"] = 100
-
-
-        Note:
-            `additional_params` resets between mcp_calls.
-            so there is not persistence between individual calls.
-            This choice has been made to allow developers to
-            dynamically switch configurations.
-            (This can be used, for example, to use a module to inject oauth headers for
-            individual users on a call-to-call basis. this also gives you direct control over
-            managing the headers yourself. For example, checking for lifetimes on JWT-Tokens.)
-
-        Note:
-            you can access `additional_params` when you are implementing your own subclasses of
-            FlockMCPClientManager and FlockMCPClient. (with self.additional_params.)
-
-        keys which are processed for `additional_params` in the flock core code are:
-        --- General ---
-
-        "refresh_client": bool -> defaults to False. Indicates whether or not to restart a connection on a call. (can be used when headers oder api-keys change to automatically switch to a new client.)
-        "read_timeout_seconds": float -> How long to wait for a connection to happen.
-
-        --- SSE ---
-
-        "override_headers": bool -> default False. If set to false, additional headers will be appended, if set to True, additional headers will override existing ones.
-        "headers": dict[str, Any] -> Additional Headers injected in sse-clients and ws-clients
-        "sse_read_timeout_seconds": float -> how long until a connection is being terminated for sse-clients.
-        "url": str -> which url the server listens on (allows switching between mcp-servers with modules.)
-
-        --- Stdio ---
-
-        "command": str -> Command to run for stdio-servers.
-        "args": list[str] -> additional paramters for stdio-servers.
-        "env": dict[str, Any] -> Environment-Variables for stdio-servers.
-        "encoding": str -> Encoding to use when talking to stdio-servers.
-        "encoding-error-handler": str -> Encoding error handler to use when talking to stdio-servers.
-
-        --- Websockets ---
-
-        "url": str -> Which url the server listens on (allows switching between mcp-servers with modules.)
-        """
-        pass
-
-    async def on_pre_mcp_call(
-        self,
-        server: Any,
-        arguments: Any | None = None,
-    ) -> None:
-        """Called before any MCP Calls."""
-        pass
-
-    async def on_post_mcp_call(
-        self,
-        server: Any,
-        result: Any | None = None,
-    ) -> None:
-        """Called after any MCP Calls."""
-        pass

flock/core/component/evaluation_component.py

@@ -1,62 +0,0 @@
-# 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
-    def set_model(self, model: str, temperature: float = 0.0, max_tokens: int = 4096) -> None:
-        """Set the model for the evaluation component."""
-        pass
-
-
-    @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

@@ -1,74 +0,0 @@
-# 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

@@ -1,69 +0,0 @@
-# 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,58 +0,0 @@
-"""Configuration settings for FlockAgent."""
-
-from typing import Literal
-
-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.
-    """
-
-    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/config/scheduled_agent_config.py

@@ -1,40 +0,0 @@
-
-
-
-from pydantic import Field
-
-from flock.core.config.flock_agent_config import FlockAgentConfig
-
-
-class ScheduledAgentConfig(FlockAgentConfig):
-    """Configuration specific to agents that run on a schedule."""
-    schedule_expression: str = Field(
-        ...,
-        description="Defines when the agent should run. "
-                    "Examples: 'every 60m', 'every 1h', 'daily at 02:00', '0 */2 * * *' (cron expression)"
-    )
-    enabled: bool = Field(
-        True,
-        description="Whether the scheduled agent is enabled. "
-                    "If False, the agent will not run even if the schedule expression is valid."
-    )
-    initial_run: bool = Field(
-        False,
-        description="If True, the agent will run immediately after being scheduled, "
-                    "regardless of the schedule expression."
-    )
-    max_runs: int = Field(
-        0,
-        description="Maximum number of times the agent can run. "
-                    "0 means unlimited runs. If set, the agent will stop running after reaching this limit."
-    )
-
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-        # Ensure schedule_expression is always set
-        if 'schedule_expression' not in kwargs:
-            raise ValueError("schedule_expression is required for ScheduledAgentConfig")
-
-        # Validate initial_run and max_runs
-        if self.initial_run and self.max_runs > 0:
-            raise ValueError("Cannot set initial_run to True if max_runs is greater than 0")