flock-core 0.3.22__py3-none-any.whl → 0.3.30__py3-none-any.whl

flock/core/__init__.py

@@ -2,18 +2,18 @@
 
 from flock.core.flock import Flock
 from flock.core.flock_agent import FlockAgent
-from flock.core.flock_api import FlockAPI
 from flock.core.flock_evaluator import FlockEvaluator, FlockEvaluatorConfig
 from flock.core.flock_factory import FlockFactory
 from flock.core.flock_module import FlockModule, FlockModuleConfig
+from flock.core.flock_registry import FlockRegistry
 
 __all__ = [
     "Flock",
-    "FlockAPI",
     "FlockAgent",
     "FlockEvaluator",
     "FlockEvaluatorConfig",
     "FlockFactory",
     "FlockModule",
     "FlockModuleConfig",
+    "FlockRegistry",
 ]

flock/core/api/__init__.py

@@ -0,0 +1,11 @@
+# src/flock/core/api/__init__.py
+"""Flock API Server components."""
+
+from .main import FlockAPI
+from .models import FlockAPIRequest, FlockAPIResponse
+
+__all__ = [
+    "FlockAPI",
+    "FlockAPIRequest",
+    "FlockAPIResponse",
+]

flock/core/api/endpoints.py

@@ -0,0 +1,222 @@
+# src/flock/core/api/endpoints.py
+"""FastAPI endpoints for the Flock API."""
+
+import html  # For escaping
+import uuid
+from typing import TYPE_CHECKING  # Added Any for type hinting clarity
+
+from fastapi import (
+    APIRouter,
+    BackgroundTasks,
+    HTTPException,
+    Request as FastAPIRequest,
+)
+
+# Import HTMLResponse for the UI form endpoint
+from fastapi.responses import HTMLResponse
+
+from flock.core.logging.logging import get_logger
+
+# Import models and UI utils
+from .models import FlockAPIRequest, FlockAPIResponse
+
+# Import UI utils - assuming they are now in ui/utils.py
+
+# Use TYPE_CHECKING to avoid circular imports for type hints
+if TYPE_CHECKING:
+    from flock.core.flock import Flock
+
+    from .main import FlockAPI
+    from .run_store import RunStore
+
+logger = get_logger("api.endpoints")
+
+
+# Factory function to create the router with dependencies
+def create_api_router(flock_api: "FlockAPI") -> APIRouter:
+    """Creates the APIRouter and defines endpoints, injecting dependencies."""
+    router = APIRouter()
+    # Get dependencies from the main FlockAPI instance passed in
+    run_store: RunStore = flock_api.run_store
+    flock_instance: Flock = flock_api.flock
+
+    # --- API Endpoints ---
+    @router.post("/run/flock", response_model=FlockAPIResponse, tags=["API"])
+    async def run_flock_json(
+        request: FlockAPIRequest, background_tasks: BackgroundTasks
+    ):
+        """Run a flock workflow starting with the specified agent (expects JSON)."""
+        run_id = None
+        try:
+            run_id = str(uuid.uuid4())
+            run_store.create_run(run_id)  # Use RunStore
+            response = run_store.get_run(
+                run_id
+            )  # Get initial response from store
+
+            processed_inputs = request.inputs if request.inputs else {}
+            logger.info(
+                f"API request: run flock '{request.agent_name}' (run_id: {run_id})",
+                inputs=processed_inputs,
+            )
+
+            if request.async_run:
+                logger.debug(
+                    f"Running flock '{request.agent_name}' asynchronously (run_id: {run_id})"
+                )
+                # Call the helper method on the passed FlockAPI instance
+                background_tasks.add_task(
+                    flock_api._run_flock,
+                    run_id,
+                    request.agent_name,
+                    processed_inputs,
+                )
+                run_store.update_run_status(run_id, "running")
+                response.status = "running"  # Update local response copy too
+            else:
+                logger.debug(
+                    f"Running flock '{request.agent_name}' synchronously (run_id: {run_id})"
+                )
+                # Call the helper method on the passed FlockAPI instance
+                await flock_api._run_flock(
+                    run_id, request.agent_name, processed_inputs
+                )
+                response = run_store.get_run(
+                    run_id
+                )  # Fetch updated status/result
+
+            return response
+        except ValueError as ve:
+            logger.error(f"Value error starting run: {ve}")
+            if run_id:
+                run_store.update_run_status(run_id, "failed", str(ve))
+            raise HTTPException(status_code=400, detail=str(ve))
+        except Exception as e:
+            error_msg = f"Internal server error: {type(e).__name__}"
+            logger.error(f"Error starting run: {e!s}", exc_info=True)
+            if run_id:
+                run_store.update_run_status(run_id, "failed", error_msg)
+            raise HTTPException(status_code=500, detail=error_msg)
+
+    @router.get("/run/{run_id}", response_model=FlockAPIResponse, tags=["API"])
+    async def get_run_status(run_id: str):
+        """Get the status of a specific run."""
+        logger.debug(f"API request: get status for run_id: {run_id}")
+        run_data = run_store.get_run(run_id)
+        if not run_data:
+            logger.warning(f"Run ID not found: {run_id}")
+            raise HTTPException(status_code=404, detail="Run not found")
+        return run_data
+
+    @router.get("/agents", tags=["API"])
+    async def list_agents():
+        """List all available agents."""
+        logger.debug("API request: list agents")
+        # Access flock instance via factory closure
+        agents_list = [
+            {"name": agent.name, "description": agent.description or agent.name}
+            for agent in flock_instance.agents.values()
+        ]
+        return {"agents": agents_list}
+
+    # --- UI Form Endpoint ---
+    @router.post("/ui/run-agent-form", response_class=HTMLResponse, tags=["UI"])
+    async def run_flock_form(fastapi_req: FastAPIRequest):
+        """Endpoint to handle form submissions from the UI."""
+        run_id = None
+        try:
+            form_data = await fastapi_req.form()
+            agent_name = form_data.get("agent_name")
+            if not agent_name:
+                logger.warning("UI form submission missing agent_name")
+                return HTMLResponse(
+                    '<div id="result-content" class="error-message">Error: Agent name not provided.</div>',
+                    status_code=400,
+                )
+
+            logger.info(f"UI Form submission for agent: {agent_name}")
+            form_inputs = {}
+            # Access flock instance via factory closure
+            agent_def = flock_instance.agents.get(agent_name)
+            # Use helper from flock_api instance for parsing
+            defined_input_fields = (
+                flock_api._parse_input_spec(agent_def.input or "")
+                if agent_def
+                else []
+            )
+
+            for key, value in form_data.items():
+                if key.startswith("inputs."):
+                    form_inputs[key[len("inputs.") :]] = value
+            for field in defined_input_fields:  # Handle checkboxes
+                if (
+                    field["html_type"] == "checkbox"
+                    and field["name"] not in form_inputs
+                ):
+                    form_inputs[field["name"]] = False
+                elif (
+                    field["html_type"] == "checkbox"
+                    and field["name"] in form_inputs
+                ):
+                    form_inputs[field["name"]] = True
+
+            logger.debug(f"Parsed form inputs for UI run: {form_inputs}")
+            run_id = str(uuid.uuid4())
+            run_store.create_run(run_id)  # Use RunStore
+            logger.debug(
+                f"Running flock '{agent_name}' synchronously from UI (run_id: {run_id})"
+            )
+
+            # Call helper method on flock_api instance
+            await flock_api._run_flock(run_id, agent_name, form_inputs)
+
+            final_status = run_store.get_run(run_id)
+            if final_status and final_status.status == "completed":
+                # Use helper from flock_api instance for formatting
+                formatted_html = flock_api._format_result_to_html(
+                    final_status.result
+                )
+                logger.info(f"UI run completed successfully (run_id: {run_id})")
+                return HTMLResponse(
+                    f"<div id='result-content'>{formatted_html}</div>"
+                )  # Wrap in target div
+            elif final_status and final_status.status == "failed":
+                logger.error(
+                    f"UI run failed (run_id: {run_id}): {final_status.error}"
+                )
+                error_msg = html.escape(final_status.error or "Unknown error")
+                return HTMLResponse(
+                    f"<div id='result-content' class='error-message'>Run Failed: {error_msg}</div>",
+                    status_code=500,
+                )
+            else:
+                status_str = (
+                    final_status.status if final_status else "Not Found"
+                )
+                logger.warning(
+                    f"UI run {run_id} ended in unexpected state: {status_str}"
+                )
+                return HTMLResponse(
+                    f"<div id='result-content' class='error-message'>Run ended unexpectedly. Status: {status_str}</div>",
+                    status_code=500,
+                )
+
+        except ValueError as ve:
+            logger.error(f"Value error processing UI form run: {ve}")
+            if run_id:
+                run_store.update_run_status(run_id, "failed", str(ve))
+            return HTMLResponse(
+                f"<div id='result-content' class='error-message'>Error: {html.escape(str(ve))}</div>",
+                status_code=400,
+            )
+        except Exception as e:
+            error_msg = f"Internal server error: {type(e).__name__}"
+            logger.error(f"Error processing UI form run: {e!s}", exc_info=True)
+            if run_id:
+                run_store.update_run_status(run_id, "failed", error_msg)
+            return HTMLResponse(
+                f"<div id='result-content' class='error-message'>{html.escape(error_msg)}</div>",
+                status_code=500,
+            )
+
+    return router

