flock-core 0.4.0b43__py3-none-any.whl → 0.4.0b45__py3-none-any.whl

flock/core/flock.py

@@ -20,23 +20,28 @@ from box import Box
 from temporalio import workflow
 
 with workflow.unsafe.imports_passed_through():
-    from datasets import Dataset
+    from datasets import Dataset  # type: ignore
 
+    # Assuming run_local_workflow is correctly placed and importable
     from flock.core.execution.local_executor import (
         run_local_workflow,
     )
 from opentelemetry import trace
 from opentelemetry.baggage import get_baggage, set_baggage
-from pandas import DataFrame
+from pandas import DataFrame  # type: ignore
 from pydantic import BaseModel, Field
 
 # Flock core components & utilities
 from flock.config import DEFAULT_MODEL, TELEMETRY
-from flock.core.api.custom_endpoint import FlockEndpoint
+from flock.core.api.custom_endpoint import (
+    FlockEndpoint,  # Keep for type hinting custom_endpoints
+)
 from flock.core.context.context import FlockContext
 from flock.core.context.context_manager import initialize_context
+
+# Assuming run_temporal_workflow is correctly placed and importable
 from flock.core.execution.temporal_executor import run_temporal_workflow
-from flock.core.flock_evaluator import FlockEvaluator
+from flock.core.flock_evaluator import FlockEvaluator  # For type hint
 from flock.core.logging.logging import LOGGERS, get_logger, get_module_loggers
 from flock.core.serialization.serializable import Serializable
 from flock.core.util.cli_helper import init_console
@@ -52,14 +57,14 @@ if TYPE_CHECKING:
 from flock.core.flock_registry import get_registry
 
 try:
-    import pandas as pd
+    import pandas as pd  # type: ignore
 
     PANDAS_AVAILABLE = True
 except ImportError:
-    pd = None
+    pd = None # type: ignore
     PANDAS_AVAILABLE = False
 
-logger = get_logger("flock")
+logger = get_logger("flock.api")
 TELEMETRY.setup_tracing()  # Setup OpenTelemetry
 tracer = trace.get_tracer(__name__)
 FlockRegistry = get_registry()  # Get the registry instance
@@ -67,10 +72,6 @@ FlockRegistry = get_registry()  # Get the registry instance
 # Define TypeVar for generic class methods like from_dict
 T = TypeVar("T", bound="Flock")
 
