api.py

"""API REST FastAPI : lancez avec `uvicorn api:app --reload`."""

from __future__ import annotations

from pathlib import Path  # Sert à extraire l'extension conservée dans le fichier temporaire.
from tempfile import NamedTemporaryFile  # Convertit le flux HTTP en fichier lisible par librosa.

from fastapi import FastAPI, File, HTTPException, UploadFile

from src.errors import AudioValidationError, PipelineError
from src.pipeline import SentimentCallPipeline

# Métadonnées visibles dans la documentation automatique /docs de FastAPI.
app = FastAPI(title="French Call Sentiment API", version="1.0.0")
# Une instance partagée évite de recharger plusieurs gigaoctets de modèles à chaque requête.
pipeline = SentimentCallPipeline()


@app.get("/health")
def health() -> dict[str, str]:
    """Vérifie que le serveur est joignable sans forcer le chargement des modèles."""
    # Ce endpoint ne charge pas les modèles ; il vérifie seulement que le serveur est accessible.
    return {"status": "ok"}


@app.post("/predict")
async def predict(file: UploadFile = File(...)) -> dict[str, str | float]:
    """Analyse un WAV/MP3 et retourne transcription, sentiment et confiance."""
    # Préserver l'extension est nécessaire afin que le décodeur reconnaisse WAV ou MP3.
    suffix = Path(file.filename or "").suffix.lower()
    try:
        # Un fichier temporaire permet à librosa de traiter le flux envoyé par HTTP.
        with NamedTemporaryFile(suffix=suffix, delete=False) as temporary:
            # `await` lit le contenu téléversé sans bloquer la boucle asynchrone de FastAPI.
            temporary.write(await file.read())
            temporary_path = Path(temporary.name)
        # Le pipeline retourne un objet Prediction ; l'API le transforme en JSON simple.
        return pipeline.predict(temporary_path).to_dict()
    except AudioValidationError as exc:
        # 400 signifie que le client doit corriger son fichier, pas que le serveur est défaillant.
        raise HTTPException(status_code=400, detail=str(exc)) from exc
    except PipelineError as exc:
        # 503 indique un problème temporaire de modèle/ressource (par exemple téléchargement indisponible).
        raise HTTPException(status_code=503, detail=str(exc)) from exc
    finally:
        # Le fichier temporaire contient un audio utilisateur : le supprimer limite stockage et exposition.
        if "temporary_path" in locals():
            temporary_path.unlink(missing_ok=True)