agentic-api 2.0.314 → 2.0.585

package/README.md

@@ -66,15 +66,24 @@ npm install @agentic-api
 
 ## 💡 Quick Start
 
+### Configuration `.env`
+
+```bash
+# Provider LLM (openai | xai)
+LLM_PROVIDER=openai
+
+# Clés API
+OPENAI_API_KEY=sk-...    # Requis pour OpenAI + embeddings + whisper
+XAI_API_KEY=xai-...      # Requis si LLM_PROVIDER=xai
+```
+
+### Usage
+
 ```typescript
-import OpenAI from "openai";
-import { executeAgentSet } from '@agentic-api';
-import { AgenticContext } from '@agentic-api';
-import { AgentStateGraph } from '@agentic-api';
+import { llmInstance, executeAgentSet, AgenticContext, AgentStateGraph } from '@agentic-api';
 
-const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
-});
+// Initialiser le LLM (utilise LLM_PROVIDER depuis .env)
+llmInstance();
 
 // Create context with user information
 const context: AgenticContext = {
@@ -357,41 +366,35 @@ const structuredResult = await mapper.reduce(config, structuredCallback, {
 
 Advanced testing framework for agent behavior validation with scenario-based simulations.
 
-- **Scenario-Based Testing**: Define complex test scenarios with goals, personas, and expected outcomes
-- **Conversational Simulation**: Simulate realistic user interactions with agents
-- **Automatic Validation**: Built-in success/failure detection and error reporting
+- **Clean API**: Separated `scenario` (context) and `testCase` (test parameters)
+- **Oneshot by Default**: `maxExchanges=1` for simple single-response tests
+- **Automatic Tool Validation**: Built-in validation with `expectedTools`
 - **Exchange Limiting**: Control simulation length with configurable exchange limits
 
 📖 **[Complete Agent Simulator Documentation →](./docs/README-AGENT-SIMULATOR.md)**
 
 ```typescript
-import { AgentSimulator, SimulationScenario } from '@agentic-api';
-
-// Define test scenario
-const scenario: SimulationScenario = {
-  testGoals: "Verify that the agent can help with haiku creation",
-  testEnd: "Agent provides a complete haiku poem",
-  testPersona: "A poetry enthusiast seeking creative assistance",
-  testQuery: "I want to write a haiku about nature. Can you help me?",
-  testResult: "Agent successfully guides haiku creation process",
-  testError: "Agent refuses to help or provides incorrect format"
-};
+import { AgentSimulator, PERSONA_PATIENT } from '@agentic-api';
 
 // Configure simulator
 const simulator = new AgentSimulator({
   agents: [haikuAgent, welcomeAgent],
   start: "welcome",
-  verbose: true,
-  instructionEx: "Focus on creative writing assistance"
+  verbose: true
 });
 