-# from rich.traceback import install
-
-# install(show_locals=True)
-
 
 class Flock(BaseModel, Serializable):
     """Orchestrator for managing and executing agent systems.
@@ -115,6 +116,7 @@ class Flock(BaseModel, Serializable):
         description="If True (default) and enable_temporal=True, start a temporary in-process worker for development/testing convenience. Set to False when using dedicated workers.",
     )
     # Internal agent storage - not part of the Pydantic model for direct serialization
+    # Marked with underscore to indicate it's managed internally and accessed via property
     _agents: dict[str, FlockAgent]
     _start_agent_name: str | None = None  # For potential pre-configuration
     _start_input: dict = {}  # Instance attribute overwritten in __init__; kept for typing clarity
@@ -122,6 +124,7 @@ class Flock(BaseModel, Serializable):
     # Pydantic v2 model config
     model_config = {
         "arbitrary_types_allowed": True,
+        # Assuming FlockRegistry type might not be serializable by default
         "ignored_types": (type(FlockRegistry),),
     }
 
@@ -148,7 +151,7 @@ class Flock(BaseModel, Serializable):
             model=model,
             description=description,
             enable_temporal=enable_temporal,
-            enable_logging=enable_logging,
+            enable_logging=bool(enable_logging), # Store as bool, specific loggers handled by _configure
             show_flock_banner=show_flock_banner,
             temporal_config=temporal_config,
             temporal_start_in_process_worker=temporal_start_in_process_worker,
@@ -161,11 +164,13 @@ class Flock(BaseModel, Serializable):
         self._start_input = {}
 
         # Set up logging based on the enable_logging flag
-        self._configure_logging(enable_logging)  # Use instance attribute
+        self._configure_logging(enable_logging) # Pass original value to _configure_logging
 
         # Register passed agents
         if agents:
-            from flock.core.flock_agent import FlockAgent as ConcreteFlockAgent
+            from flock.core.flock_agent import (
+                FlockAgent as ConcreteFlockAgent,  # Local import
+            )
 
             for agent in agents:
                 if isinstance(agent, ConcreteFlockAgent):
@@ -176,7 +181,8 @@ class Flock(BaseModel, Serializable):
                     )
 
         # Initialize console if needed for banner
-        init_console(clear_screen=True, show_banner=self.show_flock_banner)
+        if self.show_flock_banner: # Check instance attribute
+            init_console(clear_screen=True, show_banner=self.show_flock_banner)
 
         # Set Temporal debug environment variable
         self._set_temporal_debug_flag()
@@ -191,33 +197,37 @@ class Flock(BaseModel, Serializable):
             enable_temporal=self.enable_temporal,
         )
 
-    def _configure_logging(self, enable_logging: bool | list[str]):
+    def _configure_logging(self, enable_logging_config: bool | list[str]):
         """Configure logging levels based on the enable_logging flag."""
         is_enabled_globally = False
-        enabled_loggers = []
+        specific_loggers_to_enable = []
 
-        if isinstance(enable_logging, bool):
-            is_enabled_globally = enable_logging
-        elif isinstance(enable_logging, list):
-            is_enabled_globally = bool(enable_logging)
-            enabled_loggers = enable_logging
+        if isinstance(enable_logging_config, bool):
+            is_enabled_globally = enable_logging_config
+        elif isinstance(enable_logging_config, list):
+            is_enabled_globally = bool(enable_logging_config) # True if list is not empty
+            specific_loggers_to_enable = enable_logging_config
 
         # Configure core loggers
-        for log_name in LOGGERS:
+        for log_name in LOGGERS: # Assuming LOGGERS is a list of known logger names
             log_instance = get_logger(log_name)
-            if is_enabled_globally or log_name in enabled_loggers:
+            if is_enabled_globally or log_name in specific_loggers_to_enable:
                 log_instance.enable_logging = True
             else:
                 log_instance.enable_logging = False
 
         # Configure module loggers (existing ones)
-        module_loggers = get_module_loggers()
+        module_loggers = get_module_loggers() # Assuming this returns list of FlockLogger instances
         for mod_log in module_loggers:
-            if is_enabled_globally or mod_log.name in enabled_loggers:
+            if is_enabled_globally or mod_log.name in specific_loggers_to_enable:
                 mod_log.enable_logging = True
             else:
                 mod_log.enable_logging = False
 
+        # Update the instance's Pydantic field
+        self.enable_logging = is_enabled_globally or bool(specific_loggers_to_enable)
+
+
     def _set_temporal_debug_flag(self):
         """Set or remove LOCAL_DEBUG env var based on enable_temporal."""
         if not self.enable_temporal:
@@ -242,7 +252,9 @@ class Flock(BaseModel, Serializable):
 
     def add_agent(self, agent: FlockAgent) -> FlockAgent:
         """Adds an agent instance to this Flock configuration and registry."""
-        from flock.core.flock_agent import FlockAgent as ConcreteFlockAgent
+        from flock.core.flock_agent import (
+            FlockAgent as ConcreteFlockAgent,  # Local import
+        )
 
         if not isinstance(agent, ConcreteFlockAgent):
             raise TypeError("Provided object is not a FlockAgent instance.")
@@ -250,7 +262,13 @@ class Flock(BaseModel, Serializable):
             raise ValueError("Agent must have a name.")
 
         if agent.name in self._agents:
-            raise ValueError("Agent with this name already exists.")
+            # Allow re-adding the same instance, but raise error for different instance with same name
+            if self._agents[agent.name] is not agent:
+                raise ValueError(f"Agent with name '{agent.name}' already exists with a different instance.")
+            else:
+                logger.debug(f"Agent '{agent.name}' is already added. Skipping.")
+                return agent # Return existing agent
+
         self._agents[agent.name] = agent
         FlockRegistry.register_agent(agent)  # Register globally
 
@@ -286,7 +304,6 @@ class Flock(BaseModel, Serializable):
         """Entry point for running an agent system synchronously."""
         try:
             loop = asyncio.get_running_loop()
-            # If loop exists, check if it's closed
             if loop.is_closed():
                 raise RuntimeError("Event loop is closed")
         except RuntimeError:  # No running loop
@@ -307,6 +324,12 @@ class Flock(BaseModel, Serializable):
             )
             return result
         else:
+            # If called from an already running loop (e.g. Jupyter, FastAPI endpoint)
+            # Create a future and run it to completion. This is tricky and
+            # ideally, one should use `await self.run_async` directly in async contexts.
+            # This simple run_until_complete on a future might block the existing loop.
+            # For truly non-blocking execution in an existing loop, one might need
+            # to schedule the coroutine differently or advise users to use `await`.
             future = asyncio.ensure_future(
                 self.run_async(
                     start_agent=start_agent,
@@ -319,6 +342,7 @@ class Flock(BaseModel, Serializable):
             )
             return loop.run_until_complete(future)
 
+
     async def run_async(
         self,
         start_agent: FlockAgent | str | None = None,
@@ -330,8 +354,9 @@ class Flock(BaseModel, Serializable):
         memo: dict[str, Any] | None = None,
     ) -> Box | dict:
         """Entry point for running an agent system asynchronously."""
-        # Import here to allow forward reference resolution
-        from flock.core.flock_agent import FlockAgent as ConcreteFlockAgent
+        from flock.core.flock_agent import (
+            FlockAgent as ConcreteFlockAgent,  # Local import
+        )
 
         with tracer.start_as_current_span("flock.run_async") as span:
             # Add passed agents first
@@ -348,11 +373,11 @@ class Flock(BaseModel, Serializable):
             start_agent_name: str | None = None
             if isinstance(start_agent, ConcreteFlockAgent):
                 start_agent_name = start_agent.name
-                if start_agent_name not in self._agents:
+                if start_agent_name not in self._agents: # Add if not already present
                     self.add_agent(start_agent)
             elif isinstance(start_agent, str):
                 start_agent_name = start_agent
-            else:
+            else: # start_agent is None
                 start_agent_name = self._start_agent_name
 
             # Default to first agent if only one exists and none specified
@@ -360,7 +385,7 @@ class Flock(BaseModel, Serializable):
                 start_agent_name = list(self._agents.keys())[0]
             elif not start_agent_name:
                 raise ValueError(
-                    "No start_agent specified and multiple/no agents exist."
+                    "No start_agent specified and multiple/no agents exist in the Flock instance."
                 )
 
             # Check if start_agent is in agents
@@ -390,41 +415,31 @@ class Flock(BaseModel, Serializable):
 
             try:
                 resolved_start_agent = self._agents.get(start_agent_name)
-                if not resolved_start_agent:
-                    resolved_start_agent = FlockRegistry.get_agent(
-                        start_agent_name
-                    )
-                    if not resolved_start_agent:
-                        raise ValueError(
-                            f"Start agent '{start_agent_name}' not found."
-                        )
-                    self.add_agent(resolved_start_agent)
+                if not resolved_start_agent: # Should have been handled by now
+                    raise ValueError(f"Start agent '{start_agent_name}' not found after checks.")
 
                 run_context = context if context else FlockContext()
-                set_baggage("run_id", effective_run_id)
+                set_baggage("run_id", effective_run_id) # Set for OpenTelemetry
 
                 initialize_context(
                     run_context,
                     start_agent_name,
                     run_input,
                     effective_run_id,
-                    not self.enable_temporal,
+                    not self.enable_temporal, # local_debug is inverse of enable_temporal
                     self.model or resolved_start_agent.model or DEFAULT_MODEL,
                 )
                 # Add agent definitions to context for routing/serialization within workflow
-                for agent_name, agent_instance in self.agents.items():
-                    # Agents already handle their serialization
-                    agent_dict_repr = agent_instance.to_dict()
+                for agent_name_iter, agent_instance_iter in self.agents.items():
+                    agent_dict_repr = agent_instance_iter.to_dict() # Agents handle their own serialization
                     run_context.add_agent_definition(
-                        agent_type=type(agent_instance),
-                        agent_name=agent_name,
-                        agent_data=agent_dict_repr,  # Pass the serialized dict
+                        agent_type=type(agent_instance_iter),
+                        agent_name=agent_name_iter,
+                        agent_data=agent_dict_repr,
                     )
 
                 # Add temporal config to context if enabled
                 if self.enable_temporal and self.temporal_config:
-                    # Store the workflow config dict for the executor/workflow to use
-                    # Using a specific key to avoid potential clashes in state
                     run_context.set_variable(
                         "flock.temporal_workflow_config",
                         self.temporal_config.model_dump(mode="json"),
@@ -439,17 +454,13 @@ class Flock(BaseModel, Serializable):
                 # Execute workflow
                 if not self.enable_temporal:
                     result = await run_local_workflow(
-                        run_context, box_result=False
+                        run_context, box_result=False # Boxing handled below
                     )
                 else:
-                    # Pass the Flock instance itself to the executor
-                    # so it can access the temporal_config directly if needed
-                    # This avoids putting potentially large/complex config objects
-                    # directly into the context state that gets passed around.
                     result = await run_temporal_workflow(
-                        self,  # Pass the Flock instance
+                        self, # Pass the Flock instance
                         run_context,
-                        box_result=False,
+                        box_result=False, # Boxing handled below
                         memo=memo,
                     )
 
@@ -465,9 +476,9 @@ class Flock(BaseModel, Serializable):
                     try:
                         logger.debug("Boxing final result.")
                         return Box(result)
-                    except ImportError:
+                    except ImportError: # Should not happen as Box is a direct dependency
                         logger.warning(
-                            "Box library not installed, returning raw dict."
+                            "Box library not installed (should be direct dependency), returning raw dict."
                         )
                         return result
                 else:
@@ -479,10 +490,15 @@ class Flock(BaseModel, Serializable):
                 )
                 span.record_exception(e)
                 span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
-                return {
+                # Return a consistent error structure
+                error_output = {
                     "error": str(e),
                     "details": f"Flock run '{self.name}' failed.",
+                    "run_id": effective_run_id,
+                    "start_agent": start_agent_name,
                 }
+                return Box(error_output) if box_result else error_output
+
 
     # --- Batch Processing (Delegation) ---
     async def run_batch_async(
@@ -539,7 +555,6 @@ class Flock(BaseModel, Serializable):
         delimiter: str = ",",
     ) -> list[Box | dict | None | Exception]:
         """Synchronous wrapper for run_batch_async."""
-        # (Standard asyncio run wrapper logic)
         try:
             loop = asyncio.get_running_loop()
             if loop.is_closed():
@@ -574,15 +589,15 @@ class Flock(BaseModel, Serializable):
     # --- Evaluation (Delegation) ---
     async def evaluate_async(
         self,
-        dataset: str | Path | list[dict[str, Any]] | DataFrame | Dataset,
+        dataset: str | Path | list[dict[str, Any]] | DataFrame | Dataset, # type: ignore
         start_agent: FlockAgent | str,
         input_mapping: dict[str, str],
         answer_mapping: dict[str, str],
         metrics: list[
             str
             | Callable[[Any, Any], bool | float | dict[str, Any]]
-            | FlockAgent
-            | FlockEvaluator
+            | FlockAgent # Type hint only
+            | FlockEvaluator # Type hint only
         ],
         metric_configs: dict[str, dict[str, Any]] | None = None,
         static_inputs: dict[str, Any] | None = None,
@@ -594,7 +609,7 @@ class Flock(BaseModel, Serializable):
         return_dataframe: bool = True,
         silent_mode: bool = False,
         metadata_columns: list[str] | None = None,
-    ) -> DataFrame | list[dict[str, Any]]:
+    ) -> DataFrame | list[dict[str, Any]]: # type: ignore
         """Evaluates the Flock's performance against a dataset (delegated)."""
         # Import processor locally
         from flock.core.execution.evaluation_executor import (
@@ -622,15 +637,15 @@ class Flock(BaseModel, Serializable):
 
     def evaluate(
         self,
-        dataset: str | Path | list[dict[str, Any]] | DataFrame | Dataset,
+        dataset: str | Path | list[dict[str, Any]] | DataFrame | Dataset, # type: ignore
         start_agent: FlockAgent | str,
         input_mapping: dict[str, str],
         answer_mapping: dict[str, str],
         metrics: list[
             str
             | Callable[[Any, Any], bool | float | dict[str, Any]]
-            | FlockAgent
-            | FlockEvaluator
+            | FlockAgent # Type hint only
+            | FlockEvaluator # Type hint only
         ],
         metric_configs: dict[str, dict[str, Any]] | None = None,
         static_inputs: dict[str, Any] | None = None,
@@ -642,9 +657,8 @@ class Flock(BaseModel, Serializable):
         return_dataframe: bool = True,
         silent_mode: bool = False,
         metadata_columns: list[str] | None = None,
-    ) -> DataFrame | list[dict[str, Any]]:
+    ) -> DataFrame | list[dict[str, Any]]: # type: ignore
         """Synchronous wrapper for evaluate_async."""
