Les services IA de DnC

Le Daemon Pyro5

Bertrand Degoy — 2026-07-07T09:30:51Z

Dans une architecture multi‑processus et multi‑utilisateur, on ne peut charger un même modèle dans chaque composant (NSOrchestrator, ReActEngine, workers, tests, scripts).
Pour cette raison, les modèles doivent être servis via un daemon.

Position du problème

Un LLM ou un SLM représente plusieurs gigaoctets en mémoire, et leur rechargement dans chaque processus provoquerait une explosion de la consommation RAM, une fragmentation CUDA, des temps de démarrage prohibitifs et une instabilité générale du système. Le mode daemon résout ce problème en garantissant qu'un modèle n'est chargé qu'une seule fois dans un processus dédié, puis partagé entre tous les autres via RPC. Cela permet un fonctionnement réellement concurrent, une gestion propre du streaming token‑par‑token, une isolation des erreurs, et une stabilité mémoire indispensable en production.

Pour cette raison, le LLM et le SLM doivent être servis via un daemon. Les deux modèles sont sollicités par plusieurs utilisateurs, plusieurs sessions et plusieurs moteurs internes, parfois simultanément. Les Thought et les réponses finales de ReAct doivent être générées sans jamais recharger les poids des modèles, sans bloquer les autres processus, et sans dépendre de l'environnement local de chaque composant. En les exécutant tous deux en daemon, l'architecture v200 devient cohérente, déterministe et scalable : un seul chargement, un seul point d'accès, un comportement identique pour tous les clients, et une capacité à monter en charge sans modifier le code des orchestrateurs ou des moteurs internes.

Ce raisonnement vaut également pour les index.

Rôle du daemon

Le daemon Pyro5 est un fournisseur multi-services.

Via ModelsConfigurator, il :

Charge les modèles définis dans models.json, ce qui initialise AppSettings et les modèles globaux (embedding, LLM, SLM).
Charge les services déclarés dans services.json et les instancie dynamiquement.
Enregistre chaque service dans Pyro5 sous un nom stable :
- llm.server
- slm.server
- embedding.server
- rag.reader

Puis : Lance la boucle d'événements Pyro5.

Exemple : chargement d'un index par RagRuntime :

Composants principaux

1. MemoryManager

Arbitre global de la RAM.
Suit les allocations d'objets persistants.
Applique une politique d'éviction (LRU locale).
Fournit un état mémoire complet.
Thread-safe.

2. InDaemonRagReader

Reader interne au daemon.
Encode les requêtes via le modèle d'embedding global.
Interroge le backend vectoriel (FAISS, LlamaIndex ...).
Renvoie des RichNode.
Fournit un mode streaming (astream).

Noter qu'une architecture séparant le modèle d'embedding et l'index dans des daemons distincts conduirait à un grand nombre d'échanges RCP et à des temps de traitement prohibitifs.

Interaction avec le client

Le client utilise InDaemonRagReaderProxy pour contacter rag.reader.

Flux typique :

RagRuntime.retrieve() → InDaemonRagReaderProxy("rag.reader").retrieve(theme, query, top_k) → InDaemonRagReader.retrieve() → encode la requête → interroge le backend vectoriel → renvoie des RichNode

Le client ne voit jamais MemoryManager : tout est encapsulé dans le daemon.

Avantages de cette architecture

Un seul daemon → cohérence mémoire.
Plusieurs services → modularité.
MemoryManager central → contrôle RAM industriel.
InDaemonRagReader → moteur RAG unifié.
Structure simple → facile à étendre.

v200 : Introduction

Bertrand Degoy — 2026-07-04T08:16:29Z

La v200 introduit une architecture RAG entièrement refondue, centrée sur la modularité, la performance et la robustesse. Elle s'appuie sur l'écriture de services dédiés pour les modèles et les index, un daemon Pyro5 pour l'accès rapide aux index en mémoire, et une API interne unifiée permettant d'abstraire totalement les backends.
L'ensemble garantit un moteur RAG totalement indépendant de toute bibliothèque (LlamaIndex, LangChain ...) .
Cette version fournit ainsi une base industrielle, stable et extensible pour un pipeline RAG totalement propriétaire.

