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

flock/core/agent/flock_agent_components.py

@@ -0,0 +1,104 @@
+"""Component management functionality for FlockAgent."""
+
+from typing import TYPE_CHECKING, Any
+
+from flock.core.component.evaluation_component import EvaluationComponent
+from flock.core.component.routing_component import RoutingComponent
+from flock.core.component.utility_component import UtilityComponent
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from flock.core.component.agent_component_base import AgentComponent
+    from flock.core.flock_agent import FlockAgent
+
+logger = get_logger("agent.components")
+
+
+class FlockAgentComponents:
+    """Helper class for managing unified components on FlockAgent."""
+
+    def __init__(self, agent: "FlockAgent"):
+        self.agent = agent
+
+    def add_component(self, component: "AgentComponent") -> None:
+        """Add a unified component to this agent."""
+        if not component.name:
+            logger.error("Component must have a name to be added.")
+            return
+
+        # Check if component with same name already exists
+        existing = self.get_component(component.name)
+        if existing:
+            logger.warning(f"Overwriting existing component: {component.name}")
+            self.agent.components.remove(existing)
+
+        self.agent.components.append(component)
+        logger.debug(f"Added component '{component.name}' to agent '{self.agent.name}'")
+
+    def remove_component(self, component_name: str) -> None:
+        """Remove a component from this agent."""
+        component = self.get_component(component_name)
+        if component:
+            self.agent.components.remove(component)
+            logger.debug(f"Removed component '{component_name}' from agent '{self.agent.name}'")
+        else:
+            logger.warning(f"Component '{component_name}' not found on agent '{self.agent.name}'")
+
+    def get_component(self, component_name: str) -> "AgentComponent | None":
+        """Get a component by name."""
+        for component in self.agent.components:
+            if component.name == component_name:
+                return component
+        return None
+
+    def get_enabled_components(self) -> list["AgentComponent"]:
+        """Get a list of currently enabled components attached to this agent."""
+        return [c for c in self.agent.components if c.config.enabled]
+
+    def get_components_by_type(self, component_type: type) -> list["AgentComponent"]:
+        """Get all components of a specific type."""
+        return [c for c in self.agent.components if isinstance(c, component_type)]
+
+    def get_evaluation_components(self) -> list[EvaluationComponent]:
+        """Get all evaluation components."""
+        return self.get_components_by_type(EvaluationComponent)
+
+    def get_routing_components(self) -> list[RoutingComponent]:
+        """Get all routing components."""
+        return self.get_components_by_type(RoutingComponent)
+
+    def get_utility_components(self) -> list[UtilityComponent]:
+        """Get all utility components."""
+        return self.get_components_by_type(UtilityComponent)
+
+    def get_primary_evaluator(self) -> EvaluationComponent | None:
+        """Get the primary evaluation component (first one found)."""
+        evaluators = self.get_evaluation_components()
+        return evaluators[0] if evaluators else None
+
+    def get_primary_router(self) -> RoutingComponent | None:
+        """Get the primary routing component (first one found)."""
+        routers = self.get_routing_components()
+        return routers[0] if routers else None
+
+    # Legacy compatibility methods (delegate to new unified approach)
+    def add_module(self, module: Any) -> None:
+        """DEPRECATED: Use add_component() instead."""
+        logger.warning("add_module is deprecated - use add_component() instead")
+        if hasattr(module, 'name'):
+            self.add_component(module)
+
+    def get_module(self, module_name: str) -> Any | None:
+        """DEPRECATED: Use get_component() instead."""
+        logger.warning("get_module is deprecated - use get_component() instead")
+        return self.get_component(module_name)
+
+    def get_evaluator(self) -> Any | None:
+        """DEPRECATED: Use get_primary_evaluator() instead."""
+        logger.warning("get_evaluator is deprecated - use get_primary_evaluator() instead")
+        return self.get_primary_evaluator()
+
+    def get_router(self) -> Any | None:
+        """DEPRECATED: Use get_primary_router() instead."""
+        logger.warning("get_router is deprecated - use get_primary_router() instead")
+        return self.get_primary_router()

flock/core/agent/flock_agent_execution.py

