asyncio : les règles de survie du projet

Pourquoi l'app est async de bout en bout

Une requête copilot passe des secondes à attendre : le LLM génère, Postgres répond, Cohere rerank. En sync, chaque requête bloquerait un worker entier. En async, l'attente libère l'event loop : un seul process sert des dizaines de conversations simultanées. D'où la règle du projet : SDK LLM en version Async*, SQLAlchemy async, et jamais un appel bloquant nu dans un handler.

Les trois gestes à maîtriser

1. asyncio.to_thread : mettre le sync en quarantaine

Une lib sync (parsing PDF, un client legacy) gèle toute l'app si on l'appelle directement. Le projet l'exile dans un thread :

tables = await asyncio.to_thread(pdfplumber_extract, pdf_bytes)   # l'event loop respire

2. asyncio.gather : paralléliser les attentes indépendantes

# Les 4 sources de la recherche hybride (module 3) partent EN MÊME TEMPS :
exact, fts, trgm, vec = await asyncio.gather(
    search_exact(q), search_fulltext(q), search_trigram(q), search_vector(q),
)

Quatre requêtes de 50 ms séquentielles = 200 ms ; en gather = ~50 ms. C'est aussi comme ça que l'agent exécute plusieurs tool calls d'un même tour en parallèle.

3. asyncio.create_task : le vrai arrière-plan

Une extraction dure 30 s — la requête HTTP ne peut pas attendre. Le projet répond 202 avec un job_id et lance asyncio.create_task(run_pipeline(...)). Deux obligations qui vont avec : garder une référence à la task (sinon le GC peut la tuer en plein vol) et persister le job (store Postgres + boucle de réconciliation) pour survivre à un redémarrage — une task in-process n'est PAS une queue durable.

L'erreur qui coûte cher : le blocage caché

time.sleep, requests.get, un pandas.read_excel de 80 Mo directement dans un handler async : tout le monde attend (chaque conversation, chaque SSE). Symptôme en prod : latences qui montent partout d'un coup, sans CPU. Réflexe de debug : chercher l'appel sync — c'est exactement ce que traque la règle ASYNC de ruff activée sur le projet.