Les services IA de DnC

Comment ReActAgent s'insère dans le Workflow LlamaIndex

Bertrand Degoy — 2026-04-13T10:15:10Z

Dans LlamaIndex, la boucle ReAct repose sur un principe simple : le workflow orchestre, l'agent raisonne. À chaque appel, génère un prompt, interroge le LLM, reconstruit une étape de raisonnement et laisse le finalizer décider de la suite. Une mécanique minimale côté workflow, une intelligence maximale côté agent.

La boucle de raisonnement ReAct

Comment `ReActAgent` s'insère dans le Workflow LlamaIndex

LlamaIndex ReActAgent, construit sur Workflow, fournit le code du step dans un workflow. Le workflow appelle :

BaseAgent.run_agent_step() → ReActAgent.take_step()

Donc :

le workflow = chef d'orchestre (encore un !)
l'agent = une étape du workflow
take_step() = la logique ReAct pour une étape

Comment sont construites les steps ReAct ?

En vérité : Le Workflow ne construit pas des steps ReAct. C'est ReActAgent qui les fait construire par le LLM. Le Workflow ne fait que :

appeler take_step()
attendre un AgentStepOutput (Thought, Action, Action Input ...)
décider avec ReActFinalizer si une nouvelle étape doit être exécutée

Voici ce qui se passe dans ReActAgent.take_step() pour construire une étape :

Étape 1 — Construire le prompt ReAct

L'agent génère le prompt ReAct qui fixe les règles que devra suivre le LLM pour élaborer les THOUGHT, ACTION et ACTION INPUT, pour appeler les outils etc. Le prompt contient également l'historique des échanges et, in fine, la question de l'utilisateur. Voici un exemple très naïf :

You are a ReAct agent.
First, think step-by-step and write:
THOUGHT:
Then, if needed, write:
ACTION:
ACTION INPUT:

Étape 2 — Appeler le LLM

L'agent appelle :

llm.stream(prompt)

Le LLM génère la réponse au prompt. → Le LLM produit progressivement, par petits fragments, les deltas.

Étape 3 — Le parser reconstruit les blocs

Le ReActStreamParser transforme les deltas en blocs :

THOUGHT: ...
ACTION: ...
OBSERVATION: ...
...
FINAL_ANSWER: ...

Étape 4 — Le ReActFinalizer décide si l'étape est terminée

Le finalizer :

valide les blocs
détecte les erreurs
empêche les boucles
décide si une nouvelle étape doit être lancée

Étape 5 — Le workflow relance `take_step()` si nécessaire

Si le finalizer dit “continue”, alors :

workflow → BaseAgent.run_agent_step → ReActAgent.take_step()

Et une nouvelle étape ReAct est produite.

En résumé : rôle du Workflow

Le workflow LlamaIndex ne fait qu'appeler take_step() en boucle.
ReActAgent.take_step() génère une étape ReAct en appelant le LLM.
Le ReActStreamParser reconstruit les blocs ReAct à partir des deltas.
Le ReActFinalizer décide si une nouvelle étape doit être lancée.
Le workflow relance take_step() si nécessaire.

Voyez aussi :
– ReActEngine v1 : Modules et traitements

ReActEngine v1 : Finalizer et StreamParser

Bertrand Degoy — 2026-04-13T09:34:02Z

Les modules ReActFinalizer, ReActStreamParser, font partie du niveau supérieur ou "Orchesrtrateur" di traitement. Ils ont été développés spécialement pour atteindre les objectifs du ReActEngine v1.

Architecture ReAct : Finalizer et StreamParser

Rôles et responsabilités

ReActStreamParser

Fait le lien entre le niveau applicatif et le ReActEngine.

Responsable de :

La segmentation du flux brut en blocs ReActBlock
L'identification du type de chaque bloc (ReActType)
La gestion du buffer et du flush final
La conservation de l'historique des blocs extraits

Ne décide jamais de l'arrêt ou de la modification du raisonnement.

Expose :

has_final_answer() : indique si un bloc FINAL_ANSWER est présent dans les blocs extraits
get_final_answer() : retourne le contenu du dernier bloc FINAL_ANSWER si présent

ReActFinalizer

Responsable de :

L'orchestration du raisonnement jusqu'à résolution
L'arrêt du flux dès qu'un bloc de type FINAL_ANSWER, ANSWER, RESPONSE ou CONCLUSION est rencontré
La détection de boucles ou d'anomalies de raisonnement, avec relance du raisonnement via un Thought injecté.

Ne connaît pas l'état interne du parser. Il ne peut pas appeler parser.has_final_answer().

Règle de séparation stricte

Le Finalizer ne doit pas inspecter parser.blocks ni utiliser ses méthodes internes.
Le Parser ne doit pas décider de l'arrêt ou la modification du raisonnement.
La détection de la résolution se fait uniquement dans le Finalizer, en fonction du type des blocs yieldés.

Exemple de flux

Thought: I need to search.
Action: search[weather]
Observation: It's raining.
Final Answer: Bring an umbrella.

Le Parser extrait 4 blocs typés.
Le Finalizer s'arrête dès réception du bloc FINAL_ANSWER.

La classe `ReActType`

Héritage :

class ReActType(str, Enum):

Hérite de str pour permettre des comparaisons directes avec des chaînes (block.type == "thought").
Hérite de Enum pour garantir l'énumération stricte des types.

Types ReAct fondamentaux

Type	Rôle dans le flux ReAct
`THOUGHT`	Raisonnement interne
`ACTION`	Appel d'outil
`OBSERVATION`	Résultat d'outil
`FINAL_ANSWER`	Clôture explicite
`ANSWER`	Réponse directe
`RESPONSE`	Variante de réponse
`CONCLUSION`	Clôture synthétique
`TOOL_CALL`	Appel structuré (optionnel)
`TOOL_RESULT`	Résultat structuré
`UNKNOWN`	Valeur de secours

3. Cohérence avec les finalizers et parsers

Les types FINAL_ANSWER, ANSWER, RESPONSE, CONCLUSION sont utilisés comme types de clôture dans le Finalizer.
Les types TOOL_CALL et TOOL_RESULT sont utiles pour des flux structurés (JSON, agents avancés).
UNKNOWN est une bonne pratique pour la robustesse du parsing.

Pourquoi deux parsers ?

Les parsers ont pour fonction d'assembler un flux de réponse brut (les tokens) en messages typés ReAct.

Les lecteurs attentifs auront remarqué que :

il existe un ReActOutputParser directement à la sortie du LLM et, pourtant, ReActEngine émet un flux brut de token ;
l'application cliente doit reconstruire les messages ReAct, par exemple avec StreamlitChatTracer.

Voici la distinction essentielle — et pourquoi elle est nécessaire — entre :

