From d1d2bdd720bafba6020cc951deeb98840a3cf549 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Mon, 12 Jan 2026 14:26:31 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`agentco?= =?UTF-8?q?re=5Fnative`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @giladivry. * https://github.com/qualifire-dev/rogue/pull/148#issuecomment-3738797701 The following files were modified: * `rogue/server/api/agentcore.py` * `rogue/server/api/evaluation.py` * `rogue/server/main.py` --- rogue/server/api/agentcore.py | 17 ++++++++++++++- rogue/server/api/evaluation.py | 39 +++++++++++++++++++++++++++++++++- rogue/server/main.py | 12 ++++++++++- 3 files changed, 65 insertions(+), 3 deletions(-) diff --git a/rogue/server/api/agentcore.py b/rogue/server/api/agentcore.py index 55f10866..d7d392d4 100644 --- a/rogue/server/api/agentcore.py +++ b/rogue/server/api/agentcore.py @@ -8,6 +8,12 @@ @router.get("/ping") def ping(): + """ + Return the service health status used for liveness checks. + + Returns: + dict: JSON object with key "status" whose value is "Healthy". + """ return {"status": "Healthy"} @@ -18,9 +24,18 @@ async def invocations( evaluation_service: EvaluationService = Depends(get_evaluation_service), ): # different entrypoint to /evaluations to meet agentcore convention + """ + Enqueue an evaluation request using the agentcore `/invocations` convention. + + Parameters: + request (EvaluationRequest): The evaluation request payload to be processed. + + Returns: + EvaluationResponse: The enqueued evaluation's status and result data. + """ return await enqueue_evaluation( request=request, background_tasks=background_tasks, evaluation_service=evaluation_service, endpoint="/invocations", - ) + ) \ No newline at end of file diff --git a/rogue/server/api/evaluation.py b/rogue/server/api/evaluation.py index da72aa1c..0e167bb9 100644 --- a/rogue/server/api/evaluation.py +++ b/rogue/server/api/evaluation.py @@ -21,6 +21,14 @@ @lru_cache(1) def get_evaluation_service(): + """ + Provide a single shared EvaluationService instance for request handlers. + + Subsequent calls return the same service instance to ensure a single, shared EvaluationService is used across the application. + + Returns: + EvaluationService: The shared EvaluationService instance. + """ return EvaluationService() @@ -30,6 +38,18 @@ async def enqueue_evaluation( evaluation_service: EvaluationService, endpoint: str, ): + """ + Enqueue a new evaluation job and schedule its execution as a background task. + + Parameters: + request (EvaluationRequest): The evaluation request payload containing agent configuration, scenarios, and execution parameters. + background_tasks (BackgroundTasks): FastAPI background task registry used to schedule job execution. + evaluation_service (EvaluationService): Service responsible for persisting and running evaluation jobs. + endpoint (str): The API endpoint path used for context and logging. + + Returns: + EvaluationResponse: Contains the created `job_id`, `status` set to `EvaluationStatus.PENDING`, and a success message. + """ job_id = str(uuid.uuid4()) # Set logging context @@ -88,6 +108,12 @@ async def create_evaluation( background_tasks: BackgroundTasks, evaluation_service: EvaluationService = Depends(get_evaluation_service), ): + """ + Enqueue an evaluation job for processing and return the created job response. + + Returns: + EvaluationResponse: Contains the enqueued job's `job_id`, `status`, and a confirmation message. + """ return await enqueue_evaluation( request=request, background_tasks=background_tasks, @@ -103,6 +129,17 @@ async def list_evaluations( offset: int = 0, evaluation_service: EvaluationService = Depends(get_evaluation_service), ): + """ + Retrieve a paginated list of evaluation jobs, optionally filtered by status. + + Parameters: + status (Optional[EvaluationStatus]): If provided, only include jobs with this status. + limit (int): Maximum number of jobs to return. + offset (int): Number of jobs to skip before collecting the result set. + + Returns: + JobListResponse: Contains `jobs` (the returned page of EvaluationJob items) and `total` (the total count of jobs matching the filter). + """ jobs = await evaluation_service.get_jobs( status=status, limit=limit, @@ -133,4 +170,4 @@ async def cancel_evaluation( success = await evaluation_service.cancel_job(job_id) if not success: raise HTTPException(status_code=404, detail="Evaluation job not found") - return {"message": "Evaluation job cancelled successfully"} + return {"message": "Evaluation job cancelled successfully"} \ No newline at end of file diff --git a/rogue/server/main.py b/rogue/server/main.py index 0c4b372f..49e9b29f 100644 --- a/rogue/server/main.py +++ b/rogue/server/main.py @@ -47,6 +47,16 @@ async def lifespan(app: FastAPI): def create_app() -> FastAPI: + """ + Create and configure the FastAPI application for the Rogue Agent Evaluator. + + The returned app is configured with CORS middleware (allowing all origins and credentials, + and standard methods/headers) and registers the health, evaluation, red-team, LLM, + interview, and websocket routers under the /api/v1 prefix, plus the agent core router at the root. + + Returns: + FastAPI: A configured FastAPI application instance. + """ app = FastAPI( title="Rogue Agent Evaluator API", description="API server for the Rogue Agent Evaluator system", @@ -115,4 +125,4 @@ def start_server( host = os.getenv("HOST", "127.0.0.1") port = int(os.getenv("PORT", "8000")) reload = os.getenv("RELOAD", "false").lower() in ("true", "1", "yes") - start_server(host, port, reload) + start_server(host, port, reload) \ No newline at end of file