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

flock/core/flock.py

@@ -3,12 +3,8 @@
 
 from __future__ import annotations  # Ensure forward references work
 
-import asyncio
-import contextvars
-import os
 import uuid
-from collections.abc import Awaitable, Callable, Sequence
-from concurrent.futures import ThreadPoolExecutor
+from collections.abc import Callable, Sequence
 from pathlib import Path
 from typing import (
     TYPE_CHECKING,
@@ -21,21 +17,12 @@ from typing import (
 from box import Box
 from temporalio import workflow
 
-from flock.core.flock_server_manager import FlockServerManager
-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
 
-    # Assuming run_local_workflow is correctly placed and importable
-    from flock.core.execution.local_executor import (
-        run_local_workflow,
-    )
-
-import opik
 from opentelemetry import trace
-from opentelemetry.baggage import get_baggage, set_baggage
-from opik.integrations.dspy.callback import OpikCallback
 from pandas import DataFrame  # type: ignore
 from pydantic import BaseModel, Field
 
@@ -45,14 +32,8 @@ 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  # For type hint
 from flock.core.logging.logging import get_logger
 from flock.core.serialization.serializable import Serializable
-from flock.core.util.cli_helper import init_console
 from flock.workflow.temporal_config import TemporalWorkflowConfig
 
 # Import FlockAgent using TYPE_CHECKING to avoid circular import at runtime
@@ -62,7 +43,7 @@ if TYPE_CHECKING:
 
 
 # Registry
-from flock.core.flock_registry import get_registry
+from flock.core.registry import get_registry
 
 try:
     import pandas as pd  # type: ignore
@@ -75,7 +56,7 @@ except ImportError:
 logger = get_logger("flock.api")
 TELEMETRY.setup_tracing()  # Setup OpenTelemetry
 tracer = trace.get_tracer(__name__)
-FlockRegistry = get_registry()  # Get the registry instance
+registry = get_registry()  # Get the registry instance
 
 # Define TypeVar for generic class methods like from_dict
 T = TypeVar("T", bound="Flock")
@@ -144,40 +125,78 @@ 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]
 
-    # Async context-manager for startup and teardown of servers
-    # Not part of the pydantic model
-    _mgr: FlockServerManager
+    # Note: _mgr is now handled by the server manager helper
 
     # Pydantic v2 model config
     model_config = {
         "arbitrary_types_allowed": True,
-        # Assuming FlockRegistry type might not be serializable by default
-        "ignored_types": (type(FlockRegistry),),
+        # Assuming registry type might not be serializable by default
+        "ignored_types": (type(registry),),
     }
 
-    def _run_sync(self, coro: Awaitable[_R]) -> _R:
-        """Execute *coro* synchronously.
+    # --- COMPOSITION HELPERS (Lazy-Loaded) ---
+    # Following the successful FlockAgent pattern
 
-        * If no loop is running → ``asyncio.run``.
-        * Otherwise run ``asyncio.run`` inside a fresh thread **with**
-          context-vars propagation.
-        """
-        try:
-            asyncio.get_running_loop()
-        except RuntimeError:  # no loop → simple
-            return asyncio.run(coro)
-
-        # A loop is already running – Jupyter / ASGI / etc.
-        ctx = contextvars.copy_context()  # propagate baggage
-        with ThreadPoolExecutor(max_workers=1) as pool:
-            future = pool.submit(ctx.run, asyncio.run, coro)
-            try:
-                return future.result()
-            finally:
-                if not future.done():
-                    future.cancel()
+    @property
+    def _execution(self):
+        """Get the execution management helper (lazy-loaded)."""
+        if not hasattr(self, '_execution_helper'):
+            from flock.core.orchestration.flock_execution import FlockExecution
+            self._execution_helper = FlockExecution(self)
+        return self._execution_helper
+
+    @property
+    def _server_manager(self):
+        """Get the server management helper (lazy-loaded)."""
+        if not hasattr(self, '_server_manager_helper'):
+            from flock.core.orchestration.flock_server_manager import (
+                FlockServerManager,
+            )
+            self._server_manager_helper = FlockServerManager(self)
+        return self._server_manager_helper
+
+    @property
+    def _batch_processor(self):
+        """Get the batch processing helper (lazy-loaded)."""
+        if not hasattr(self, '_batch_processor_helper'):
+            from flock.core.orchestration.flock_batch_processor import (
+                FlockBatchProcessor,
+            )
+            self._batch_processor_helper = FlockBatchProcessor(self)
+        return self._batch_processor_helper
+
+    @property
+    def _evaluator(self):
+        """Get the evaluation helper (lazy-loaded)."""
+        if not hasattr(self, '_evaluator_helper'):
+            from flock.core.orchestration.flock_evaluator import FlockEvaluator
+            self._evaluator_helper = FlockEvaluator(self)
+        return self._evaluator_helper
+
+    @property
+    def _web_server(self):
+        """Get the web server helper (lazy-loaded)."""
+        if not hasattr(self, '_web_server_helper'):
+            from flock.core.orchestration.flock_web_server import FlockWebServer
+            self._web_server_helper = FlockWebServer(self)
+        return self._web_server_helper
+
+    @property
+    def _initialization(self):
+        """Get the initialization helper (lazy-loaded)."""
+        if not hasattr(self, '_initialization_helper'):
+            from flock.core.orchestration.flock_initialization import (
+                FlockInitialization,
+            )
+            self._initialization_helper = FlockInitialization(self)
+        return self._initialization_helper
+
+    @property
+    def _mgr(self):
+        """Get the internal server manager for compatibility."""
+        return self._server_manager._internal_mgr
 
     def __init__(
         self,
@@ -188,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,
@@ -215,65 +234,10 @@ class Flock(BaseModel, Serializable):
         self._servers = {}
         self._start_agent_name = None
         self._start_input = {}
-        self._mgr = FlockServerManager()
-
-        # Register passed servers
-        # (need to be registered first so that agents can retrieve them from the registry)
-        # This will also add them to the managed list of self._mgr
-        if servers:
-            from flock.core.mcp.flock_mcp_server import (
-                FlockMCPServerBase as ConcreteFlockMCPServer,
-            )
-
-            for server in servers:
-                if isinstance(server, ConcreteFlockMCPServer):
-                    self.add_server(server)
-                else:
-                    logger.warning(
-                        f"Item provided in 'servers' list is not a FlockMCPServer: {type(server)}"
-                    )
-
-        # Register passed agents
-        if agents:
-            from flock.core.flock_agent import (
-                FlockAgent as ConcreteFlockAgent,  # Local import
-            )
+        # Note: _mgr will be handled by the server manager helper
 
-            for agent in agents:
-                if isinstance(agent, ConcreteFlockAgent):
-                    self.add_agent(agent)
-                else:
-                    logger.warning(
-                        f"Item provided in 'agents' list is not a FlockAgent: {type(agent)}"
-                    )
-
-        # Initialize console if needed for 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()
-
-        # Ensure session ID exists in baggage
-        self._ensure_session_id()
-
-        FlockRegistry.discover_and_register_components()
-
-        if self.enable_opik:
-            import dspy
-
-            opik.configure(use_local=True, automatic_approvals=True)
-            opik_callback = OpikCallback(project_name=self.name, log_graph=True)
-            dspy.settings.configure(
-                callbacks=[opik_callback],
-            )
-
-        logger.info(
-            "Flock instance initialized",
-            name=self.name,
-            model=self.model,
-            enable_temporal=self.enable_temporal,
-        )
+        # Delegate complex initialization to the initialization helper
+        self._initialization.setup(agents=agents, servers=servers)
 
     def prepare_benchmark(
         self,
@@ -315,7 +279,7 @@ class Flock(BaseModel, Serializable):
             agent_input = {self.benchmark_input_field: msg_content}
 
             result = await self.run_async(
-                start_agent=self.benchmark_agent_name,
+                agent=self.benchmark_agent_name,
                 input=agent_input,
                 box_result=False,
             )
@@ -330,61 +294,11 @@ class Flock(BaseModel, Serializable):
 
         return run
 
-    def _set_temporal_debug_flag(self):
-        """Set or remove LOCAL_DEBUG env var based on enable_temporal."""
-        if not self.enable_temporal:
-            if "LOCAL_DEBUG" not in os.environ:
-                os.environ["LOCAL_DEBUG"] = "1"
-                logger.debug(
-                    "Set LOCAL_DEBUG environment variable for local execution."
-                )
-        elif "LOCAL_DEBUG" in os.environ:
-            del os.environ["LOCAL_DEBUG"]
-            logger.debug(
-                "Removed LOCAL_DEBUG environment variable for Temporal execution."
-            )
 
-    def _ensure_session_id(self):
-        """Ensure a session_id exists in the OpenTelemetry baggage."""
-        session_id = get_baggage("session_id")
-        if not session_id:
-            session_id = str(uuid.uuid4())
-            set_baggage("session_id", session_id)
-            logger.debug(f"Generated new session_id: {session_id}")
-
-    def add_server(self, server: FlockMCPServerBase) -> FlockMCPServerBase:
-        """Adds a server instance to this Flock configuration and registry as well as set it up to be managed by self._mgr."""
-        from flock.core.mcp.flock_mcp_server import (
-            FlockMCPServerBase as ConcreteFlockMCPServer,
-        )
 
-        if not isinstance(server, ConcreteFlockMCPServer):
-            raise TypeError("Provided object is not a FlockMCPServer instance.")
-        if not server.config.name:
-            raise ValueError("Server must have a name.")
-
-        if server.config.name in self.servers:
-            raise ValueError(
-                f"Server with this name already exists. Name: '{server.config.name}'"
-            )
-
-        self._servers[server.config.name] = server
-        FlockRegistry.register_server(server)  # Register globally.
-
-        # Make sure that the server is also added to
-        # the server_list managed by FlockServerManager
-        if not self._mgr:
-            self._mgr = FlockServerManager()
-
-        # Prepare server to be managed by the FlockServerManager
-        logger.info(f"Adding server '{server.config.name}' to managed list.")
-        self._mgr.add_server_sync(server=server)
-        logger.info(f"Server '{server.config.name}' is now on managed list.")
-
-        logger.info(
-            f"Server '{server.config.name}' added to Flock '{self.name}'"
-        )
-        return server
+    def add_server(self, server: FlockMCPServer) -> FlockMCPServer:
+        """Adds a server instance to this Flock configuration and registry."""
+        return self._server_manager.add_server(server)
 
     def add_agent(self, agent: FlockAgent) -> FlockAgent:
         """Adds an agent instance to this Flock configuration and registry.
@@ -412,7 +326,7 @@ class Flock(BaseModel, Serializable):
                 return agent  # Return existing agent
 
         self._agents[agent.name] = agent
-        FlockRegistry.register_agent(agent)  # Register globally
+        registry.register_agent(agent)  # Register globally
 
         # Set default model if agent doesn't have one
         if agent.model is None:
@@ -435,226 +349,56 @@ 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._servers
+        return self._server_manager.servers
 
     def run(
         self,
-        start_agent: FlockAgent | str | None = None,
+        agent: FlockAgent | str | None = None,
         input: dict | None = None,
         context: FlockContext | None = None,
         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:
-        return self._run_sync(
-            self.run_async(
-                start_agent=start_agent,
-                input=input,
-                context=context,
-                run_id=run_id,
-                box_result=box_result,
-                agents=agents,
-                servers=servers,
-                memo=memo,
-            )
+        """Synchronous execution wrapper."""
+        return self._execution.run(
+            agent=agent,
+            input=input,
+            context=context,
+            run_id=run_id,
+            box_result=box_result,
+            agents=agents,
+            servers=servers,
+            memo=memo,
         )
 
     async def run_async(
         self,
-        start_agent: FlockAgent | str | None = None,
+        agent: FlockAgent | str | None = None,
         input: dict | None = None,
         context: FlockContext | None = None,
         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."""
-        # Import here to allow forward reference resolution
-        from flock.core.flock_agent import FlockAgent as ConcreteFlockAgent
-        from flock.core.mcp.flock_mcp_server import (
-            FlockMCPServerBase as ConcreteFlockServer,
+        return await self._execution.run_async(
+            agent=agent,
+            input=input,
+            context=context,
+            run_id=run_id,
+            box_result=box_result,
+            agents=agents,
+            servers=servers,
+            memo=memo,
         )
 
-        with tracer.start_as_current_span("flock.run_async") as span:
-            # Add passed servers so that agents have access to them.
-            if servers:
-                for server_obj in servers:
-                    if isinstance(server_obj, ConcreteFlockServer):
-                        self.add_server(server=server_obj)
-                    else:
-                        logger.warning(
-                            f"Item in 'servers' list is not a FlockMCPServer: {type(server_obj)}"
-                        )
-
-            # Add passed agents
-            if agents:
-                for agent_obj in agents:
-                    if isinstance(agent_obj, ConcreteFlockAgent):
-                        self.add_agent(agent_obj)
-                    else:
-                        logger.warning(
-                            f"Item in 'agents' list is not a FlockAgent: {type(agent_obj)}"
-                        )
-
-            # Determine starting agent name
-            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
-                ):  # Add if not already present
-                    self.add_agent(start_agent)
-            elif isinstance(start_agent, str):
-                start_agent_name = start_agent
-            else:  # start_agent is None
-                start_agent_name = self._start_agent_name
-
-            # Default to first agent if only one exists and none specified
-            if not start_agent_name and len(self._agents) == 1:
-                start_agent_name = next(iter(self._agents.keys()))
-            elif not start_agent_name:
-                raise ValueError(
-                    "No start_agent specified and multiple/no agents exist in the Flock instance."
-                )
-
-            # Check if start_agent is in agents
-            if start_agent_name not in self._agents:
-                # Try loading from registry if not found locally yet
-                reg_agent = FlockRegistry.get_agent(start_agent_name)
-                if reg_agent:
-                    self.add_agent(reg_agent)
-                    logger.info(
-                        f"Loaded start agent '{start_agent_name}' from registry."
-                    )
-                else:
-                    raise ValueError(
-                        f"Start agent '{start_agent_name}' not found locally or in registry."
-                    )
-
-            run_input = input if input is not None else self._start_input
-            effective_run_id = run_id or f"flockrun_{uuid.uuid4().hex[:8]}"
-
-            span.set_attribute("start_agent", start_agent_name)
-            span.set_attribute("input", str(run_input))
-            span.set_attribute("run_id", effective_run_id)
-            span.set_attribute("enable_temporal", self.enable_temporal)
-            logger.info(
-                f"Initiating Flock run '{self.name}'. Start Agent: '{start_agent_name}'. Temporal: {self.enable_temporal}."
-            )
-
-            try:
-                resolved_start_agent = self._agents.get(start_agent_name)
-                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 for OpenTelemetry
-
-                initialize_context(
-                    run_context,
-                    start_agent_name,
-                    run_input,
-                    effective_run_id,
-                    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_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_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:
-                    run_context.set_variable(
-                        "flock.temporal_workflow_config",
-                        self.temporal_config.model_dump(mode="json"),
-                    )
-
-                # At this point, initial setup is done
-                # and flock is ready to execute it's agent_workflow.
-                # Befor that happens, the ServerManager needs to
-                # get the Servers up and running (Populate pools, build connections, start scripts, etc.)
-                async with self._mgr:
-                    # Enter the manager's async context,
-                    # running it's __aenter__ method and starting all registered servers
-                    # after this block ends, self._mgr's __aexit__ will be called
-                    # all servers will be torn down.
-                    logger.info(
-                        f"Entering managed server context. Servers starting up."
-                    )
-
-                    logger.info(
-                        "Starting agent execution",
-                        agent=start_agent_name,
-                        enable_temporal=self.enable_temporal,
-                    )
-
-                    # Execute workflow
-                    if not self.enable_temporal:
-                        result = await run_local_workflow(
-                            run_context,
-                            box_result=False,  # Boxing handled below
-                        )
-                    else:
-                        result = await run_temporal_workflow(
-                            self,  # Pass the Flock instance
-                            run_context,
-                            box_result=False,  # Boxing handled below
-                            memo=memo,
-                        )
-
-                    span.set_attribute("result.type", str(type(result)))
-                    result_str = str(result)
-                    span.set_attribute(
-                        "result.preview",
-                        result_str[:1000]
-                        + ("..." if len(result_str) > 1000 else ""),
-                    )
-
-                    if box_result:
-                        try:
-                            logger.debug("Boxing final result.")
-                            return Box(result)
-                        except ImportError:
-                            logger.warning(
-                                "Box library not installed, returning raw dict."
-                            )
-                            return result
-                    else:
-                        return result
-
-                        # The context of self._mgr ends here, meaning, that servers will
-                        # be cleaned up and shut down.
-
-            except Exception as e:
-                logger.error(
-                    f"Flock run '{self.name}' failed: {e}", exc_info=True
-                )
-                span.record_exception(e)
-                span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
-                # 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(
         self,
@@ -673,11 +417,7 @@ class Flock(BaseModel, Serializable):
         delimiter: str = ",",
     ) -> list[Box | dict | None | Exception]:
         """Runs the specified agent/workflow for each item in a batch asynchronously (delegated)."""
-        # Import processor locally
-        from flock.core.execution.batch_executor import BatchProcessor
-
-        processor = BatchProcessor(self)  # Pass self
-        return await processor.run_batch_async(
+        return await self._batch_processor.run_batch_async(
             start_agent=start_agent,
             batch_inputs=batch_inputs,
             input_mapping=input_mapping,
@@ -709,22 +449,21 @@ class Flock(BaseModel, Serializable):
         hide_columns: list[str] | None = None,
         delimiter: str = ",",
     ) -> list[Box | dict | None | Exception]:
-        return self._run_sync(
-            self.run_batch_async(
-                start_agent=start_agent,
-                batch_inputs=batch_inputs,
-                input_mapping=input_mapping,
-                static_inputs=static_inputs,
-                parallel=parallel,
-                max_workers=max_workers,
-                use_temporal=use_temporal,
-                box_results=box_results,
-                return_errors=return_errors,
-                silent_mode=silent_mode,
-                write_to_csv=write_to_csv,
-                hide_columns=hide_columns,
-                delimiter=delimiter,
-            )
+        """Synchronous wrapper for batch processing."""
+        return self._batch_processor.run_batch(
+            start_agent=start_agent,
+            batch_inputs=batch_inputs,
+            input_mapping=input_mapping,
+            static_inputs=static_inputs,
+            parallel=parallel,
+            max_workers=max_workers,
+            use_temporal=use_temporal,
+            box_results=box_results,
+            return_errors=return_errors,
+            silent_mode=silent_mode,
+            write_to_csv=write_to_csv,
+            hide_columns=hide_columns,
+            delimiter=delimiter,
         )
 
     # --- Evaluation (Delegation) ---
@@ -738,7 +477,6 @@ class Flock(BaseModel, Serializable):
             str
             | Callable[[Any, Any], bool | float | dict[str, Any]]
             | FlockAgent  # Type hint only
-            | FlockEvaluator  # Type hint only
         ],
         metric_configs: dict[str, dict[str, Any]] | None = None,
         static_inputs: dict[str, Any] | None = None,
@@ -752,13 +490,7 @@ class Flock(BaseModel, Serializable):
         metadata_columns: list[str] | None = None,
     ) -> 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 (
-            EvaluationExecutor,
-        )
-
-        processor = EvaluationExecutor(self)  # Pass self
-        return await processor.evaluate_async(
+        return await self._evaluator.evaluate_async(
             dataset=dataset,
             start_agent=start_agent,
             input_mapping=input_mapping,
@@ -786,7 +518,6 @@ class Flock(BaseModel, Serializable):
             str
             | Callable[[Any, Any], bool | float | dict[str, Any]]
             | FlockAgent  # Type hint only
-            | FlockEvaluator  # Type hint only
         ],
         metric_configs: dict[str, dict[str, Any]] | None = None,
         static_inputs: dict[str, Any] | None = None,
@@ -799,60 +530,26 @@ class Flock(BaseModel, Serializable):
         silent_mode: bool = False,
         metadata_columns: list[str] | None = None,
     ) -> DataFrame | list[dict[str, Any]]:  # type: ignore
-        return self._run_sync(
-            self.evaluate_async(
-                dataset=dataset,
-                start_agent=start_agent,
-                input_mapping=input_mapping,
-                answer_mapping=answer_mapping,
-                metrics=metrics,
-                metric_configs=metric_configs,
-                static_inputs=static_inputs,
-                parallel=parallel,
-                max_workers=max_workers,
-                use_temporal=use_temporal,
-                error_handling=error_handling,
-                output_file=output_file,
-                return_dataframe=return_dataframe,
-                silent_mode=silent_mode,
-                metadata_columns=metadata_columns,
-            )
+        """Synchronous wrapper for evaluation."""
+        return self._evaluator.evaluate(
+            dataset=dataset,
+            start_agent=start_agent,
+            input_mapping=input_mapping,
+            answer_mapping=answer_mapping,
+            metrics=metrics,
+            metric_configs=metric_configs,
+            static_inputs=static_inputs,
+            parallel=parallel,
+            max_workers=max_workers,
+            use_temporal=use_temporal,
+            error_handling=error_handling,
+            output_file=output_file,
+            return_dataframe=return_dataframe,
+            silent_mode=silent_mode,
+            metadata_columns=metadata_columns,
         )
 
     # --- Server & CLI Starters (Delegation) ---
-    def start_api(
-        self,
-        host: str = "127.0.0.1",
-        port: int = 8344,
-        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 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,
-        )
-
-    # ------------------------------------------------------------------
-    # New preferred method name
-    # ------------------------------------------------------------------
 
     def serve(
         self,
@@ -870,44 +567,17 @@ class Flock(BaseModel, Serializable):
         | 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,
+        """Launch an HTTP server that exposes the core REST API and, optionally, the browser-based UI."""
+        return self._web_server.serve(
             host=host,
             port=port,
-            server_title=server_name,
-            enable_ui_routes=ui,
-            enable_chat_routes=chat,
+            server_name=server_name,
+            ui=ui,
+            chat=chat,
+            chat_agent=chat_agent,
+            chat_message_key=chat_message_key,
+            chat_history_key=chat_history_key,
+            chat_response_key=chat_response_key,
             ui_theme=ui_theme,
             custom_endpoints=custom_endpoints,
         )
@@ -922,24 +592,8 @@ class Flock(BaseModel, Serializable):
         edit_mode: bool = False,
     ) -> None:
         """Starts an interactive CLI for this Flock instance."""
-        # Import runner locally
-        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
+        return self._web_server.start_cli(
+            start_agent=start_agent,
             server_name=server_name,
             show_results=show_results,
             edit_mode=edit_mode,