agentic-api 2.0.491 → 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/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,10 +1,35 @@
-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 :

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;
+}

package/dist/src/agents/simulator.dashboard.js

@@ -0,0 +1,344 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimulatorDashboard = void 0;
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const readline_1 = require("readline");
+const path_1 = __importDefault(require("path"));
+const simulator_1 = require("./simulator");
+// ============================================================================
+// CLASS: SimulatorDashboard
+// ============================================================================
+class SimulatorDashboard {
+    constructor(config) {
+        this.config = config;
+        this.simulator = null;
+        this.abortController = null;
+        this._currentOutputPath = null;
+        this._currentInputPath = null;
+        this.status = this.createInitialStatus();
+    }
+    /**
+     * Chemin du fichier output actuel (ou du dernier run)
+     */
+    get currentOutputPath() {
+        return this._currentOutputPath;
+    }
+    /**
+     * Chemin du fichier input actuel (ou du dernier run)
+     */
+    get currentInputPath() {
+        return this._currentInputPath;
+    }
+    createInitialStatus() {
+        return {
+            isRunning: false,
+            sessionId: null,
+            currentTest: 0,
+            totalTests: 0,
+            passed: 0,
+            failed: 0,
+            errors: 0,
+            startTime: null,
+            lastUpdate: null
+        };
+    }
+    /**
+     * Obtenir le status actuel (pour le contrôleur backend)
+     */
+    getStatus() {
+        return { ...this.status };
+    }
+    /**
+     * Vérifier si une exécution est en cours
+     */
+    isRunning() {
+        return this.status.isRunning;
+    }
+    /**
+     * Annuler l'exécution en cours
+     */
+    abort() {
+        if (this.abortController) {
+            this.abortController.abort();
+        }
+    }
+    /**
+     * Charger un fichier JSON d'entrée
+     */
+    async loadInputFile(filePath) {
+        const content = await (0, promises_1.readFile)(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    /**
+     * 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) {
+        const dir = path_1.default.dirname(inputPath);
+        const basename = path_1.default.basename(inputPath, path_1.default.extname(inputPath));
+        return path_1.default.join(dir, `results.${basename}.jsonl`);
+    }
+    /**
+     * 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
+     */
+    async loadResults(inputPath) {
+        // Déterminer le chemin du fichier output
+        let outputPath = null;
+        if (inputPath) {
+            outputPath = this.createOutputPath(inputPath);
+        }
+        else if (this._currentInputPath) {
+            outputPath = this.createOutputPath(this._currentInputPath);
+        }
+        else if (this._currentOutputPath) {
+            outputPath = this._currentOutputPath;
+        }
+        if (!outputPath || !(0, fs_1.existsSync)(outputPath)) {
+            return null;
+        }
+        return new Promise((resolve, reject) => {
+            const lines = [];
+            const stream = (0, fs_1.createReadStream)(outputPath, { encoding: 'utf-8' });
+            const rl = (0, readline_1.createInterface)({ input: stream, crlfDelay: Infinity });
+            rl.on('line', (line) => {
+                if (line.trim()) {
+                    try {
+                        lines.push(JSON.parse(line));
+                    }
+                    catch (e) {
+                        // Ignorer les lignes mal formées (fichier en cours d'écriture)
+                    }
+                }
+            });
+            rl.on('close', () => resolve(lines));
+            rl.on('error', reject);
+        });
+    }
+    /**
+     * Obtenir le résumé des résultats (dernière ligne type='end')
+     * @param inputPath - Chemin du fichier JSON d'entrée
+     */
+    async getResultsSummary(inputPath) {
+        const results = await this.loadResults(inputPath);
+        if (!results)
+            return null;
+        const endLine = results.find(r => r.type === 'end');
+        return endLine?.summary || null;
+    }
+    /**
+     * Vérifier si les résultats sont complets (contient une ligne 'end')
+     * @param inputPath - Chemin du fichier JSON d'entrée
+     */
+    async isResultsComplete(inputPath) {
+        const results = await this.loadResults(inputPath);
+        if (!results)
+            return false;
+        return results.some(r => r.type === 'end');
+    }
+    /**
+     * 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)
+     */
+    async run(input, outputPath, onLine) {
+        // Stocker et charger l'input si c'est un chemin
+        const isInputFile = typeof input === 'string';
+        this._currentInputPath = isInputFile ? input : null;
+        const data = isInputFile
+            ? await this.loadInputFile(input)
+            : input;
+        // Générer automatiquement le outputPath si input est un fichier
+        const resolvedOutputPath = outputPath ?? (isInputFile ? this.createOutputPath(input) : undefined);
+        this._currentOutputPath = resolvedOutputPath || null;
+        // Initialiser le status
+        const sessionId = `session-${Date.now()}`;
+        this.status = {
+            isRunning: true,
+            sessionId,
+            currentTest: 0,
+            totalTests: data.tests.length,
+            passed: 0,
+            failed: 0,
+            errors: 0,
+            startTime: new Date(),
+            lastUpdate: new Date()
+        };
+        // Créer le simulateur avec config mergée
+        const mergedConfig = {
+            ...this.config,
+            ...data.config
+        };
+        this.simulator = new simulator_1.AgentSimulator(mergedConfig);
+        // Créer l'AbortController
+        this.abortController = new AbortController();
+        // Ouvrir le fichier de sortie si spécifié
+        let writeStream = null;
+        if (resolvedOutputPath) {
+            writeStream = (0, fs_1.createWriteStream)(resolvedOutputPath, { encoding: 'utf-8' });
+        }
+        const results = [];
+        const startTime = Date.now();
+        // Helper pour écrire une ligne
+        const writeLine = (line) => {
+            results.push(line);
+            const jsonLine = JSON.stringify(line) + '\n';
+            if (writeStream) {
+                writeStream.write(jsonLine);
+            }
+            if (onLine) {
+                onLine(line);
+            }
+        };
+        try {
+            // Écrire la ligne de début
+            writeLine({
+                type: 'start',
+                timestamp: new Date().toISOString(),
+                sessionId,
+                totalTests: data.tests.length
+            });
+            // Exécuter chaque test
+            for (let i = 0; i < data.tests.length; i++) {
+                // Vérifier si annulé
+                if (this.abortController.signal.aborted) {
+                    break;
+                }
+                const testCase = data.tests[i];
+                const testId = testCase.id || `test-${i}`;
+                const testStartTime = Date.now();
+                // Mettre à jour le status
+                this.status.currentTest = i + 1;
+                this.status.lastUpdate = new Date();
+                try {
+                    // Exécuter le test
+                    const result = await this.simulator.testCase(testCase.scenario, testCase.case);
+                    // Déterminer le status
+                    const status = result.success ? 'completed' : 'failed';
+                    // Mettre à jour les compteurs
+                    if (result.success) {
+                        this.status.passed++;
+                    }
+                    else {
+                        this.status.failed++;
+                    }
+                    // Écrire le résultat
+                    writeLine({
+                        type: 'result',
+                        timestamp: new Date().toISOString(),
+                        testId,
+                        testIndex: i,
+                        name: testCase.name || testId,
+                        description: testCase.scenario.description || testCase.scenario.goals,
+                        query: testCase.case.query,
+                        status,
+                        success: result.success,
+                        message: result.message,
+                        error: result.error || undefined,
+                        exchangeCount: result.exchangeCount,
+                        messages: result.messages,
+                        duration: Date.now() - testStartTime
+                    });
+                }
+                catch (error) {
+                    // Erreur d'exécution
+                    this.status.errors++;
+                    writeLine({
+                        type: 'error',
+                        timestamp: new Date().toISOString(),
+                        testId,
+                        testIndex: i,
+                        name: testCase.name || testId,
+                        description: testCase.scenario.description || testCase.scenario.goals,
+                        query: testCase.case.query,
+                        status: 'error',
+                        success: false,
+                        error: error.message || String(error),
+                        duration: Date.now() - testStartTime
+                    });
+                }
+            }
+            // Écrire la ligne de fin
+            writeLine({
+                type: 'end',
+                timestamp: new Date().toISOString(),
+                sessionId,
+                summary: {
+                    total: data.tests.length,
+                    passed: this.status.passed,
+                    failed: this.status.failed,
+                    errors: this.status.errors,
+                    totalDuration: Date.now() - startTime
+                }
+            });
+        }
+        finally {
+            // Fermer le stream et attendre la fin de l'écriture
+            if (writeStream) {
+                await new Promise((resolve, reject) => {
+                    writeStream.end(() => resolve());
+                    writeStream.on('error', reject);
+                });
+            }
+            // Reset le status
+            this.status.isRunning = false;
+            this.status.lastUpdate = new Date();
+            this.simulator = null;
+            this.abortController = null;
+        }
+        return results;
+    }
+    /**
+     * Exécuter avec callback de streaming (pour SSE/WebSocket)
+     */
+    async runWithStream(input, onLine) {
+        return this.run(input, undefined, onLine);
+    }
+    /**
+     * Créer un fichier JSON d'exemple pour les tests
+     */
+    static createExampleInput() {
+        return {
+            name: "Example Test Suite",
+            description: "Exemple de suite de tests pour le simulator",
+            tests: [
+                {
+                    id: "test-greeting",
+                    name: "Test de salutation",
+                    scenario: {
+                        goals: "L'agent doit répondre poliment à la salutation",
+                        persona: "Utilisateur poli et patient"
+                    },
+                    case: {
+                        query: "Bonjour, comment allez-vous?"
+                        // maxExchanges: 1 par défaut
+                        // expectedTools: {} par défaut
+                    }
+                },
+                {
+                    id: "test-transfer",
+                    name: "Test de transfert",
+                    scenario: {
+                        goals: "L'agent doit transférer vers l'agent spécialisé",
+                        persona: "Utilisateur avec une demande spécifique"
+                    },
+                    case: {
+                        query: "J'ai besoin d'aide spécialisée",
+                        maxExchanges: 3,
+                        expectedTools: { 'transferAgents': { gte: 1 } }
+                    }
+                }
+            ]
+        };
+    }
+}
+exports.SimulatorDashboard = SimulatorDashboard;