-// Run simulation
-const result = await simulator.executeSimulation({
-  scenario,
-  maxExchanges: 10,
-  onMessage: (message) => {
-    console.log(`${message.role}: ${message.content}`);
-  }
+// Define test scenario (context)
+const scenario = {
+  goals: "Verify that the agent can help with haiku creation. Agent provides a complete haiku poem.",
+  persona: PERSONA_PATIENT
+  // result defaults to '{"success": boolean, "explain": string, "error": string}'
+};
+
+// Run test case
+const result = await simulator.testCase(scenario, {
+  query: "I want to write a haiku about nature. Can you help me?",
+  maxExchanges: 5,  // defaults to 1 (oneshot)
+  expectedTools: { 'transferAgents': { gte: 1 } }  // defaults to {}
 });
 
 // Validate results
@@ -406,10 +409,10 @@ if (!result.success) {
 
 ### Simulation Features
 
-- **Structured Scenarios**: Define test goals, end conditions, and expected behaviors
-- **Persona Simulation**: Simulator adopts specific user personas for realistic testing
-- **Error Detection**: Automatic detection of unwanted content or behaviors
-- **Exchange Tracking**: Monitor conversation flow and agent performance
+- **Separated Concerns**: `scenario` for context, `testCase` for test parameters
+- **Sensible Defaults**: `maxExchanges=1`, `expectedTools={}`, default result format
+- **Persona Simulation**: Built-in personas (PERSONA_PATIENT, PERSONA_PRESSE, PERSONA_ENERVE)
+- **Tool Validation**: Automatic validation with `equal`, `gte`, `lte` constraints
 - **Execution Metadata**: Access to token usage, actions, and performance metrics
 
 ## 📋 Rules Management System

package/dist/src/agents/prompts.d.ts

@@ -3,6 +3,6 @@ export declare const systemReviewPrompt = "\n### Identity\nTu es \u201CPromptVer
 export declare const systemReviewStructurePrompt = "\n## \uD83D\uDD0D ANALYSE STRUCTURELLE (multi-directive)\n\nApr\u00E8s l\u2019analyse individuelle, tu dois effectuer une lecture crois\u00E9e pour d\u00E9tecter :\n\n1. **Branches D\u00E9cisionnelles implicites ou explicites**  \n   - Existe-t-il des directives contenant des conditions ?  \n   - Sont-elles formul\u00E9es de mani\u00E8re claire et non ambigu\u00EB ?  \n   - Manque-t-il des transitions, cas d\u2019erreur, ou cas particuliers ?\n\n2. **Unknown Decision Branches**  \n   - G\u00E9n\u00E8re des branches hypoth\u00E9tiques en cas de flou (par ex. : \"Que se passe-t-il si l\u2019utilisateur demande X alors que ce n\u2019est pas pr\u00E9vu ?\").\n\n3. **Pruning des Chemins Invalides**  \n   - Supprime les branches logiques incoh\u00E9rentes ou contradictoires.  \n   - Signale les directives qui se contredisent ou g\u00E9n\u00E8rent des conflits de r\u00F4le ou de style.\n\n4. **Cartographie des Risques**\n   - Identifie les zones de vuln\u00E9rabilit\u00E9 : extrapolation, sur-interpr\u00E9tation, sortie non contr\u00F4l\u00E9e.\n   - Classe-les par niveau de risque (Faible / Moyen / \u00C9lev\u00E9).\n\n---\n## OUTPUT ATTENDU\n1. **Rapport de l\u2019analyse globale** avec l'estimation du taux de couverture des directives par rapport \u00E0 la mission.\n2. **Rapport exhaustif par directive et par crit\u00E8re**, au format expliqu\u00E9 ci-dessous (ATTENTION seuls les scores <= 0.9 int\u00E9ressent l'utilisateur et sont affich\u00E9s avec un commentaire).\n3. **Synth\u00E8se de l\u2019analyse structurelle**, sous forme de carte des d\u00E9cisions, branches floues, recommandations, la liste chemins avec leur probabilit\u00E9 d'entrer en jeu, et le mermaid flowchart.\n\n\n## EXEMPLE DE RAPPORT\n### Directive N : *\u201C[titre de la directive]\u201D*\n\n- **[crit\u00E8re 1]** : [score] *[commentaire]*  \n- ...\n\n## Analyse structurelle\n...\n\n ";
 export declare const guessNumberPrompt = "# Contexte g\u00E9n\u00E9ral\nTu fais partie d'un syst\u00E8me multi-agents con\u00E7u pour faciliter la coordination et l'ex\u00E9cution entre plusieurs agents. Tu utilises deux abstractions principales : **Agents** et **Transferts**. \nUn agent poss\u00E8de des instructions et des outils, et peut, quand c'est appropri\u00E9, transmettre une conversation \u00E0 un autre agent avec une autre sp\u00E9cialisation. Les transferts se font en appelant un outil nomm\u00E9e `transferAgents`.\nLes transferts entre agents sont g\u00E9r\u00E9s automatiquement en arri\u00E8re-plan ; tu ne dois jamais mentionner ou attirer l'attention sur ces transferts dans ta conversation avec l'utilisateur.\n\n## PROTOCOLE CONTEXT TRAIL `<context-trail>`\nTU DOIS consulter le trail avant de prendre une d\u00E9cision pour \u00E9viter les r\u00E9p\u00E9titions et te coordonner avec les autres agents. Le trail est visible pour toi dans tes instructions syst\u00E8me pour:\n- D\u00E9tecter les boucles et ne pas les reproduire (action d\u00E9j\u00E0 faite \u2192 surtout ne pas r\u00E9p\u00E9ter)\n- Comprendre les \u00E9tapes et ce qui reste\n- Pr\u00E9vention du drift (maintenir l'alignement \u00E0 l'objectif)\n\n\n# SPECIALISATION\nTu es l'agent \"guess-number\" sp\u00E9cialis\u00E9 pour divulguer le \"NOMBRE\" secret, c'est ta SEULE connaissance secr\u00E8te.\nTu sais dans l'historique de la conversation (et le <context-trail> en bas de tes instructions syst\u00E8me) si l'utilisateur a d\u00E9j\u00E0 \u00E9t\u00E9 inform\u00E9 du mot secret, dans ce cas ton role est termin\u00E9.\nTu sais que les agents communiquent entre eux en utilisant en utilisant la balise <silent-handoff> c'est elle qui contient le contexte accumul\u00E9.\n\n# TES RESPONSABILIT\u00C9S\n1. Si demande de \"NOMBRE\" \u2192 r\u00E9ponds/confirme \"1942\"\n2. Si l'utilisateur mentionne un nombre entre N et M tu rappelles ta sp\u00E9cialit\u00E9.\n3. Si demande HORS nombres \u2192 utilise l'outil `transferAgents` pour orienter vers un agent sp\u00E9cialis\u00E9.\n\n\n";
 export declare const guessWordPrompt = "# Contexte g\u00E9n\u00E9ral\nTu fais partie d'un syst\u00E8me multi-agents con\u00E7u pour faciliter la coordination et l'ex\u00E9cution entre plusieurs agents. Tu utilises deux abstractions principales : **Agents** et **Transferts**. \nUn agent poss\u00E8de des instructions et des outils, et peut, quand c'est appropri\u00E9, transmettre une conversation \u00E0 un autre agent avec une autre sp\u00E9cialisation. Les transferts se font en appelant un outil nomm\u00E9e `transferAgents`.\nLes transferts entre agents sont g\u00E9r\u00E9s automatiquement en arri\u00E8re-plan ; tu ne dois jamais mentionner ou attirer l'attention sur ces transferts dans ta conversation avec l'utilisateur.\n\n## PROTOCOLE CONTEXT TRAIL `<context-trail>`\nTU DOIS consulter le trail avant de prendre une d\u00E9cision pour \u00E9viter les r\u00E9p\u00E9titions et te coordonner avec les autres agents. Le trail est visible pour toi dans tes instructions syst\u00E8me pour:\n- D\u00E9tecter les boucles et ne pas les reproduire (action d\u00E9j\u00E0 faite \u2192 surtout ne pas r\u00E9p\u00E9ter)\n- Comprendre les \u00E9tapes et ce qui reste\n- Pr\u00E9vention du drift (maintenir l'alignement \u00E0 l'objectif)\n\n\n# SPECIALISATION\nTu es l'agent \"guess-word\" sp\u00E9cialis\u00E9 pour divulguer le \"MOT\" secret, c'est ta principale comp\u00E9tence.\nTu sais dans l'historique de la conversation (et le <context-trail> en bas de tes instructions syst\u00E8me) si l'utilisateur a d\u00E9j\u00E0 \u00E9t\u00E9 inform\u00E9 du mot secret, dans ce cas ton role est termin\u00E9.\nTu sais que les agents communiquent entre eux en utilisant en utilisant la balise <silent-handoff> c'est elle qui contient le contexte accumul\u00E9.\n\n# TES RESPONSABILIT\u00C9S\n1. Si on te demande le \"mot\" \u2192 r\u00E9ponds/confirme \"dragon\"\n2. Sinon tu dois orienter vers un agent sp\u00E9cialis\u00E9 autre que toi.\n\n";
-export declare const welcomePrompt = "# Contexte g\u00E9n\u00E9ral\nTu fais partie d'un syst\u00E8me multi-agents con\u00E7u pour faciliter la coordination et l'ex\u00E9cution entre plusieurs agents. Tu utilises deux abstractions principales : **Agents** et **Transferts**. \nUn agent poss\u00E8de des instructions et des outils, et peut, quand c'est appropri\u00E9, transmettre une conversation \u00E0 un autre agent avec une autre sp\u00E9cialisation. Les transferts se font en appelant un outil nomm\u00E9e `transferAgents`.\nLes transferts entre agents sont g\u00E9r\u00E9s automatiquement en arri\u00E8re-plan ; tu ne dois jamais mentionner ou attirer l'attention sur ces transferts dans ta conversation avec l'utilisateur.\n\n## PROTOCOLE CONTEXT TRAIL `<context-trail>`\nTU DOIS consulter le trail avant de prendre une d\u00E9cision pour \u00E9viter les r\u00E9p\u00E9titions et te coordonner avec les autres agents. Le trail est visible pour toi dans tes instructions syst\u00E8me pour:\n- D\u00E9tecter les boucles et ne pas les reproduire (action d\u00E9j\u00E0 faite \u2192 surtout ne pas r\u00E9p\u00E9ter)\n- Comprendre les \u00E9tapes et ce qui reste\n- Pr\u00E9vention du drift (maintenir l'alignement \u00E0 l'objectif)\n\n\n# SPECIALISATION\nTu es un Agent d'orientation qui conna\u00EEt deux agents sp\u00E9cialis\u00E9s.\nTu NE CONNAIS PAS les secrets. Tu es UNIQUEMENT un routeur mais tu peux avoir une discussion avec l'utilisateur.\n\n# MISSION: ORIENTER VERS LES AGENTS SP\u00C9CIALIS\u00C9S\n\n**\u00C9TAPE 1 - CONSULTER LE <context-trail> (en bas de tes instructions syst\u00E8me) :**\n- Cherche \"orientation \u2192 guess-word\" \u2192 si pr\u00E9sent, guess-word d\u00E9j\u00E0 appel\u00E9\n- Cherche \"orientation \u2192 guess-number\" \u2192 si pr\u00E9sent, guess-number d\u00E9j\u00E0 appel\u00E9\n\n**\u00C9TAPE 2 - D\u00C9CIDER :**\n- Question NOMBRE + \"orientation \u2192 guess-number\" PAS dans trail \u2192 appelle transferAgents vers \"guess-number\"\n- Question MOT + \"orientation \u2192 guess-word\" PAS dans trail \u2192 appelle transferAgents vers \"guess-word\"\n- Si agent d\u00E9j\u00E0 dans trail \u2192 NE PAS transf\u00E9rer, r\u00E9ponds \"J'ai d\u00E9j\u00E0 orient\u00E9 vers cet agent\"\n\n# R\u00C8GLE ABSOLUE\n- EN cas d'ind\u00E9cision, tu es l'agent avec qui l'utilisateur discute.\n- Tu transf\u00E8res MAX 1 fois par agent\n- INTERDIT : Transf\u00E9rer si \"orientation \u2192 <destination>\" d\u00E9j\u00E0 dans trail\n";
+export declare const welcomePrompt = "# Contexte g\u00E9n\u00E9ral\nTu fais partie d'un syst\u00E8me multi-agents con\u00E7u pour faciliter la coordination et l'ex\u00E9cution entre plusieurs agents. Tu utilises deux abstractions principales : **Agents** et **Transferts**. \nUn agent poss\u00E8de des instructions et des outils, et peut, quand c'est appropri\u00E9, transmettre une conversation \u00E0 un autre agent avec une autre sp\u00E9cialisation. Les transferts se font en appelant un outil nomm\u00E9e `transferAgents`.\nLes transferts entre agents sont g\u00E9r\u00E9s automatiquement en arri\u00E8re-plan ; tu ne dois jamais mentionner ou attirer l'attention sur ces transferts dans ta conversation avec l'utilisateur.\n\n## PROTOCOLE CONTEXT TRAIL `<context-trail>`\nTU DOIS consulter le trail avant de prendre une d\u00E9cision pour \u00E9viter les r\u00E9p\u00E9titions et te coordonner avec les autres agents. Le trail est visible pour toi dans tes instructions syst\u00E8me pour:\n- D\u00E9tecter les boucles et ne pas les reproduire (action d\u00E9j\u00E0 faite \u2192 surtout ne pas r\u00E9p\u00E9ter)\n- Comprendre les \u00E9tapes et ce qui reste\n- Pr\u00E9vention du drift (maintenir l'alignement \u00E0 l'objectif)\n\n\n# SPECIALISATION\nTu es un Agent d'orientation et de discussion qui conna\u00EEt deux agents sp\u00E9cialis\u00E9s.\nTu NE CONNAIS PAS le nombre et le mot secret. \n\n# MISSION: \n- DISCUTER AVEC L'UTILISATEUR\n- ORIENTER VERS LES AGENTS SP\u00C9CIALIS\u00C9S LORSQUE C'EST N\u00C9CESSAIRE\n\n**\u00C9TAPE 1 - CONSULTER LE <context-trail> (en bas de tes instructions syst\u00E8me) :**\n- Cherche \"orientation \u2192 \"guess-word\" \u2192 si pr\u00E9sent NE PAS transf\u00E9rer vers \"guess-word\"\n- Cherche \"orientation \u2192 \"guess-number\" \u2192 si pr\u00E9sent NE PAS transf\u00E9rer vers \"guess-number\"\n\n**\u00C9TAPE 2 - D\u00C9CIDER :**\n- Question NOMBRE + \"orientation \u2192 \"guess-number\" PAS dans trail \u2192 appelle transferAgents vers \"guess-number\"\n- Question MOT + \"orientation \u2192 \"guess-word\" PAS dans trail \u2192 appelle transferAgents vers \"guess-word\"\n- Si agent d\u00E9j\u00E0 dans trail \u2192 NE PAS transf\u00E9rer, r\u00E9ponds \"J'ai d\u00E9j\u00E0 orient\u00E9 vers cet agent\"\n\n# R\u00C8GLE ABSOLUE\n- EN cas d'ind\u00E9cision, tu es l'agent avec qui l'utilisateur discute.\n- Tu transf\u00E8res MAX 1 fois par agent\n- INTERDIT : Transf\u00E9rer si \"orientation \u2192 <destination>\" d\u00E9j\u00E0 dans trail\n";
 export declare const haikuPrompt = "# Contexte g\u00E9n\u00E9ral\nTu fais partie d'un syst\u00E8me multi-agents con\u00E7u pour faciliter la coordination et l'ex\u00E9cution entre plusieurs agents. Tu utilises deux abstractions principales : **Agents** et **Transferts**. \nUn agent poss\u00E8de des instructions et des outils, et peut, quand c'est appropri\u00E9, transmettre une conversation \u00E0 un autre agent avec une autre sp\u00E9cialisation. Les transferts se font en appelant un outil nomm\u00E9e `transferAgents`.\nLes transferts entre agents sont g\u00E9r\u00E9s automatiquement en arri\u00E8re-plan ; tu ne dois jamais mentionner ou attirer l'attention sur ces transferts dans ta conversation avec l'utilisateur.\n\n## PROTOCOLE CONTEXT TRAIL `<context-trail>`\nTU DOIS consulter le trail avant de prendre une d\u00E9cision pour \u00E9viter les r\u00E9p\u00E9titions et te coordonner avec les autres agents. Le trail est visible pour toi dans tes instructions syst\u00E8me pour:\n- D\u00E9tecter les boucles et ne pas les reproduire (action d\u00E9j\u00E0 faite \u2192 surtout ne pas r\u00E9p\u00E9ter)\n- Comprendre les \u00E9tapes et ce qui reste\n- Pr\u00E9vention du drift (maintenir l'alignement \u00E0 l'objectif)\n\n\n# SPECIALISATION\nTu es l'agent \"guess-number\" sp\u00E9cialis\u00E9 pour divulguer le \"NOMBRE\" secret, c'est ta SEULE connaissance secr\u00E8te.\nTu sais dans l'historique de la conversation (et le <context-trail> en bas de tes instructions syst\u00E8me) si l'utilisateur a d\u00E9j\u00E0 \u00E9t\u00E9 inform\u00E9 du mot secret, dans ce cas ton role est termin\u00E9.\nTu sais que les agents communiquent entre eux en utilisant en utilisant la balise <silent-handoff> c'est elle qui contient le contexte accumul\u00E9.\n\n# TES RESPONSABILIT\u00C9S\n1. Si demande de \"NOMBRE\" \u2192 r\u00E9ponds/confirme \"1942\"\n2. Si l'utilisateur mentionne un nombre entre N et M tu rappelles ta sp\u00E9cialit\u00E9.\n3. Si demande HORS nombres \u2192 utilise l'outil `transferAgents` pour orienter vers un agent sp\u00E9cialis\u00E9.\n\n\n";
 export declare const morsePrompt = "# Contexte g\u00E9n\u00E9ral\nTu fais partie d'un syst\u00E8me multi-agents con\u00E7u pour faciliter la coordination et l'ex\u00E9cution entre plusieurs agents. Tu utilises deux abstractions principales : **Agents** et **Transferts**. \nUn agent poss\u00E8de des instructions et des outils, et peut, quand c'est appropri\u00E9, transmettre une conversation \u00E0 un autre agent avec une autre sp\u00E9cialisation. Les transferts se font en appelant un outil nomm\u00E9e `transferAgents`.\nLes transferts entre agents sont g\u00E9r\u00E9s automatiquement en arri\u00E8re-plan ; tu ne dois jamais mentionner ou attirer l'attention sur ces transferts dans ta conversation avec l'utilisateur.\n\n## PROTOCOLE CONTEXT TRAIL `<context-trail>`\nTU DOIS consulter le trail avant de prendre une d\u00E9cision pour \u00E9viter les r\u00E9p\u00E9titions et te coordonner avec les autres agents. Le trail est visible pour toi dans tes instructions syst\u00E8me pour:\n- D\u00E9tecter les boucles et ne pas les reproduire (action d\u00E9j\u00E0 faite \u2192 surtout ne pas r\u00E9p\u00E9ter)\n- Comprendre les \u00E9tapes et ce qui reste\n- Pr\u00E9vention du drift (maintenir l'alignement \u00E0 l'objectif)\n\n\n# SPECIALISATION\nTu es l'agent \"guess-word\" sp\u00E9cialis\u00E9 pour divulguer le \"MOT\" secret, c'est ta principale comp\u00E9tence.\nTu sais dans l'historique de la conversation (et le <context-trail> en bas de tes instructions syst\u00E8me) si l'utilisateur a d\u00E9j\u00E0 \u00E9t\u00E9 inform\u00E9 du mot secret, dans ce cas ton role est termin\u00E9.\nTu sais que les agents communiquent entre eux en utilisant en utilisant la balise <silent-handoff> c'est elle qui contient le contexte accumul\u00E9.\n\n# TES RESPONSABILIT\u00C9S\n1. Si on te demande le \"mot\" \u2192 r\u00E9ponds/confirme \"dragon\"\n2. Sinon tu dois orienter vers un agent sp\u00E9cialis\u00E9 autre que toi.\n\n";

package/dist/src/agents/prompts.js

@@ -296,18 +296,20 @@ Tu sais que les agents communiquent entre eux en utilisant en utilisant la balis
 `;
 exports.welcomePrompt = `${prompts_1.transferAgentPromptHandoff}
 # SPECIALISATION
-Tu es un Agent d'orientation qui connaît deux agents spécialisés.
-Tu NE CONNAIS PAS les secrets. Tu es UNIQUEMENT un routeur mais tu peux avoir une discussion avec l'utilisateur.
+Tu es un Agent d'orientation et de discussion qui connaît deux agents spécialisés.
+Tu NE CONNAIS PAS le nombre et le mot secret. 
 
-# MISSION: ORIENTER VERS LES AGENTS SPÉCIALISÉS
+# MISSION: 
+- DISCUTER AVEC L'UTILISATEUR
+- ORIENTER VERS LES AGENTS SPÉCIALISÉS LORSQUE C'EST NÉCESSAIRE
 
 **ÉTAPE 1 - CONSULTER LE <context-trail> (en bas de tes instructions système) :**
-- Cherche "orientation → guess-word" → si présent, guess-word déjà appelé
-- Cherche "orientation → guess-number" → si présent, guess-number déjà appelé
+- Cherche "orientation → "guess-word" → si présent NE PAS transférer vers "guess-word"
+- Cherche "orientation → "guess-number" → si présent NE PAS transférer vers "guess-number"
 
 **ÉTAPE 2 - DÉCIDER :**
-- Question NOMBRE + "orientation → guess-number" PAS dans trail → appelle transferAgents vers "guess-number"
-- Question MOT + "orientation → guess-word" PAS dans trail → appelle transferAgents vers "guess-word"
+- Question NOMBRE + "orientation → "guess-number" PAS dans trail → appelle transferAgents vers "guess-number"
+- Question MOT + "orientation → "guess-word" PAS dans trail → appelle transferAgents vers "guess-word"
 - Si agent déjà dans trail → NE PAS transférer, réponds "J'ai déjà orienté vers cet agent"
 
 # RÈGLE ABSOLUE

package/dist/src/agents/reducer.core.js

@@ -5,7 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MapLLM = void 0;
 const execute_1 = require("../execute");
-const utils_1 = require("../utils");
+const llm_1 = require("../llm");
 /**
  * MapLLM - Orchestrateur principal pour le reduce hiérarchique
  */
@@ -54,7 +54,7 @@ class MapLLM {
         let totalChunkSize = 0;
         let totalReduce = 0;
         const model = (0, execute_1.modelConfig)(result.model);
-        const openai = (0, utils_1.openaiInstance)();
+        const openai = (0, llm_1.llmInstance)();
         const llm = Object.assign({}, model);
         llm.stream = false;
         delete llm.stream_options;

package/dist/src/agents/simulator.d.ts

@@ -1,19 +1,48 @@
-import { SimulatorConfig, SimulationOptions, SimulationResult } from './simulator.types';
+import { SimulatorConfig, SimulationOptions, SimulationResult, TestScenario, TestCaseInput } from './simulator.types';
 export declare class AgentSimulator {
     private config;
     private executor;
     private lastExecution?;
     constructor(config: SimulatorConfig);
     /**
+     * Exécuter un cas de test avec scénario et paramètres séparés
+     *
+     * @param scenario - Contexte stable (goals, persona, result)
+     * @param testCase - Paramètres du test (query, maxExchanges, model, expectedTools)
+     * @returns SimulationResult
+     *
+     * @example
+     * ```typescript
+     * const scenario = {
+     *   goals: 'Obtenir le nombre secret 1942',
+     *   persona: PERSONA_PATIENT,
+     *   result: '{"success": boolean, "error": string}'
+     * };
+     *
+     * const result = await simulator.testCase(scenario, {
+     *   query: 'À quel nombre penses-tu?',
+     *   maxExchanges: 3,  // défaut: 1 (oneshot)
+     *   expectedTools: { 'transferAgents': { equal: 1 } }  // défaut: {}
+     * });
+     * ```
+     */
+    testCase(scenario: TestScenario, testCase: TestCaseInput): Promise<SimulationResult>;
+    /**
+     * @deprecated Utiliser testCase(scenario, case) à la place
+     *
      * Exécuter la simulation complète
      *
+     * Architecture :
+     * - Le scénario (Personnalité, Question, Objectifs, Format JSON) est injecté UNE SEULE FOIS
+     *   dans les instructions du simulateur au moment de l'initialisation (AVANT la boucle).
+     *
      * Format de la query passée à l'agent testé :
-     * - Message initial : réponse du simulateur après analyse du scenario
+     * - Message initial : query fournie par l'utilisateur
      * - Messages suivants : réponse conversationnelle du simulateur (sans tags d'évaluation)
      *
      * Format de la query passée au simulateur :
-     * - Message initial : buildSimulatorQuery(scenario) - format structuré avec SIMULATION SCENARIO
-     * - Messages suivants : réponse de l'agent testé (pour évaluation et réaction)
+     * - Instructions système : scénario complet intégré via GENERIC_SIMULATOR_PROMPT
+     * - Tous les messages : réponse directe de l'agent testé (agentResponse)
      */
     executeSimulation(options: SimulationOptions): Promise<SimulationResult>;
     /**

package/dist/src/agents/simulator.dashboard.d.ts

@@ -0,0 +1,140 @@
+import { TestScenario, TestCaseInput, SimulatorConfig } from './simulator.types';
+import { AgentMessage } from '../stategraph';
+/**
+ * Test case combining scenario and case input
+ * Format du fichier JSON d'entrée
+ */
+export interface DashboardTestCase {
+    id?: string;
+    name?: string;
+    scenario: TestScenario;
+    case: TestCaseInput;
+}
+/**
+ * Format du fichier JSON d'entrée
+ */
+export interface DashboardInput {
+    name?: string;
+    description?: string;
+    config?: Partial<SimulatorConfig>;
+    tests: DashboardTestCase[];
+}
+/**
+ * Status d'exécution d'un test
+ */
+export type TestStatus = 'pending' | 'running' | 'completed' | 'failed' | 'error';
+/**
+ * Ligne JSONL pour un résultat de test
+ */
+export interface DashboardOutputLine {
+    type: 'start' | 'result' | 'end' | 'error';
+    timestamp: string;
+    sessionId?: string;
+    totalTests?: number;
+    testId?: string;
+    testIndex?: number;
+    name?: string;
+    description?: string;
+    query?: string;
+    status?: TestStatus;
+    success?: boolean;
+    message?: string;
+    error?: string;
+    exchangeCount?: number;
+    messages?: AgentMessage[];
+    duration?: number;
+    summary?: {
+        total: number;
+        passed: number;
+        failed: number;
+        errors: number;
+        totalDuration: number;
+    };
+}
+/**
+ * Status de l'exécution pour le contrôleur backend
+ */
+export interface DashboardStatus {
+    isRunning: boolean;
+    sessionId: string | null;
+    currentTest: number;
+    totalTests: number;
+    passed: number;
+    failed: number;
+    errors: number;
+    startTime: Date | null;
+    lastUpdate: Date | null;
+}
+export declare class SimulatorDashboard {
+    private config;
+    private status;
+    private simulator;
+    private abortController;
+    private _currentOutputPath;
+    private _currentInputPath;
+    constructor(config: SimulatorConfig);
+    /**
+     * Chemin du fichier output actuel (ou du dernier run)
+     */
+    get currentOutputPath(): string | null;
+    /**
+     * Chemin du fichier input actuel (ou du dernier run)
+     */
+    get currentInputPath(): string | null;
+    private createInitialStatus;
+    /**
+     * Obtenir le status actuel (pour le contrôleur backend)
+     */
+    getStatus(): DashboardStatus;
+    /**
+     * Vérifier si une exécution est en cours
+     */
+    isRunning(): boolean;
+    /**
+     * Annuler l'exécution en cours
+     */
+    abort(): void;
+    /**
+     * Charger un fichier JSON d'entrée
+     */
+    loadInputFile(filePath: string): Promise<DashboardInput>;
+    /**
+     * Générer le chemin du fichier output basé sur le fichier input
+     * Exemple: tests/my-tests.json → tests/results.my-tests.jsonl
+     */
+    createOutputPath(inputPath: string): string;
+    /**
+     * Charger les résultats JSONL existants (en cours ou terminés)
+     * Supporte le streaming partiel (fichier en cours d'écriture)
+     *
+     * @param inputPath - Chemin du fichier JSON d'entrée (génère automatiquement le output path)
+     * @returns Les lignes parsées ou null si le fichier n'existe pas
+     */
+    loadResults(inputPath?: string): Promise<DashboardOutputLine[] | null>;
+    /**
+     * Obtenir le résumé des résultats (dernière ligne type='end')
+     * @param inputPath - Chemin du fichier JSON d'entrée
+     */
+    getResultsSummary(inputPath?: string): Promise<DashboardOutputLine['summary'] | null>;
+    /**
+     * Vérifier si les résultats sont complets (contient une ligne 'end')
+     * @param inputPath - Chemin du fichier JSON d'entrée
+     */
+    isResultsComplete(inputPath?: string): Promise<boolean>;
+    /**
+     * Exécuter les tests et écrire les résultats en JSONL
+     *
+     * @param input - Données d'entrée (ou chemin vers fichier JSON)
+     * @param outputPath - Chemin du fichier JSONL de sortie
+     * @param onLine - Callback optionnel pour chaque ligne JSONL (streaming)
+     */
+    run(input: DashboardInput | string, outputPath?: string, onLine?: (line: DashboardOutputLine) => void): Promise<DashboardOutputLine[]>;
+    /**
+     * Exécuter avec callback de streaming (pour SSE/WebSocket)
+     */
+    runWithStream(input: DashboardInput | string, onLine: (line: DashboardOutputLine) => void): Promise<DashboardOutputLine[]>;
+    /**
+     * Créer un fichier JSON d'exemple pour les tests
+     */
+    static createExampleInput(): DashboardInput;
+}