SSE : streamer la progression et les tokens

Pourquoi SSE (et pas WebSocket)

Le copilot et le pipeline streament du serveur vers le client : tokens du LLM, progression node par node. Le besoin est unidirectionnel → Server-Sent Events : du HTTP simple, compatible proxys/CDN, reconnexion native — là où WebSocket paie sa bidirectionnalité inutile ici. Le front envoie ses actions par des POST classiques.

Le format et le générateur

SSE = une réponse text/event-stream qui ne se termine pas, découpée en blocs event:/data: séparés par une ligne vide :

event: node_completed
data: {"node": "matcher_fast", "matched": 12}

event: text_delta
data: {"text": "Voici les produits"}

Côté FastAPI : un générateur async branché sur StreamingResponse :

async def event_stream(run) -> AsyncIterator[str]:
    async for ev in run:                      # ← ex. graph.astream(...) (module 6)
        yield f"event: {ev.type}\ndata: {json.dumps(ev.payload)}\n\n"

@router.post("/extract/stream")
async def extract_stream(...):
    return StreamingResponse(event_stream(run), media_type="text/event-stream")

Le contrat d'événements : la vraie difficulté

Le flux SSE est une API publique : le front se câble sur les noms d'événements et la forme des payloads. Dans le projet, les événements suivent le protocole AG-UI (module 8) et les noms des nodes du pipeline (persist_document…) sont un contrat stable — renommer un node casse la barre de progression du front. Traite tes événements de stream comme des routes : nommés, documentés, versionnés.

Deux détails d'ops à connaître : un ping périodique garde les connexions vivantes à travers les proxys ; et si le client part, le générateur reçoit une annulation — le code doit y survivre proprement (fermer la génération LLM, pas la laisser tourner pour personne).