ReActOutputParser (côté LLM, logique interne de l'agent)
ReActEngine / Workflow (côté runtime, flux brut de tokens)
StreamlitChatTracer / client (côté application, reconstruction des messages)


Deux parser en parallèle avec des objectifs et une temporalité différents

**1. Le ReActOutputParser n'est pas utilisé pendant le streaming**

ReActOutputParser est conçu pour analyser un bloc complet de texte produit par le LLM, contenant typiquement :

Thought: ...
Action: tool_name
Action Input: {...}

ou bien :

Thought: ...
Answer: ...

Ce parser fonctionne uniquement lorsque le LLM a fini de produire tout le message.
Il ne peut pas fonctionner sur un flux token-par-token, car :

le pattern ReAct n'est pas encore complet,
les sections Thought / Action / Observation / Answer peuvent arriver dans n'importe quel ordre,
le LLM peut réviser sa sortie en cours de génération.

Donc : pendant le streaming, LlamaIndex ne peut pas appliquer ReActOutputParser.

2. Pourquoi ReActEngine émet un flux brut de tokens

Le moteur ReAct dans LlamaIndex Workflow est conçu pour :

exposer l'intégralité du raisonnement ReAct,
permettre au client de suivre la progression en temps réel,
laisser la liberté au développeur de tracer, filtrer ou visualiser les étapes.

Le flux brut contient donc :

les Thought : intermédiaires,
les Action : et Action Input :,
les Observation :,
les Answer : finales.

Ce flux est intentionnellement non structuré, car :

il reflète exactement ce que le LLM produit,
il permet d'afficher la réflexion pas à pas,
il évite d'imposer un format unique de parsing pendant le streaming.

Le moteur ne structure pas le flux, car cela casserait la transparence et la flexibilité du workflow.

3. Pourquoi le client doit reconstruire les messages ReAct

Comme le flux est brut, c'est l'application cliente qui doit :

détecter les segments Thought / Action / Observation / Answer,
les afficher proprement,
éventuellement les agréger ou les filtrer,
ou les transformer en messages de chat.

Pour une application de chatbot fondée sur StreamLit, nous avons développé StreamlitChatTracer qui a l'avantage de produire en streaming un flux décoré (police, couleur etc.).

LlamaIndex fournit des helpers comme :

LlamaTrace
OpenInference instrumentation

Ces outils :

écoutent les événements AgentStream, ToolCall, ToolCallResult, etc.,
reconstruisent une vue structurée du raisonnement,
permettent une visualisation claire dans le client.

La reconstruction côté client est volontaire : elle permet d'adapter l'affichage au contexte (UI, logs, monitoring, etc.).

4. Pourquoi cette séparation est nécessaire

A. Le LLM produit du texte libre → pas structuré

Même si ReAct impose un format, le LLM reste libre dans sa génération.
Le parser ne peut fonctionner qu'une fois la sortie complète.

B. Le streaming impose de ne pas parser prématurément

Un parser ReAct ne peut pas fonctionner sur :

un Thought incomplet,
un Action Input partiellement généré,
un Answer tronqué.

C. Le workflow doit rester générique

Le moteur ReAct doit :

fonctionner avec n'importe quel LLM,
ne pas dépendre d'un format strict,
permettre des outils de tracing externes.

D. Le client peut choisir son mode de visualisation

Certains veulent :

tout afficher (Thoughts inclus),
masquer les Thoughts,
afficher uniquement les Tool Calls,
ou ne montrer que la réponse finale.

Impossible de satisfaire tous les cas dans le moteur lui-même.

Conclusion

La différence est nécessaire car :

ReActOutputParser est un outil post-hoc pour analyser une sortie complète.
ReActEngine doit fournir un flux brut pour permettre le streaming et la transparence.
Le client doit reconstruire les messages ReAct selon ses besoins (UI, logs, monitoring).

Cette architecture garantit :

flexibilité,
transparence,
compatibilité avec tous les LLM,
et contrôle total côté application.

ReActEngine, l'IA qui raisonne, s'adapte et comprend votre réalité métier

Bertrand Degoy — 2026-04-11T16:33:39Z

Fondé sur ReAct (Raisoning and Acting) ReActEngine appartient à la nouvelle génération d'agents intelligents capables de raisonner et d'interagir avec vos outils métier en s'appuyant sur les données de votre entreprise en temps réel ainsi que sur votre documentation.
Avec le standard MCP (Model Context Protocol), il se connecte naturellement à votre écosystème industriel et devient un véritable copilote cognitif pour l'Industrie 4.0 et au‑delà.
Grâce au RAG (Research Augmented Generation), il exploite la documentation interne de l'entreprise pour éclairer son raisonnement et illustrer ses réponses.

ReActEngine est développé en France et utilise un modèle de langage de MistralAI. Cocorico !

Une vision fine, prédictive et explicable de vos processus

ReActEngine combine trois piliers complémentaires :

1. ReAct — Raisonnement structuré

L'agent ne se contente pas de répondre :
il analyse, décompose, vérifie, puis agit.
Cette approche multi‑étapes permet :

une compréhension plus fine des intentions,
des réponses explicites et argumentées,
une meilleure gestion des situations complexes ou ambiguës.

2. RAG — Votre documentation comme socle de vérité

Grâce à un module RAG intégré, ReActEngine s'appuie sur :

vos historiques,
vos procédures,
vos référentiels techniques,
vos routines métier.

Il devient un assistant qui parle votre langage, comprend vos règles et s'appuie sur votre corpus documentaire . Le principe du RAG est de traiter les documents d'une entité. Il faut pouvoir saisir facilement toute la documentation et surtout tenir à jour cette documentation de façon continue. C'est le rôle du RAG Manager.

3. MCP — Vos données temps réel, sans intégration complexe

MCP agit comme un USB‑C de l'IA :
une interface universelle pour connecter l'agent à vos systèmes (ERP, CRM, API internes, capteurs, machines…).

Il apporte :

des données toujours à jour,
une réduction massive des coûts d'intégration,
une meilleure sécurité,
une interopérabilité immédiate.

Pensé pour l'Industrie 4.0… et prêt pour l'Industrie 5.0

Dans les environnements industriels, ReActEngine devient un assistant opérationnel capable de :

suivre l'évolution des données en direct,
anticiper les dérives,
expliquer ses analyse et justifier ses propositions,
demander l'expertise de l'humain quand nécessaire, sans jamais inventer ou halluciner.

Avec l'arrivée de l'Industrie 5.0, il s'intègre naturellement aux jumeaux numériques, offrant une vision :

plus fine,
plus prédictive,
plus explicable
des processus industriels.

Une architecture modulaire, conçue pour vos métiers

ReActEngine s'appuie sur trois ToolKits complémentaires :

GeneralToolKit
Les outils génériques indispensables à tout raisonnement.
ThemeToolKit
Les outils spécifiques à votre domaine métier, incluant un outil RAG dédié.
ToolKit temps réel (MCP)
Les connecteurs vers vos données opérationnelles, capteurs, API et systèmes internes.

Cette modularité garantit une adaptation rapide à chaque contexte, sans réécriture de l'agent.

Les bénéfices immédiats

Décisions plus rapides et mieux informées
Grâce à des données actualisées et un raisonnement expliqué.
Interopérabilité native
Via MCP, un standard universel, sans connecteurs maison ni intégrations lourdes, adapté à l'atelier comme à l'administration.
Personnalisation métier
Chaque thème, configuré pour vous, dispose de ses outils, de votre vocabulaire et de votre logique.
Réduction de la dette technique
Une architecture standardisée, durable et évolutive.
Sécurité renforcée
Contrôles d'accès par OAuth 2.0 ou OpenID Connect et gestion des autorisations, y compris pour le RAG et MCP.

ReActEngine — L'IA qui comprend votre métier et agit avec vous

Un agent capable de raisonner, d'expliquer, d'interroger vos systèmes en direct et de s'appuyer sur votre documentation interne.
Un assistant qui vous accompagne dans la transformation vers une industrie plus réactive, plus prédictive et connectée à l'humain.

Pour en savoir plus :

ReActEngine v1 : traitement des erreurs

Bertrand Degoy — 2026-04-11T08:53:07Z

Dans un agent de type ReAct, le raisonnement est construit étape par étape. Si une étape échoue, le LLM doit avoir des informations suffisantes pour reprendre le raisonnement, ou sinon risque de s'arrêter simplement, de façon silencieuse.
L'enjeu du traitement des erreurs est de toujours fournir au LLM de quoi construire une nouvelle étape de raisonnement.
Dans l'état actuel des modules LlamaIndex, trop d'erreurs sont simplement levées avec une classe d'exception "pythonique", en dehors de tout processus de reprise. C'est un problème assez général, que l'on retrouve dans les plus grands chatbots, se traduisant alors par un silence, un abandon ou un blocage.

Le traitement des erreurs dans ReActEngine

Dans ReActEngine, les erreurs sont traitées de deux manières, à deux niveaux et de façon indépendante : les Exceptions et les Thoughts injectés.

A - Exceptions

Pour corriger la sortie ReAct mal formée avant même qu'elle n'entre dans le flux. Exceptions = correction structurelle.

Aucune erreur survenant au cours de l'exécution de take_step() ( ce qui inclut de nombreux modules tels que les ToolBox, MCP etc. ) ne doit lever une exception de classe générale. Seules deux classes d'exceptions peuvent être utilisées, et doivent être traitées dans ce module :

RetryException Indique qu'une erreur récupérable s'est produite ( une réponse du LLM incomplète ou mal formée, une erreur d'outil etc. ). La même étape ReAct doit être ré-essayée, à charge du LLM de trouver un contournement en se basant sur les indications du message d'erreur.
ForceFinalizeException Indique qu'une erreur non récupérable s'est produite ( un état ReAct invalide, une erreur d'outil sans contournement possible etc. ) et que le LLM doit produire directement une réponse finale.

Exemple d'exception levée par un outil :

if date_str_s.isdigit():
raise RetryException("Invalid input: this function expects a readable date, not a timestamp, retry with ISO 8601 formats (`YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SS`).")

Télécharger

Exemples de situations récupérables :

Action Input manquant
Thought sans Action
JSON invalide
protocole ReAct violé
output tronqué en streaming
outil mal appellé ou mal utilisé Dans ces cas, le LLM reçoit les informations nécessaires pour régénérer une étape ReAct correcte.

B - Thought injecté

Pour corriger le raisonnement, pas la forme. Thought = correction cognitive

Exemple :

if block.type in {ReActType.OBSERVATION, ReActType.FINAL_ANSWER} and not block.content.strip(): #x
yield ReActBlock(
type=ReActType.THOUGHT,
content="Je constate que je n'ai obtenu aucune réponse. Peut-être devrais-je vérifier les paramètres ou reformuler ma demande."
)
continue

Télécharger

Cas d'usage :

bouclage sur un outil en erreur
observation vide ( pertinente ou résultant d'une erreur )
itérations excessives
action répétée
modèle qui "tourne en rond"

Dans ces cas, on veut reprendre le flux, pas relancer le LLM.

Diagramme du traitement des erreurs

Les deux modes influencent le raisonnement, mais à des niveaux différents du pipeline. La différence entre ces deux modes et leur indépendance apparaît clairement dans ce diagramme :


ReActEngine : Traitement des erreurs

Les exceptions RetryException et ForceFinalizeException agissent entre 3 et 7 ( interne au ReActAgent ), l'insertion des Thoughts entre 8 et 12 ( le niveau d(orchestration par le Finalizer).

##Est-ce suffisant ?
S'agissant de la boucle ReAct (les exceptions), le traitement ne peut être amélioré sans remonter explicitement dans un arbre de raisonnement (Backtracking) en cas d'erreur.
Il s'agit de quitter ou corriger la branche courante :
– le moteur revient à un état antérieur du raisonnement,
– demande au modèle de réessayer une nouvelle étape de contournement.

C'est déjà fait partiellement via RetryException, mais ce n'est pas encore du vrai backtracking, car :
– on n'a pas un historique structuré - pas d'"arborescence" ni de "branches" - des états (stack des ReasoningSteps)
– on ne revient pas à un état antérieur du raisonnement,
– on ne supprime pas la branche fautive,
– on ne modifie pas le contexte du modèle.

*à suivre...*

ReActEngine v1 : Modules et traitements

Bertrand Degoy — 2026-04-09T08:23:12Z

ReActEngine Mistral v1 est un moteur agentique modulaire, contrôlable et extensible, combinant RAG (Research Augmented Generation), outils personnalisés, sélection dynamique d'outils dont MCP (Model Context Protocol) et génération orchestrée.
Il est conçu pour les environnements multi-thèmes, multi-sources et nécessitant une auditabilité stricte du raisonnement et des actions.

Destinée à un public expert, voici une description de l'agent ReActEngine Mistral v104 fondé sur llama_index.core.agent.workflow.ReActAgent, intégrant Finalizer, ToolRouter, RAG, outils personnalisés et orchestration.

ReActEngine Mistral v104 — Description technique

1. Nature de l'agent

L'agent Mistral ReAct v104 est un moteur agentique basé sur le paradigme ReAct (Reasoning + Acting).
Il combine :

un LLM Mistral (via API ou local),
un orchestrateur d'outils dont MCP,
un Finalizer pour la génération contrôlée,
un ToolRouter pour la sélection dynamique d'outils,
un RAG (Research Augmented Generation) modulaire basé sur l'agent de recherche Chat Engine Mistral utilisé par notre ChatBot simple.

Il s'appuie sur la classe ReActAgent(Workflow) plutôt que sur les agents préconstruits, afin de garantir :

un contrôle fin du cycle ReAct,
une meilleure auditabilité,
une intégration propre des outils personnalisés,
une compatibilité avec les pipelines agentiques complexes.

Constatant que les erreurs dans la boucle ReAct non interceptées ou mal traitées aboutissaient sur un arrêt intempestif et silencieux du raisonnement, un principe est posé : dans la boucle ReAct, seules deux exceptions peuvent ( et doivent ) être levées : RetryException et ForceFinalizeException. Le message d'erreur doit être explicite pour permettre au raisonnement de poursuivre ou de retourner proprement vers l'utilisateur. Ceci a motivé une part des modifications au code de Llamaindex.

Avec le même objectif - éviter les arrêts du raisonnement - deux autres modifications portent sur la génération et le traitement de question posée à l'utilisateur ainsi que le recours au RAG pour y trouver des informations susceptibles de guider le raisonnement.

Points clés de la version v104

Intégration du Finalizer (contrôle de la réponse finale).
Intégration du ToolRouter (sélection dynamique des outils).
Utilisation de ReActAgent(Workflow) plutôt que l'agent préconstruit, afin d'atteindre le cœur de la boucle ReAct et y apporter des améliorations .
Accès du LLM au RAG avec l'outil RagTool.
Accès du LLM aux données temps réel avec MCP.
Architecture stateless côté agent, stateful côté application.
Gestion centralisée des erreurs assurant la continuité du raisonnement.

2. Architecture générale

2.1. Diagramme des échanges


ReActEngine v1 diagramme des échanges

Les modules de la partie gauche (ReActEngine, ToolRouter, ReActFinalizer, ReActStreamParser) ont été développés spécialement pour atteindre les objectifs du ReActEngine v1, tandis que la partie droite comprend les modules du ReActAgent(Workflow) de LlamaIndex avec quelques adaptations. Le LLM est une API de MistralAI.

Conseils : Cliquez sur le diagramme pour le zoomer. Ouvrez le diagramme dans une autre fenêtre pour mieux suivre la suite.

2.2. Vision globale du flux

Utilisateur → ReActEngine : prompt.
ReActEngine → ToolRouter : sélection d'outils.
ReActEngine → ReActAgent : initialisation du pipeline.
Formatter → LLM : message formaté.
LLM → StreamParser : tokens bruts → blocs ReAct.
Parser → Agent : StepResult.
Workflow : décide de la suite (outil, raisonnement, final).
Finalizer : rebouclage sur erreur ou réponse finale.
ReActEngine → Utilisateur : streaming de la réponse.

A partir d'ici, nous pouvons distinguer :

La boucle ReAct reposant sur les modules LlamaIndex : ReActAgent, BaseWorkflowAgent, ReActWorkflow, ReActOutputParser. Seule la boucle ReAct échange avec le LLM.
L'Orchestrateur composé des modules de haut-niveau : ReActEngine, ToolRouter, ReActFinalizer, ReActStreamParser. ReActAgent est le seul lien avec ce niveau applicatif.

2.3. Boucle ReAct

L'agent suit la logique décrite dans Synergizing Reasoning and Acting in Language Models :

Reasoning : le LLM produit une intention ou un plan.
Acting : l'agent appelle un outil.
Observation : l'outil renvoie un résultat.
Reasoning : le LLM intègre l'observation.
Final Answer : produit par le Finalizer.

Avec LlamaIndex ReActAgent basé sur Workflow, la boucle ReAct est orchestrée par répétition de la fonction take_step(). Toute action est synonyme d'appel à un outil. Il est mis fin à la boucle lorsqu'une réponse finale est détectée .


La boucle ReAct

En résumé :

Le workflow ne fait qu'appeler en boucle la méthode take_step.
ReActAgent construit chaque étape en appelant le LLM.
Le parser transforme les deltas en blocs ReAct.
Le finalizer décide si l'agent doit continuer ou s'arrêter.
Le workflow relance l'étape tant que nécessaire.

ReActAgent (remanié)

Entrée : message formaté (prompt + contexte + outils).
Traitement : Implémente la logique ReAct :
Thought → Action → Observation → Thought → …
Décide quand appeler un outil. Produit un StepResult à chaque itération.
Sortie : StepResult (structure contenant Thought/Action/Observation).

Ce module est au centre du protocole ReAct. Il fournit l'infrastructure nécessaire pour traiter : la construction des étapes de raisonnement, les appels au LLM, le parsing structuré des réponses du LLM, le déclenchement d'outils, la production de la réponse finale.

Le ReActAgent ne traite qu'une étape à la fois. Il est appelé, d'étape en étape, par la méthode run_agent_step du Workflow.

La méthode take_step()

Au cœur de la boucle ReAct, cette méthode traite une seule étape de raisonnement :

Formater l'entrée du LLM à l'aide du template ReAct.
Appeler le LLM (en mode streaming ou non).
Parser la sortie du modèle en un ReasoningStep structuré.
Gérer les erreurs de parsing ou les états ReAct invalides.
Puis, selon le cas :
- retourner une réponse finale,
- déclencher un appel d'outil,
- ou demander au LLM de réessayer ou de finaliser.

Les principales modifications portent sur la gestion des sorties LLM mal formées ou incomplètes, ainsi que sur le traitement des exceptions :

normalisation du format de sortie du LLM, contribuant à rendre l'agent agnostique en ce qui concerne les LLMs dont les formats sont peu normalisés.
relance de la boucle lorsque le parseur détecte une sortie ReAct incomplète, mal formée ou autrement invalide, mais pouvant être corrigée par le modèle.
traitement de deux exceptions, :
- RetryException → la sortie est incomplète ou tronquée ; le LLM doit réessayer en se fondant sur le message d'erreur. Cela couvre aussi les erreurs des outils.
- ForceFinalizeException → le modèle a produit un état ReAct invalide (ex. : Thought sans Action ni Answer) ; le prochain appel LLM doit produire uniquement une réponse finale. Ces exceptions sont les seules autorisées au sein de la boucle afin d'éviter les arrêts silencieux de l'agent. Toutes les exceptions d'une autre classe levées au sein du code sont interceptées et ramenées à l'une de ces deux exceptions.

La méthode handle_tool_call_result()

Cette méthode traite les résultats des appels d'outils :

récupère l'historique courant de raisonnement (variable d'état ctx),
inspecte chaque résultat d'outil,
distingue les erreurs réelles des contenus vides légitimes,
normalise le contenu observé,
ajoute une étape d'observation au raisonnement,
gère les cas particuliers (ask_user, return_direct),
met à jour l'état persistant du raisonnement dans le contexte (variable d'état ctx). Les principales modifications incluent :
la distinction entre un retour d'outil légitimement vide et une erreur de l'outil.
la normalisation du retour d'outil (le contenu observé), contribuant à l'adaptation aux différents LLMs.
une détection d'erreurs garantissant que les outils signalent explicitement leurs échecs en levant l'une des exception RetryException ou ForceFinalizeException afin d'éviter un arrêt intempestif du raisonnement.
la gestion d'un outil AskUserTool ( créé dans la GeneralToolBox ) permettant au modèle de poser une question à l'utilisateur, puis la transformation de sa réponse en Observation ReAct et la relance de la boucle ReAct via take_step().

BaseWorkflowAgent (modifié)

Entrée : StepResult ou message intermédiaire.
Traitement : Gère la logique générique d'un agent (état, transitions, erreurs). Coordonne les appels entre Workflow, Formatter, Parser.
Sortie : instructions pour la prochaine étape du workflow.

La principale modification porte sur la gestion de la pause en attente d'une réponse de l'utilisateur (outil AskUser).

ReActWorkflow

Entrée : StepResult + contexte d'exécution.
Traitement : Orchestration du cycle ReAct. Détermine si l'agent doit :
continuer à raisonner,
appeler un outil,
ou produire la réponse finale.
Sortie : nouvelle étape à exécuter (run_step).

ReActChatFormatter

Entrée : prompt utilisateur + état du workflow.
Traitement : Formate le message dans le style attendu par le LLM (system + user + tool instructions). Injecte les outils dans le prompt si nécessaire.
Sortie : message formaté envoyé au LLM.

ReActOutputParser (modifié)

Entrée : sortie brute du LLM. Traitement : Analyse la réponse du LLM. Extrait Thought / Action / Observation / FinalAnswer. Détecte les erreurs de format.
Sortie : StepResult structuré.

Les principales modifications portent sur une détection et une gestion correcte des erreurs en levant RetryException ou ForceFinalizeException afin d'éviter les arrêts intempestifs du LLM.

Modèle LLM

Entrée : message formaté (prompt complet).
Traitement : Génération token-par-token. Produit du texte brut sans structure interne explicite.
Sortie : tokens bruts → envoyés au StreamParser.

Il faut noter que, si de nombreuses adaptations visent à rendre notre ReActAgent agnostique vis-à-vis des LLMs, notamment en normalisant les formats des requêtes et des réponses, cela n'est pas encore finalisé dans l'état actuel du développement.

Tool

L'agent combine trois familles d'outils :

A. RAG (QueryEngineTool)

Basé sur chat_engine_mistral_v1.3.x.
Utilise les index créés par RAG Manager ou IngestCmd.
Permet un RAG cohérent, multithème, multilingue.

Exposer un outil RAG à la boucle ReAct permet au LLM d'accéder à des descriptions systémiques, des routines de raisonnement, des spécifications etc., tout documents normatifs permettant de soutenir le raisonnement et de le ré-orienter en cas d'impasse.

B. Outils personnalisés (FunctionTools)

Fournissent des données temps réel (par exemple issues de WhatisWhat).
Les données sont injectées via MCP. Voir : ReAct et intégration des données temps réel avec MCP ( Model Context Protocol )
Exemples : météo, état d'un système, données métier, etc.

Voir également : RAG : Chat Engine ReAct avec outils

C. Outils généralistes

Calculs : arithmétique, statistique
Manipulation de texte
Utilitaires divers

2.3. Orchestrateur

De ce point de vue, on peut considérer le ReActEngine décrit précédemment comme une boîte noire (dont on représente tout de même l'essentiel pour une meilleure compréhension) animée par l'Orchestrateur.


Modules de haut niveau, autour de l'agent ReAct

User

Entrée : intention humaine, question, commande.
Traitement : aucun — c'est la source du prompt.
Sortie : prompt utilisateur envoyé au ReActEngine.

ToolRouter

Entrée : prompt brut.
Traitement : Analyse sémantique du prompt. Sélectionne les outils pertinents (toolbag).
Sortie : liste d'outils pertinents → renvoyée au ReActEngine.

ReActEngine

Entrée : prompt utilisateur.
Traitement : Détermine si le prompt nécessite des outils. Appelle le ToolRouter pour identifier les outils pertinents. Initialise un agent ReAct complet (Finalizer, Workflow, Formatter, Parser…). Lance la boucle de streaming (token-par-token).
Sortie : flux de tokens structurés (Thought / Action / Observation / FinalAnswer).

ReActStreamParser

Entrée : tokens bruts provenant du LLM. Traitement : Reconstitue les blocs ReAct (Thought, Action, Observation…). Filtre les artefacts, nettoie les tokens. Émet des fragments de réponse via un générateur asynchrone.
Sortie : tokens nettoyés + blocs ReAct structurés.

ReActFinalizer

Entrée : instance d'agent ReAct.
Traitement : Surveille la fin du raisonnement. Détecte un FinalAnswer ou une condition d'arrêt. Nettoie et finalise la réponse.
Sortie : réponse finale propre, prête à être envoyée à l'utilisateur.

3. API du ReActEngine v1

3.1. `init(...)`

Deux modes d'initialisation :

Mode 1 : avec `ragkwargs`

Adapté à une utilisation en mode API, relançant l'instanciation à chaque requête.
Le thème, la langue, le niveau de détail, etc. sont fournis dès l'instanciation.
L'agent est immédiatement opérationnel.

Mode 2 : sans `ragkwargs`

Adapté à un fonctionnement en mode démon ou worker multi-thèmes.
L'application doit ensuite appeler start() avec le thème en argument.

Paramètres clés :

config : configuration globale (commune à IngestCmd, ChattyBot, ChattyWS…)
llmapikey : clé API MistralAI
token : jeton de sécurité pour les serveurs de données
ragkwargs : dictionnaire contenant au minimum :
- theme
- detail
- language

3.2. Méthode `start()`

Méthode pour les services REST ou workers persistants.

complète l'initialisation selon le thème,
charge l'index si nécessaire,
permet aux applications stateful de fournir leur propre index (optimisation),
prépare l'agent ReAct pour le thème courant.

Retour : un objet ReActAgent prêt à l'emploi.

3.3. Gestion de l'historique — `set_history()`

Cette méthode :

reçoit un historique OpenAI-style :
[{ "role": "user", "content": "..." }, ...]
nettoie et compresse l'historique pour compatibilité ReAct,
stocke :
- self.conversation_history
- self.compressed_history

L'agent est statique :
→ l'application appelante doit gérer la persistance de l'historique ( plus précisément "historique de conversation" ) et le transmettre avant chaque requête.

3.4. Exécution asynchrone — `stream(prompt)`

Fonctionnement

Pour chaque prompt :

ToolRouter sélectionne dynamiquement les outils pertinents
→ réduction du contexte, optimisation des coûts, meilleure précision.
L'agent ReAct est reconstruit avec uniquement les outils routés.
Un tote bag est préparé :
- historique compressé
- langue
- profil (ex. "expert")
Le ReActFinalizer gère la génération incrémentale.
La méthode retourne un AsyncGenerator.

3.5. Exécution synchrone — `get_engine_response()`

Fonctionnement

récupère l'historique compressé si non fourni,
applique le ToolRouter,
exécute l'agent ReAct,
retourne une réponse complète (non streamée).

4. Mise en œuvre des outils dans ReActAgent

4.1. Les outils

L'agent s'appuie sur trois ToolKits complémentaires :

GeneralToolKit : outils génériques toujours disponibles.
ThemeToolKit : outils métier + un outil RAG pour accéder à la documentation interne.
ToolKit Temps Réel : outils connectés à des sources de données dynamiques (internes/externes).

Voir également : ReAct et intégration des données temps réel avec MCP ( Model Context Protocol )

4.2. L'outil RAG dans la boucle ReAct

Le RAG (Research Augmented Generation) est intégré comme un outil standard, accessible via la logique ReAct.

Rôle du RAG

Il permet à l'agent d'interroger la documentation interne de l'entreprise, composée de : documents historiques (rapports, notes, logs), référentiels documentaires (procédures, notices techniques), routines spécialisées pour guider le raisonnement dans des tâches répétitives.

Fonction dans ReAct

Le RAG est utilisé lorsque l'agent doit : vérifier une information interne, s'appuyer sur des documents de référence, exécuter une tâche nécessitant un contexte métier documenté.

Le RAG enrichit le raisonnement de l'agent en lui donnant accès à la connaissance interne, tout en restant orchestré par ReAct.

4.3. le ToolRouter

Le ToolRouter identifie automatiquement les outils les plus adaptés à une requête utilisateur grâce à un mécanisme de similarité vectorielle.

Fonctionnement : Chaque outil possède une description textuelle (métadonnées). Voir : ReAct : la carte des intentions : Intent Map Les descriptions et la requête utilisateur sont vectorisées via un modèle d'embedding. Le routeur calcule la similarité cosinus entre la requête et chaque outil. Les outils sont classés par pertinence. Le ReActAgent choisit l'outil à appeler en fonction du classement et du contexte.

→ Le ToolRouter guide la boucle ReAct vers l'outil optimal au moment opportun.

Résultat : Un agent capable de combiner raisonnement, outils spécialisés, documentation interne et données temps réel.

Le module ModelLoaderFactory ( "la factory" )

Bertrand Degoy — 2026-04-02T07:22:02Z

Ce document explique la façon dont les modèles locaux sont créés et utilisés dans un environnement LlamaIndex.
On y détaille :
– les différences classes structurelles de modèles locaux, ce qui nécessite une abstraction pour LlamaIndex,
– comment le module ModelLoaderFactory ( "la factory" ) assure la création des modèles locaux et leur abstraction,
– le rôle du singleton AppSettings pour exposer les modèles.

Différences entre modèles HuggingFace, SentenceTransformer et modèles génériques

Tout d'abord, il faut considérer que :

le modèle d'embedding DOIT être celui utilisé par le LLM,
dans une architecture RAG, il doit être le même pour l'ingestion, la sélection et la génération.

Les modèles d'embeddings utilisés dans un pipeline RAG ou agentique n'appartiennent pas tous à la même famille. Ils diffèrent par leur format, leur API, leur manière de produire les embeddings et leur niveau de spécialisation. Comprendre ces différences aide à choisir le bon modèle et à structurer une architecture propre et stable.

Note : la factory peut également gérer de façon similaire des modèles 'causal LM' ( notamment des LLM ), on se concentre ici sur les modèles d'embedding.

Modèles HuggingFace (HF Encoders)

Les modèles HF de type encoder (comme BERT, RoBERTa, MPNet, BGE, E5, GTE, Jina) sont des modèles Transformers polyvalents. Ils ne sont pas conçus spécifiquement pour produire des embeddings, mais ils peuvent le faire.

Ils utilisent le format standard HuggingFace, avec des fichiers comme config.json, model.safetensors et tokenizer.json. Leur API repose sur l'appel direct du modèle avec un tokenizer, ce qui renvoie un tenseur PyTorch contenant les représentations de chaque token. Pour obtenir un embedding final, il faut appliquer un pooling manuel (par exemple une moyenne des tokens ou l'utilisation du token CLS).

Ces modèles sont très flexibles et peuvent servir à d'autres tâches que les embeddings, mais ils demandent plus de travail pour produire un vecteur cohérent et stable. Ils peuvent aussi être plus lourds en mémoire et en temps d'inférence.

Modèles SentenceTransformer (ST)

Les modèles SentenceTransformer sont construits à partir de modèles HF, mais ils sont spécialement adaptés pour produire des embeddings de phrases. Ils incluent un pipeline complet : tokenizer, modèle Transformer et couche de pooling intégrée.

Leur format est différent de celui de HuggingFace : ils utilisent des fichiers comme modules.json et des sous-dossiers tels que 0_Transformer/ et 1_Pooling/. Leur API est simple : une seule méthode encode(text) renvoie directement un vecteur numpy prêt à l'emploi.

Ces modèles sont optimisés pour la similarité sémantique, ce qui les rend particulièrement adaptés aux systèmes RAG, aux moteurs de recherche et aux tâches de clustering. Ils sont plus simples à utiliser que les modèles HF, mais moins flexibles pour d'autres usages.

Note : BAAI fournit ses modèles ( comme BAAI/bge-small-en-v1.5" ) sous les deux formats HF et ST.

Modèles génériques ou personnalisés

Il existe aussi des modèles qui ne suivent ni le format HF ni celui de SentenceTransformer. Ils peuvent être très simples, comme un modèle maison exposant une méthode embed(text), ou très spécialisés, comme un modèle ONNX ou quantisé avec une API minimale.

Ces modèles n'ont pas de format standard et leur API varie selon l'implémentation. Ils peuvent renvoyer des listes Python, des tenseurs ou d'autres structures. Ils sont souvent utilisés pour les tests, les prototypes ou les environnements très contraints.

Ils sont faciles à intégrer, mais nécessitent une couche d'abstraction pour garantir une sortie cohérente et éviter les comportements imprévisibles.

Pourquoi une architecture unifiée est nécessaire

Les différences entre HF, ST et les modèles génériques rendent indispensable une couche d'unification. Sans cela, chaque composant du système devrait gérer des formats différents, des API différentes et des comportements différents.

L' architecture décrite par la suite résout ce problème en trois étapes :

la factory installe et valide le modèle ;
le wrapper normalise les sorties et fournit une API interne stable ;
l'adapter expose une API compatible LlamaIndex.

Cette approche garantit que tous les modèles, quelle que soit leur origine, produisent des embeddings cohérents, normalisés et utilisables dans l'ensemble du pipeline.

Architecture de la création des modèles locaux

Objectifs

Déterminisme total : aucun fallback, aucune heuristique.
Installation automatique au premier appel de la factory, sans lazy-loading des poids.
Compatibilité offline : tout fonctionne ensuite sans réseau.
Normalisation stricte : toujours retourner des list[float].
Séparation nette des responsabilités :
- Factory = installation/validation
- Wrapper = normalisation
- Adapter = API LlamaIndex ou autre
Assurer un point d'accès aux API unique et global : AppSettings

1. Vue d'ensemble

Le chargement d'un modèle repose sur trois couches clairement séparées :

ModelLoaderFactory
- Installe, valide et instancie les modèles HF/ST.
- Garantit un fonctionnement déterministe, sans fallback ni heuristique.
UniversalEmbeddingWrapper Normalisation et abstraction du backend :
- Unifie tous les backends (HF, ST, générique).
- Fournit une API interne stable : embed(str) -> list[float].

et, dans le cas d'un modèle d'embeddings :

LlamaIndexEmbeddingAdapter
- Expose l'API LlamaIndex (get_text_embedding, get_query_embedding).
- Utilise le wrapper pour garantir la normalisation.

Le résultat est stocké dans le singleton global , AppSettings.embed_model devient le modèle d'embeddings pour tout le système.

2. Chargement du modèle via la factory

factory = ModelLoaderFactory() embedding = factory.create_embedding( model_path= "/home/iadnc/.models/bge-small, model_name= "BAAI/bge-small-en-v1.5", model_type= "sentence_transformer", device= "cuda"
)

Ce que fait la factory :

Sélectionne l'installateur approprié (HFInstaller, STInstaller).
Installe ou valide le modèle dans model_path.
Détecte le type réel du modèle (HF, ST, causal LM).
Vérifie la cohérence entre type déclaré et type détecté.
Instancie l'embedding RAM (HFEmbedding ou STEmbedding).

Résultat : un embedding brut, non encore adapté à LlamaIndex.

3. Construction du singleton `AppSettings.embed_model`

AppSettings.embed_model = create_llamaindex_embedding(embedding)

Cette fonction construit la chaîne API complète :

AppSettings.embed_model
├── wrapper (UniversalEmbeddingWrapper)
│ └── embedding (HFEmbedding ou STEmbedding)
└── get_*_embedding() (API LlamaIndex BaseEmbedding)

Architecture

 ┌──────────────────────────┐
 │ ModelLoaderFactory │
 │ (installation + RAM) │
 └─────────────┬────────────┘
 │
 ▼
 Embedding RAM instancié 
 
 HFEmbedding (HF) | STEmbedding (ST) | Generic 
 - tensor output | - numpy output | - list 
 - pooling manuel | - pooling intégré | - API custom
 
 │
 ▼
 ┌────────────────────────────────────┐
 │ UniversalEmbeddingWrapper │
 │ embed(str) -> list[float] │
 │ backend = HF / ST / generic │
 └─────────────────┬──────────────────┘
 │
 ▼
 ┌──────────────────────────────────────┐
 │ LlamaIndexEmbeddingAdapter │
 │ get_text_embedding() │
 │ get_query_embedding() │
 └──────────────────┬───────────────────┘
 │
 ▼
 ┌────────────────────────────────┐
 │ AppSettings.embed_model │
 │ (singleton global complet) │
 │ │
 │ ├── wrapper │
 │ │ └── embedding (HF/ST) │
 │ └── get_*_embedding() │
 └────────────────────────────────┘

Le singleton AppSettings permet d'accéder à trois niveaux d'API, chacun avec un rôle clair :

API interne :
AppSettings.embed_model.wrapper.embed("texte")
→ utilisée par les compresseurs, le RAG, les agents.
API LlamaIndex :
AppSettings.embed_model.get_text_embedding("texte")
→ utilisée par les index, retrievers, query engines.
API modèle brut :
AppSettings.embed_model.wrapper.embedding.model
→ utile pour debug, tests, opérations avancées.

4. Exemples d'usage

API interne (wrapper)

vec = AppSettings.embed_model.wrapper.embed("Bonjour")

API LlamaIndex

vec = AppSettings.embed_model.get_text_embedding("Bonjour")

API modèle HF/ST brut

hf_model = AppSettings.embed_model.wrapper.embedding.model

En savoir plus :
– AppSettings : un Singleton Global pour stabiliser les modèles face aux limites du singleton LlamaIndex

#! python3
# coding: utf8
# PythonApp/commons/model_loader_factory.py
'''
Classe ModelLoaderFactory
## Usage pour un modèle d'embedding :
embedding = factory.create_embedding(
...
)
app_settings.embed_model = create_llamaindex_embedding(embedding)
Voir : https://ia.dnc.global/Preparation-et-utilisation-des-modeles-locaux-pour-LlamaIndex.html
Auteur : B.Degoy bertrand@degoy.com
copyright (c) 2026 B.Degoy
licence : All rights reserved - Tous droits réservés
v 0.0.1
2026/02/16-20 (t=9h)
'''
# Standard imports
from typing import List
from pathlib import Path
import json
from sentence_transformers import SentenceTransformer
from transformers import AutoModel, AutoTokenizer, PreTrainedModel
# Third-party Imports
from llama_index.core.embeddings import BaseEmbedding
from huggingface_hub import hf_hub_download, list_repo_files
from langchain.embeddings.base import Embeddings as LCEmbeddings
#TODO Futurs installateurs (à ajouter progressivement) :
# from commons.installers.hf_seq2seq_installer import HFSeq2SeqInstaller
# from commons.installers.onnx_installer import ONNXInstaller
# from commons.installers.gguf_installer import GGUFInstaller
# Fonction utilitaire : assemble wrapper + adapter
def create_llamaindex_embedding(embedding):
wrapper = UniversalEmbeddingWrapper(embedding)
return LlamaIndexEmbeddingAdapter(
wrapper=wrapper,
model_name=embedding.model_name,
)
import numpy as np
class UniversalEmbeddingWrapper:
"""
Couche d'unification des embeddings garantissant une interface unique,
stable et normalisée pour tous les backends utilisés dans le système.
Cette classe encapsule un objet d'embedding arbitraire (HFEmbedding,
STEmbedding, modèle générique, mock de test, etc.) et fournit une API
minimale mais strictement définie :
embed(str) -> list[float]
indépendamment du backend réel. Elle élimine ainsi toute ambiguïté sur le
format de sortie et protège les couches supérieures (compresseurs,
LlamaIndexEmbeddingAdapter, moteurs RAG, etc.) contre les variations
d'implémentation des bibliothèques tierces.
Détection du backend
--------------------
Le wrapper identifie le type d'embedding fourni selon les attributs présents :
- SentenceTransformer → présence de `embed_documents`
- HFEmbedding custom → présence de `_get_text_embedding`
- Embedding générique → présence de `embed`
- Sinon → backend inconnu (erreur explicite)
Cette détection est volontairement simple, explicite et déterministe :
aucune heuristique, aucun fallback, aucune supposition implicite.
Normalisation des sorties
-------------------------
Les backends peuvent renvoyer différents formats :
- numpy.ndarray
- torch.Tensor
- list[float]
- objets HF/ST spécifiques
Le wrapper applique systématiquement :
- si l'objet possède `.tolist()` → conversion en liste Python
- si c'est déjà une liste → renvoi direct
- sinon → conversion explicite via `list(v)`
Garanties
---------
- Sortie toujours en `list[float]`, quel que soit le backend.
- Fonctionnement déterministe et compatible offline.
- Aucune prise en charge de `embed(list[str])` : la méthode ne traite
que des chaînes individuelles, conformément aux invariants du système.
- Protection contre les comportements implicites ou non documentés des
bibliothèques tierces.
Paramètres
----------
embedding : object
Instance d'un backend d'embedding (HF, ST, générique, mock, etc.)
fournissant au minimum une méthode d'encodage compatible avec l'un
des backends détectés.
"""
def __init__(self, embedding):
self.embedding = embedding
self.backend = self._detect_backend()
def _detect_backend(self):
if hasattr(self.embedding, "embed_documents"):
return "st_embedding"
if hasattr(self.embedding, "_get_text_embedding"):
return "hf_embedding"
if hasattr(self.embedding, "embed"):
return "generic_embedding"
return "unknown"
def embed(self, text: str) -> list[float]:
"""Normalise toutes les sorties en list[float]."""
if self.backend == "hf_embedding":
arr = self.embedding._get_text_embedding(text)
if isinstance(arr, list):
return arr
return arr.tolist()
if self.backend == "st_embedding":
arr_list = self.embedding.embed_documents([text])
v = arr_list[0]
if isinstance(v, list):
return v
return v.tolist()
if self.backend == "generic_embedding":
arr = self.embedding.embed(text)
if isinstance(arr, list):
return arr
return arr.tolist()
raise RuntimeError("Backend inconnu")
from llama_index.core.embeddings import BaseEmbedding
from pydantic import Field
from pydantic import ConfigDict
class LlamaIndexEmbeddingAdapter(BaseEmbedding):
"""
Adaptateur entre UniversalEmbeddingWrapper et l'API BaseEmbedding de LlamaIndex.
Cette classe fournit une couche d'intégration stable et minimale permettant
d'utiliser n'importe quel backend d'embeddings (HF, SentenceTransformer,
embeddings génériques, modèles locaux, etc.) au sein de LlamaIndex, tout en
respectant strictement les invariants du wrapper universel :
- Toutes les sorties sont normalisées en `list[float]`.
- Aucun appel `embed(list[str])` n'est autorisé : l'adapter boucle
explicitement sur les listes de textes.
- Les méthodes sync/async de BaseEmbedding sont correctement implémentées.
- Le comportement est déterministe et thread-safe.
Paramètres
----------
wrapper : UniversalEmbeddingWrapper
Wrapper unifié fournissant la méthode `embed(str) -> list[float]`.
L'adapter délègue tous les calculs d'embeddings à ce wrapper.
"""
#Pydantic v2
model_config = ConfigDict(extra="allow")
wrapper: object = Field(...)
model_name: str = Field(default="unknown")
def __init__(self, wrapper, model_name="unknown"):
super().__init__(
model_name=model_name,
wrapper=wrapper,
)
def describe(self) -> str:
cls = self.__class__.__name__
return (
f"{cls}:\n"
f" model_name : {self.model_name}\n"
f" wrapper : {self.wrapper.__class__.__name__}\n"
f" embedding : {self.wrapper.embedding.model_name}\n"
)
@property
def embedding_root(self):
return self.wrapper.embedding
def _to_list(self, v):
"""
Convertit un vecteur en liste Python.
Cette méthode garantit que les embeddings renvoyés par les backends
(NumPy, Torch, HF, ST, etc.) sont convertis proprement en `list[float]`.
Si `v` est déjà une liste Python, elle est renvoyée telle quelle.
Paramètres
----------
v : array-like
Vecteur d'embedding potentiel (numpy.ndarray, torch.Tensor, list).
Retour
------
list[float]
Embedding converti en liste Python.
"""
if hasattr(v, "tolist"):
return v.tolist()
return list(v)
# --- Méthodes privées requises par BaseEmbedding ---
def _get_query_embedding(self, query: str):
"""
Embedding d'une requête utilisateur (méthode interne LlamaIndex).
Cette méthode est appelée par LlamaIndex pour encoder les requêtes
textuelles. Elle délègue directement au wrapper universel, garantissant
une sortie normalisée en `list[float]`.
Paramètres
----------
query : str
Texte de la requête.
Retour
------
list[float]
Embedding de la requête.
"""
return self.wrapper.embed(query)
def _get_text_embedding(self, text: str):
"""
Embedding d'un document ou d'un chunk (méthode interne LlamaIndex).
LlamaIndex appelle cette méthode pour encoder les documents ou les
chunks lors de la construction d'index. Le wrapper universel garantit
une sortie cohérente et normalisée.
Paramètres
----------
text : str
Texte à encoder.
Retour
------
list[float]
Embedding du texte.
"""
return self.wrapper.embed(text)
async def _aget_query_embedding(self, query: str):
"""
Version asynchrone de l'embedding de requête.
Comme le wrapper universel ne fournit qu'une API synchrone, cette
méthode utilise `asyncio.to_thread` pour exécuter l'embedding dans un
thread séparé, garantissant la compatibilité avec les pipelines async
de LlamaIndex.
Paramètres
----------
query : str
Requête utilisateur.
Retour
------
list[float]
Embedding de la requête.
"""
# wrapper.embed() est sync, on passe par asyncio.to_thread
import asyncio
return await asyncio.to_thread(self.wrapper.embed, query)
# --- Méthodes publiques ---
def get_query_embedding(self, query: str):
"""
API publique LlamaIndex pour encoder une requête.
Cette méthode est un simple proxy vers `_get_query_embedding`, afin de
respecter l'interface publique de BaseEmbedding.
Paramètres
----------
query : str
Requête utilisateur.
Retour
------
list[float]
Embedding de la requête.
"""
return self._get_query_embedding(query)
def get_text_embedding(self, text: str):
"""
API publique LlamaIndex pour encoder un texte.
Proxy direct vers `_get_text_embedding`, utilisé par les indexeurs et
les moteurs de recherche internes de LlamaIndex.
Paramètres
----------
text : str
Texte à encoder.
Retour
------
list[float]
Embedding du texte.
"""
return self._get_text_embedding(text)
def get_text_embeddings(self, texts: list[str]):
"""
Encode une liste de textes.
Le wrapper universel ne supportant pas `embed(list[str])`, cette méthode
applique explicitement `embed()` sur chaque élément. Cela garantit une
compatibilité totale avec BaseEmbedding et évite les erreurs de type.
Paramètres
----------
texts : list[str]
Liste de textes à encoder.
Retour
------
list[list[float]]
Liste d'embeddings, un par texte.
"""
# wrapper n'a pas embed(list), on boucle
return [self.wrapper.embed(t) for t in texts]
class ModelLoaderFactory:
"""
Fabrique centralisée et déterministe pour l'installation, la validation et
l'instanciation des modèles d'embeddings et des modèles CausalLM.
Cette classe constitue le point d'entrée unique pour charger des modèles
locaux ou distants dans un environnement strictement contrôlé. Elle impose
une discipline forte : aucun comportement implicite, aucune heuristique,
aucune détection automatique du type de modèle. L'appelant doit fournir
explicitement le type attendu, et toute incohérence entre le type déclaré
et la structure réelle du modèle installé entraîne une erreur immédiate.
Rôle et garanties
-----------------
- Gestion centralisée de l'installation via des installateurs spécialisés
(HFInstaller, STInstaller, HFInstallerCausalLM).
- Validation stricte de la structure locale du modèle :
* HF : lecture de config.json + vérification des poids.
* SentenceTransformer : présence de modules.json + 1_Pooling.
- Aucun fallback, aucune récupération implicite, aucun accès réseau dans
les méthodes de création (l'installation peut télécharger, mais jamais
create_embedding / create_causal_lm).
- Fonctionnement 100 % déterministe et compatible offline après installation.
- Registry interne permettant de suivre les modèles chargés en RAM et de
les décharger proprement (GPU/CPU + GC).
Méthodes
------------
- create_embedding() :
Instancie un embedding RAM (HFEmbedding ou STEmbedding) après installation
et validation stricte du modèle.
- create_causal_lm() :
Instancie un moteur CausalLM local (HFCausalLMEngine) après validation.
- _select_installer() :
Sélection explicite de l'installateur en fonction du type déclaré.
- _detect_local_model_type() :
Détection stricte du type réel du modèle installé, sans heuristique.
- unload_model() :
Décharge proprement un modèle
"""
def __init__(self):
# Régistre interne
self._registry = {}
# Entrée principale : création d'un embedding RAM
def create_embedding(self, model_path: str, model_name: str, model_type: str, device: str = None):
"""
Crée un embedding RAM à partir d'un modèle local ou distant sans aucun comportement implicite.
Cette méthode ne tente jamais de déduire automatiquement le type de modèle. Le type
doit être fourni explicitement par l'appelant (ex. "hf_encoder", "sentence_transformer").
Aucun fallback, aucune heuristique et aucune détection distante (HuggingFace Hub) ne
sont effectués ( parce que c'est impossible du fait que les modèles en cache HF n'ont généralement pas de fichier config.json).
Toute incohérence entre le type déclaré et la structure du modèle installé entraîne une erreur explicite.
Pipeline :
1. Sélection de l'installateur correspondant au type déclaré.
- Aucun choix automatique : l'appelant est responsable du type.
- Si le type n'est pas supporté → RuntimeError.
2. Installation ou validation du modèle dans `model_path`.
- L'installateur garantit une installation idempotente et déterministe.
- Si le modèle est absent ou incomplet → installation complète.
- Si le modèle est présent → validation stricte.
- Aucun fallback, aucune récupération implicite.
3. Détection locale du type réel du modèle installé.
- Lecture de `config.json` (HF) ou `modules.json` (ST).
- Si la structure locale ne correspond pas au type déclaré → RuntimeError.
4. Instanciation de l'embedding RAM approprié.
- HFEmbedding pour "hf_encoder".
- STEmbedding pour "sentence_transformer".
- Aucun autre type n'est supporté.
Garanties :
- Fonctionnement strictement déterministe : aucun comportement caché.
- Compatibilité offline totale après installation.
- Pas d'accès réseau dans cette méthode.
- Pas de dépendance au cache HuggingFace Hub.
- Pas de heuristique, pas de fallback, pas de supposition.
- Validation systématique de la cohérence entre type déclaré et type détecté.
Paramètres :
model_path (str) :
Chemin local où installer ou valider le modèle.
Peut être un dossier vide ou un dossier contenant une installation existante.
model_name (str) :
Nom du modèle HuggingFace (ex. "BAAI/bge-small-en-v1.5").
Utilisé uniquement par l'installateur pour télécharger le modèle si nécessaire.
model_type (str) :
Type explicite du modèle. Doit être l'un des types supportés :
- "hf_encoder"
- "sentence_transformer"
Toute autre valeur entraîne une erreur immédiate.
device (str | None) :
Device d'exécution ("cpu", "cuda", etc.).
Si None → sélection automatique par l'embedding.
Retour :
Instance d'un embedding en RAM (CustomHFEmbedding, CustomSTEmbedding).
Exceptions :
RuntimeError :
- Type de modèle non supporté.
- Incohérence entre type déclaré et type détecté localement.
- Modèle local invalide ou structure incorrecte.
- Échec d'installation ou de validation.
"""
if model_type == "hf_causal_lm":
raise RuntimeError("[ModelLoaderFactory] Un modèle CausalLM ne peut pas être instancié comme embedding. Utiliser create_causal_lm")
# Installer le modèle via l'installateur défini
installer = self._select_installer(model_type)
local_path = installer.resolve(model_path, model_name)
# Détecter le type local pour validation
detected = self._detect_local_model_type(Path(local_path))
if model_type not in detected :
raise RuntimeError(
f"[ModelLoaderFactory] Incohérence : modèle déclaré '{model_type}' mais détecté '{detected}'"
)
# Instancier l'embedding RAM
if model_type == "sentence_transformer":
from commons.embeddings.st_embeddings import STEmbedding
embedding = STEmbedding(local_path, model_path, model_name, device)
self._registry[model_name] = embedding
return embedding
if model_type == "hf_encoder":
from commons.embeddings.hf_embeddings import HFEmbedding
embedding = HFEmbedding(local_path, device)
self._registry[model_name] = embedding
return embedding
raise RuntimeError(f"[ModelLoaderFactory] Aucun embedding disponible pour le type : {model_type}")
def create_causal_lm(self, model_path: str, model_name: str, device: str = None):
"""
Instancie un modèle HuggingFace CausalLM (génératif) en RAM de manière
strictement déterministe, après installation locale complète et validation
structurelle.
Cette méthode est l'équivalent "génération" de `create_embedding()`. Elle ne
traite que les modèles de type `hf_causal_lm`, c'est-à-dire les modèles
autoregressifs compatibles avec `AutoModelForCausalLM` (LLaMA, Mistral,
GPT-like, Qwen, Phi, Gemma, etc.).
Étapes garanties :
1. Installation stricte et idempotente via HFInstallerCausalLM :
- Téléchargement explicite de tous les fichiers du repo HF.
- Aucun fallback réseau après installation.
- Aucun recours au cache HF.
- Support des modèles sharded.
- Validation stricte de la structure CausalLM.
2. Détection locale du type réel du modèle via `_detect_local_model_type()`.
- Le type détecté doit être exactement "hf_causal_lm".
- Toute incohérence entraîne une erreur explicite.
3. Instanciation du moteur de génération HFCausalLMEngine :
- Chargement RAM du modèle.
- Configuration explicite du device.
- Enregistrement dans le registre interne pour réutilisation.
Paramètres :
model_path (str) :
Chemin local où le modèle doit être installé ou déjà présent.
Le dossier est créé si nécessaire.
model_name (str) :
Nom du modèle HuggingFace (repo_id) à installer et charger.
device (str, optionnel) :
Device explicite pour l'inférence ("cpu", "cuda", "cuda:0", etc.).
Si None, le moteur applique sa logique interne.
Retour :
HFCausalLMEngine :
Instance prête à l'emploi du modèle CausalLM chargé en RAM.
Exceptions :
RuntimeError :
- Le modèle installé n'est pas détecté comme "hf_causal_lm".
- Structure locale invalide ou incomplète.
- Installation impossible ou incohérente.
- Toute violation du contrat de déterminisme ou de validation.
Notes :
Cette méthode ne doit jamais être utilisée pour des embeddings.
Les modèles CausalLM sont distinct des encodeurs HF et des SentenceTransformers dans leur architecture.
"""
installer = HFInstallerCausalLM()
local_path = installer.resolve(model_path, model_name)
detected = self._detect_local_model_type(Path(local_path))
if detected != ["hf_causal_lm"]:
raise RuntimeError(
f"[ModelLoaderFactory] Incohérence : modèle déclaré 'hf_causal_lm' mais détecté '{detected}'"
)
from commons.llm.hf_causal_lm import HFCausalLMEngine
engine = HFCausalLMEngine(local_path, model_name, device)
self._registry[model_name] = engine
return engine
# Sélection de l'installateur
def _select_installer(self, model_type: str):
if model_type == "sentence_transformer":
from commons.installers.st_installer import STInstaller
return STInstaller()
if model_type == "hf_encoder":
from commons.installers.hf_installer import HFInstaller
return HFInstaller()
if model_type == "hf_causal_lm":
from commons.installers.hf_causal_installer import HFInstallerCausalLM
return HFInstallerCausalLM()
raise RuntimeError(f"[ModelLoaderFactory] Aucun installateur disponible pour le type : {model_type}")
def _detect_local_model_type(self, path: Path) -> str:
"""
Détermine les types réels d'un modèle installé localement en inspectant
uniquement la structure du dossier, sans heuristiques implicites ni
priorité arbitraire.
Certains modèles (ex. BAAI/BGE, E5, GTE, Jina) peuvent exposer
simultanément une structure HuggingFace et une structure
SentenceTransformer. Cette méthode détecte donc tous les formats
présents et renvoie une liste de types possibles.
Détection :
- Format HuggingFace (HF) si :
* un fichier config.json lisible contient un champ "model_type"
* au moins un fichier de poids HF est présent
(model.safetensors, pytorch_model.bin, *.index.json)
* si model_type in {llama, mistral, gpt2, qwen, phi, gemma}
-> "hf_causal_lm"
* sinon si model_type in {bert, roberta, mpnet, bge, e5, gte, jina}
-> "hf_encoder"
- Format SentenceTransformer si :
* modules.json est présent
* le dossier 1_Pooling/ existe
Retour :
Liste des types détectés, par exemple :
["hf_encoder"]
["sentence_transformer"]
["hf_encoder", "sentence_transformer"]
["hf_causal_lm"]
Exceptions :
RuntimeError si aucune structure valide n'est détectée ou si les
fichiers présents sont incohérents ou non supportés.
"""
types = []
# --- Détection HuggingFace ---
config_path = path / "config.json"
if config_path.exists():
try:
cfg = json.loads(config_path.read_text())
except Exception as e:
raise RuntimeError(f"[ModelLoaderFactory] config.json illisible dans {path} : {e}")
cfg_model_type = cfg.get("model_type", "").lower()
if not cfg_model_type:
raise RuntimeError(f"[ModelLoaderFactory] config.json ne contient pas 'model_type' dans {path}")
weight_files = [
"model.safetensors",
"pytorch_model.bin",
"pytorch_model.bin.index.json",
]
if any((path / wf).exists() for wf in weight_files):
causal_types = {"llama", "mistral", "gpt2", "qwen", "phi", "gemma"}
if cfg_model_type in causal_types:
types.append("hf_causal_lm")
else:
hf_supported = {"bert", "roberta", "mpnet", "bge", "e5", "gte", "jina"}
if cfg_model_type in hf_supported:
types.append("hf_encoder")
else:
raise RuntimeError(
f"[ModelLoaderFactory] Type HF non supporté : '{cfg_model_type}' dans {path}. "
f"Types supportés : {sorted(hf_supported)}"
)
# --- Détection SentenceTransformer ---
if (path / "modules.json").exists() and (path / "1_Pooling").exists():
types.append("sentence_transformer")
# --- Aucun type détecté ---
if not types:
raise RuntimeError(f"[ModelLoaderFactory] Impossible de déterminer le type de modèle dans {path}")
return types
def unload_model(self, model_name: str):
"""
Désinstalle complètement un modèle de la RAM, en supprimant toutes les
références Python connues, en nettoyant le registry interne, et en
vidant les caches PyTorch. Cette méthode garantit qu'aucun résidu
mémoire ne persiste après déchargement.
Règles contractuelles :
- Le modèle doit avoir été chargé via ModelLoaderFactory.
- Le registry interne doit contenir une entrée pour ce modèle.
- Le déchargement supprime :
- l'objet embedding (STEmbedding ou HFEmbedding)
- le modèle HF ou SentenceTransformer sous-jacent
- les buffers internes éventuels
- les références dans le registry
- Les caches PyTorch sont vidés explicitement.
- Aucun fallback, aucune suppression silencieuse.
Paramètres :
model_name (str) :
Nom du modèle tel qu'enregistré dans le registry RAM.
Exceptions :
RuntimeError :
- Si le modèle n'est pas présent dans le registry.
"""
# Vérifier la présence dans le registry
if model_name not in self._registry:
raise RuntimeError(
f"[ModelLoaderFactory] Impossible de décharger '{model_name}' : "
f"aucune entrée dans le registry RAM."
)
embedding = self._registry[model_name]
# Supprimer les références internes du wrapper
if hasattr(embedding, "model"):
del embedding.model
if hasattr(embedding, "tokenizer"):
del embedding.tokenizer
# Supprimer l'entrée du registry
del self._registry[model_name]
# Nettoyage PyTorch
try:
import torch
torch.cuda.empty_cache()
torch.cuda.ipc_collect()
except Exception:
pass # CPU-only ou PyTorch non installé
# Garbage collector Python
import gc
gc.collect()

Télécharger

AppSettings : un Singleton Global pour stabiliser les modèles face aux limites du singleton LlamaIndex

Bertrand Degoy — 2026-03-30T10:12:26Z

Dans une architecture utilisant LlamaIndex, la gestion des modèles (LLM, embeddings, tokenizer, etc.) repose sur des mécanismes internes du framework.

Ces mécanismes fonctionnent correctement dans des cas simples, mais présentent plusieurs limites structurelles dans un écosystème d'applications devant partager des modèles identiques.

Le “singleton” interne de LlamaIndex n'est ni strict, ni stable, et peut être réinitialisé ou modifié de manière implicite selon l'ordre des imports, les contextes d'exécution ou les workers. Cela conduit à des comportements non déterministes, difficiles à diagnostiquer, et parfois dangereux (modèles différents selon les modules ou les workers). Pour stabiliser l'ensemble, il est nécessaire d'introduire un singleton global explicite, contrôlé, verrouillé, traçable et idempotent : c'est le rôle de AppSettings et AppSettingsManager qui forment un système robuste plus strict et plus fiable que celui fourni par LlamaIndex, et adapté à une architecture modulaire, multi‑thread et multiprocess.

Introduction : pourquoi un Singleton global dédié ?

Dans une architecture utilisant LlamaIndex, la gestion des modèles (LLM, embeddings, tokenizer, versions) repose sur des mécanismes internes du framework. Ces mécanismes fonctionnent correctement dans des cas simples, mais présentent plusieurs limites structurelles lorsqu'on construit une application :

modulaire,
multi‑thread,
multi‑process (ex. plusieurs workers uvicorn/gunicorn),
ou composée de plusieurs modules indépendants devant partager des modèles identiques.

Ce texte documente :

le principe du Singleton global utilisé dans nos applications d'IA,
en quoi il diffère du “singleton” de LlamaIndex,
la structure et le rôle de AppSettings,
la logique et les responsabilités de AppSettingsManager,
les mécanismes d'initialisation, de verrouillage et de traçage.

1. Principe général

AppSettings est un singleton global destiné à contenir les objets critiques de l'application :

le modèle LLM,
le modèle d'embedding,
le tokenizer,
les versions associées.

Ce singleton est conçu pour être :

unique dans le processus,
initialisé une seule fois,
verrouillé après initialisation,
idempotent (les appels suivants ne modifient rien),
traçable (on sait qui a initialisé en premier).

Ce mécanisme garantit que toutes les parties de l'application utilisent les mêmes objets, sans risque de divergence ou de réinitialisation accidentelle.

2. Différence avec le “singleton” de LlamaIndex

LlamaIndex utilise un mécanisme interne d'initialisation (souvent via Settings ou des loaders) qui :

n'est pas global à l'application, mais local au framework,
peut être réinitialisé selon les contextes,
n'est pas conçu pour être partagé entre plusieurs modules indépendants,
ne fournit pas de verrou multi‑thread ou multi‑process,
ne trace pas l'origine de l'initialisation.

En résumé :

Aspect	Notre AppSettings	LlamaIndex Settings
Portée	Globale à l'application	Locale au framework
Initialisation	Unique, verrouillée	Réinitialisable
Idempotence	Oui	Non garanti
Traçage	Oui (stack + timestamp)	Non
Multi‑thread	Protégé	Non
Multi‑process	Protégé (file lock)	Non

Notre système est donc plus strict, plus robuste et plus adapté à une application multi‑modules.

3. Structure de AppSettings

AppSettings est un BaseModel Pydantic contenant les objets critiques :

llm: Optional[Any]
embed_model: Optional[Any]
tokenizer: Optional[Any]
versions: Optional[Dict[str, Any]]
locked: bool
initialized_by: Optional[str]
initialized_at: Optional[float]

Caractéristiques :

locked empêche toute modification après initialisation.
initialized_by contient la stack trace du premier appel.
initialized_at contient le timestamp d'initialisation.
extra = "forbid" empêche l'ajout d'attributs fantômes.
validate_assignment = True garantit un comportement fail‑closed.

4. Rôle de AppSettingsManager

AppSettingsManager est le seul point d'entrée pour modifier ou initialiser AppSettings.

Il fournit :

4.1. `load_models()`

Charge les objets critiques.
Capture la stack trace du premier appel.
Capture le timestamp.
Valide les objets.
Verrouille l'état.
Est idempotent : si déjà initialisé, ne fait rien.

4.2. `validate()`

Vérifie la présence de llm, embed_model, tokenizer.
Comporte un comportement fail‑closed.

4.3. `lock()`

Marque l'état comme immuable.

4.4. `describe()`

Retourne un dictionnaire d'introspection complet.

5. Sécurité multi‑thread et multi‑process

L'initialisation est protégée par deux verrous :

5.1. Verrou thread‑safe

_thread_lock = threading.Lock()

Empêche deux threads du même processus d'initialiser simultanément.

5.2. Verrou multi‑process (file lock)

_process_lock = FileLock("/tmp/appsettings_init.lock")

Empêche deux processus (ex. plusieurs workers uvicorn/gunicorn) d'initialiser simultanément.

Ce mécanisme garantit une initialisation unique, même dans un environnement multi‑workers.

6. Cycle de vie complet

Une application appelle load_models().
Le verrou multi‑process est acquis.
Le verrou multi‑thread est acquis.
Si locked == True → rien n'est fait.
Sinon :
- stack trace enregistrée,
- timestamp enregistré,
- objets chargés,
- validation stricte,
- verrouillage.
Les appels suivants sont silencieusement ignorés.


Diagramme de séquence: Ce diagramme illustre le processus par lequel l'application obtient le singleton AppSettings pour accéder aux modèles dont elle a besoin

7. Avantages de cette architecture

Initialisation unique garantie.
Protection contre les réinitialisations accidentelles.
Sécurité multi‑thread et multi‑process.
Traçabilité complète.
Idempotence.
Isolation claire entre :
- le stockage global (AppSettings)
- la logique métier (AppSettingsManager)
- les configurateurs externes (ex. LlamaConfigurator).

8. Résumé

AppSettings et AppSettingsManager forment un système robuste permettant :

de centraliser les objets critiques,
de garantir une initialisation unique,
de sécuriser l'accès concurrent,
de tracer l'origine de l'initialisation,
de fournir une introspection complète.

Ce mécanisme est plus strict et plus fiable que celui fourni par LlamaIndex, et il est adapté à une architecture modulaire, multi‑thread et multiprocess.

9.Usage

En version v1xx :

from react.modules.tools.config_llama_mistral import LlamaConfigurator
from commons.settings.app_settings import get_app_settings
...
# Initialize application settings with LlamaIndex objects : LLM, embeddings etc.
os.environ['MISTRAL_LLM_API_KEY'] = llmapikey
LlamaConfigurator.load_models()
self.app_settings = get_app_settings()
...
llm=self.app_settings.llm,
embed_model=self.app_settings.embed_model

Télécharger

En version v2xx :

Architecture v200 :

ModelsConfigurator → charge les modèles purs (HF/ST, MistralAI, tokenizer) → stocke dans AppSettings ↓ AppSettings ↓ LlamaIndexAdapter → convertit en objets LlamaIndex ↓ RAGEngine v200

Avec la nouvelle architecture :

ModelsConfigurator charge uniquement les modèles applicatifs (embedding HF/ST, LLM MistralAI, tokenizer)
LlamaIndexAdapter convertit ces modèles en objets LlamaIndex si et seulement l'application en a besoin. besoin.

from react_v2.modules.tools.config_models import ModelsConfigurator
from react_v2.modules.tools.llamaindex_adapter import LlamaIndexAdapter
from commons.settings.app_settings import get_app_settings
# 1. Charger les modèles applicatifs
os.environ["MISTRAL_LLM_API_KEY"] = llmapikey
ModelsConfigurator.load_models()
# 2. Récupérer les objets applicatifs
self.app_settings = get_app_settings()
# 3. Convertir en objets LlamaIndex si nécessaire
llm = self.app_settings.llm
embed_model = LlamaIndexAdapter.get_llamaindex_embedding()

Télécharger

La classe AppSettings

# app_settings.py
# coding: utf8
'''
Classe AppSettings
Remplace le singleton 'Settings' de LlamaIndex.
Le singleton de LlamaIndex n'est pas stable :
- il est réinitialisé par certains modules internes lors d'imports tardifs,
- il est mutable et non verrouillé,
- il est globalement partagé par tout LlamaIndex, et peut être écrasé silencieusement par des appels internes,
etc..
Auteur :
B.Degoy bertrand@degoy.com
copyright (c) 2026 B.Degoy
licence : all rights reserved
'''
from functools import lru_cache
from pydantic import BaseModel, Field
from typing import Any, Optional, Dict
class AppSettings(BaseModel):
"""Singleton global contenant les objets critiques de l'application."""
llm: Optional[Any] = None
embed_model: Optional[Any] = None
tokenizer: Optional[Any] = None
versions: Optional[Dict[str, Any]] = None
locked: bool = Field(default=False, exclude=True)
initialized_by: Optional[str] = Field(default=None, exclude=False)
initialized_at: Optional[float] = None
class Config:
arbitrary_types_allowed = True
validate_assignment = True # fail-closed si mauvais type
extra = "forbid" # pas d'attributs fantômes
@lru_cache(maxsize=1)
def get_app_settings() -> AppSettings:
return AppSettings()

Télécharger

La classe AppSettingsManager

# app_settings_manager.py
# coding: utf8
'''
Classe AppSettingsManager
thread-safe, multiprocess-safe
Auteur :
B.Degoy bertrand@degoy.com
copyright (c) 2026 B.Degoy
licence : all rights reserved
'''
import traceback, time
import commons.settings.app_settings
from pydantic import ValidationError
from commons.settings.app_settings import get_app_settings #j
# verrous multi-processus
from filelock import FileLock
import threading
# Verrou inter-processus
_process_lock = FileLock("/tmp/appsettings_init.lock") # répertoire standard pour les verrous inter-processus
# Verrou intra-processus (threads)
_thread_lock = threading.Lock()
class AppSettingsManager:
@staticmethod
def load_models(llm, embed_model, tokenizer, versions=None):
app = get_app_settings()
with _process_lock: # verrou multi-process
with _thread_lock: # verrou thread-safe
# Déjà chargé et verrouillé : OK, on ne fait rien
if app.locked:
# Optionnel : vérifier la cohérence
if (app.llm and app.embed_model and app.tokenizer):
return # idempotent, silencieux
else:
raise RuntimeError(
"[AppSettingsManager] AppSettings is locked but incomplete."
)
# Initialisation au premier appel :
# capturer la stack du premier appel
app.initialized_by = "".join(traceback.format_stack(limit=10))
app.initialized_at = time.time()
# on charge
app.llm = llm
app.embed_model = embed_model
app.tokenizer = tokenizer
app.versions = versions or None
AppSettingsManager.validate()
AppSettingsManager.lock()
@staticmethod
def validate():
"""Validation stricte fail-closed."""
app = get_app_settings()
if app.llm is None:
raise ValidationError("[AppSettingsManager] Missing LLM in AppSettings")
if app.embed_model is None:
raise ValidationError("[AppSettingsManager] Missing embed_model in AppSettings")
if app.tokenizer is None:
raise ValidationError("[AppSettingsManager] Missing tokenizer in AppSettings")
@staticmethod
def lock():
"""Empêche toute modification ultérieure."""
app = get_app_settings()
app.locked = True
@staticmethod
def describe() -> dict:
"""Introspection complète pour debug."""
app = get_app_settings()
return {
"llm": type(app.llm).__name__ if app.llm else None,
"embed_model": type(app.embed_model).__name__ if app.embed_model else None,
"tokenizer": type(app.tokenizer).__name__ if app.tokenizer else None,
"versions": app.versions,
"locked": app.locked,
"initialized_by": app.initialized_by,
"initialized_at": app.initialized_at,
}

Télécharger

Chat Engine Mistral

Bertrand Degoy — 2026-03-09T13:14:00Z

Avec les réglages adoptés, le ChatEngine est de type C3 : CondensePlusContextChatEngine.

La classe est :

Il en résulte l'API suivante :

Méthodes par catégorie fonctionnelle

1. Méthodes publiques (API officielle)

`chat(prompt)`

Appel synchrone.
Retourne une réponse complète (pas de streaming).
Utilise la condensation + récupération de contexte + synthèse.

`stream_chat(message)`

Version streaming de chat().
Retourne un ChatResponse avec response_gen (générateur de tokens).
C'est celle que tu utilises.

`achat(prompt)`

Version async de chat().

`astream_chat(message)`

Version async de stream_chat().

`chat_history`

Liste interne des messages échangés.
Utilisée pour la condensation (C3).

`reset()`

Vide l'historique du chat.
Réinitialise l'état interne.
Ne ferme aucun stream (important).

`from_defaults(...)`

Constructeur de convenance.
Permet de créer un CondensePlusContextChatEngine avec des paramètres par défaut.

`chat_repl()` / `streaming_chat_repl()`

Interfaces REPL (console).
Pas utiles dans ton architecture Streamlit.

2. Méthodes internes liées à la condensation (C3)

C'est le cœur du moteur.

`_condense_question()`

Prend la dernière question utilisateur.
Condense en une question autonome.
Utilise _condense_prompt_template.

`_acondense_question()`

Version async.

`_skip_condense`

Booléen interne.
Permet de bypasser la condensation (rare).

`_condense_prompt_template`

Prompt utilisé pour la condensation.

3. Méthodes internes liées à la récupération de contexte

`_get_nodes(query)`

Appelle le retriever.
Retourne les nœuds pertinents.

`_aget_nodes(query)`

Version async.

`_retriever`

L'objet retriever (vector store, BM25, hybrid…).

`_node_postprocessors`

Liste de post‑processeurs appliqués aux nœuds (rerankers, filtres…).

4. Méthodes internes liées à la synthèse de réponse

`_run_c3()`

Pipeline complet :
1. condensation
2. récupération
3. synthèse

`_arun_c3()`

Version async.

`_get_response_synthesizer()`

Retourne l'objet responsable de la génération finale.
Souvent un ResponseSynthesizer.

5. Méthodes internes liées au LLM

`_llm`

L'instance du LLM (OpenAI, Ollama, Azure, etc.).

`_system_prompt`

Prompt système injecté dans la conversation.

`_token_counter`

Compteur interne pour mesurer les tokens consommés.

`_verbose`

Active les logs détaillés.

6. Méthodes héritées / utilitaires

`callback_manager`

Gestion des callbacks (events, logs, instrumentation).

`abstractmethods`

Indique que la classe hérite d'une ABC.

`dict`, `repr`, etc.

Méthodes Python standard.

Résumé

Méthode	Rôle
`chat()`	Réponse complète
`stream_chat()`	Streaming
`achat()`	Async
`astream_chat()`	Async streaming
`reset()`	Réinitialise l'historique
`_condense_question()`	Condensation
`_get_nodes()`	Récupération
`_run_c3()`	Pipeline complet
`_llm`	LLM utilisé
`chat_history`	Historique interne

Le pipeline C3

CondensePlusContextChatEngine applique un pipeline en 3 phases :

Condense → transformer l'entrée utilisateur en une question autonome
Context → récupérer les nœuds pertinents via le retriever
Chat → synthétiser une réponse avec le LLM (streaming ou non)

Ce pipeline est implémenté dans _run_c3() et _arun_c3().

Étape 1 — Condensation de la question

Méthode interne : _condense_question()

Objectif :
Transformer la question utilisateur + historique en une question autonome, courte, optimisée pour le retriever.

Processus :

Le moteur regarde chat_history
Il prend le dernier message utilisateur
Il applique _condense_prompt_template
Il appelle le LLM (_llm) pour produire une version condensée
Il retourne un texte propre, sans bruit conversationnel

Si _skip_condense=True, cette étape est sautée.

Étape 2 — Récupération du contexte

Méthode interne : _get_nodes()

Objectif :
Récupérer les documents pertinents pour répondre à la question condensée.

Processus :

Le moteur appelle _retriever.retrieve(condensed_question)
Le retriever renvoie une liste de NodeWithScore
Le moteur applique les post‑processeurs (_node_postprocessors)
Le moteur obtient une liste finale de nœuds pertinents

C'est ici que vector store, BM25, hybrid search, etc. interviennent.

Étape 3 — Synthèse de la réponse

Méthode interne : _get_response_synthesizer()

Objectif :
Générer la réponse finale à partir :

de la question condensée
des nœuds récupérés
du prompt système
de l'historique

Processus :

Le moteur construit un prompt complet (system + context + question)
Il appelle le LLM via le ResponseSynthesizer
Si on utilise stream_chat() :
- le LLM est appelé en mode streaming
- un générateur Python est créé (response.response_gen)
- chaque token est yieldé au fur et à mesure
Le moteur met à jour chat_history avec :
- la question condensée
- la réponse finale

Ce qui se passe EXACTEMENT dans `stream_chat()`

Voici la séquence interne réelle :

1. Normalisation de l'entrée

stream_chat() accepte :

un dict
un ChatMessage
un QueryBundle

Il convertit tout en un ChatMessage.

2. Ajout du message utilisateur dans `chat_history`

Le moteur stocke le message brut.

3. Appel à `_run_c3()`

C'est le pipeline complet :

condensed = _condense_question()
nodes = _get_nodes(condensed)
response = synthesizer.synthesize(condensed, nodes, streaming=True)

4. Construction d'un `ChatResponse`

Ce n'est pas un simple objet :
c'est un wrapper contenant :

response_gen → le générateur de tokens
response → la réponse complète (remplie à la fin)
metadata → infos sur les nœuds, tokens, etc.

5. Retour du `ChatResponse`

Et c'est là que tu dois consommer le générateur.

Le point critique : le générateur

response.response_gen est un générateur Python qui encapsule :

un flux HTTP (OpenAI, Ollama, Azure…)
un pipe interne
un buffer de tokens

Et il n'est jamais fermé automatiquement.

Cela peut provoquer l'erreur :

OSError: [Errno 24] Too many open files

Pourquoi `reset()` ne ferme rien

Parce que :

reset() vide chat_history
mais ne touche pas aux générateurs
ni aux connexions HTTP
ni aux file descriptors

Donc aucun impact sur les fuites.

Comment terminer le pipeline proprement

gen = response.response_gen
try: for token in gen: ...
finally: gen.close()

C'est la seule manière de libérer les ressources.

Résumé

Voici le pipeline interne complet :

stream_chat() ↓
normalisation du message ↓
chat_history.append(user_message) ↓
_run_c3() ↓
_condense_question() ↓
_get_nodes() ↓
_get_response_synthesizer() ↓
LLM(streaming=True) ↓
ChatResponse(response_gen=generator) ↓
return ChatResponse

ReActEngine v1 : intégration dans le front end

Bertrand Degoy — 2026-02-12T09:30:00Z

Cette article décrit comment ReActEngine v1 s'intègre dans le front‑end Streamlit chatitego_v128, et clarifie la séparation des responsabilités entre les deux couches. Il faut considérer que le moteur est stateless, tandis que le front‑end assure toute la persistance (index, historique, thème, paramètres).

1. Architecture générale

ReActEngine v1

Ne conserve aucun état interne.
Ne stocke ni index, ni historique, ni thème.
Ne gère pas la session Streamlit.
Ne persiste aucune donnée.
Reçoit à chaque appel :
- le thème,
- l'index,
- la langue,
- le niveau de détail,
- le jeton de sécurité,
- l'historique de conversation.

Il exécute ensuite la logique ReAct et renvoie un flux de blocs (Thought, Action, Observation, Answer).

Front‑end Streamlit (chatitego_v128)

Charge et persiste l'index du thème.
Charge et persiste l'historique de conversation.
Gère les cookies (thème, historique).
Gère les paramètres du thème.
Construit et maintient l'état de session (st.session_state).
Réinjecte l'état dans ReActEngine à chaque requête.
Gère l'affichage du streaming (placeholders, Markdown, HTML).
Extrait la réponse finale et la sauvegarde.

2. Cycle de vie d'une session


Intégration de ReActEngine v1 : diagramme des séquences

Lecture du thème depuis l'URL ou les cookies.
Chargement de l'index du thème depuis le disque.
Instanciation de ReActEngine.
Appel à start() avec :
- thème,
- langue,
- jeton de sécurité,
- index.
Chargement de l'historique depuis les cookies.
Affichage de l'historique dans l'interface.
Lors d'un nouveau prompt :
- ajout du message utilisateur à l'historique,
- passage de l'historique à set_history(),
- appel à stream(prompt) pour obtenir les blocs ReAct,
- affichage progressif des blocs,
- extraction de la réponse finale,
- sauvegarde de l'historique.

3. Rôle exact de `start()` dans ReActEngine v1

La méthode start() est appelée à chaque session Streamlit. Elle reçoit :

le thème,
le niveau de détail,
le jeton de sécurité,
la langue,
l'index.

Comme le moteur est stateless, start() ne fait qu'initialiser un contexte de travail pour l'appel courant. Aucun état n'est conservé entre deux sessions ou deux requêtes.

4. Gestion de l'historique

Le front‑end utilise :

StreamlitCookieStore pour la persistance,
HistoryStore pour la lecture/écriture.

Avant chaque appel à stream(), le front‑end reconstruit l'historique :

my_react_engine.set_history(msg_copy)

Le moteur ne stocke rien : il ne fait que consommer l'historique fourni.

5. Gestion de l'index

L'index est chargé une seule fois par session :

index = thm.load_data()
st.session_state.index = index

Puis il est passé à ReActEngine via start().

Le moteur ne conserve pas l'index entre deux appels. C'est le front‑end qui le garde en mémoire et le réinjecte.

6. Streaming et affichage

Le front‑end gère :

la création des placeholders,
l'affichage des blocs Thought / Action / Observation,
l'affichage de la réponse finale en Markdown,
la reconstruction du texte final,
la sauvegarde dans l'historique.

ReActEngine ne gère que la génération des blocs.

7. Résumé

ReActEngine v1 est stateless.
Toute la persistance est assurée par le front‑end Streamlit.
Le front‑end charge l'index, les paramètres, le thème et l'historique.
Le front‑end réinjecte l'état dans ReActEngine via start() et set_history().
ReActEngine ne conserve rien entre deux appels.
Le front‑end gère entièrement le streaming et l'affichage.

Evolution

L'évolution proposée vise à dépasser les limites de l'architecture actuelle, où Streamlit impose un fonctionnement stateless et un rechargement répété des index et de l'historique, entraînant une latence inutile et un couplage fort entre l'interface et le moteur.

La nouvelle approche consiste à transformer ReActEngine en un composant stateful intégré dans un daemon local, capable de charger les index en lazy‑loading et de conserver l'état utilisateur de manière persistante.

Cette séparation nette des responsabilités permet d'obtenir un moteur plus performant, plus robuste et réellement multi‑utilisateur. En parallèle, le remplacement de Streamlit par NiceGUI offre un front‑end plus stable, plus réactif et mieux adapté au streaming et aux sessions persistantes, tout en conservant une intégration Python directe avec le daemon.

L'ensemble aboutit à une architecture plus modulaire, plus efficace et plus industrielle.

Inconvénients de la solution actuelle

La version actuelle repose sur Streamlit, qui relance le script à chaque interaction et ne garantit pas la persistance des objets en mémoire. L'index du thème doit être rechargé à chaque session, ce qui augmente la latence et la charge CPU. L'historique de conversation est géré côté front‑end via des cookies, ce qui limite la robustesse et la capacité multi‑utilisateur. ReActEngine reste stateless et dépend du front‑end pour recevoir l'index, le thème et l'historique, ce qui crée un couplage fort et empêche toute montée en charge ou réutilisation du moteur dans d'autres contextes.

L'objectif est de rendre l'architecture plus modulaire, plus performante et plus industrielle. Il s'agit de séparer clairement le moteur ReAct de la couche d'interface, de réduire les rechargements inutiles, d'améliorer la gestion multi‑utilisateur, et de permettre une persistance durable de l'état. L'architecture doit également permettre un front‑end plus stable, plus réactif et plus flexible que Streamlit.

Transformation de ReActEngine en moteur stateful

ReActEngine doit être intégré dans un composant long‑living qui conserve en mémoire les index des thèmes et l'état des utilisateurs. L'index est chargé en lazy‑loading lors de la première utilisation d'un thème, puis conservé en RAM. L'état utilisateur est indexé par la déclaration 'sub' (subject) du jeton d'identité JWT et contient l'historique et les données persistantes. Le moteur ne dépend plus du front‑end pour recevoir l'état : il le gère lui‑même via un gestionnaire interne. La logique ReAct reste inchangée, mais elle s'exécute désormais dans un environnement persistant.

Daemon local

Le moteur stateful doit être encapsulé dans un daemon Python local, instancié une seule fois au démarrage de l'application. Ce daemon maintient :

un cache d'index par thème,
un dictionnaire d'états utilisateur ( identifié par authentification ).

Le front‑end communique avec lui via des appels Python directs, sans passer par une API HTTP. Cette approche élimine la latence réseau, simplifie l'architecture et permet une gestion efficace de la mémoire et des sessions.

NiceGUI

NiceGUI peut remplacer avantageusement Streamlit comme front‑end. Il fournit un serveur web stable, basé sur FastAPI et WebSockets, qui permet un streaming fluide des réponses et une gestion robuste des sessions utilisateur. Il s'intègre naturellement avec un daemon local Python et permet de construire une interface moderne, réactive et persistante. Le front‑end devient un simple client du daemon, chargé d'afficher les messages, de gérer l'authentification et de transmettre les prompts.

RAG : Compression contextuelle

Bertrand Degoy — 2026-02-12T08:19:12Z

La contextual compression est un sujet qui est devenu central dans les RAG modernes.

C'est une technique qui permet de réduire dynamiquement - c'est à dire en fonction du contexte - la quantité de texte envoyée au LLM en ne gardant que ce qui est pertinent pour la requête.

On ne renvoit pas les documents bruts, mais une version compressée, filtrée, ou résumée, adaptée à la question.

C'est un pré‑processing intelligent du contexte.

C'est devenu indispensable

Parce que :

les fenêtres de contexte sont grandes mais pas infinies,
les chunks bruts sont souvent trop verbeux,
les embeddings récupèrent parfois trop de documents,
les modèles hallucinent moins quand le contexte est précis.

La contextual compression permet :

d'augmenter la précision,
de réduire le bruit,
d'améliorer la factualité,
de diminuer le coût.

Les 3 grandes familles de contextual compression

1. Compression par résumé (LLM summarization)

On récupère les documents pertinents, puis on demandes au LLM :

« Résume uniquement les parties utiles pour répondre à la requête X. »

C'est la version la plus simple et la plus efficace.

Exemple

Document : 3 pages
Requête : « Quels sont les effets secondaires du médicament ? »
Résumé compressé : 4 lignes ciblées

2. Compression par extraction (LLM extraction)

Le LLM ne résume pas : il extrait les passages pertinents.

« Extrait uniquement les phrases qui répondent à la question X. »

C'est plus précis et moins risqué que le résumé.

3. Compression par filtrage sémantique (embedding‑based filtering)

On fait un re‑ranking interne :

récupérer les chunks via embeddings.
re‑embed de chaque chunk par rapport à la requête.
élimination des chunks peu pertinents.

C'est du semantic pruning.

Comment ça s'intègre dans un pipeline RAG ?

Voici le pipeline classique :

User query
→ embedding de la requête
→ retrieval (top‑k documents)
→ contextual compression (résumé / extraction / filtrage)
→ Prompt final = system + historique + requête + contexte compressé
→ LLM

La compression intervient entre le retrieval et le prompt final.

Pourquoi c'est supérieur au RAG naïf ?

Sans compression :

envoit trop de texte,
dépasse la fenêtre,
ajoute du bruit,
augmente les hallucinations.

Avec compression :

n'envoie que l'essentiel,
reste dans la fenêtre,
augmente la précision,
réduit le coût.

Le point clé : la compression est contextuelle
Ce n'est pas un résumé générique.
C'est un résumé conditionné par la requête.

Exemple :

Requête A : « Quels sont les risques ? »
Requête B : « Quels sont les bénéfices ? »

Le même document donnera deux compressions différentes pour des requêtes différentes.

Notons que, par requête, on peut entendre historique + question. Ainsi, la même question de l'utilisateur, après avoir posé différentes questions et obtenu différentes réponses, une nouvelle question sera traitée en tenant compte des précédentes.

C'est ce qui rend la technique si puissante.

Les erreurs fréquentes

-résumer les documents avant le retrieval
→ tu perds de l'information utile

-compresser sans conditionner sur la requête
→ tu obtiens un résumé générique, inutile

-compresser trop tôt dans le pipeline
→ tu risques de biaiser la recherche

-compresser avec un modèle trop faible
→ tu introduis des erreurs dans le contexte

Comment faire une contextual compression robuste ?

Étape 1 — Retrieval large (top‑20 ou top‑50)

On récupère large pour ne rien rater.

Étape 2 — Re‑ranking (embedding ou cross‑encoder)

On réduit à top‑5 ou top‑10.

Étape 3 — Compression LLM (résumé/extraction)

On produit un contexte propre, court, précis.

Étape 4 — Prompt final

On injecte uniquement la version compressée.

Ce pipeline est beaucoup plus stable que le RAG naïf.

Les services IA de DnC

Comment ReActAgent s'insère dans le Workflow LlamaIndex

La boucle de raisonnement ReAct

Comment ReActAgent s'insère dans le Workflow LlamaIndex

Comment sont construites les steps ReAct ?

Étape 1 — Construire le prompt ReAct

Étape 2 — Appeler le LLM

Étape 3 — Le parser reconstruit les blocs

Étape 4 — Le ReActFinalizer décide si l'étape est terminée

Étape 5 — Le workflow relance take_step() si nécessaire

En résumé : rôle du Workflow

ReActEngine v1 : Finalizer et StreamParser

Architecture ReAct : Finalizer et StreamParser

Rôles et responsabilités

ReActStreamParser

ReActFinalizer

Règle de séparation stricte

Exemple de flux

La classe ReActType

Héritage :

Types ReAct fondamentaux

3. Cohérence avec les finalizers et parsers

Pourquoi deux parsers ?

1. Le ReActOutputParser n'est pas utilisé pendant le streaming

2. Pourquoi ReActEngine émet un flux brut de tokens

3. Pourquoi le client doit reconstruire les messages ReAct

4. Pourquoi cette séparation est nécessaire

A. Le LLM produit du texte libre → pas structuré

B. Le streaming impose de ne pas parser prématurément

C. Le workflow doit rester générique

D. Le client peut choisir son mode de visualisation

Conclusion

ReActEngine, l'IA qui raisonne, s'adapte et comprend votre réalité métier

Une vision fine, prédictive et explicable de vos processus

1. ReAct — Raisonnement structuré

2. RAG — Votre documentation comme socle de vérité

3. MCP — Vos données temps réel, sans intégration complexe

Pensé pour l'Industrie 4.0… et prêt pour l'Industrie 5.0

Une architecture modulaire, conçue pour vos métiers

Les bénéfices immédiats

ReActEngine — L'IA qui comprend votre métier et agit avec vous

ReActEngine v1 : traitement des erreurs

Le traitement des erreurs dans ReActEngine

A - Exceptions

B - Thought injecté

Diagramme du traitement des erreurs

ReActEngine v1 : Modules et traitements

ReActEngine Mistral v104 — Description technique

1. Nature de l'agent

2. Architecture générale

2.1. Diagramme des échanges

2.2. Vision globale du flux

2.3. Boucle ReAct

ReActAgent (remanié)

La méthode take_step()

La méthode handle_tool_call_result()

BaseWorkflowAgent (modifié)

ReActWorkflow

ReActChatFormatter

ReActOutputParser (modifié)

Modèle LLM

Tool

A. RAG (QueryEngineTool)

B. Outils personnalisés (FunctionTools)

C. Outils généralistes

2.3. Orchestrateur

User

ToolRouter

ReActEngine

ReActStreamParser

ReActFinalizer

3. API du ReActEngine v1

3.1. __init__(...)

Mode 1 : avec ragkwargs

Mode 2 : sans ragkwargs

3.2. Méthode start()

3.3. Gestion de l'historique — set_history()

3.4. Exécution asynchrone — stream(prompt)

Fonctionnement

3.5. Exécution synchrone — get_engine_response()

Comment `ReActAgent` s'insère dans le Workflow LlamaIndex

Étape 5 — Le workflow relance `take_step()` si nécessaire

La classe `ReActType`

**1. Le ReActOutputParser n'est pas utilisé pendant le streaming**

3.1. `init(...)`

Mode 1 : avec `ragkwargs`

Mode 2 : sans `ragkwargs`

3.2. Méthode `start()`

3.3. Gestion de l'historique — `set_history()`

3.4. Exécution asynchrone — `stream(prompt)`

3.5. Exécution synchrone — `get_engine_response()`

3. Construction du singleton `AppSettings.embed_model`

4.1. `load_models()`

4.2. `validate()`

4.3. `lock()`

4.4. `describe()`

`chat(prompt)`

`stream_chat(message)`

`achat(prompt)`

`astream_chat(message)`

`chat_history`

`reset()`

`from_defaults(...)`

`chat_repl()` / `streaming_chat_repl()`

`_condense_question()`

`_acondense_question()`

`_skip_condense`

`_condense_prompt_template`

`_get_nodes(query)`

`_aget_nodes(query)`

`_retriever`

`_node_postprocessors`

`_run_c3()`

`_arun_c3()`

`_get_response_synthesizer()`

`_llm`