flock-core 0.4.543__py3-none-any.whl → 0.5.0__py3-none-any.whl

flock/core/api/custom_endpoint.py

@@ -1,45 +0,0 @@
-"""Lightweight helper object for declaring additional REST routes.
-
-Developers can pass instances of :class:`FlockEndpoint` to
-``Flock.start_api(custom_endpoints=[...])`` instead of the terse dictionary
-syntax.  The class carries optional Pydantic request/response models plus
-OpenAPI metadata so the generated docs look perfect.
-"""
-from __future__ import annotations
-
-from collections.abc import Callable
-from typing import Any
-
-from pydantic import BaseModel
-
-__all__ = [
-    "FlockEndpoint",
-]
-
-
-class FlockEndpoint(BaseModel):
-    """Declarative description of an extra API route."""
-
-    path: str
-    methods: list[str] = ["GET"]
-    callback: Callable[..., Any]
-
-    # Optional schema models
-    request_model: type[BaseModel] | None = None
-    response_model: type[BaseModel] | None = None
-    # Query-string parameters as a Pydantic model (treated as Depends())
-    query_model: type[BaseModel] | None = None
-
-    # OpenAPI / Swagger metadata
-    summary: str | None = None
-    description: str | None = None
-    name: str | None = None  # Route name in FastAPI
-    include_in_schema: bool = True
-
-    # FastAPI dependency injections (e.g. security)
-    dependencies: list[Any] | None = None
-
-    model_config = {
-        "arbitrary_types_allowed": True,
-        "validate_default": True,
-    }

flock/core/api/endpoints.py