La v200 constitue une réarchitecture complète du pipeline RAG, conçue pour offrir une modularité stricte, une indépendance vis‑à‑vis de LlamaIndex ou de toute autre bibliothèque, et une performance accrue grâce à un daemon gérant les index en mémoire persistante. Elle introduit une séparation nette des responsabilités, une normalisation des API internes, et un modèle d'exécution cohérent pour tous les types d'index et de modèles.

1. Objectif : Modularité systémique

1.1. Modularité des modèles

La v200 définit des services dédiés pour les modèles :

services/llm/
services/embeddings/

Chaque service expose une API normalisée :

generate()
astream()
embed()

Cette abstraction permet de remplacer un modèle (OpenAI, Ollama, HF, local) sans impact sur le reste du pipeline.

1.2. Modularité des index

Les index sont encapsulés dans des backends interchangeables :

FaissBackend
LlamaIndexBackend
DummyBackend

Tous implémentent une API unifiée :

retrieve(query, top_k)
query(query)
astream(query)
ping()

Cette normalisation garantit que le RAG ne dépend plus du type d'index sous‑jacent.

1.3. Rapidité via daemon Pyro5

La v200 introduit un daemon Pyro5 :

chargé de maintenir les index en mémoire,
exposant une API RPC homogène,
permettant un accès rapide depuis n'importe quel worker.

Le client est minimal :

IndexesManager → IndexService → RemoteIndexBackend

Un mécanisme de **fallback local** assure la continuité de service en cas d'indisponibilité du daemon. ### **1.4. Couche interne de normalisation** Une couche interne (`internal/`) garantit : - la normalisation des résultats des backends, - la conversion des formats hétérogènes en structures standardisées, - la cohérence des données consommées par RagRuntime. Tous les résultats sont convertis en dictionnaires homogènes :

