feat(health): call /metrics to set health of models (#911)

* add basic auth for metrics endpoint and change health/models logic

* add tests

* add docs

* fix tests

* Update unit coverage badge

---------

Co-authored-by: leoguillaume <leoguillaume@users.noreply.github.com>

Author: leoguillaume

.github/badges/coverage.json

@@ -1 +1 @@
-{"schemaVersion":1,"label":"coverage","message":"56.19%","color":"red"}
+{"schemaVersion":1,"label":"coverage","message":"56.67%","color":"red"}

api/alembic/versions/2026_06_10_1828-0daf52aadaf0_add_basic_auth_to_provider_definition.py

@@ -0,0 +1,32 @@
+"""add basic auth to provider definition
+
+Revision ID: 0daf52aadaf0
+Revises: 7498a3a48271
+Create Date: 2026-06-10 18:28:42.580559
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '0daf52aadaf0'
+down_revision: Union[str, None] = '7498a3a48271'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('provider', sa.Column('basic_auth', sa.JSON(), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('provider', 'basic_auth')
+    # ### end Alembic commands ###

api/dependencies.py

@@ -162,9 +162,13 @@ def _router_rate_limiter() -> RouterRateLimiter:
 # health use cases
 def get_health_models_use_case_factory(
     postgres_session: AsyncSession = Depends(get_postgres_session),
+    provider_adapter_builder: ProviderAdapterBuilder = Depends(_provider_adapter_builder),
+    provider_client: ProviderClient = Depends(_provider_client),
     redis_client: Redis = Depends(get_redis_client),
 ) -> GetHealthModelsUseCase:
     return GetHealthModelsUseCase(
+        provider_adapter_builder=provider_adapter_builder,
+        provider_client=provider_client,
         provider_metrics_logger=_provider_metrics_logger(redis_client),
         router_repository=_router_repository(postgres_session),
         provider_repository=_provider_repository(postgres_session),

api/domain/provider/_providerrepository.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 
 from api.domain import SortOrder
-from api.domain.provider.entities import HostingZone, Metric, Provider, ProviderPage, ProviderSortField, ProviderType
+from api.domain.provider.entities import BasicAuth, HostingZone, Metric, Provider, ProviderPage, ProviderSortField, ProviderType
 from api.domain.provider.errors import ProviderAlreadyExistsError, ProviderNotFoundError
 
 
@@ -14,6 +14,7 @@ async def create_provider(
         provider_type: ProviderType,
         url: str,
         key: str | None,
+        basic_auth: BasicAuth | None,
         timeout: int,
         model_name: str,
         model_hosting_zone: HostingZone,

api/domain/provider/entities.py

@@ -1,11 +1,11 @@
 from enum import StrEnum
 from http import HTTPMethod
-from typing import Annotated
+from typing import Annotated, Literal
 
 import pycountry
-from pydantic import BaseModel, Field
+from pydantic import Field
 
-from api.domain import EntitiesPage
+from api.domain import BaseModel, EntitiesPage
 from api.domain.embeddings.entities import CreateEmbeddingsBody, Embeddings
 from api.domain.model.entities import Models, ModelType
 from api.domain.rerank.entities import CreateRerankBody, Rerank
@@ -33,6 +33,11 @@ class QoSMetric(StrEnum):
     PERFORMANCE = "performance"  # custom performance metric
 
 
+class BasicAuth(BaseModel):
+    username: str
+    password: str
+
+
 class ProviderType(StrEnum):
     ALBERT = "albert"
     OPENAI = "openai"
@@ -96,6 +101,7 @@ class Provider(BaseModel):
     type: ProviderType
     url: str
     key: str | None = None
+    basic_auth: BasicAuth | None = None
     timeout: int
     model_name: str
     model_hosting_zone: HostingZone = HostingZone.WOR
@@ -146,24 +152,31 @@ class ProviderOriginalRequest(BaseModel):
     files: Annotated[dict | None, Field(default=None, description="The files to use for the request.")]
 
 
+class ResponseMetrics(BaseModel):
+    latency: Annotated[int, Field(default=0, description="The latency of the response.")]
+    ttft: Annotated[int | None, Field(default=None, description="The time to first byte of the response.")]
+
+
 class ProviderFormattedRequest(BaseModel):
     method: Annotated[HTTPMethod, Field(description="The HTTP method to build the request.")]
     url: Annotated[str, Field(description="The model API URL to build the request.")]
+    auth: Annotated[BasicAuth | None, Field(default=None, description="The authentication to use for the request.")]
     body: Annotated[dict, Field(default={}, description="The JSON body to use for the request.")]
     form: Annotated[dict, Field(default={}, description="The form-encoded data to use for the request.")]
     files: Annotated[dict, Field(default={}, description="The files to use for the request.")]
 
 
-class ResponseMetrics(BaseModel):
-    latency: Annotated[int, Field(default=0, description="The latency of the response.")]
-    ttft: Annotated[int | None, Field(default=None, description="The time to first byte of the response.")]
-
-
 class ProviderOriginalResponse(BaseModel):
-    data: Annotated[dict | list, Field(default={}, description="The JSON data to use for the response.")]
+    data: Annotated[dict | list | None, Field(default=None, description="The JSON data to use for the response.")]
     text: Annotated[str | None, Field(default=None, description="The text data to use for the response.")]
 
 
+class ProviderMetrics(BaseModel):
+    object: Literal["providerMetrics"] = "providerMetrics"
+    waiting_requests: float
+    running_requests: float
+
+
 class ProviderFormattedResponse(BaseModel):
-    data: Annotated[AudioTranscription | ChatCompletion | ChatCompletionChunk | Embeddings | Models | OCR | Rerank | None, Field(default=None, description="The JSON data to use for the response.")]  # fmt: off
+    data: Annotated[AudioTranscription | ChatCompletion | ChatCompletionChunk | Embeddings | Models  | OCR | ProviderMetrics | Rerank | None, Field(default=None, description="The JSON data to use for the response.")]  # fmt: off
     text: Annotated[str | None, Field(default=None, description="The text data to use for the response.")]

api/infrastructure/fastapi/endpoints/admin/providers.py

@@ -90,6 +90,7 @@ async def create_provider(
             provider_type=body.type,
             url=body.url,
             key=body.key,
+            basic_auth=body.basic_auth,
             timeout=body.timeout,
             model_name=body.model_name,
             model_hosting_zone=body.model_hosting_zone,

api/infrastructure/fastapi/endpoints/health.py

@@ -11,7 +11,7 @@
 from api.use_cases.health import GetHealthModelsCommand, GetHealthModelsUseCase, GetHealthModelsUseCaseSuccess
 from api.utils.variables import EndpointRoute, RouterName
 
-router = APIRouter(tags=[RouterName.MONITORING.title()])
+router = APIRouter(tags=[RouterName.HEALTH.title()])
 
 
 @router.get(path=EndpointRoute.HEALTH, status_code=200)

api/infrastructure/fastapi/schemas/providers.py

@@ -2,7 +2,7 @@
 
 from pydantic import Field, StringConstraints, model_validator
 
-from api.domain.provider.entities import HostingZone, ProviderType, QoSMetric
+from api.domain.provider.entities import BasicAuth, HostingZone, ProviderType, QoSMetric
 from api.infrastructure.fastapi.schemas import BaseModel
 from api.schemas.core.configuration import ModelProvider
 
@@ -18,6 +18,7 @@ class CreateProviderResponse(BaseModel):
     type: Annotated[ProviderType, Field(..., description="Provider type.")]
     url: Annotated[str | None, StringConstraints(strip_whitespace=True, min_length=1, to_lower=True), Field(default=None, description="Provider API url. The url must only contain the domain name (without `/v1` suffix for example).")]  # fmt: off
     key: Annotated[str | None, StringConstraints(strip_whitespace=True, min_length=1), Field(default=None, description="Provider API key.")]  # fmt: off
+    basic_auth: Annotated[BasicAuth | None, Field(default=None, description="Provider basic authentication.")]
     timeout: Annotated[int, Field(..., ge=1, le=3600, description="Timeout for the provider requests, after user receive an 500 error (model is too busy).")]  # fmt: off
     model_name: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1), Field(..., description="Model name from the model provider.")]  # fmt: off
     model_hosting_zone: Annotated[HostingZone, Field(default=HostingZone.WOR, description="Model hosting zone using ISO 3166-1 alpha-3 code format (e.g., `WOR` for World, `FRA` for France, `USA` for United States). This determines the electricity mix used for carbon intensity calculations. For more information, see https://ecologits.ai", examples=["WOR"])]  # fmt: off
@@ -53,7 +54,6 @@ class ProviderResponse(BaseModel):
     user_id: Annotated[int, Field(description="ID of the user that owns the provider.")]  # fmt: off
     provider_type: Annotated[ProviderType, Field(alias="type", description="Provider type.")]  # fmt: off
     url: Annotated[str | None, StringConstraints(strip_whitespace=True, min_length=1, to_lower=True), Field(default=None, description="provider API url. The url must only contain the domain name (without `/v1` suffix for example).")]  # fmt: off
-    key: Annotated[str | None, StringConstraints(strip_whitespace=True, min_length=1), Field(default=None, description="provider API key.")]
     timeout: Annotated[int, Field(description="Timeout for the provider requests, after user receive an 500 error (model is too busy).")]
     model_name: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1), Field(description="Model name from the model provider.")]
     model_hosting_zone: Annotated[HostingZone, Field(default=HostingZone.WOR, description="Model hosting zone using ISO 3166-1 alpha-3 code format (e.g., `WOR` for World, `FRA` for France, `USA` for United States). This determines the electricity mix used for carbon intensity calculations. For more information, see https://ecologits.ai", examples=["WOR"])]  # fmt: off

api/infrastructure/http/_httpprovideradapterbuilder.py

@@ -15,6 +15,8 @@
 from api.infrastructure.http.adapters.embeddings.openai import OpenaiEmbeddingsAdapter
 from api.infrastructure.http.adapters.embeddings.tei import TeiEmbeddingsAdapter
 from api.infrastructure.http.adapters.embeddings.vllm import VllmEmbeddingsAdapter
+from api.infrastructure.http.adapters.metrics.mistral import MistralMetricsAdapter
+from api.infrastructure.http.adapters.metrics.vllm import VllmMetricsAdapter
 from api.infrastructure.http.adapters.models.albert import AlbertModelsAdapter
 from api.infrastructure.http.adapters.models.mistral import MistralModelsAdapter
 from api.infrastructure.http.adapters.models.openai import OpenaiModelsAdapter
@@ -56,6 +58,10 @@ class HttpProviderAdapterBuilder(ProviderAdapterBuilder):
             ProviderType.TEI: TeiModelsAdapter,
             ProviderType.VLLM: VllmModelsAdapter,
         },
+        EndpointRoute.METRICS: {
+            ProviderType.MISTRAL: MistralMetricsAdapter,
+            ProviderType.VLLM: VllmMetricsAdapter,
+        },
         EndpointRoute.OCR: {
             ProviderType.ALBERT: AlbertOcrAdapter,
             ProviderType.MISTRAL: MistralOcrAdapter,

api/infrastructure/http/_httpproviderclient.py

@@ -3,6 +3,7 @@
 import logging
 
 import httpx
+from httpx import BasicAuth
 
 from api.domain.model.errors import StatusCodeModelError, TooBusyModelError, UnknownModelError
 from api.domain.provider import ProviderClient, ProviderClientResponse
@@ -13,10 +14,14 @@
 
 class HttpProviderClient(ProviderClient):
     async def forward_request(self, provider: Provider, formatted_request: ProviderFormattedRequest) -> ProviderClientResponse:
+        # TEMPORARY PATCH FOR MISTRAL METRICS ENDPOINT
+        auth = BasicAuth(username=formatted_request.auth.username, password=formatted_request.auth.password) if formatted_request.auth else None
+
         async with httpx.AsyncClient(timeout=provider.timeout) as async_client:
             try:
                 response = await async_client.request(
                     headers={"Authorization": f"Bearer {provider.key}"} if provider.key else {},
+                    auth=auth,
                     method=formatted_request.method,
                     url=formatted_request.url,
                     json=formatted_request.body,