flock/core/api/main.py

@@ -0,0 +1,237 @@
+# src/flock/core/api/main.py
+"""Main Flock API server class and setup."""
+
+from typing import Any
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.responses import RedirectResponse
+
+# Flock core imports
+from flock.core.flock import Flock
+from flock.core.logging.logging import get_logger
+
+from .endpoints import create_api_router
+
+# Import components from the api package
+from .run_store import RunStore
+from .ui.routes import FASTHTML_AVAILABLE, create_ui_app
+from .ui.utils import format_result_to_html, parse_input_spec  # Import UI utils
+
+logger = get_logger("api.main")
+
+
+class FlockAPI:
+    """Coordinates the Flock API server, including endpoints and UI."""
+
+    def __init__(self, flock: Flock):
+        self.flock = flock
+        self.app = FastAPI(title="Flock API")
+        self.run_store = RunStore()  # Create the run store instance
+        self._setup_routes()
+
+    def _setup_routes(self):
+        """Includes API routers."""
+        # Create and include the API router, passing self
+        api_router = create_api_router(self)
+        self.app.include_router(api_router)
+
+        # Root redirect (if UI is enabled later) will be added in start()
+
+    # --- Core Execution Helper Methods ---
+    # These remain here as they need access to self.flock and self.run_store
+
+    async def _run_agent(
+        self, run_id: str, agent_name: str, inputs: dict[str, Any]
+    ):
+        """Executes a single agent run (internal helper)."""
+        try:
+            if agent_name not in self.flock.agents:
+                raise ValueError(f"Agent '{agent_name}' not found")
+            agent = self.flock.agents[agent_name]
+            # Type conversion (remains important)
+            typed_inputs = self._type_convert_inputs(agent_name, inputs)
+
+            logger.debug(
+                f"Executing single agent '{agent_name}' (run_id: {run_id})",
+                inputs=typed_inputs,
+            )
+            result = await agent.run_async(typed_inputs)
+            logger.info(
+                f"Single agent '{agent_name}' completed (run_id: {run_id})"
+            )
+
+            # Use RunStore to update
+            self.run_store.update_run_result(run_id, result)
+
+        except Exception as e:
+            logger.error(
+                f"Error in single agent run {run_id} ('{agent_name}'): {e!s}",
+                exc_info=True,
+            )
+            # Update store status
+            self.run_store.update_run_status(run_id, "failed", str(e))
+            raise  # Re-raise for the endpoint handler
+
+    async def _run_flock(
+        self, run_id: str, agent_name: str, inputs: dict[str, Any]
+    ):
+        """Executes a flock workflow run (internal helper)."""
+        try:
+            if agent_name not in self.flock.agents:
+                raise ValueError(f"Starting agent '{agent_name}' not found")
+
+            # Type conversion
+            typed_inputs = self._type_convert_inputs(agent_name, inputs)
+
+            logger.debug(
+                f"Executing flock workflow starting with '{agent_name}' (run_id: {run_id})",
+                inputs=typed_inputs,
+            )
+            result = await self.flock.run_async(
+                start_agent=agent_name, input=typed_inputs
+            )
+            # Result is potentially a Box object
+
+            # Use RunStore to update
+            self.run_store.update_run_result(run_id, result)
+
+            # Log using the local result variable
+            final_agent_name = (
+                result.get("agent_name", "N/A") if result is not None else "N/A"
+            )
+            logger.info(
+                f"Flock workflow completed (run_id: {run_id})",
+                final_agent=final_agent_name,
+            )
+
+        except Exception as e:
+            logger.error(
+                f"Error in flock run {run_id} (started with '{agent_name}'): {e!s}",
+                exc_info=True,
+            )
+            # Update store status
+            self.run_store.update_run_status(run_id, "failed", str(e))
+            raise  # Re-raise for the endpoint handler
+
+    # --- UI Helper Methods (kept here as they are called by endpoints via self) ---
+
+    def _parse_input_spec(self, input_spec: str) -> list[dict[str, str]]:
+        """Parses an agent input string into a list of field definitions."""
+        # Use the implementation moved to ui.utils
+        return parse_input_spec(input_spec)
+
+    def _format_result_to_html(self, data: Any) -> str:
+        """Recursively formats a Python object into an HTML string."""
+        # Use the implementation moved to ui.utils
+        return format_result_to_html(data)
+
+    def _type_convert_inputs(
+        self, agent_name: str, inputs: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Converts input values (esp. from forms) to expected Python types."""
+        typed_inputs = {}
+        agent_def = self.flock.agents.get(agent_name)
+        if not agent_def or not agent_def.input:
+            return inputs  # Return original if no spec
+
+        parsed_fields = self._parse_input_spec(agent_def.input)
+        field_types = {f["name"]: f["type"] for f in parsed_fields}
+
+        for k, v in inputs.items():
+            target_type = field_types.get(k)
+            if target_type and target_type.startswith("bool"):
+                typed_inputs[k] = (
+                    str(v).lower() in ["true", "on", "1", "yes"]
+                    if isinstance(v, str)
+                    else bool(v)
+                )
+            elif target_type and target_type.startswith("int"):
+                try:
+                    typed_inputs[k] = int(v)
+                except (ValueError, TypeError):
+                    logger.warning(
+                        f"Could not convert input '{k}' value '{v}' to int for agent '{agent_name}'"
+                    )
+                    typed_inputs[k] = v
+            elif target_type and target_type.startswith("float"):
+                try:
+                    typed_inputs[k] = float(v)
+                except (ValueError, TypeError):
+                    logger.warning(
+                        f"Could not convert input '{k}' value '{v}' to float for agent '{agent_name}'"
+                    )
+                    typed_inputs[k] = v
+            # TODO: Add list/dict parsing (e.g., json.loads) if needed
+            else:
+                typed_inputs[k] = v  # Assume string or already correct type
+        return typed_inputs
+
+    # --- Server Start/Stop ---
+
+    def start(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 8344,
+        server_name: str = "Flock API",
+        create_ui: bool = False,
+    ):
+        """Start the API server, optionally creating and mounting a FastHTML UI."""
+        if create_ui:
+            if not FASTHTML_AVAILABLE:
+                logger.error(
+                    "FastHTML not installed. Cannot create UI. Running API only."
+                )
+            else:
+                logger.info("Attempting to create and mount FastHTML UI at /ui")
+                try:
+                    # Pass self (FlockAPI instance) to the UI creation function
+                    # It needs access to self.flock and self._parse_input_spec
+                    fh_app = create_ui_app(
+                        self,
+                        api_host=host,
+                        api_port=port,
+                        server_name=server_name,
+                    )
+                    self.app.mount("/ui", fh_app, name="ui")
+                    logger.info("FastHTML UI mounted successfully.")
+
+                    # Add root redirect only if UI was successfully mounted
+                    @self.app.get(
+                        "/",
+                        include_in_schema=False,
+                        response_class=RedirectResponse,
+                    )
+                    async def root_redirect():
+                        logger.debug("Redirecting / to /ui/")
+                        return "/ui/"
+
+                except ImportError as e:
+                    logger.error(
+                        f"Could not create UI due to import error: {e}. Running API only."
+                    )
+                except Exception as e:
+                    logger.error(
+                        f"An error occurred setting up the UI: {e}. Running API only.",
+                        exc_info=True,
+                    )
+
+        logger.info(f"Starting API server on http://{host}:{port}")
+        if (
+            create_ui
+            and FASTHTML_AVAILABLE
+            and any(
+                m.path == "/ui" for m in self.app.routes if hasattr(m, "path")
+            )
+        ):
+            logger.info(f"UI available at http://{host}:{port}/ui/")
+
+        uvicorn.run(self.app, host=host, port=port)
+
+    async def stop(self):
+        """Stop the API server."""
+        logger.info("Stopping API server (cleanup if necessary)")
+        pass  # Add cleanup logic if needed
+
+
+# --- End of file ---

flock/core/api/models.py

@@ -0,0 +1,34 @@
+# src/flock/core/api/models.py
+"""Pydantic models for the Flock API."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class FlockAPIRequest(BaseModel):
+    """Request model for running an agent via JSON API."""
+
+    agent_name: str = Field(..., description="Name of the agent to run")
+    inputs: dict[str, Any] = Field(
+        default_factory=dict, description="Input data for the agent"
+    )
+    async_run: bool = Field(
+        default=False, description="Whether to run asynchronously"
+    )
+
+
+class FlockAPIResponse(BaseModel):
+    """Response model for API run requests."""
+
+    run_id: str = Field(..., description="Unique ID for this run")
+    status: str = Field(..., description="Status of the run")
+    result: dict[str, Any] | None = Field(
+        None, description="Run result if completed"
+    )
+    started_at: datetime = Field(..., description="When the run started")
+    completed_at: datetime | None = Field(
+        None, description="When the run completed"
+    )
+    error: str | None = Field(None, description="Error message if failed")

flock/core/api/run_store.py

@@ -0,0 +1,72 @@
+# src/flock/core/api/run_store.py
+"""Manages the state of active and completed Flock runs."""
+
+import threading
+from datetime import datetime
+
+from flock.core.logging.logging import get_logger
+
+from .models import FlockAPIResponse  # Import from the models file
+
+logger = get_logger("api.run_store")
+
+
+class RunStore:
+    """Stores and manages the state of Flock runs."""
+
+    def __init__(self):
+        self._runs: dict[str, FlockAPIResponse] = {}
+        self._lock = threading.Lock()  # Basic lock for thread safety
+
+    def create_run(self, run_id: str) -> FlockAPIResponse:
+        """Creates a new run record with 'starting' status."""
+        with self._lock:
+            if run_id in self._runs:
+                logger.warning(f"Run ID {run_id} already exists. Overwriting.")
+            response = FlockAPIResponse(
+                run_id=run_id, status="starting", started_at=datetime.now()
+            )
+            self._runs[run_id] = response
+            logger.debug(f"Created run record for run_id: {run_id}")
+            return response
+
+    def get_run(self, run_id: str) -> FlockAPIResponse | None:
+        """Gets the status of a run."""
+        with self._lock:
+            return self._runs.get(run_id)
+
+    def update_run_status(
+        self, run_id: str, status: str, error: str | None = None
+    ):
+        """Updates the status and potentially error of a run."""
+        with self._lock:
+            if run_id in self._runs:
+                self._runs[run_id].status = status
+                if error:
+                    self._runs[run_id].error = error
+                if status in ["completed", "failed"]:
+                    self._runs[run_id].completed_at = datetime.now()
+                logger.debug(f"Updated status for run_id {run_id} to {status}")
+            else:
+                logger.warning(
+                    f"Attempted to update status for non-existent run_id: {run_id}"
+                )
+
+    def update_run_result(self, run_id: str, result: dict):
+        """Updates the result of a completed run."""
+        with self._lock:
+            if run_id in self._runs:
+                # Ensure result is serializable (e.g., convert Box)
+                final_result = (
+                    dict(result) if hasattr(result, "to_dict") else result
+                )
+                self._runs[run_id].result = final_result
+                self._runs[run_id].status = "completed"
+                self._runs[run_id].completed_at = datetime.now()
+                logger.debug(f"Updated result for completed run_id: {run_id}")
+            else:
+                logger.warning(
+                    f"Attempted to update result for non-existent run_id: {run_id}"
+                )
+
+    # Add methods for cleanup, persistence, etc. later