@@ -1,262 +0,0 @@
-# src/flock/core/api/endpoints.py
-"""FastAPI endpoints for the Flock API, using FastAPI's dependency injection."""
-
-import uuid
-from typing import TYPE_CHECKING
-
-from fastapi import (
-    APIRouter,
-    BackgroundTasks,
-    Depends,  # Crucial import for dependency injection
-    HTTPException,
-)
-
-from flock.core.logging.logging import get_logger
-
-# Import the dependency provider functions
-# This assumes you'll create 'src/flock/webapp/app/dependencies.py' (or similar)
-# with get_flock_instance and get_run_store functions.
-# For now, to make this file runnable in isolation for generation,
-# we might need temporary stubs or to adjust the import path later.
-# Let's assume a common location for dependencies.
-from flock.webapp.app.dependencies import get_flock_instance, get_run_store
-
-from .models import (
-    FlockAPIRequest,
-    FlockAPIResponse,
-    FlockBatchRequest,
-    FlockBatchResponse,
-)
-
-if TYPE_CHECKING:
-    from flock.core.flock import Flock
-
-    from .run_store import RunStore
-    # We also need the _run_flock, _run_batch, _type_convert_inputs methods.
-    # These will be part of the Flock instance itself or helper functions
-    # that take Flock/RunStore as arguments. For now, let's assume they
-    # are methods on the Flock instance or can be called statically with it.
-
-logger = get_logger("api.endpoints")
-
-# The create_api_router function no longer needs to be passed the FlockAPI instance
-# as dependencies will be injected directly into the route handlers.
-def create_api_router() -> APIRouter:
-    """Creates the APIRouter for core Flock API endpoints."""
-    router = APIRouter()
-
-    # --- API Endpoints ---
-    @router.post("/run/flock", response_model=FlockAPIResponse, tags=["Flock API Core"])
-    async def run_flock_workflow(
-        request_model: FlockAPIRequest, # Renamed from 'request' to avoid conflict with FastAPI's Request
-        background_tasks: BackgroundTasks,
-        flock_instance: "Flock" = Depends(get_flock_instance), # Injected
-        run_store: "RunStore" = Depends(get_run_store)          # Injected
-    ):
-        """Run a flock workflow starting with the specified agent."""
-        run_id = None
-        try:
-            run_id = str(uuid.uuid4())
-            run_store.create_run(run_id)
-            response_data = run_store.get_run(run_id)
-
-            if not response_data:
-                logger.error(f"Failed to create run record for run_id: {run_id}")
-                raise HTTPException(status_code=500, detail="Failed to initialize run.")
-
-            processed_inputs = request_model.inputs if request_model.inputs else {}
-            logger.info(
-                f"API request: run flock '{request_model.agent_name}' (run_id: {run_id})",
-                inputs=processed_inputs,
-            )
-
-            # The _run_flock logic now needs to be called. It could be a method on
-            # flock_instance, or a static/helper function that takes flock_instance.
-            # Let's assume it's a method on flock_instance for now.
-            # To avoid direct calls to private-like methods from router,
-            # Flock class would expose a public method that handles this internal logic.
-            # For this refactoring step, let's assume a helper `_execute_flock_run` exists
-            # that we can call.
-
-            async def _execute_flock_run_task(
-                run_id_task, agent_name_task, inputs_task, use_production_tools_task
-            ):
-                # This is a simplified version of what was in FlockAPI._run_flock
-                try:
-                    if agent_name_task not in flock_instance.agents:
-                        raise ValueError(f"Starting agent '{agent_name_task}' not found")
-                    # Type conversion would ideally be part of the Flock's run logic
-                    # or a utility. For now, assume it's handled or simple.
-                    # typed_inputs = flock_instance._type_convert_inputs(agent_name_task, inputs_task) # Example if kept on Flock
-                    typed_inputs = inputs_task # Simplified for now
-
-                    result = await flock_instance.run_async(
-                        start_agent=agent_name_task,
-                        input=typed_inputs,
-                        use_production_tools=use_production_tools_task,
-                    )
-                    run_store.update_run_result(run_id_task, result)
-                except Exception as e_task:
-                    logger.error(f"Error in background flock run {run_id_task}: {e_task!s}", exc_info=True)
-                    run_store.update_run_status(run_id_task, "failed", str(e_task))
-
-
-            if request_model.async_run:
-                logger.debug(
-                    f"Running flock '{request_model.agent_name}' asynchronously (run_id: {run_id})"
-                )
-                background_tasks.add_task(
-                    _execute_flock_run_task,
-                    run_id,
-                    request_model.agent_name,
-                    processed_inputs,
-                    request_model.use_production_tools,
-                )
-                run_store.update_run_status(run_id, "running")
-                response_data.status = "running"
-            else:
-                logger.debug(
-                    f"Running flock '{request_model.agent_name}' synchronously (run_id: {run_id})"
-                )
-                await _execute_flock_run_task(
-                    run_id,
-                    request_model.agent_name,
-                    processed_inputs,
-                    request_model.use_production_tools,
-                )
-                response_data = run_store.get_run(run_id)
-
-            if not response_data:
-                 logger.error(f"Run data lost for run_id: {run_id} after execution.")
-                 raise HTTPException(status_code=500, detail="Run data lost after execution.")
-
-            return response_data
-        except ValueError as ve:
-            logger.error(f"Value error starting run for agent '{request_model.agent_name}': {ve}", exc_info=True)
-            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 during flock run: {type(e).__name__}"
-            logger.error(f"Error starting flock 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.post("/run/batch", response_model=FlockBatchResponse, tags=["Flock API Core"])
-    async def run_batch_workflow(
-        request_model: FlockBatchRequest, # Renamed from 'request'
-        background_tasks: BackgroundTasks,
-        flock_instance: "Flock" = Depends(get_flock_instance),
-        run_store: "RunStore" = Depends(get_run_store)
-    ):
-        """Run a batch of inputs through the flock workflow."""
-        batch_id = None
-        try:
-            if request_model.agent_name not in flock_instance.agents:
-                raise ValueError(f"Agent '{request_model.agent_name}' not found in current Flock.")
-
-            if isinstance(request_model.batch_inputs, list) and not request_model.batch_inputs:
-                raise ValueError("Batch inputs list cannot be empty if provided as a list.")
-
-            batch_id = str(uuid.uuid4())
-            run_store.create_batch(batch_id)
-            response_data = run_store.get_batch(batch_id)
-
-            if not response_data:
-                logger.error(f"Failed to create batch record for batch_id: {batch_id}")
-                raise HTTPException(status_code=500, detail="Failed to initialize batch run.")
-
-            batch_size = (
-                len(request_model.batch_inputs)
-                if isinstance(request_model.batch_inputs, list)
-                else "CSV/DataFrame"
-            )
-            logger.info(
-                f"API request: run batch with '{request_model.agent_name}' (batch_id: {batch_id})",
-                batch_size=batch_size,
-            )
-
-            async def _execute_flock_batch_task(batch_id_task, batch_request_task: FlockBatchRequest):
-                # This is a simplified version of what was in FlockAPI._run_batch
-                try:
-                    # Directly use the flock_instance's run_batch_async method
-                    results = await flock_instance.run_batch_async(
-                        start_agent=batch_request_task.agent_name,
-                        batch_inputs=batch_request_task.batch_inputs,
-                        input_mapping=batch_request_task.input_mapping,
-                        static_inputs=batch_request_task.static_inputs,
-                        parallel=batch_request_task.parallel,
-                        max_workers=batch_request_task.max_workers,
-                        use_temporal=batch_request_task.use_temporal,
-                        box_results=batch_request_task.box_results,
-                        return_errors=batch_request_task.return_errors,
-                        silent_mode=True, # API batch runs should be internally silent
-                        write_to_csv=None # API handles CSV writing based on request if needed, not here
-                    )
-                    run_store.update_batch_result(batch_id_task, results)
-                    logger.info(f"Batch run completed (batch_id: {batch_id_task})", num_results=len(results))
-                except Exception as e_task:
-                    logger.error(f"Error in background flock batch {batch_id_task}: {e_task!s}", exc_info=True)
-                    run_store.update_batch_status(batch_id_task, "failed", str(e_task))
-
-            logger.debug(
-                f"Running batch with '{request_model.agent_name}' asynchronously (batch_id: {batch_id})"
-            )
-            background_tasks.add_task(
-                _execute_flock_batch_task,
-                batch_id,
-                request_model, # Pass the Pydantic request model
-            )
-            run_store.update_batch_status(batch_id, "running")
-            response_data.status = "running"
-
-            return response_data
-        except ValueError as ve:
-            error_msg = f"Value error starting batch for agent '{request_model.agent_name}': {ve}"
-            logger.error(error_msg, exc_info=True)
-            if batch_id: run_store.update_batch_status(batch_id, "failed", str(ve))
-            raise HTTPException(status_code=400, detail=str(ve))
-        except Exception as e:
-            error_msg = f"Internal server error during batch run: {type(e).__name__}: {e!s}"
-            logger.error(error_msg, exc_info=True)
-            if batch_id: run_store.update_batch_status(batch_id, "failed", error_msg)
-            raise HTTPException(status_code=500, detail=error_msg)
-
-    @router.get("/run/{run_id}", response_model=FlockAPIResponse, tags=["Flock API Core"])
-    async def get_run_status(
-        run_id: str,
-        run_store: "RunStore" = Depends(get_run_store)
-    ):
-        """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("/batch/{batch_id}", response_model=FlockBatchResponse, tags=["Flock API Core"])
-    async def get_batch_status(
-        batch_id: str,
-        run_store: "RunStore" = Depends(get_run_store)
-    ):
-        """Get the status and results of a specific batch run."""
-        logger.debug(f"API request: get status for batch_id: {batch_id}")
-        batch_data = run_store.get_batch(batch_id)
-        if not batch_data:
-            logger.warning(f"Batch ID not found: {batch_id}")
-            raise HTTPException(status_code=404, detail="Batch not found")
-        return batch_data
-
-    @router.get("/agents", tags=["Flock API Core"])
-    async def list_agents(
-        flock_instance: "Flock" = Depends(get_flock_instance)
-    ):
-        """List all available agents in the currently loaded Flock."""
-        logger.debug("API request: list agents")
-        agents_list = [
-            {"name": agent.name, "description": agent.resolved_description or agent.name}
-            for agent in flock_instance.agents.values()
-        ]
-        return {"agents": agents_list}
-
-    return router

flock/core/api/main.py

@@ -1,162 +0,0 @@
-# src/flock/core/api/main.py
-"""This module defines the FlockAPI class, which is now primarily responsible for
-managing and adding user-defined custom API endpoints to a main FastAPI application.
-"""
-
-import inspect
-from collections.abc import Callable, Sequence
-from typing import TYPE_CHECKING, Any
-
-from fastapi import (  # Ensure Request is aliased
-    Body,
-    Depends,
-    FastAPI,
-    Request as FastAPIRequest,
-)
-
-from flock.core.logging.logging import get_logger
-
-from .custom_endpoint import FlockEndpoint
-
-if TYPE_CHECKING:
-    from flock.core.flock import Flock
-
-logger = get_logger("core.api.custom_setup")
-
-
-class FlockAPI:
-    """A helper class to manage the addition of user-defined custom API endpoints
-    to an existing FastAPI application, in the context of a Flock instance.
-    """
-
-    def __init__(
-        self,
-        flock_instance: "Flock",
-        custom_endpoints: Sequence[FlockEndpoint] | dict[tuple[str, list[str] | None], Callable[..., Any]] | None = None,
-    ):
-        self.flock = flock_instance
-        self.processed_custom_endpoints: list[FlockEndpoint] = []
-        if custom_endpoints:
-            if isinstance(custom_endpoints, dict):
-                logger.warning("Received custom_endpoints as dict, converting. Prefer Sequence[FlockEndpoint].")
-                for (path, methods), cb in custom_endpoints.items():
-                    self.processed_custom_endpoints.append(
-                        FlockEndpoint(path=path, methods=list(methods) if methods else ["GET"], callback=cb)
-                    )
-            elif isinstance(custom_endpoints, Sequence):
-                for ep_item in custom_endpoints: # Renamed loop variable
-                    if isinstance(ep_item, FlockEndpoint):
-                        self.processed_custom_endpoints.append(ep_item)
-                    else:
-                        logger.warning(f"Skipping non-FlockEndpoint item in custom_endpoints sequence: {type(ep_item)}")
-            else:
-                logger.warning(f"Unsupported type for custom_endpoints: {type(custom_endpoints)}")
-        logger.info(
-            f"FlockAPI helper initialized for Flock: '{self.flock.name}'. "
-            f"Prepared {len(self.processed_custom_endpoints)} custom endpoints."
-        )
-
-    def add_custom_routes_to_app(self, app: FastAPI):
-        if not self.processed_custom_endpoints:
-            logger.debug("No custom endpoints to add to the FastAPI app.")
-            return
-
-        logger.info(f"Adding {len(self.processed_custom_endpoints)} custom endpoints to the FastAPI app instance.")
-
-        for current_ep_def in self.processed_custom_endpoints: # Use current_ep_def to avoid closure issues
-
-            # This factory now takes current_ep_def to ensure it uses the correct endpoint's details
-            def _create_handler_factory(
-                # Capture the specific endpoint definition for this factory instance
-                specific_ep: FlockEndpoint
-            ):
-                # This inner function prepares the payload and calls the user's callback
-                async def _invoke_user_callback(
-                    request_param: FastAPIRequest, # Parameter for FastAPI's Request object
-                    body_param: Any,      # Will be populated by the _route_handler
-                    query_param: Any      # Will be populated by the _route_handler
-                ):
-                    payload_to_user: dict[str, Any] = {"flock": self.flock} # self here refers to FlockAPI instance
-
-                    if request_param: # Ensure request_param is not None
-                        payload_to_user.update(request_param.path_params)
-                        # query_param is already the parsed Pydantic model or None
-                        if specific_ep.query_model and query_param is not None:
-                            payload_to_user["query"] = query_param
-                        # Fallback for raw query if callback expects 'query' but no query_model was set
-                        elif 'query' in inspect.signature(specific_ep.callback).parameters and not specific_ep.query_model:
-                             if request_param.query_params:
-                                payload_to_user["query"] = dict(request_param.query_params)
-
-                        # body_param is already the parsed Pydantic model or None
-                        if specific_ep.request_model and body_param is not None:
-                            payload_to_user["body"] = body_param
-                        # Fallback for raw body if callback expects 'body' but no request_model was set
-                        elif 'body' in inspect.signature(specific_ep.callback).parameters and \
-                             not specific_ep.request_model and \
-                             request_param.method in {"POST", "PUT", "PATCH"}:
-                            try: payload_to_user["body"] = await request_param.json()
-                            except Exception: payload_to_user["body"] = await request_param.body()
-
-                        # If user callback explicitly asks for 'request'
-                        if 'request' in inspect.signature(specific_ep.callback).parameters:
-                            payload_to_user['request'] = request_param
-
-
-                    user_callback_sig = inspect.signature(specific_ep.callback)
-                    final_kwargs = {
-                        k: v for k, v in payload_to_user.items() if k in user_callback_sig.parameters
-                    }
-
-                    if inspect.iscoroutinefunction(specific_ep.callback):
-                        return await specific_ep.callback(**final_kwargs)
-                    return specific_ep.callback(**final_kwargs)
-
-                # --- Select the correct handler signature based on specific_ep's models ---
-                if specific_ep.request_model and specific_ep.query_model:
-                    async def _route_handler_body_query(
-                        request: FastAPIRequest, # Correct alias for FastAPI Request
-                        body: specific_ep.request_model = Body(...),  # type: ignore
-                        query: specific_ep.query_model = Depends(specific_ep.query_model)  # type: ignore
-                    ):
-                        return await _invoke_user_callback(request, body, query)
-                    return _route_handler_body_query
-                elif specific_ep.request_model and not specific_ep.query_model:
-                    async def _route_handler_body_only(
-                        request: FastAPIRequest, # Correct alias
-                        body: specific_ep.request_model = Body(...)  # type: ignore
-                    ):
-                        return await _invoke_user_callback(request, body, None)
-                    return _route_handler_body_only
-                elif not specific_ep.request_model and specific_ep.query_model:
-                    async def _route_handler_query_only(
-                        request: FastAPIRequest, # Correct alias
-                        query: specific_ep.query_model = Depends(specific_ep.query_model)  # type: ignore
-                    ):
-                        return await _invoke_user_callback(request, None, query)
-                    return _route_handler_query_only
-                else: # Neither request_model nor query_model
-                    async def _route_handler_request_only(
-                        request: FastAPIRequest # Correct alias
-                    ):
-                        return await _invoke_user_callback(request, None, None)
-                    return _route_handler_request_only
-
-            # Create the handler for the current_ep_def
-            selected_handler = _create_handler_factory(current_ep_def) # Pass current_ep_def
-            selected_handler.__name__ = f"handler_for_{current_ep_def.path.replace('/', '_').lstrip('_')}_{current_ep_def.methods[0]}"
-
-
-            app.add_api_route(
-                current_ep_def.path,
-                selected_handler,
-                methods=current_ep_def.methods or ["GET"],
-                name=current_ep_def.name or f"custom:{current_ep_def.path.replace('/', '_').lstrip('_')}",
-                include_in_schema=current_ep_def.include_in_schema,
-                response_model=current_ep_def.response_model,
-                summary=current_ep_def.summary,
-                description=current_ep_def.description,
-                dependencies=current_ep_def.dependencies,
-                tags=["Flock API Custom Endpoints"],
-            )
-            logger.debug(f"Added custom route to app: {current_ep_def.methods} {current_ep_def.path} (Handler: {selected_handler.__name__}, Summary: {current_ep_def.summary})")

flock/core/api/models.py

@@ -1,101 +0,0 @@
-# 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"
-    )
-    use_production_tools: bool = Field(
-        default=False,
-        description="If true, run agents with their production tool set where available",
-    )
-
-
-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")
-
-
-class FlockBatchRequest(BaseModel):
-    """Request model for batch processing via JSON API."""
-
-    agent_name: str = Field(..., description="Name of the agent to run")
-    batch_inputs: list[dict[str, Any]] | str = Field(
-        ..., description="List of input dictionaries or path to CSV file"
-    )
-    input_mapping: dict[str, str] | None = Field(
-        None, description="Maps DataFrame/CSV column names to agent input keys"
-    )
-    static_inputs: dict[str, Any] | None = Field(
-        None, description="Inputs constant across all batch runs"
-    )
-    parallel: bool = Field(
-        default=True, description="Whether to run jobs in parallel"
-    )
-    max_workers: int = Field(
-        default=5, description="Max concurrent workers for parallel runs"
-    )
-    use_temporal: bool | None = Field(
-        None, description="Override Flock's enable_temporal setting"
-    )
-    box_results: bool = Field(
-        default=True, description="Wrap results in Box objects"
-    )
-    return_errors: bool = Field(
-        default=False, description="Return Exception objects for failed runs"
-    )
-    silent_mode: bool = Field(
-        default=True, description="Suppress output and show progress bar"
-    )
-    write_to_csv: str | None = Field(
-        None, description="Path to save results as CSV file"
-    )
-
-
-class FlockBatchResponse(BaseModel):
-    """Response model for batch processing requests."""
-
-    batch_id: str = Field(..., description="Unique ID for this batch run")
-    status: str = Field(..., description="Status of the batch run")
-    results: list[Any] = Field(
-        default_factory=list,
-        description="List of results from batch processing",
-    )
-    started_at: datetime = Field(..., description="When the batch run started")
-    completed_at: datetime | None = Field(
-        None, description="When the batch run completed"
-    )
-    error: str | None = Field(None, description="Error message if failed")
-
-    # Additional fields for batch progress tracking
-    total_items: int = Field(
-        0, description="Total number of items in the batch"
-    )
-    completed_items: int = Field(
-        0, description="Number of completed items in the batch"
-    )
-    progress_percentage: float = Field(
-        0.0, description="Percentage of completion (0-100)"
-    )