flock-core 0.5.0b1__py3-none-any.whl → 0.5.0b3__py3-none-any.whl

flock/core/agent/flock_agent_integration.py

@@ -1,17 +1,80 @@
 # src/flock/core/agent/flock_agent_integration.py
 """Tool and server integration functionality for FlockAgent."""
 
-from typing import TYPE_CHECKING, Any
+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 FlockMCPServerBase
+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."""
@@ -19,30 +82,26 @@ class FlockAgentIntegration:
     def __init__(self, agent: "FlockAgent"):
         self.agent = agent
 
-    def resolve_callables(self, context: FlockContext | None = None) -> None:
-        """Resolves callable fields (description, input, output) using context."""
-        if callable(self.agent.description):
-            self.agent.description = self.agent.description(
-                context
-            )  # Pass context if needed by callable
-        if callable(self.agent.input):
-            self.agent.input = self.agent.input(context)
-        if callable(self.agent.output):
-            self.agent.output = self.agent.output(context)
-
-    def resolve_description(self, context: FlockContext | None = None) -> str:
-        if callable(self.agent.description):
-            try:
-                # Attempt to call without context first.
-                return self.agent.description(context)
-            except Exception as e:
-                logger.error(
-                    f"Error resolving callable description for agent '{self.agent.name}': {e}"
-                )
-                return None
-        elif isinstance(self.agent.description, str):
-            return self.agent.description
-        return None
+    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."""
@@ -52,9 +111,9 @@ class FlockAgentIntegration:
 
             registry = get_registry()  # Get the registry
             for server in self.agent.servers:
-                registered_server: FlockMCPServerBase | None = None
+                registered_server: FlockMCPServer | None = None
                 server_tools = []
-                if isinstance(server, FlockMCPServerBase):
+                if isinstance(server, FlockMCPServer):
                     # check if registered
                     server_name = server.config.name
                     registered_server = registry.get_server(
@@ -72,7 +131,7 @@ class FlockAgentIntegration:
                     )
                 else:
                     logger.warning(
-                        f"No Server with name '{server.config.name if isinstance(server, FlockMCPServerBase) else server}' registered! Skipping."
+                        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

flock/core/agent/flock_agent_serialization.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Any, TypeVar
 
 # Legacy component imports removed
 from flock.core.logging.logging import get_logger
-from flock.core.mcp.flock_mcp_server import FlockMCPServerBase
+from flock.core.mcp.flock_mcp_server import FlockMCPServer
 from flock.core.serialization.json_encoder import FlockJSONEncoder
 from flock.core.serialization.serialization_utils import (
     deserialize_component,
@@ -68,20 +68,20 @@ class FlockAgentSerialization:
         is_output_callable = False
         is_next_agent_callable = False
         # if self.agent.description is a callable, exclude it
-        if callable(self.agent.description):
+        if callable(self.agent.description_spec):
             is_description_callable = True
-            exclude.append("description")
+            exclude.append("description_spec")
         # if self.agent.input is a callable, exclude it
-        if callable(self.agent.input):
+        if callable(self.agent.input_spec):
             is_input_callable = True
-            exclude.append("input")
+            exclude.append("input_spec")
         # if self.agent.output is a callable, exclude it
-        if callable(self.agent.output):
+        if callable(self.agent.output_spec):
             is_output_callable = True
-            exclude.append("output")
-        if callable(self.agent.next_agent):
+            exclude.append("output_spec")
+        if callable(self.agent.next_agent_spec):
             is_next_agent_callable = True
-            exclude.append("next_agent")
+            exclude.append("next_agent_spec")
 
         logger.debug(f"Serializing agent '{self.agent.name}' to dict.")
         # Use Pydantic's dump, exclude manually handled fields and runtime context
@@ -122,7 +122,7 @@ class FlockAgentSerialization:
             )
             serialized_servers = []
             for server in self.agent.servers:
-                if isinstance(server, FlockMCPServerBase):
+                if isinstance(server, FlockMCPServer):
                     serialized_servers.append(server.config.name)
                 else:
                     # Write it down as a list of server names.
@@ -167,7 +167,7 @@ class FlockAgentSerialization:
                 )
 
         if is_description_callable:
