Merge pull request lightspeed-core#375 from tisnik/docstrings-for-endpoints-1

Docstrings for endpoints handlers

Author: tisnik

src/app/endpoints/authorized.py

@@ -33,7 +33,15 @@
 async def authorized_endpoint_handler(
     auth: Any = Depends(auth_dependency),
 ) -> AuthorizedResponse:
-    """Handle request to the /authorized endpoint."""
+    """
+    Handle request to the /authorized endpoint.
+
+    Process POST requests to the /authorized endpoint, returning
+    the authenticated user's ID and username.
+
+    Returns:
+        AuthorizedResponse: Contains the user ID and username of the authenticated user.
+    """
     # Ignore the user token, we should not return it in the response
     user_id, user_name, _ = auth
     return AuthorizedResponse(user_id=user_id, username=user_name)

src/app/endpoints/config.py

@@ -57,7 +57,15 @@
 
 @router.get("/config", responses=get_config_responses)
 def config_endpoint_handler(_request: Request) -> Configuration:
-    """Handle requests to the /config endpoint."""
+    """
+    Handle requests to the /config endpoint.
+
+    Process GET requests to the /config endpoint and returns the
+    current service configuration.
+
+    Returns:
+        Configuration: The loaded service configuration object.
+    """
     # ensure that configuration is loaded
     check_configuration_loaded(configuration)
 

src/app/endpoints/health.py

@@ -23,10 +23,13 @@
 
 
 async def get_providers_health_statuses() -> list[ProviderHealthStatus]:
-    """Check health of all providers.
+    """
+    Retrieve the health status of all configured providers.
 
     Returns:
-        List of provider health statuses.
+        list[ProviderHealthStatus]: A list containing the health
+        status of each provider. If provider health cannot be
+        determined, returns a single entry indicating an error.
     """
     try:
         client = AsyncLlamaStackClientHolder().get_client()
@@ -70,7 +73,13 @@ async def get_providers_health_statuses() -> list[ProviderHealthStatus]:
 
 @router.get("/readiness", responses=get_readiness_responses)
 async def readiness_probe_get_method(response: Response) -> ReadinessResponse:
-    """Ready status of service with provider health details."""
+    """
+    Handle the readiness probe endpoint, returning service readiness.
+
+    If any provider reports an error status, responds with HTTP 503
+    and details of unhealthy providers; otherwise, indicates the
+    service is ready.
+    """
     provider_statuses = await get_providers_health_statuses()
 
     # Check if any provider is unhealthy (not counting not_implemented as unhealthy)
@@ -104,5 +113,10 @@ async def readiness_probe_get_method(response: Response) -> ReadinessResponse:
 
 @router.get("/liveness", responses=get_liveness_responses)
 def liveness_probe_get_method() -> LivenessResponse:
-    """Live status of service."""
+    """
+    Return the liveness status of the service.
+
+    Returns:
+        LivenessResponse: Indicates that the service is alive.
+    """
     return LivenessResponse(alive=True)

src/app/endpoints/info.py

@@ -23,5 +23,13 @@
 
 @router.get("/info", responses=get_info_responses)
 def info_endpoint_handler(_request: Request) -> InfoResponse:
-    """Handle request to the /info endpoint."""
+    """
+    Handle request to the /info endpoint.
+
+    Process GET requests to the /info endpoint, returning the
+    service name and version.
+
+    Returns:
+        InfoResponse: An object containing the service's name and version.
+    """
     return InfoResponse(name=configuration.configuration.name, version=__version__)

src/app/endpoints/metrics.py

@@ -14,7 +14,16 @@
 
 @router.get("/metrics", response_class=PlainTextResponse)
 async def metrics_endpoint_handler(_request: Request) -> PlainTextResponse:
-    """Handle request to the /metrics endpoint."""
+    """
+    Handle request to the /metrics endpoint.
+
+    Process GET requests to the /metrics endpoint, returning the
+    latest Prometheus metrics in form of a plain text.
+
+    Initializes model metrics on the first request if not already
+    set up, then responds with the current metrics snapshot in
+    Prometheus format.
+    """
     # Setup the model metrics if not already done. This is a one-time setup
     # and will not be run again on subsequent calls to this endpoint
     await setup_model_metrics()