Subgraphs et streaming d'exécution

Subgraph : le graphe comme node

Un graphe compilé est un node comme un autre — c'est la composition du projet :

orchestrator = StateGraph(UnifiedState)
orchestrator.add_node("extraction", create_extraction_graph_with_matching())  # ← un GRAPHE
orchestrator.add_node("post_extraction", post_extraction_node)
orchestrator.add_node("persist_document", persist_node)
orchestrator.add_edge(START, "extraction")
orchestrator.add_edge("extraction", "post_extraction")

L'orchestrateur reste lisible en trois lignes ; le détail (router → extractor → structurer → validator → matchers) vit dans le subgraph. Même state partagé (le UnifiedState plat, section par section) → pas de mapping d'entrées/sorties entre niveaux. Le projet a aussi un subgraph multi_request (splitter + fan-out) quand un même document contient plusieurs commandes — la composition permet de brancher ce cas sans toucher au chemin principal.

astream : l'exécution comme flux d'événements

async for chunk in graph.astream(initial_state, stream_mode="updates"):
    # chunk = {"matcher_fast": {"match_results": [...]}}  ← delta par node terminé
    node_name, delta = next(iter(chunk.items()))
    yield sse_event("node_completed", {"node": node_name, **summary(delta)})

stream_mode="updates" émet un événement par node terminé, avec son delta — exactement la granularité d'une UI de progression. C'est le pont direct vers le générateur SSE du module 2 : le front affiche « extraction ✓ → matching en cours… » et même les lignes matchées en live. (Les autres modes existent : values = le state complet à chaque étape, messages = les tokens LLM.)

La conséquence : les noms de nodes sont une API

Puisque le front se câble sur {"node": "persist_document"}, renommer un node est un breaking change. Le projet en fait un contrat documenté. Corollaire de design : nomme tes nodes comme tu nommes tes routes — pour le consommateur, pas pour toi.