-            path_str = registry.get_callable_path_string(self.agent.description)
+            path_str = registry.get_callable_path_string(self.agent.description_spec)
             if path_str:
                 func_name = path_str.split(".")[-1]
                 data["description_callable"] = func_name
@@ -176,11 +176,11 @@ class FlockAgentSerialization:
                 )
             else:
                 logger.warning(
-                    f"Could not get path string for description {self.agent.description} in agent '{self.agent.name}'. Skipping."
+                    f"Could not get path string for description {self.agent.description_spec} in agent '{self.agent.name}'. Skipping."
                 )
 
         if is_input_callable:
-            path_str = registry.get_callable_path_string(self.agent.input)
+            path_str = registry.get_callable_path_string(self.agent.input_spec)
             if path_str:
                 func_name = path_str.split(".")[-1]
                 data["input_callable"] = func_name
@@ -189,11 +189,11 @@ class FlockAgentSerialization:
                 )
             else:
                 logger.warning(
-                    f"Could not get path string for input {self.agent.input} in agent '{self.agent.name}'. Skipping."
+                    f"Could not get path string for input {self.agent.input_spec} in agent '{self.agent.name}'. Skipping."
                 )
 
         if is_output_callable:
-            path_str = registry.get_callable_path_string(self.agent.output)
+            path_str = registry.get_callable_path_string(self.agent.output_spec)
             if path_str:
                 func_name = path_str.split(".")[-1]
                 data["output_callable"] = func_name
@@ -202,20 +202,20 @@ class FlockAgentSerialization:
                 )
             else:
                 logger.warning(
-                    f"Could not get path string for output {self.agent.output} in agent '{self.agent.name}'. Skipping."
+                    f"Could not get path string for output {self.agent.output_spec} in agent '{self.agent.name}'. Skipping."
                 )
 
         if is_next_agent_callable:
-            path_str = registry.get_callable_path_string(self.agent.next_agent)
+            path_str = registry.get_callable_path_string(self.agent.next_agent_spec)
             if path_str:
                 func_name = path_str.split(".")[-1]
-                data["next_agent"] = func_name
+                data["next_agent_callable"] = func_name
                 logger.debug(
                     f"Added next_agent '{func_name}' (from path '{path_str}') to agent '{self.agent.name}'"
                 )
             else:
                 logger.warning(
-                    f"Could not get path string for next_agent {self.agent.next_agent} in agent '{self.agent.name}'. Skipping."
+                    f"Could not get path string for next_agent {self.agent.next_agent_spec} in agent '{self.agent.name}'. Skipping."
                 )
 
 
@@ -245,6 +245,7 @@ class FlockAgentSerialization:
             "description_callable",
             "input_callable",
             "output_callable",
+            "next_agent_callable",
         ]
 
         for key in callable_keys:
@@ -322,7 +323,7 @@ class FlockAgentSerialization:
                 if isinstance(server_name, str):
                     # Case 1 (default behavior): A server name is passed.
                     agent.servers.append(server_name)
-                elif isinstance(server_name, FlockMCPServerBase):
+                elif isinstance(server_name, FlockMCPServer):
                     # Case 2 (highly unlikely): If someone somehow manages to pass
                     # an instance of a server during the deserialization step (however that might be achieved)
                     # check the registry, if the server is already registered, if not, register it
@@ -373,6 +374,8 @@ class FlockAgentSerialization:
         resolve_and_assign("description", "description_callable")
         resolve_and_assign("input", "input_callable")
         resolve_and_assign("output", "output_callable")
+        resolve_and_assign("next_agent", "next_agent_callable")
+        # --- Finalize ---
 
         logger.info(f"Successfully deserialized agent '{agent.name}'.")
         return agent

flock/core/api/endpoints.py

@@ -246,7 +246,7 @@ def create_api_router() -> APIRouter:
         """List all available agents in the currently loaded Flock."""
         logger.debug("API request: list agents")
         agents_list = [
-            {"name": agent.name, "description": agent.resolved_description or agent.name}
+            agent.to_dict()
             for agent in flock_instance.agents.values()
         ]
         return {"agents": agents_list}

flock/core/component/__init__.py