-        # (Standard asyncio run wrapper logic)
         try:
             loop = asyncio.get_running_loop()
             if loop.is_closed():
@@ -678,104 +692,148 @@ class Flock(BaseModel, Serializable):
             future = asyncio.ensure_future(coro)
             return loop.run_until_complete(future)
 
-    # --- API Server Starter ---
+    # --- Server & CLI Starters (Delegation) ---
     def start_api(
         self,
         host: str = "127.0.0.1",
         port: int = 8344,
-        server_name: str = "Flock API",
-        create_ui: bool = False,
+        server_name: str = "Flock Server",
+        create_ui: bool = True, # Default to True for the integrated experience
         ui_theme: str | None = None,
         custom_endpoints: Sequence[FlockEndpoint] | dict[tuple[str, list[str] | None], Callable[..., Any]] | None = None,
     ) -> None:
-        """Starts a REST API server for this Flock instance.
-        If create_ui is True, integrates the web UI, potentially with a specific theme.
-        """
-        # Import runner locally
-        # We need to decide if start_api now *always* tries to use the integrated approach
-        # or if it still calls the API-only runner when create_ui=False.
-        # Let's assume it uses the integrated approach starter if create_ui=True
-        # and the API-only starter (FlockAPI) if create_ui=False.
+        """Starts a unified REST API server and/or Web UI for this Flock instance."""
+        import warnings
+        warnings.warn(
+            "start_api() is deprecated and will be removed in a future release. "
+            "Use serve() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        # Delegate to the new serve() method (create_ui maps to ui)
+        return self.serve(
+            host=host,
+            port=port,
+            server_name=server_name,
+            ui=create_ui,
+            ui_theme=ui_theme,
+            custom_endpoints=custom_endpoints,
+        )
 
-        if create_ui:
-            # Use the integrated server approach
-            try:
-                # We need a function similar to start_flock_api but for the integrated app
-                # Let's assume it exists in webapp.run for now, called start_integrated_server
-                from flock.webapp.run import start_integrated_server
-
-                start_integrated_server(
-                    flock_instance=self,
-                    host=host,
-                    port=port,
-                    server_name=server_name,
-                    theme_name=ui_theme,
-                    custom_endpoints=custom_endpoints,
-                )
-            except ImportError:
-                # Log error - cannot start integrated UI
-                from flock.core.logging.logging import get_logger
+    # ------------------------------------------------------------------
+    # New preferred method name
+    # ------------------------------------------------------------------
 
-                logger = get_logger("flock.core")
-                logger.error(
-                    "Cannot start integrated UI: Required components (e.g., flock.webapp.run.start_integrated_server) not found."
-                )
-            except Exception as e:
-                from flock.core.logging.logging import get_logger
-
-                logger = get_logger("flock.core")
-                logger.error(
-                    f"Failed to start integrated UI server: {e}", exc_info=True
-                )
-        else:
-            # Use the API-only server approach
-            from flock.core.api.runner import start_flock_api
-
-            start_flock_api(
-                flock=self,
-                host=host,
-                port=port,
-                server_name=server_name,
-                create_ui=False,  # Explicitly false for API only runner
-                custom_endpoints=custom_endpoints,
+    def serve(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 8344,
+        server_name: str = "Flock Server",
+        ui: bool = True,
+        chat: bool = False,
+        chat_agent: str | None = None,  # Reserved for future real agent chat
+        chat_message_key: str = "message",
+        chat_history_key: str = "history",
+        chat_response_key: str = "response",
+        ui_theme: str | None = None,
+        custom_endpoints: Sequence[FlockEndpoint] | dict[tuple[str, list[str] | None], Callable[..., Any]] | None = None,
+    ) -> None:
+        """Launch an HTTP server that exposes the core REST API and, optionally, the
+        browser-based UI.
+
+        Args:
+            host: Bind address for the server (default "127.0.0.1").
+            port: TCP port to listen on (default 8344).
+            server_name: Title shown in the OpenAPI docs / logs.
+            ui: If True (default) the Pico/HTMX web UI routes are included. If False
+                 only the JSON API groups (core & custom) are served.
+            chat: If True, enable chat routes.
+            chat_agent: Name of the agent to use for chat.
+            chat_message_key: Key for chat message in input.
+            chat_history_key: Key for chat history in input.
+            chat_response_key: Key for chat response in output.
+            ui_theme: Optional UI theme name or "random".
+            custom_endpoints: Additional API routes to add, either as a list of
+                 FlockEndpoint objects or the legacy dict format.
+        """
+        try:
+            from flock.webapp.run import start_unified_server
+        except ImportError:
+            logger.error(
+                "Web application components not found (flock.webapp.run). "
+                "Cannot start HTTP server. Ensure webapp dependencies are installed."
             )
+            return
+
+        logger.info(
+            f"Attempting to start server for Flock '{self.name}' on {host}:{port}. UI enabled: {ui}"
+        )
+
+        start_unified_server(
+            flock_instance=self,
+            host=host,
+            port=port,
+            server_title=server_name,
+            enable_ui_routes=ui,
+            enable_chat_routes=chat,
+            ui_theme=ui_theme,
+            custom_endpoints=custom_endpoints,
+        )
 
-    # --- CLI Starter ---
     def start_cli(
         self,
+        start_agent: FlockAgent | str | None = None, # Added start_agent to match method signature in file_26
         server_name: str = "Flock CLI",
         show_results: bool = False,
         edit_mode: bool = False,
     ) -> None:
         """Starts an interactive CLI for this Flock instance."""
         # Import runner locally
-        from flock.cli.runner import start_flock_cli
+        try:
+            from flock.cli.runner import start_flock_cli
+        except ImportError:
+            logger.error(
+                "CLI components not found. Cannot start CLI. "
+                "Ensure CLI dependencies are installed."
+            )
+            return
+
+        # The start_flock_cli function in file_50 doesn't take start_agent
+        # but the original docs for start_cli did.
+        # For now, I'll pass it through, assuming start_flock_cli will be updated or ignore it.
+        # If start_agent is crucial here, start_flock_cli needs to handle it.
+        logger.info(f"Starting CLI for Flock '{self.name}'...")
+        start_flock_cli(
+            flock=self, # Pass the Flock instance
+            # start_agent=start_agent, # This argument is not in the definition of start_flock_cli in file_50
+            server_name=server_name,
+            show_results=show_results,
+            edit_mode=edit_mode
+        )
 
-        start_flock_cli(self, server_name, show_results, edit_mode)
 
     # --- Serialization Delegation Methods ---
     def to_dict(self, path_type: str = "relative") -> dict[str, Any]:
         """Serialize Flock instance to dictionary using FlockSerializer."""
-        # Import locally to prevent circular imports at module level if structure is complex
         from flock.core.serialization.flock_serializer import FlockSerializer
 
-        # Assuming FlockSerializer handles the nested temporal_config serialization
         return FlockSerializer.serialize(self, path_type=path_type)
 
     @classmethod
     def from_dict(cls: type[T], data: dict[str, Any]) -> T:
         """Deserialize Flock instance from dictionary using FlockSerializer."""
-        # Import locally
         from flock.core.serialization.flock_serializer import FlockSerializer
 
-        # Assuming FlockSerializer handles the nested temporal_config deserialization
         return FlockSerializer.deserialize(cls, data)
 
     # --- Static Method Loader (Delegates to loader module) ---
     @staticmethod
-    def load_from_file(file_path: str) -> Flock:
+    def load_from_file(file_path: str) -> Flock: # Ensure return type is Flock
         """Load a Flock instance from various file formats (delegates to loader)."""
-        # Import locally
         from flock.core.util.loader import load_flock_from_file
 
-        return load_flock_from_file(file_path)
+        loaded_flock = load_flock_from_file(file_path)
+        # Ensure the loaded object is indeed a Flock instance
+        if not isinstance(loaded_flock, Flock):
+            raise TypeError(f"Loaded object from {file_path} is not a Flock instance, but {type(loaded_flock)}")
+        return loaded_flock

flock/core/flock_agent.py

@@ -195,6 +195,37 @@ class FlockAgent(BaseModel, Serializable, DSPyIntegrationMixin, ABC):
         """Get a list of currently enabled modules attached to this agent."""
         return [m for m in self.modules.values() if m.config.enabled]
 
+    @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.
+        """
+        if callable(self.description):
+            try:
+                # Attempt to call without context first.
+                # If callables consistently need context, this might need adjustment
+                # or the template-facing property might need to be simpler,
+                # relying on prior resolution via resolve_callables.
+                return self.description()
+            except TypeError:
+                # Log a warning that context might be needed?
+                # For now, treat as unresolvable in this simple property.
+                logger.warning(
+                    f"Callable description for agent '{self.name}' could not be resolved "
+                    f"without context via the simple 'resolved_description' property. "
+                    f"Consider calling 'agent.resolve_callables(context)' beforehand if context is required."
+                )
+                return None # Or a placeholder like "[Callable Description]"
+            except Exception as e:
+                logger.error(
+                    f"Error resolving callable description for agent '{self.name}': {e}"
+                )
+                return None
+        elif isinstance(self.description, str):
+            return self.description
+        return None
+
     # --- Lifecycle Hooks (Keep as they were) ---
     async def initialize(self, inputs: dict[str, Any]) -> None:
         """Initialize agent and run module initializers."""