flock-core 0.3.23__py3-none-any.whl → 0.3.31__py3-none-any.whl

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

flock/core/api/ui/routes.py

@@ -0,0 +1,271 @@
+# src/flock/core/api/ui/routes.py
+"""FastHTML UI routes for the Flock API."""
+
+from typing import TYPE_CHECKING
+
+# --- Conditional FastHTML Imports ---
+try:
+    import httpx
+    from fasthtml.common import *
+
+    # Import Form explicitly with an alias to avoid collisions
+    from fasthtml.common import Form as FHForm
+
+    FASTHTML_AVAILABLE = True
+except ImportError:
+    FASTHTML_AVAILABLE = False
+
+    # Define necessary dummies if not available
+    class Request:
+        pass
+
+    class Titled:
+        pass
+
+    class Div:
+        pass
+
+    class H1:
+        pass
+
+    class P:
+        pass
+
+    class H2:
+        pass
+
+    class Pre:
+        pass
+
+    class Code:
+        pass
+
+    class Label:
+        pass
+
+    class Select:
+        pass
+
+    class Option:
+        pass
+
+    class FHForm:
+        pass  # Dummy alias if not available
+
+    class Button:
+        pass
+
+    class Span:
+        pass
+
+    class Script:
+        pass
+
+    class Style:
+        pass
+
+    class Hidden:
+        pass
+
+    class Textarea:
+        pass
+
+    class Input:
+        pass
+
+    def fast_app():
+        return None, None
+
+    def picolink():
+        return None
+# ------------------------------------
+
+# Use TYPE_CHECKING to avoid circular import errors for type hints
+if TYPE_CHECKING:
+    from flock.core.api.main import FlockAPI
+
+# Import logger and utils needed by UI routes
+from flock.core.logging.logging import get_logger
+
+logger = get_logger("api.ui")
+
+
+def create_ui_app(
+    flock_api_instance: "FlockAPI",
+    api_host: str,
+    api_port: int,
+    server_name: str,
+) -> Any:
+    """Creates and configures the FastHTML application and its routes."""
+    if not FASTHTML_AVAILABLE:
+        raise ImportError("FastHTML is not installed. Cannot create UI.")
+    logger.debug("Creating FastHTML application instance for UI")
+
+    # Use the passed FlockAPI instance to access necessary data/methods
+    flock_instance = flock_api_instance.flock
+    parse_input_spec_func = (
+        flock_api_instance._parse_input_spec
+    )  # Get reference to parser
+
+    fh_app, fh_rt = fast_app(
+        hdrs=(
+            Script(src="https://unpkg.com/htmx.org@1.9.10/dist/htmx.min.js"),
+            picolink,  # Pass directly
+            Style("""
+            body { padding: 20px; max-width: 800px; margin: auto; font-family: sans-serif; }
+            label { display: block; margin-top: 1rem; font-weight: bold;}
+            input, select, textarea { width: 100%; margin-top: 0.25rem; padding: 0.5rem; border: 1px solid #ccc; border-radius: 4px; box-sizing: border-box; }
+            input[type=checkbox] { width: auto; margin-right: 0.5rem; vertical-align: middle; }
+            label[for^=input_] { font-weight: normal; display: inline; margin-top: 0;} /* Style for checkbox labels */
+            button[type=submit] { margin-top: 1.5rem; padding: 0.75rem 1.5rem; background-color: #007bff; color: white; border: none; border-radius: 4px; cursor: pointer; font-size: 1rem;}
+            button[type=submit]:hover { background-color: #0056b3; }
+            #result-area { margin-top: 2rem; background-color: #f8f9fa; padding: 15px; border: 1px solid #dee2e6; border-radius: 5px; white-space: pre-wrap; word-wrap: break-word; font-family: monospace; }
+            .htmx-indicator { display: none; margin-left: 10px; font-style: italic; color: #6c757d; }
+            .htmx-request .htmx-indicator { display: inline; }
+            .htmx-request.htmx-indicator { display: inline; }
+            .error-message { color: #721c24; margin-top: 10px; font-weight: bold; background-color: #f8d7da; border: 1px solid #f5c6cb; padding: 10px; border-radius: 5px;}
+        """),
+        )
+    )
+
+    @fh_rt("/get-agent-inputs")
+    def get_agent_inputs(request: Request):
+        """Endpoint called by HTMX to get agent input fields."""
+        agent_name = request.query_params.get("agent_name")
+        logger.debug(f"UI requesting inputs for agent: {agent_name}")
+        if not agent_name:
+            return Div("Please select an agent.", cls="error-message")
+
+        # Access agents via the passed FlockAPI instance
+        agent_def = flock_instance.agents.get(agent_name)
+        if not agent_def:
+            logger.warning(f"Agent '{agent_name}' not found for UI.")
+            return Div(f"Agent '{agent_name}' not found.", cls="error-message")
+
+        # Use the parsing function from the FlockAPI instance
+        input_fields = parse_input_spec_func(agent_def.input or "")
+        logger.debug(f"Parsed input fields for {agent_name}: {input_fields}")
+
+        inputs_html = []
+        for field in input_fields:
+            field_id = f"input_{field['name']}"
+            label_text = f"{field['name']}"
+            if field["type"] != "bool":
+                label_text += f" ({field['type']})"
+            label = Label(label_text, fr=field_id)
+            input_attrs = dict(
+                id=field_id,
+                name=f"inputs.{field['name']}",
+                type=field["html_type"],
+            )
+            if field.get("step"):
+                input_attrs["step"] = field["step"]
+            if field.get("desc"):
+                input_attrs["placeholder"] = field["desc"]
+            if field.get("rows"):
+                input_attrs["rows"] = field["rows"]
+
+            if field["html_type"] == "textarea":
+                input_el = Textarea(**input_attrs)
+            elif field["html_type"] == "checkbox":
+                input_el = Div(
+                    Input(**input_attrs, value="true"),
+                    Label(f" Enable?", fr=field_id),
+                )
+            else:
+                input_el = Input(**input_attrs)
+
+            inputs_html.append(
+                Div(label, input_el, style="margin-bottom: 1rem;")
+            )
+
+        inputs_html.append(
+            Hidden(
+                id="selected_agent_name", name="agent_name", value=agent_name
+            )
+        )
+        return (
+            Div(*inputs_html)
+            if inputs_html
+            else P("This agent requires no input.")
+        )
+
+    @fh_rt("/")
+    async def ui_root(request: Request):
+        """Serves the main UI page."""
+        logger.info("Serving main UI page /ui/")
+        agents_list = []
+        error_msg = None
+        api_url = f"http://{api_host}:{api_port}/agents"
+        try:
+            async with httpx.AsyncClient() as client:
+                logger.debug(f"UI fetching agents from {api_url}")
+                response = await client.get(api_url)
+                response.raise_for_status()
+                agent_data = response.json()
+                agents_list = agent_data.get("agents", [])
+                logger.debug(f"Fetched {len(agents_list)} agents for UI")
+        except Exception as e:
+            error_msg = f"UI Error: Could not fetch agent list from API at {api_url}. Details: {e}"
+            logger.error(error_msg, exc_info=True)
+
+        options = [
+            Option("-- Select Agent --", value="", selected=True, disabled=True)
+        ] + [
+            Option(
+                f"{agent['name']}: {agent['description']}", value=agent["name"]
+            )
+            for agent in agents_list
+        ]
+
+        # Use FHForm alias here
+        content = Div(
+            H2(f"Agent Runner"),
+            P(
+                "Select an agent, provide the required inputs, and click 'Run Flock'."
+            ),
+            Label("Select Starting Agent:", fr="agent_select"),
+            Select(
+                *options,
+                id="agent_select",
+                name="agent_name",
+                hx_get="/ui/get-agent-inputs",
+                hx_trigger="change",
+                hx_target="#agent-inputs-container",
+                hx_indicator="#loading-indicator",
+            ),
+            FHForm(
+                Div(id="agent-inputs-container", style="margin-top: 1rem;"),
+                Button("Run Flock", type="submit"),
+                Span(
+                    " Processing...",
+                    id="loading-indicator",
+                    cls="htmx-indicator",
+                ),
+                hx_post="/ui/run-agent-form",  # Target the dedicated form endpoint
+                hx_target="#result-area",
+                hx_swap="innerHTML",
+                hx_indicator="#loading-indicator",
+            ),
+            H2("Result"),
+            Div(
+                Pre(
+                    Code(
+                        "Result will appear here...",
+                        id="result-content",
+                        class_="language-json",
+                    )
+                ),
+                id="result-area",
+                style="min-height: 100px;",
+            ),
+        )
+
+        if error_msg:
+            content = Div(
+                H1("Flock UI - Error"), P(error_msg, cls="error-message")
+            )
+
+        return Titled(f"{server_name}", content)
+
+    return fh_app