@@ -2,14 +2,14 @@
 """Unified component system for Flock agents."""
 
 from .agent_component_base import AgentComponent, AgentComponentConfig
-from .evaluation_component_base import EvaluationComponentBase
-from .routing_component_base import RoutingComponentBase
-from .utility_component_base import UtilityComponentBase
+from .evaluation_component import EvaluationComponent
+from .routing_component import RoutingComponent
+from .utility_component import UtilityComponent
 
 __all__ = [
     "AgentComponent",
-    "AgentComponentConfig", 
-    "EvaluationComponentBase",
-    "RoutingComponentBase",
-    "UtilityComponentBase",
+    "AgentComponentConfig",
+    "EvaluationComponent",
+    "RoutingComponent",
+    "UtilityComponent",
 ]

flock/core/component/{evaluation_component_base.py → evaluation_component.py}

@@ -9,7 +9,7 @@ from flock.core.context.context import FlockContext
 from .agent_component_base import AgentComponent
 
 
-class EvaluationComponentBase(AgentComponent):
+class EvaluationComponent(AgentComponent):
     """Base class for evaluation components.
     
     Evaluation components implement the core intelligence/logic of an agent.
@@ -23,7 +23,7 @@ class EvaluationComponentBase(AgentComponent):
     - ScriptEvaluationComponent (Python script-based)
     - LLMEvaluationComponent (direct LLM API)
     """
