Documentation API FastAPI (OAS 3.1) — Addendum à la documentation pipeline v1.0
Série ToxTwin — Article 3/3. Voir aussi : Pipeline ToxGNN-V1 · Rapport RPT-2026-001
Ce document constitue l’addendum technique à la documentation du pipeline ToxTwin v1.0. Il décrit l’interface API REST (FastAPI, OpenAPI 3.1), les résultats de validation sur deux molécules de référence pharmaceutique, le format de réponse JSON structuré, et la dette technique identifiée.
L’API ToxTwin expose une documentation interactive Swagger UI automatiquement générée par FastAPI, accessible à http://localhost:8000/docs. Quatre endpoints sont disponibles : GET /health (état de l’API, modèle chargé, device, FP training set, calibration), POST /v1/score-toxicity (scoring d’un composé via JSON {query: string}), GET /v1/score-toxicity (scoring via paramètre URL), POST /v1/score-toxicity/batch (scoring batch jusqu’à 50 molécules en parallèle).
Huit schémas Pydantic structurent les échanges : ScoreRequest, ScoreResponse, ResolvedMolecule, ToxPredictions, ExperimentalData, ApplicabilityDomain, BatchRequest, HTTPValidationError.
Environnement conda ml (Python 3.11, PyTorch 2.12, PyG 2.7), modèle toxgnn_v1_finetune.pt, températures de calibration JSON, Delta Lake Silver accessible. Au démarrage, l’API charge séquentiellement le modèle (~2 s), les températures (instantané) et les 2 000 Morgan FP du training set via Spark (~8 s).
Requête par nom DCI, résolution PubChem PUG-REST → CID 2244, SMILES canonique CC(=O)Oc1ccccc1C(=O)O, MW 180.16 g/mol. Temps d’inférence : 2 017 ms. Signal le plus élevé : NR-ER 0.350 (récepteur œstrogène, attendu pour un AINS), suivi de NR-AhR 0.191 et SR-ARE 0.168. Données Silver : LD50 orale rat 200 mg/kg, tox_score 4/5, organe cible foie. Domaine applicatif : Tanimoto 0.594 (dans le domaine). Le profil prédictif est cohérent avec la pharmacologie connue.
Soumission par SMILES direct (CC(C)Cc1ccc(cc1)C(C)C(=O)O), résolution RDKit sans appel réseau, gain ~430 ms. Signal le plus élevé : NR-PPAR-gamma 0.383 — activation PPAR-γ documentée dans la littérature (Lehmann et al., 1997, Nature Medicine). Le modèle ToxGNN-V1 a capturé cette relation structure-activité sans supervision explicite. NR-ER 0.318 et NR-ER-LBD 0.264 indiquent une perturbation endocrinienne modérée, cohérente avec la classe AINS. LD50 orale rat : 636 mg/kg (moins toxique que l’aspirine en aigu), tox_score 2/5. Tanimoto : 0.600 (dans le domaine).
Le différentiel NR-PPAR-gamma entre aspirine (0.038) et ibuprofène (0.383) constitue un résultat non trivial : il correspond à une différence pharmacologique documentée qui émerge des représentations apprises par le GNN pré-entraîné, sans avoir été explicitement supervisée. Ce type de signal valide la capacité du modèle à capturer des relations structure-activité au-delà de la simple corrélation avec les labels d’entraînement. L’ibuprofène présente un stress mitochondrial (SR-MMP 0.119) et une perturbation endocrinienne (NR-ER-LBD 0.264) plus marqués, tandis que l’aspirine domine sur NR-ER (0.350) et le tox_score aigu (4/5 vs 2/5). Les deux composés sont dans le domaine applicatif (Tanimoto > 0.59).
Le JSON de réponse contient 8 champs de premier niveau : query, resolved (ResolvedMolecule), predictions (ToxPredictions avec 12 scores + incertitudes + mean_uncertainty), experimental_data (LD50, tox_score, severity, Ames, organes), applicability_domain (max_tanimoto_similarity, is_in_domain, warning), calibration_warning (booléen si ECE > 0.10), inference_time_ms, model_version.
Grille d’interprétation des scores : < 0.10 (très faible), 0.10–0.25 (faible, surveillance), 0.25–0.50 (modéré, investigation recommandée), > 0.50 (élevé, études in vitro prioritaires). Grille d’incertitude MC Dropout : < 0.05 (fiable), 0.05–0.15 (modéré), > 0.15 (haute incertitude).
Calibration ECE 0.149 (FAIL > 0.10) — cause racine pos_weight BCE, correction prévue par Isotonic Regression (v1.1). Temps d’inférence 1 500–2 000 ms sur CPU — GPU RTX 5080 réduira à < 200 ms (v1.1). NR-AR sous baseline RF (0.659 vs 0.750) — enrichissement données ChEMBL recommandé. Domaine applicatif : 38,2 % hors domaine sur scaffold split (normal par design, k-NN mean similarity à implémenter en v1.2).