turn_context et assemblage du prompt

源码版本v2026.7.20

Responsabilité

Avant chaque appel API, assemble « messages d'historique + entrée utilisateur du tour + contexte additionnel côté passerelle + marqueurs de compression » en api_messages envoyé au provider. TurnContext est le conteneur produit pour ce tour, build_turn_context en est l'entrée d'assemblage. Il injecte aussi dans le contenu multimodal les notes collectées par la passerelle.

Fichiers clés

• class TurnContext:242-268 — dataclass du contexte du tour
• def build_turn_context:268-400 — entrée d'assemblage
• compose_user_api_content:44-79 — assemblage du contenu du message utilisateur
• substitute_api_content:79-101 — substitution de placeholders
• consume_gateway_turn_context_notes:124-164 — consomme les notes additionnelles de la passerelle et les injecte dans le contenu multimodal
• reanchor_current_turn_user_idx:164-210 — repositionne l'index du message utilisateur du tour (correction post-compression)
• estimation progression compression:190-242 — _compression_made_progress / _should_run_preflight_estimate
• prompt_builder — assemblage du prompt système (référencé ici)

Flux de données

1. La boucle principale appelle build_turn_context:268 à chaque tour et obtient un TurnContext.
2. compose_user_api_content (agent/turn_context.py:44) assemble l'entrée utilisateur brute en contenu API.
3. Si la passerelle a accumulé des notes (pièces jointes, indices de contexte), consume_gateway_turn_context_notes (agent/turn_context.py:124) les récupère et les injecte via append_notes_to_multimodal_content.
4. substitute_api_content (agent/turn_context.py:79) remplace les placeholders ; drop_stale_api_content nettoie le contenu périmé.
5. Si le tour précédent a déclenché une compression, reanchor_current_turn_user_idx (agent/turn_context.py:164) corrige la position du message utilisateur du tour dans l'historique.
6. Les api_messages assemblés entrent dans sous-boucle de retry API:1227.

Résumé

turn_context est la « fabrique d'instantanés par tour » : il fige un contexte dynamique en une structure envoyable. Il travaille de pair avec la compression de contexte — une fois la compression effectuée, turn_context est chargé de réaligner les pointeurs.