```python { "text": "...", "score": None, "metadata": {} }

2. Objectif : RAGEngine indépendant d'API externes

2.1. Suppression des dépendances structurelles

La v200 élimine toute dépendance directe à LlamaIndex ( ou autre) dans le moteur RAG :

plus de QueryEngine,
plus de Node, Document, Response,
plus de formats étrangers.

Par exemple, LlamaIndex est encapsulé dans LlamaIndexBackend, qui expose l'API unifiée. Dans l'état actuel du développement, il existe une adaptation à FAISS.

2.2. RAGEngine basé sur une API interne stable

Le moteur RAG (RagRuntime) ne dépend plus :

du type d'index,
du type de modèle,
de LlamaIndex ou FAISS.

Il consomme uniquement l'API unifiée :

retrieve()
query()
astream()

2.3. Normalisation systématique des résultats

Les résultats bruts des backends (souvent des chaînes de caractères) sont systématiquement convertis en objets structurés avant traitement par RagRuntime.

Cela garantit :

la stabilité du pipeline,
la compatibilité avec les hooks,
l'absence d'erreurs liées à des formats hétérogènes.

2.4. Fallback local cohérent

En cas d'indisponibilité du daemon :

IndexService.connect() → RemoteIndexBackend (si daemon disponible) → LocalIndexBackend (si daemon indisponible)

LocalIndexBackend est un proxy thread‑safe, totalement indépendant du type d'index.

Synthèse

La v200 est une architecture RAG :

modulaire, grâce à des services dédiés pour les modèles et les index,
performante, via un daemon Pyro5 servant les index en mémoire,
normalisée, grâce à une API interne unifiée pour tous les backends,
résiliente, via un fallback local automatique,
indépendante de LlamaIndex, grâce à l'encapsulation complète dans LlamaIndexBackend,
stable, grâce à une couche de normalisation systématique pour RagRuntime.

Elle constitue une base industrielle, cohérente, et extensible pour un pipeline RAG moderne.

Politique LRU/MRU

Bertrand Degoy — 2026-06-29T09:04:20Z

Dans l'architecture Pyro5, les index ( et certains modèles ) sont chargés depuis le disque puis conservés en RAM pour être accessibles rapidement par les services distants. Le daemon joue le rôle de processus maître.

Pour les index par exemple, il les expose via IndexServer, et sert de point d'accès unique pour tous les RemoteIndexService.

Comme ces index peuvent être volumineux et que le daemon est conçu pour rester actif longtemps, il doit gérer sa mémoire de manière autonome et efficace. C'est précisément pour cela qu'une politique LRU/MRU est indispensable : elle permet de conserver en RAM les index les plus récemment utilisés (MRU), tout en évinçant automatiquement ceux qui ne sont plus sollicités (LRU).

Cette stratégie garantit que le flowchart Pyro5 fonctionne de manière fluide, sans surcharge mémoire, et que les services distants accèdent toujours aux index pertinents sans rechargement inutile depuis le disque.

Politique LRU/MRU

La politique LRU/MRU (Least Recently Used / Most Recently Used) est un mécanisme de gestion de la mémoire qui permet de décider quel objet doit être évincé lorsque la RAM atteint sa capacité maximale. Elle repose sur un principe simple :

MRU = objets récemment utilisés → à conserver
LRU = objets peu utilisés récemment → candidats à l'éviction

Dans notre système, cette politique est appliquée par le MemoryManager, qui maintient un ordre strict des objets en RAM grâce à un OrderedDict.

MRU — Most Recently Used

Un objet devient MRU lorsqu'il est :

chargé en RAM,
accédé via get(),
marqué via touch().

Le MemoryManager déplace alors la clé à la fin de l'OrderedDict :

[ LRU ... → ... MRU ]

Cela signifie :

cet index est actif,
il doit être conservé en priorité,
il ne doit pas être évincé tant que d'autres objets moins utilisés existent.

LRU — Least Recently Used

L'objet LRU est celui qui :

n'a pas été utilisé depuis le plus longtemps,
n'a pas été touché récemment,
se trouve au début de l'OrderedDict.

Lorsqu'une éviction est nécessaire (ex : len(store) > max_items), le MemoryManager fait :

key, _ = self._store.popitem(last=False)

Ce qui retire le premier élément, donc le LRU.

Pourquoi LRU/MRU est idéal dans ton architecture

1. Les index sont lourds

Ils peuvent peser plusieurs centaines de Mo.
Il est donc crucial d'éviter de recharger inutilement depuis le disque.

2. Les RemoteIndexService sont stateless

Ils ne conservent rien : tout repose sur la RAM du daemon.
LRU/MRU garantit que les index réellement utilisés restent disponibles.

3. Le daemon est long-lived

Il doit s'auto-réguler sans intervention humaine.
LRU/MRU fournit une politique simple, déterministe et efficace.

4. Les thèmes ont des patterns d'accès naturels

Certains thèmes sont consultés souvent (MRU), d'autres rarement (LRU).
La politique s'adapte automatiquement à ces usages.

Résultat : une mémoire auto-optimisée

Grâce à LRU/MRU :

Les index actifs restent en RAM → latence minimale
Les index inactifs sont évincés → RAM maîtrisée
Le daemon ne recharge que si nécessaire → I/O minimisées
Le système reste stable même sous forte charge → robustesse

Construction des modèles : models.json et services.json

Bertrand Degoy — 2026-06-23T08:51:00Z

L'architecture v200 repose sur une séparation stricte entre la définition des modèles, leur construction centralisée, et la déclaration des services qui les consomment.
Les modèles sont décrits dans un fichier unique (`models.json`), puis construits une seule fois au démarrage par le `ModelsConfigurator`, avant d'être stockés dans `AppSettings` pour être partagés par l'ensemble du runtime.
Les services Pyro5, déclarés dans `services.json`, ne chargent jamais de modèles eux‑mêmes : ils se contentent d'exposer des capacités en s'appuyant sur les objets déjà initialisés, garantissant ainsi cohérence, performance et isolation des responsabilités.

Construction des modèles : `models.json` et `services.json`

1. Présentation générale : comment les modèles sont construits dans v200

L'architecture v200 repose sur une séparation stricte des responsabilités :

1. `models.json` décrit les modèles

Ce fichier déclare uniquement les modèles utilisés par le runtime :

embedding
slm
tokenizer
llm

Chaque entrée décrit :

model_name
model_path (optionnel)
backend
device
api_key_env (si backend = API) etc.

2. ModelsConfigurator construit les modèles

Le composant ModelsConfigurator :

lit models.json
instancie les modèles (HF, API, local, etc.)
crée les objets Python correspondants

Il ne connaît pas les services Pyro5.

3. AppSettingsManager stocke les modèles

Une fois construits, les modèles sont transmis à :

AppSettingsManager.load_models(...)

Ce composant :

crée un objet AppSettings
stocke les modèles dans des attributs statiques
verrouille la configuration

4. Les services Pyro5 consomment les modèles

Les services (EmbeddingServer, SLMServer, IndexServer, MemoryManager) :

ne chargent pas de modèles
ne reçoivent pas de paramètres de modèle
récupèrent les modèles via :

from runtime_v2.settings.app_settings import AppSettings self.embedding = AppSettings.embedding
self.slm = AppSettings.slm
self.tokenizer = AppSettings.tokenizer
self.llm = AppSettings.llm

5. `services.json` décrit uniquement les services

Ce fichier :

déclare les services Pyro5
indique leur classe Python
fournit uniquement les paramètres nécessaires aux RPC (ex : nom d'un autre service)

Il ne doit jamais contenir de paramètres de modèle.

2. Comment écrire `models.json`

Voici la structure de base :

{ "__comment": "Source de ModelsConfigurator pour la configuration des modèles du runtime v200.", "embedding": { "__comment": "Embedding local basé sur SentenceTransformers (ST). Utilise BGE-small en mode léger, sans AutoModel/AutoTokenizer, pour éviter la surcharge mémoire des modèles HF.", "model_type": "embedding", "model_name": "BAAI/bge-small-en-v1.5", "model_path": "/home/iadnc/.models/bge-small", "backend": "st", "device": "cpu" }, "slm": { "__comment": "SLM local optionnel (TinyLlama, Phi, etc.). Null = désactivé.", "model_type": "causal_lm", "model_name": null, "model_path": null, "backend": null, "device": null }, "tokenizer": { "__comment": "Tokenizer HF externe (Mixtral), téléchargé via HF.", "model_type": "tokenizer", "model_name": "mistralai/Mixtral-8x7B-Instruct-v0.1", "model_path": null, "backend": "hf", "device": null }, "llm": { "__comment": "LLM principal via Daemon.", "model_type": "causal_lm", "backend": "mistral_daemon", "model_name": "mistral-medium-latest", "api_key_env": "MISTRAL_API_KEY", "daemon_host": "127.0.0.1", "daemon_port": 50050 }
}

Ou, plus ambitieux ( à condition que les backends aient été écrits) :

{ "__comment": "Configuration canonique v200 — aucun champ implicite, aucun type déduit automatiquement.", "llm_api": { "model_name": "mistral-medium-latest", "backend": "mistral_api", "model_type": "causal_lm", "api_key_env": "MISTRAL_API_KEY", "max_new_tokens": 2048, "temperature": 0.2 }, "llm_daemon": { "model_name": "mistral-medium-latest", "backend": "mistral_daemon", "model_type": "causal_lm", "api_key": "env:MISTRAL_API_KEY", "daemon_host": "127.0.0.1", "daemon_port": 50050, "max_new_tokens": 2048, "temperature": 0.0 }, "slm": { "model_name": "TinyLlama/TinyLlama-1.1B-Chat-v1.0", "backend": "hf_local", "model_type": "hf_causal_lm", "model_path": "/home/iadnc/.models/TinyLlama-1.1B-Chat-v1.0", "device": "cpu", "dtype": "float16", "max_new_tokens": 512, "temperature": 0.0 }, "embedding": { "model_name": "BAAI/bge-small-en-v1.5", "backend": "st", "model_type": "embedding", "model_path": "/home/iadnc/.models/bge-small", "device": "cpu" }, "tokenizer": { "model_name": "mistralai/Mixtral-8x7B-Instruct-v0.1", "backend": "hf", "model_type": "tokenizer", "device": "cpu" }, "service_router": { "model_name": "router-v1", "backend": "internal", "model_type": "router", "strategy": "round_robin", "targets": ["llm_api", "llm_daemon", "slm"] }, "reranker": { "model_name": "colbertv2", "backend": "hf_local", "model_type": "reranker", "model_path": "/home/iadnc/.models/colbertv2", "device": "cuda", "dtype": "float16" }, "vision_encoder": { "model_name": "openai/clip-vit-base-patch32", "backend": "hf_local", "model_type": "vision_encoder", "model_path": "/home/iadnc/.models/clip-vit-base-patch32", "device": "cuda" }, "audio_encoder": { "model_name": "facebook/wav2vec2-base-960h", "backend": "hf_local", "model_type": "audio_encoder", "model_path": "/home/iadnc/.models/wav2vec2", "device": "cpu" }, "http_service": { "model_name": "custom-service", "backend": "http", "model_type": "service", "service_url": "http://127.0.0.1:8080/infer", "timeout": 30 }
}

Règles :

Chaque modèle doit avoir un model_name
model_path peut être null si HF doit télécharger automatiquement
backend détermine le loader (hf, hf_local, mistral_api, etc.)
device peut être cpu, cuda, ou null
api_key est utilisé uniquement pour les backends API

3. Comment écrire `services.json`

Voici la version minimale, conforme à v200 :

{ "daemon": { "host": "127.0.0.1", "port": XXX }, "services": [ { "name": "llm.server", "class": "runtime_v21.services.llm.llm_server.LlmServer", "params": {} }, { "name": "slm.server", "class": "runtime_v21.services.llm.slm_server.SlmServer", "params": {} }, { "name": "memory.server", "class": "runtime_v21.services.memory_manager.MemoryManager", "params": {} } ], "index": { "loader": { "class": "runtime_v21.services.index.loaders.loader_manager.ThemeIndexLoaderManager", "params": {} }, "reserved_ram": 100000000 }
}, "tokenizer": { "model_name": "mistralai/Mixtral-8x7B-Instruct-v0.1", "backend": "hf", "model_type": "tokenizer", "device": "cpu" }
}

Règles :

Aucun service ne doit recevoir de modèle
→ pas de model, model_name, backend, device, etc.
Les services doivent recevoir uniquement :
- des noms de services Pyro5 (pour RPC)
- des paramètres métier (rare)
Les services doivent récupérer les modèles via AppSettings.

4. Résumé

Élément	Rôle	Contenu
`models.json`	Décrit les modèles	model_name, backend, device, path
`ModelsConfigurator`	Construit les modèles	HF, API, local
`AppSettingsManager`	Stocke les modèles	AppSettings.embedding, etc.
`services.json`	Décrit les services	classes, RPC, dépendances
Services Pyro5	Consomment les modèles	via AppSettings

Protocoles des API LLM

Bertrand Degoy — 2026-06-16T08:12:06Z

Ce document décrit les deux modes d'appel aux API utilisés par les modèles LLM dans l'architecture v200 : synchrone et streaming.

Protocoles d'appel LLM : synchrone vs streaming

Ce document décrit les deux modes d'appel utilisés par les modèles LLM dans l'architecture v200 :

appel synchrone (generate)
appel en streaming (stream_generate)

Les deux modes utilisent HTTP(S), mais pas le même protocole.

Dans la v200, les InternalLLM sont les seules classes responsables :

de la configuration backend (client, modèle, URL si HTTP)
de l'appel synchrone
de l'appel streaming
de la normalisation des réponses

1. Appel synchrone : HTTP POST classique

L'appel synchrone (generate) utilise un POST HTTP standard.

Caractéristiques

Une seule requête
Une seule réponse
Format JSON complet
Pas de flux
Pas de tokens intermédiaires

Exemple (OpenAI/Mistral-like)

POST /v1/chat/completions
Content-Type: application/json { "model": "mistral-large", "messages": [...]
}

Réponse :

200 OK
Content-Type: application/json { "id": "...", "choices": [ { "message": { "content": "réponse complète" } } ]
}

2. Appel streaming : HTTP POST + protocole de flux

L'appel stream_generate utilise également un POST HTTP, mais la réponse n'est pas un JSON unique.
Le serveur envoie un flux d'événements ou de chunks.

Deux protocoles sont utilisés selon les backends :

2.1. SSE (Server-Sent Events)

C'est le protocole utilisé par :

OpenAI
Mistral
Anthropic
Groq
LM Studio (mode OpenAI)

Caractéristiques

Content-Type: text/event-stream
Transfer-Encoding: chunked
Chaque ligne commence par data:
Chaque événement contient un fragment (delta)
Le flux se termine par data: [DONE]

Exemple

data: {"choices":[{"delta":{"content":"Bon"}}]}
data: {"choices":[{"delta":{"content":"jour"}}]}
data: {"choices":[{"delta":{"content":" !"}}]}
data: [DONE]

2.2. Chunked Transfer Encoding (Ollama)

Ollama n'utilise pas SSE mais un flux de JSON successifs, un par chunk.

Exemple

{"response": "Bon"}
{"response": "jour"}
{"response": " Bertrand"}
{"done": true}

Caractéristiques

Pas de data:
Pas de SSE
Chaque chunk est un JSON indépendant
Le client doit lire le flux chunk par chunk

3. Pourquoi deux protocoles différents ?

Parce que :

un appel synchrone renvoie une réponse complète
un streaming renvoie un flux de tokens

HTTP classique ne permet pas d'envoyer plusieurs réponses successives.
Les serveurs utilisent donc :

SSE → flux d'événements textuels
chunked transfer → flux de JSON partiels
WebSocket (rare) → flux bidirectionnel

4. Conséquences pour l'architecture v200

4.1. `generate()`

utilise un appel HTTP simple
renvoie un JSON complet
normalisation effectuée dans la classe LLM

4.2. `stream_generate()`

utilise SSE ou chunked transfer
lit les fragments au fur et à mesure
normalise chaque fragment en format v200 :

{ "delta": "texte" }
...
{ "delta": "", "meta": {...} }

Retourne un flux de chunks représentant la réponse en streaming. Contrat de l'interface :

La méthode doit produire un itérable de chunks.

Convention v200 (obligatoire pour toutes les implémentations) :
- Les chunks intermédiaires sont des dicts contenant : { "delta": "" }
- Le dernier chunk contient en plus des métadonnées : { "delta": "", "meta": {...} } Cette convention garantit un format standardisé pour toutes les
implémentations InternalLLM, indépendamment du backend utilisé.

5. Résumé

6. Exemple

from commons.models.internal.base import BaseGenerativeModel
from commons.models.response import Response
class MistralAPIInternalLLM(BaseGenerativeModel):
"""
Implémentation Mistral API pour v200.
Cette classe contient :
- la configuration backend (client, modèle)
- generate() : appel synchrone
- stream_generate() : appel SSE
- normalisation des réponses
"""
def __init__(self, client, model_name: str):
self.client = client
self.model_name = model_name
def generate(self, prompt: str, **kwargs) -> Response:
"""
Appel synchrone : requête HTTP complète, pas de streaming.
Le format exact de la réponse dépend du backend.
"""
raw = self.client.chat.completions.create(
model=self.model_name,
messages=[{"role": "user", "content": prompt}],
stream=False,
**kwargs,
)
try:
text = raw["choices"][0]["message"]["content"]
except Exception:
text = str(raw)
return Response(
response=text,
raw_response=raw,
source_nodes=None,
metadata={},
)
def stream_generate(self, prompt: str, **kwargs):
"""
Retourne un flux de chunks.
Le format exact dépend de l'implémentation.
Convention interne v200 :
- chunks intermédiaires : {"delta": "..."}
- chunk final : {"delta": "", "meta": {...}}
"""
stream = self.client.chat.completions.create(
model=self.model_name,
messages=[{"role": "user", "content": prompt}],
stream=True,
**kwargs,
)
final_message = None
for chunk in stream:
delta = ""
if chunk.choices:
c = chunk.choices[0]
if getattr(c, "delta", None) and getattr(c.delta, "content", None):
delta = c.delta.content or ""
if getattr(c, "message", None):
final_message = c.message
yield {"delta": delta}
yield {
"delta": "",
"meta": {
"raw_response": final_message,
"nodes": None,
"metadata": {},
},
}

Télécharger

Orchestration : ReAct et Backtracking

Bertrand Degoy — 2026-05-17T10:04:49Z

Une boucle ReAct "Raisonne" en marche avant, selon une suite d'étapes successives. Si le raisonnement échoue à donner une réponse à la question posée, la boucle s'arrête sans réponse. Même si une réponse est trouvée, elle n'a pas été élaborée par l'exploration de plusieurs branches : le résultat reste non exhaustif.
Cet article décrit comment on pourrait revenir en arrière et recommencer sur une hypothèse différente (backtracking), à la façon d'un moteur d'inférences.

Nous proposons une architecture dans laquelle ReAct (Reasoning + Acting) est accompagné par un Superviseur qui peut remonter l'arbre de décisions ("backtracking") et explorer des alternatives en cas d'échec ou d'insatisfaction. Dans cette approche, le superviseur serait un méta-contrôleur.

Un moteur d'inférences logiques peut jouer un rôle central dans l'orchestration des actions et des décisions à suivre en cas d'échec.
En effet, un moteur logique excelle dans :
– la détection de situations complexes,
– la représentation déclarative ("symbolique") de règles, de contraintes et d'alternatives ,
– le raisonnement sur des violations et des exceptions,
– le retour en arrière (backtracking) dans un arbre de solutions pour explorer les alternatives.

L'approche développée — ReAct + Inférence logique — se distingue nettement de tout ce qui existe aujourd'hui :

– elle est originale,
– elle est techniquement solide,
– elle répond à un besoin non couvert par les architectures actuelles,
– elle combine deux mondes rarement réunis :
agents LLM et moteurs logiques déterministes.

Aucun travail MIT, Stanford, DeepMind ou autre ne couvre cette architecture.

La version v2 de ReActEngine (en développement) est fondé sur cette architecture. Un moteur ReAct complet, en streaming entièrement écrit à la main, sans LlamaIndex ou autre, avec un LLM de Mistral AI : Made in France, cocorico !

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" du 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 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 daemon 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.

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

Les services IA de DnC

Le Daemon Pyro5

Position du problème

Rôle du daemon

Composants principaux

1. MemoryManager

2. InDaemonRagReader

Interaction avec le client

Avantages de cette architecture

v200 : Introduction

1. Objectif : Modularité systémique

1.1. Modularité des modèles

1.2. Modularité des index

1.3. Rapidité via daemon Pyro5

2. Objectif : RAGEngine indépendant d'API externes

2.1. Suppression des dépendances structurelles

2.2. RAGEngine basé sur une API interne stable

2.3. Normalisation systématique des résultats

2.4. Fallback local cohérent

Synthèse

Politique LRU/MRU

Politique LRU/MRU

MRU — Most Recently Used

LRU — Least Recently Used

Pourquoi LRU/MRU est idéal dans ton architecture

1. Les index sont lourds

2. Les RemoteIndexService sont stateless

3. Le daemon est long-lived

4. Les thèmes ont des patterns d'accès naturels

Résultat : une mémoire auto-optimisée

Construction des modèles : models.json et services.json

Construction des modèles : models.json et services.json

1. Présentation générale : comment les modèles sont construits dans v200

1. models.json décrit les modèles

2. ModelsConfigurator construit les modèles

3. AppSettingsManager stocke les modèles

4. Les services Pyro5 consomment les modèles

5. services.json décrit uniquement les services

2. Comment écrire models.json

Règles :

3. Comment écrire services.json

Règles :

4. Résumé

Protocoles des API LLM

Protocoles d'appel LLM : synchrone vs streaming

1. Appel synchrone : HTTP POST classique

Caractéristiques

Exemple (OpenAI/Mistral-like)

2. Appel streaming : HTTP POST + protocole de flux

2.1. SSE (Server-Sent Events)

Caractéristiques

Exemple

2.2. Chunked Transfer Encoding (Ollama)

Exemple

Caractéristiques

3. Pourquoi deux protocoles différents ?

4. Conséquences pour l'architecture v200

4.1. generate()

4.2. stream_generate()

5. Résumé

6. Exemple

Orchestration : ReAct et Backtracking

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

Construction des modèles : `models.json` et `services.json`

1. `models.json` décrit les modèles

5. `services.json` décrit uniquement les services

2. Comment écrire `models.json`

3. Comment écrire `services.json`

4.1. `generate()`

4.2. `stream_generate()`

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()`