@@ -0,0 +1,101 @@
+# src/flock/core/agent/flock_agent_execution.py
+"""Execution management functionality for FlockAgent."""
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from opentelemetry import trace
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+
+logger = get_logger("agent.execution")
+tracer = trace.get_tracer(__name__)
+
+
+class FlockAgentExecution:
+    """Handles execution management for FlockAgent including run, run_async, and run_temporal."""
+
+    def __init__(self, agent: "FlockAgent"):
+        self.agent = agent
+
+    def run(self, inputs: dict[str, Any]) -> dict[str, Any]:
+        """Synchronous wrapper for run_async."""
+        try:
+            loop = asyncio.get_running_loop()
+        except (
+            RuntimeError
+        ):  # 'RuntimeError: There is no current event loop...'
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+        return loop.run_until_complete(self.run_async(inputs))
+
+    async def run_async(self, inputs: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronous execution logic with lifecycle hooks."""
+        with tracer.start_as_current_span("agent.run") as span:
+            span.set_attribute("agent.name", self.agent.name)
+            span.set_attribute("inputs", str(inputs))
+            try:
+                # Initialize lifecycle system if not already present
+                if not hasattr(self.agent, '_lifecycle'):
+                    from flock.core.agent.flock_agent_lifecycle import FlockAgentLifecycle
+                    self.agent._lifecycle = FlockAgentLifecycle(self.agent)
+                    
+                await self.agent._lifecycle.initialize(inputs)
+                result = await self.agent._lifecycle.evaluate(inputs)
+                await self.agent._lifecycle.terminate(inputs, result)
+                span.set_attribute("result", str(result))
+                logger.info("Agent run completed", agent=self.agent.name)
+                return result
+            except Exception as run_error:
+                logger.error(
+                    "Error running agent", agent=self.agent.name, error=str(run_error)
+                )
+                if "evaluate" not in str(
+                    run_error
+                ):  # Simple check, might need refinement
+                    await self.agent._lifecycle.on_error(run_error, inputs)
+                logger.error(
+                    f"Agent '{self.agent.name}' run failed: {run_error}",
+                    exc_info=True,
+                )
+                span.record_exception(run_error)
+                raise  # Re-raise after handling
+
+    async def run_temporal(self, inputs: dict[str, Any]) -> dict[str, Any]:
+        """Execute agent using Temporal workflow orchestration."""
+        with tracer.start_as_current_span("agent.run_temporal") as span:
+            span.set_attribute("agent.name", self.agent.name)
+            span.set_attribute("inputs", str(inputs))
+            try:
+                from temporalio.client import Client
+
+                from flock.workflow.agent_activities import (
+                    run_flock_agent_activity,
+                )
+                from flock.workflow.temporal_setup import run_activity
+
+                client = await Client.connect(
+                    "localhost:7233", namespace="default"
+                )
+                agent_data = self.agent._serialization.to_dict()
+                inputs_data = inputs
+
+                result = await run_activity(
+                    client,
+                    self.agent.name,
+                    run_flock_agent_activity,
+                    {"agent_data": agent_data, "inputs": inputs_data},
+                )
+                span.set_attribute("result", str(result))
+                logger.info("Temporal run successful", agent=self.agent.name)
+                return result
+            except Exception as temporal_error:
+                logger.error(
+                    "Error in Temporal workflow",
+                    agent=self.agent.name,
+                    error=str(temporal_error),
+                )
+                span.record_exception(temporal_error)
+                raise

flock/core/agent/flock_agent_integration.py

@@ -0,0 +1,206 @@
+# src/flock/core/agent/flock_agent_integration.py
+"""Tool and server integration functionality for FlockAgent."""
+
+from collections.abc import Callable
+from functools import wraps
+from inspect import Parameter, signature
+from typing import TYPE_CHECKING, Any, TypeVar, cast
+
+from flock.core.context.context import FlockContext
+from flock.core.logging.logging import get_logger
+from flock.core.mcp.flock_mcp_server import FlockMCPServer
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+
+logger = get_logger("agent.integration")
+
+R = TypeVar("R", bound=str)
+
+
+def adapt(prop_name: str, fn: Callable[..., R]) -> Callable[[FlockContext], R]:
+    """Coerce *fn* into the canonical ``(ctx: FlockContext) -> str`` form.
+
+    Acceptable signatures
+    ---------------------
+    1. ``() -> str``                           (no parameters)
+    2. ``(ctx: FlockContext) -> str``          (exactly one positional parameter)
+
+    Anything else raises ``TypeError``.
+
+    The wrapper also enforces at runtime that the result is ``str``.
+    """
+    if not callable(fn):
+        raise TypeError(f"{prop_name} must be a callable, got {type(fn).__name__}")
+
+    sig = signature(fn)
+    params = list(sig.parameters.values())
+
+    def _validate_result(res: object) -> R:
+        if not isinstance(res, str):
+            raise TypeError(
+                f"{prop_name} callable must return str, got {type(res).__name__}"
+            )
+        return cast(R, res)
+
+    # ── Case 1: () -> str ────────────────────────────────────────────────────
+    if len(params) == 0:
+
+        @wraps(fn)
+        def _wrapped(ctx: FlockContext) -> R:
+            return _validate_result(fn())
+
+        return _wrapped
+
+    # ── Case 2: (ctx) -> str ────────────────────────────────────────────────
+    if len(params) == 1:
+        p: Parameter = params[0]
+        valid_kind = p.kind in (
+            Parameter.POSITIONAL_ONLY,
+            Parameter.POSITIONAL_OR_KEYWORD,
+        )
+        valid_annotation = p.annotation in (Parameter.empty, FlockContext)
+        has_no_default = p.default is Parameter.empty
+
+        if valid_kind and valid_annotation and has_no_default:
+
+            @wraps(fn)
+            def _wrapped(ctx: FlockContext) -> R:
+                return _validate_result(fn(ctx))  # type: ignore[arg-type]
+
+            return _wrapped
+
+    # ── Anything else: reject ───────────────────────────────────────────────
+    raise TypeError(
+        f"{prop_name} callable must be () -> str or (ctx: FlockContext) -> str; "
+        f"got signature {sig}"
+    )
+
+class FlockAgentIntegration:
+    """Handles tool and server integration for FlockAgent including MCP servers and callable tools."""
+
+    def __init__(self, agent: "FlockAgent"):
+        self.agent = agent
+
+    def _resolve(self, raw: str | Callable[..., str], name: str, ctx: FlockContext | None) -> str | None:
+        if callable(raw):
+            raw = adapt(name, raw)(ctx or FlockContext())
+        return raw
+
+    def resolve_description(self, context: FlockContext | None = None) -> str | None:
+        """Resolve the agent's description, handling callable descriptions."""
+        return self._resolve(self.agent.description_spec, "description", context)
+
+    def resolve_input(self, context: FlockContext | None = None) -> str | None:
+        """Resolve the agent's input, handling callable inputs."""
+        return self._resolve(self.agent.input_spec, "input", context)
+
+    def resolve_output(self, context: FlockContext | None = None) -> str | None:
+        """Resolve the agent's output, handling callable outputs."""
+        return self._resolve(self.agent.output_spec, "output", context)
+
+    def resolve_next_agent(self, context: FlockContext | None = None) -> str | None:
+        """Resolve the next agent, handling callable next agents."""
+        return self._resolve(self.agent.next_agent_spec, "next_agent", context)
+
+    async def get_mcp_tools(self) -> list[Any]:
+        """Get tools from registered MCP servers."""
+        mcp_tools = []
+        if self.agent.servers:
+            from flock.core.registry import get_registry
+
+            registry = get_registry()  # Get the registry
+            for server in self.agent.servers:
+                registered_server: FlockMCPServer | None = None
+                server_tools = []
+                if isinstance(server, FlockMCPServer):
+                    # check if registered
+                    server_name = server.config.name
+                    registered_server = registry.get_server(
+                        server_name
+                    )
+                else:
+                    # servers must be registered.
+                    registered_server = registry.get_server(
+                        name=server
+                    )
+                if registered_server:
+                    server_tools = await registered_server.get_tools(
+                        agent_id=self.agent.agent_id,
+                        run_id=self.agent.context.run_id,
+                    )
+                else:
+                    logger.warning(
+                        f"No Server with name '{server.config.name if isinstance(server, FlockMCPServer) else server}' registered! Skipping."
+                    )
+                mcp_tools = mcp_tools + server_tools
+        return mcp_tools
+
+    async def execute_with_middleware(
+        self,
+        current_inputs: dict[str, Any],
+        registered_tools: list[Any],
+        mcp_tools: list[Any]
+    ) -> dict[str, Any]:
+        """Execute evaluator with optional DI middleware pipeline."""
+        container = None
+        if self.agent.context is not None:
+            container = self.agent.context.get_variable("di.container")
+
+        # If a MiddlewarePipeline is registered in DI, wrap the evaluator
+        result: dict[str, Any] | None = None
+
+        if container is not None:
+            try:
+                from wd.di.middleware import (
+                    MiddlewarePipeline,
+                )
+
+                pipeline: MiddlewarePipeline | None = None
+                try:
+                    pipeline = container.get_service(MiddlewarePipeline)
+                except Exception:
+                    pipeline = None
+
+                if pipeline is not None:
+                    # Build execution chain where the evaluator is the terminal handler
+
+                    async def _final_handler():
+                        return await self.agent.evaluator.evaluate_core(
+                            self.agent, current_inputs, self.agent.context, registered_tools, mcp_tools
+                        )
+
+                    idx = 0
+
+                    async def _invoke_next():
+                        nonlocal idx
+
+                        if idx < len(pipeline._middleware):
+                            mw = pipeline._middleware[idx]
+                            idx += 1
+                            return await mw(self.agent.context, _invoke_next)  # type: ignore[arg-type]
+                        return await _final_handler()
+
+                    # Execute pipeline
+                    result = await _invoke_next()
+                else:
+                    # No pipeline registered, direct evaluation
+                    result = await self.agent.evaluator.evaluate_core(
+                        self.agent, current_inputs, self.agent.context, registered_tools, mcp_tools
+                    )
+            except ImportError:
+                # wd.di not installed – fall back
+                result = await self.agent.evaluator.evaluate_core(
+                    self.agent, current_inputs, self.agent.context, registered_tools, mcp_tools
+                )
+        else:
+            # No DI container – standard execution
+            result = await self.agent.evaluator.evaluate_core(
+                self.agent,
+                current_inputs,
+                self.agent.context,
+                registered_tools,
+                mcp_tools,
+            )
+
+        return result

flock/core/agent/flock_agent_lifecycle.py

@@ -0,0 +1,177 @@
+# src/flock/core/agent/flock_agent_lifecycle.py
+"""Lifecycle management functionality for FlockAgent."""
+
+from typing import TYPE_CHECKING, Any
+
+from opentelemetry import trace
+
+from flock.core.logging.logging import get_logger
+
+if TYPE_CHECKING:
+    from flock.core.flock_agent import FlockAgent
+
+logger = get_logger("agent.lifecycle")
+tracer = trace.get_tracer(__name__)
+
+
+class FlockAgentLifecycle:
+    """Handles lifecycle management for FlockAgent including initialization, evaluation, and termination."""
+
+    def __init__(self, agent: "FlockAgent"):
+        self.agent = agent
+
+    async def initialize(self, inputs: dict[str, Any]) -> None:
+        """Initialize agent and run module initializers."""
+        logger.debug(f"Initializing agent '{self.agent.name}'")
+        with tracer.start_as_current_span("agent.initialize") as span:
+            span.set_attribute("agent.name", self.agent.name)
+            span.set_attribute("inputs", str(inputs))
+            logger.info(
+                f"agent.initialize",
+                agent=self.agent.name,
+            )
+            try:
+                for component in self.agent.get_enabled_components():
+                    await component.on_initialize(self.agent, inputs, self.agent.context)
+            except Exception as component_error:
+                logger.error(
+                    "Error during initialize",
+                    agent=self.agent.name,
+                    error=str(component_error),
+                )
+                span.record_exception(component_error)
+
+    async def terminate(
+        self, inputs: dict[str, Any], result: dict[str, Any]
+    ) -> None:
+        """Terminate agent and run module terminators."""
+        logger.debug(f"Terminating agent '{self.agent.name}'")
+        with tracer.start_as_current_span("agent.terminate") as span:
+            span.set_attribute("agent.name", self.agent.name)
+            span.set_attribute("inputs", str(inputs))
+            span.set_attribute("result", str(result))
+            logger.info(
+                f"agent.terminate",
+                agent=self.agent.name,
+            )
+            try:
+                current_result = result
+                for component in self.agent.get_enabled_components():
+                    tmp_result = await component.on_terminate(
+                        self.agent, inputs, self.agent.context, current_result
+                    )
+                    # If the component returns a result, use it
+                    if tmp_result:
+                        current_result = tmp_result
+
+                if self.agent.config.write_to_file:
+                    self.agent._serialization._save_output(self.agent.name, current_result)
+
+                if self.agent.config.wait_for_input:
+                    # simple input prompt
+                    input("Press Enter to continue...")
+
+            except Exception as component_error:
+                logger.error(
+                    "Error during terminate",
+                    agent=self.agent.name,
+                    error=str(component_error),
+                )
+                span.record_exception(component_error)
+
+    async def on_error(self, error: Exception, inputs: dict[str, Any]) -> None:
+        """Handle errors and run component error handlers."""
+        logger.error(f"Error occurred in agent '{self.agent.name}': {error}")
+        with tracer.start_as_current_span("agent.on_error") as span:
+            span.set_attribute("agent.name", self.agent.name)
+            span.set_attribute("inputs", str(inputs))
+            try:
+                for component in self.agent.get_enabled_components():
+                    await component.on_error(self.agent, inputs, self.agent.context, error)
+            except Exception as component_error:
+                logger.error(
+                    "Error during on_error",
+                    agent=self.agent.name,
+                    error=str(component_error),
+                )
+                span.record_exception(component_error)
+
+    async def evaluate(self, inputs: dict[str, Any]) -> dict[str, Any]:
+        """Core evaluation logic, calling the assigned evaluator and components."""
+        if not self.agent.evaluator:
+            raise RuntimeError(
+                f"Agent '{self.agent.name}' has no evaluator assigned."
+            )
+        with tracer.start_as_current_span("agent.evaluate") as span:
+            span.set_attribute("agent.name", self.agent.name)
+            span.set_attribute("inputs", str(inputs))
+            logger.info(
+                f"agent.evaluate",
+                agent=self.agent.name,
+            )
+
+            logger.debug(f"Evaluating agent '{self.agent.name}'")
+            current_inputs = inputs
+
+            # Pre-evaluate hooks
+            for component in self.agent.get_enabled_components():
+                current_inputs = await component.on_pre_evaluate(
+                    self.agent, current_inputs, self.agent.context
+                )
+
+            # Actual evaluation
+            try:
+                # Get tools and MCP tools through integration handler
+                registered_tools = []
+                if self.agent.tools:
+                    registered_tools = self.agent.tools
+
+                # Retrieve available mcp_tools if the evaluator needs them
+                mcp_tools = []
+                if self.agent.servers:
+                    mcp_tools = await self.agent._integration.get_mcp_tools()
+
+                # --------------------------------------------------
+                # Use evaluator component's evaluate_core method
+                # --------------------------------------------------
+                result = await self.agent.evaluator.evaluate_core(
+                    self.agent, current_inputs, self.agent.context, registered_tools, mcp_tools
+                )
+
+            except Exception as eval_error:
+                logger.error(
+                    "Error during evaluate",
+                    agent=self.agent.name,
+                    error=str(eval_error),
+                )
+                span.record_exception(eval_error)
+                await self.on_error(
+                    eval_error, current_inputs
+                )  # Call error hook
+                raise  # Re-raise the exception
+
+            # Post-evaluate hooks
+            current_result = result
+            for component in self.agent.get_enabled_components():
+                tmp_result = await component.on_post_evaluate(
+                    self.agent,
+                    current_inputs,
+                    self.agent.context,
+                    current_result,
+                )
+                # If the component returns a result, use it
+                if tmp_result:
+                    current_result = tmp_result
+
+            # Handle routing logic
+            router = self.agent.router
+            if router:
+                try:
+                    self.agent.next_agent = await router.determine_next_step(
+                        self.agent, current_result, self.agent.context
+                    )
+                except Exception as e:
+                    logger.error(f"Error in routing: {e}")
+
+            logger.debug(f"Evaluation completed for agent '{self.agent.name}'")
+            return current_result