-    
+
     @abstractmethod
     async def evaluate_core(
         self,

flock/core/component/{routing_component_base.py → routing_component.py}

@@ -6,11 +6,10 @@ from typing import Any
 
 from flock.core.context.context import FlockContext
 
-
 from .agent_component_base import AgentComponent
 
 
-class RoutingComponentBase(AgentComponent):
+class RoutingComponent(AgentComponent):
     """Base class for routing components.
     
     Routing components determine the next step in a workflow based on the
@@ -26,7 +25,7 @@ class RoutingComponentBase(AgentComponent):
     - DefaultRoutingModule (simple next-agent routing)
     - ListGeneratorRoutingModule (dynamic agent creation)
     """
-    
+
     @abstractmethod
     async def determine_next_step(
         self,
@@ -54,7 +53,7 @@ class RoutingComponentBase(AgentComponent):
         raise NotImplementedError(
             f"{self.__class__.__name__} must implement determine_next_step()"
         )
-        
+
     async def evaluate_core(
         self,
         agent: Any,

flock/core/component/{utility_component_base.py → utility_component.py}

@@ -4,12 +4,12 @@
 from typing import Any
 
 from flock.core.context.context import FlockContext
-# HandOffRequest removed - using agent.next_agent directly
 
+# HandOffRequest removed - using agent.next_agent directly
 from .agent_component_base import AgentComponent
 
 
-class UtilityComponentBase(AgentComponent):
+class UtilityComponent(AgentComponent):
     """Base class for utility/enhancement components.
     
     Utility components add cross-cutting concerns to agents without being
@@ -32,7 +32,7 @@ class UtilityComponentBase(AgentComponent):
     - MetricsUtilityModule (performance tracking)
     - AssertionUtilityModule (result validation)
     """
-    
+
     async def evaluate_core(
         self,
         agent: Any,

flock/core/flock.py

@@ -17,7 +17,7 @@ from typing import (
 from box import Box
 from temporalio import workflow
 
-from flock.core.mcp.flock_mcp_server import FlockMCPServerBase
+from flock.core.mcp.flock_mcp_server import FlockMCPServer
 
 with workflow.unsafe.imports_passed_through():
     from datasets import Dataset  # type: ignore
@@ -125,7 +125,7 @@ class Flock(BaseModel, Serializable):
     _start_input: dict = {}  # For potential pre-configuration
 
     # Internal server storage - not part of the Pydantic model for direct serialization
-    _servers: dict[str, FlockMCPServerBase]
+    _servers: dict[str, FlockMCPServer]
 
     # Note: _mgr is now handled by the server manager helper
 
@@ -207,7 +207,7 @@ class Flock(BaseModel, Serializable):
         enable_temporal: bool = False,
         enable_opik: bool = False,
         agents: list[FlockAgent] | None = None,
-        servers: list[FlockMCPServerBase] | None = None,
+        servers: list[FlockMCPServer] | None = None,
         temporal_config: TemporalWorkflowConfig | None = None,
         temporal_start_in_process_worker: bool = True,
         **kwargs,
@@ -296,7 +296,7 @@ class Flock(BaseModel, Serializable):
 
 
 
-    def add_server(self, server: FlockMCPServerBase) -> FlockMCPServerBase:
+    def add_server(self, server: FlockMCPServer) -> FlockMCPServer:
         """Adds a server instance to this Flock configuration and registry."""
         return self._server_manager.add_server(server)
 
@@ -349,7 +349,7 @@ class Flock(BaseModel, Serializable):
         return self._agents
 
     @property
-    def servers(self) -> dict[str, FlockMCPServerBase]:
+    def servers(self) -> dict[str, FlockMCPServer]:
         """Returns the dictionary of servers managed by this Flock instance."""
         return self._server_manager.servers
 
@@ -361,7 +361,7 @@ class Flock(BaseModel, Serializable):
         run_id: str = "",
         box_result: bool = True,
         agents: list[FlockAgent] | None = None,
-        servers: list[FlockMCPServerBase] | None = None,
+        servers: list[FlockMCPServer] | None = None,
         memo: dict[str, Any] | None = None,
     ) -> Box | dict:
         """Synchronous execution wrapper."""
@@ -384,7 +384,7 @@ class Flock(BaseModel, Serializable):
         run_id: str = "",
         box_result: bool = True,
         agents: list[FlockAgent] | None = None,
-        servers: list[FlockMCPServerBase] | None = None,
+        servers: list[FlockMCPServer] | None = None,
         memo: dict[str, Any] | None = None,
     ) -> Box | dict:
         """Entry point for running an agent system asynchronously."""

flock/core/flock_agent.py

@@ -12,14 +12,14 @@ from flock.core.agent.flock_agent_execution import FlockAgentExecution
 from flock.core.agent.flock_agent_integration import FlockAgentIntegration
 from flock.core.agent.flock_agent_serialization import FlockAgentSerialization
 from flock.core.component.agent_component_base import AgentComponent
-from flock.core.component.evaluation_component_base import (
-    EvaluationComponentBase,
+from flock.core.component.evaluation_component import (
+    EvaluationComponent,
 )
-from flock.core.component.routing_component_base import RoutingComponentBase
+from flock.core.component.routing_component import RoutingComponent
 from flock.core.config.flock_agent_config import FlockAgentConfig
 from flock.core.context.context import FlockContext
 from flock.core.logging.logging import get_logger
-from flock.core.mcp.flock_mcp_server import FlockMCPServerBase
+from flock.core.mcp.flock_mcp_server import FlockMCPServer
 
 # Mixins and Serialization components
 from flock.core.mixin.dspy_integration import DSPyIntegrationMixin
@@ -30,14 +30,8 @@ logger = get_logger("agent.unified")
 
 T = TypeVar("T", bound="FlockAgent")
 
-SignatureType = (
-    str
-    | Callable[..., str]
-    | type[BaseModel]
-    | Callable[..., type[BaseModel]]
-    | None
-)
 
+DynamicStr = str | Callable[[FlockContext], str]
 
 class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
     """Unified FlockAgent using the new component architecture.
@@ -63,23 +57,29 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         None,
         description="The model identifier to use (e.g., 'openai/gpt-4o'). If None, uses Flock's default.",
     )
-    description: str | Callable[..., str] | None = Field(
-        "",
+    description_spec: DynamicStr | None = Field(
+        default="",
+        alias="description",
+        validation_alias="description",
         description="A human-readable description or a callable returning one.",
     )
-    input: SignatureType = Field(
-        None,
+    input_spec: DynamicStr | None = Field(
+        default="",
+        alias="input",
+        validation_alias="input",
         description="Signature for input keys. Supports type hints (:) and descriptions (|).",
     )
-    output: SignatureType = Field(
-        None,
+    output_spec: DynamicStr | None = Field(
+        default="",
+        alias="output",
+        validation_alias="output",
         description="Signature for output keys. Supports type hints (:) and descriptions (|).",
     )
     tools: list[Callable[..., Any]] | None = Field(
         default=None,
         description="List of callable tools the agent can use. These must be registered.",
     )
-    servers: list[str | FlockMCPServerBase] | None = Field(
+    servers: list[str | FlockMCPServer] | None = Field(
         default=None,
         description="List of MCP Servers the agent can use to enhance its capabilities.",
     )
@@ -91,9 +91,10 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
     )
 
     # --- EXPLICIT WORKFLOW STATE ---
-    next_agent: str | Callable[..., str] | None = Field(
+    next_agent_spec: DynamicStr | None = Field(
         default=None,
-       # exclude=True,  # Runtime state, don't serialize
+        alias="next_agent",
+        validation_alias="next_agent",
         description="Next agent in workflow - set by user or routing components.",
     )
 
@@ -118,14 +119,14 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         self,
         name: str,
         model: str | None = None,
-        description: str | Callable[..., str] | None = "",
-        input: SignatureType = None,
-        output: SignatureType = None,
+        description: DynamicStr | None = None,
+        input: DynamicStr | None = None,
+        output: DynamicStr | None = None,
         tools: list[Callable[..., Any]] | None = None,
-        servers: list[str | FlockMCPServerBase] | None = None,
+        servers: list[str | FlockMCPServer] | None = None,
         components: list[AgentComponent] | None = None,
         config: FlockAgentConfig | None = None,
-        next_agent: str | Callable[..., str] | None = None,
+        next_agent: DynamicStr | None = None,
         temporal_activity_config: TemporalActivityConfig | None = None,
     ):
         """Initialize the unified FlockAgent with components and configuration."""
@@ -155,12 +156,12 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
     # These provide familiar access patterns while using the unified model
 
     @property
-    def evaluator(self) -> EvaluationComponentBase | None:
+    def evaluator(self) -> EvaluationComponent | None:
         """Get the primary evaluation component for this agent."""
         return self._components.get_primary_evaluator()
 
     @property
-    def router(self) -> RoutingComponentBase | None:
+    def router(self) -> RoutingComponent | None:
         """Get the primary routing component for this agent."""
         return self._components.get_primary_router()
 
@@ -270,22 +271,51 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
                 f"Agent '{self.name}' has no evaluator to set model for."
             )
 
-    def resolve_callables(self, context: FlockContext | None = None) -> None:
-        """Resolves callable fields (description, input, output) using context."""
-        self.context = context or self.context
-        return self._integration.resolve_callables(self.context)
-
     @property
-    def resolved_description(self) -> str | None:
-        """Returns the resolved agent description.
-        If the description is a callable, it attempts to call it.
-        Returns None if the description is None or a callable that fails.
-        """
+    def description(self) -> str | None:
+        """Returns the resolved agent description."""
         return self._integration.resolve_description(self.context)
 
+    @property
+    def input(self) -> str | None:
+        """Returns the resolved agent input."""
+        return self._integration.resolve_input(self.context)
+
+    @property
+    def output(self) -> str | None:
+        """Returns the resolved agent output."""
+        return self._integration.resolve_output(self.context)
+
+    @property
+    def next_agent(self) -> str | None:
+        """Returns the resolved agent next agent."""
+        return self._integration.resolve_next_agent(self.context)
+
+    @description.setter
+    def description(self, value: DynamicStr) -> None:
+        self.description_spec = value
+
+    @input.setter
+    def input(self, value: DynamicStr) -> None:
+        self.input_spec = value
+
+    @output.setter
+    def output(self, value: DynamicStr) -> None:
+        self.output_spec = value
+
+    @next_agent.setter
+    def next_agent(self, value: DynamicStr) -> None:
+        self.next_agent_spec = value
+
     def _save_output(self, agent_name: str, result: dict[str, Any]) -> None:
         """Save output to file if configured (delegated to serialization)."""
         return self._serialization._save_output(agent_name, result)
 
     # --- Pydantic v2 Configuration ---
-    model_config = {"arbitrary_types_allowed": True}
+    model_config = {
+        "arbitrary_types_allowed": True,
+        "populate_by_name": True,
+        # "json_encoders": {
+        #     Callable: lambda f: f"{f.__module__}.{f.__qualname__}",
+        # },
+    }