agentic-api 2.0.491 → 2.0.592

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/job.runner.d.ts

@@ -0,0 +1,130 @@
+export type JobStatus = 'planned' | 'running' | 'done' | 'failed';
+export type TaskStatus = 'todo' | 'doing' | 'done' | 'failed';
+export interface TaskSpec {
+    id: string;
+    title: string;
+    type?: string;
+    dependsOn?: string[];
+    input?: any;
+    acceptance?: string[];
+}
+export interface TaskResult {
+    taskId: string;
+    ok: boolean;
+    summary: string;
+    data?: any;
+    artifacts?: {
+        kind: string;
+        ref: string;
+        meta?: any;
+    }[];
+    error?: string;
+}
+export interface JobPlan {
+    jobId: string;
+    goal: string;
+    beneficiary?: string;
+    tasks: TaskSpec[];
+}
+export interface ReducedJobMemory {
+    memory: string;
+    index: Record<string, any>;
+    statusLine?: string;
+}
+export interface JobRunnerState {
+    jobId: string;
+    plan?: JobPlan;
+    jobStatus: JobStatus;
+    taskStatus: Record<string, TaskStatus>;
+    lastMemory: ReducedJobMemory | null;
+    lastError?: string;
+}
+export type PlannerFn = (input: any, seedMemory?: ReducedJobMemory | null) => Promise<JobPlan>;
+export type ExecutorFn = (task: TaskSpec, memory: ReducedJobMemory | null) => Promise<TaskResult>;
+export type ReducerFn = (previous: ReducedJobMemory | null, task: TaskSpec, result: TaskResult) => Promise<ReducedJobMemory>;
+export type JobEventType = 'job_created' | 'plan_ready' | 'task_started' | 'task_done' | 'memory_reduced' | 'job_done' | 'job_failed';
+export interface JobEvent<T = any> {
+    type: JobEventType;
+    at: string;
+    payload?: T;
+}
+export interface JobRunnerConfig {
+    planner: PlannerFn;
+    executor: ExecutorFn;
+    reducer: ReducerFn;
+    /**
+     * Directory where snapshots and events are persisted.
+     * If not provided, persistence is disabled.
+     */
+    storeDir?: string;
+    /**
+     * Max attempts per task when schema validation fails or executor throws.
+     * (Logical failure with ok=false does not trigger retry)
+     */
+    maxAttempts?: number;
+    onEvent?: (event: JobEvent) => void;
+}
+export interface RunJobOptions {
+    jobId?: string;
+    seedMemory?: ReducedJobMemory | null;
+    resume?: boolean;
+}
+export interface JobRunSuccess {
+    ok: true;
+    jobId: string;
+    plan: JobPlan;
+    finalSummary: string;
+    artifactsIndex: Record<string, any>;
+    memory: ReducedJobMemory | null;
+    taskStatus: Record<string, TaskStatus>;
+    snapshotFile?: string;
+    eventsFile?: string;
+}
+export interface JobRunFailure {
+    ok: false;
+    jobId: string;
+    plan?: JobPlan;
+    failedTaskId?: string;
+    error: string;
+    errorSummary: {
+        taskId?: string;
+        taskTitle?: string;
+        nature: string;
+        progress?: string;
+        nextAction: string;
+    };
+    memory: ReducedJobMemory | null;
+    taskStatus: Record<string, TaskStatus>;
+    snapshotFile?: string;
+    eventsFile?: string;
+}
+export type JobRunOutcome = JobRunSuccess | JobRunFailure;
+export declare class JobRunner {
+    private readonly storeDir?;
+    private readonly maxAttempts;
+    private readonly planner;
+    private readonly executor;
+    private readonly reducer;
+    private readonly onEvent?;
+    constructor(config: JobRunnerConfig);
+    /**
+     * Run a job end-to-end (Plan → Execute → Reduce) with persistence and retries.
+     */
+    run(input: any, options?: RunJobOptions): Promise<JobRunOutcome>;
+    private planJob;
+    private initTaskStatus;
+    private nextReadyTask;
+    private executeWithRetry;
+    private reduceWithRetry;
+    private handleFailure;
+    private validateJobPlan;
+    private validateTaskResult;
+    private validateMemory;
+    private persistState;
+    private loadState;
+    private ensureStoreDir;
+    private snapshotPath;
+    private eventsPath;
+    private logEvent;
+    private emit;
+}

package/dist/src/agents/job.runner.js

@@ -0,0 +1,339 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobRunner = void 0;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+class JobRunner {
+    constructor(config) {
+        this.planner = config.planner;
+        this.executor = config.executor;
+        this.reducer = config.reducer;
+        this.storeDir = config.storeDir;
+        this.maxAttempts = config.maxAttempts || 2;
+        this.onEvent = config.onEvent;
+    }
+    /**
+     * Run a job end-to-end (Plan → Execute → Reduce) with persistence and retries.
+     */
+    async run(input, options) {
+        const seedMemory = options?.seedMemory ?? null;
+        const jobId = options?.jobId || (0, crypto_1.randomUUID)();
+        let state = null;
+        if (options?.resume && this.storeDir) {
+            state = await this.loadState(jobId);
+        }
+        if (!state) {
+            const plan = await this.planJob(jobId, input, seedMemory);
+            state = {
+                jobId: plan.jobId,
+                plan,
+                jobStatus: 'running',
+                taskStatus: this.initTaskStatus(plan.tasks),
+                lastMemory: seedMemory || null
+            };
+            await this.persistState(state);
+            this.emit({ type: 'job_created', at: new Date().toISOString(), payload: { jobId: state.jobId } });
+        }
+        if (!state.plan) {
+            return {
+                ok: false,
+                jobId,
+                error: 'Missing plan in restored state',
+                errorSummary: {
+                    nature: 'state_corruption',
+                    nextAction: 'Re-run planner to regenerate plan'
+                },
+                memory: state.lastMemory,
+                taskStatus: state.taskStatus
+            };
+        }
+        this.emit({ type: 'plan_ready', at: new Date().toISOString(), payload: { jobId: state.jobId, tasks: state.plan.tasks.length } });
+        const plan = state.plan;
+        state.jobStatus = 'running';
+        while (true) {
+            const nextTask = this.nextReadyTask(plan.tasks, state.taskStatus);
+            if (!nextTask)
+                break;
+            state.taskStatus[nextTask.id] = 'doing';
+            await this.persistState(state);
+            const execResult = await this.executeWithRetry(nextTask, state.lastMemory);
+            if (!execResult.valid) {
+                return await this.handleFailure(state, plan, nextTask, execResult.error || 'Execution failed');
+            }
+            const result = execResult.result;
+            this.emit({ type: 'task_done', at: new Date().toISOString(), payload: { jobId: plan.jobId, taskId: nextTask.id, ok: result.ok } });
+            const reduced = await this.reduceWithRetry(state.lastMemory, nextTask, result);
+            if (!reduced.valid) {
+                return await this.handleFailure(state, plan, nextTask, reduced.error || 'Reducer failed');
+            }
+            state.lastMemory = reduced.memory;
+            state.taskStatus[nextTask.id] = result.ok ? 'done' : 'failed';
+            await this.persistState(state);
+            this.emit({ type: 'memory_reduced', at: new Date().toISOString(), payload: { jobId: plan.jobId, taskId: nextTask.id } });
+            if (!result.ok) {
+                return await this.handleFailure(state, plan, nextTask, result.error || 'Task reported logical failure');
+            }
+        }
+        state.jobStatus = 'done';
+        await this.persistState(state);
+        this.emit({ type: 'job_done', at: new Date().toISOString(), payload: { jobId: plan.jobId } });
+        return {
+            ok: true,
+            jobId: plan.jobId,
+            plan,
+            finalSummary: state.lastMemory?.memory || '',
+            artifactsIndex: state.lastMemory?.index || {},
+            memory: state.lastMemory,
+            taskStatus: state.taskStatus,
+            snapshotFile: this.snapshotPath(plan.jobId),
+            eventsFile: this.eventsPath(plan.jobId)
+        };
+    }
+    async planJob(jobId, input, seedMemory) {
+        const plan = await this.planner(input, seedMemory);
+        const finalPlan = {
+            ...plan,
+            jobId: plan.jobId || jobId
+        };
+        this.validateJobPlan(finalPlan, true);
+        return finalPlan;
+    }
+    initTaskStatus(tasks) {
+        return tasks.reduce((acc, task) => {
+            acc[task.id] = 'todo';
+            return acc;
+        }, {});
+    }
+    nextReadyTask(tasks, status) {
+        return tasks.find(task => {
+            if (status[task.id] !== 'todo')
+                return false;
+            if (!task.dependsOn || task.dependsOn.length === 0)
+                return true;
+            return task.dependsOn.every(dep => status[dep] === 'done');
+        }) || null;
+    }
+    async executeWithRetry(task, memory) {
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            this.emit({ type: 'task_started', at: new Date().toISOString(), payload: { taskId: task.id, attempt } });
+            try {
+                const result = await this.executor(task, memory);
+                const errors = this.validateTaskResult(result);
+                if (errors.length === 0) {
+                    return { valid: true, result, attempts: attempt };
+                }
+                if (attempt >= this.maxAttempts) {
+                    return { valid: false, error: `TaskResult validation failed: ${errors.join(', ')}`, attempts: attempt };
+                }
+            }
+            catch (err) {
+                if (attempt >= this.maxAttempts) {
+                    return { valid: false, error: err?.message || 'Executor error', attempts: attempt };
+                }
+            }
+        }
+        return { valid: false, error: 'Unknown execution failure', attempts: this.maxAttempts };
+    }
+    async reduceWithRetry(previous, task, result) {
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            try {
+                const nextMemory = await this.reducer(previous, task, result);
+                const errors = this.validateMemory(nextMemory);
+                if (errors.length === 0) {
+                    return { valid: true, memory: nextMemory };
+                }
+                if (attempt >= this.maxAttempts) {
+                    return { valid: false, error: `Reducer validation failed: ${errors.join(', ')}` };
+                }
+            }
+            catch (err) {
+                if (attempt >= this.maxAttempts) {
+                    return { valid: false, error: err?.message || 'Reducer error' };
+                }
+            }
+        }
+        return { valid: false, error: 'Unknown reducer failure' };
+    }
+    async handleFailure(state, plan, task, reason) {
+        state.jobStatus = 'failed';
+        state.taskStatus[task.id] = state.taskStatus[task.id] === 'done' ? 'done' : 'failed';
+        state.lastError = reason;
+        await this.persistState(state);
+        const errorSummary = {
+            taskId: task.id,
+            taskTitle: task.title,
+            nature: reason,
+            progress: state.lastMemory?.memory,
+            nextAction: 'Inspect executor/reducer outputs or planner schema, then retry'
+        };
+        this.emit({ type: 'job_failed', at: new Date().toISOString(), payload: { jobId: plan.jobId, taskId: task.id, reason } });
+        return {
+            ok: false,
+            jobId: plan.jobId,
+            plan,
+            failedTaskId: task.id,
+            error: reason,
+            errorSummary,
+            memory: state.lastMemory,
+            taskStatus: state.taskStatus,
+            snapshotFile: this.snapshotPath(plan.jobId),
+            eventsFile: this.eventsPath(plan.jobId)
+        };
+    }
+    validateJobPlan(plan, throwOnError = false) {
+        const errors = [];
+        if (!plan || typeof plan !== 'object') {
+            errors.push('plan must be an object');
+        }
+        if (!plan.jobId || typeof plan.jobId !== 'string' || !plan.jobId.trim()) {
+            errors.push('jobId is required');
+        }
+        if (!plan.goal || typeof plan.goal !== 'string' || !plan.goal.trim()) {
+            errors.push('goal is required');
+        }
+        if (!Array.isArray(plan.tasks) || plan.tasks.length === 0) {
+            errors.push('tasks must be a non-empty array');
+        }
+        else {
+            plan.tasks.forEach((task, idx) => {
+                if (!task || typeof task !== 'object') {
+                    errors.push(`task[${idx}] must be an object`);
+                    return;
+                }
+                if (!task.id || typeof task.id !== 'string' || !task.id.trim()) {
+                    errors.push(`task[${idx}].id is required`);
+                }
+                if (!task.title || typeof task.title !== 'string' || !task.title.trim()) {
+                    errors.push(`task[${idx}].title is required`);
+                }
+                if (task.dependsOn && !Array.isArray(task.dependsOn)) {
+                    errors.push(`task[${idx}].dependsOn must be an array if provided`);
+                }
+                if (task.acceptance && !Array.isArray(task.acceptance)) {
+                    errors.push(`task[${idx}].acceptance must be an array if provided`);
+                }
+            });
+        }
+        if (throwOnError && errors.length) {
+            throw new Error(`Invalid JobPlan: ${errors.join(', ')}`);
+        }
+        return errors;
+    }
+    validateTaskResult(result) {
+        const errors = [];
+        if (!result || typeof result !== 'object') {
+            errors.push('TaskResult must be an object');
+            return errors;
+        }
+        if (!result.taskId || typeof result.taskId !== 'string' || !result.taskId.trim()) {
+            errors.push('taskId is required');
+        }
+        if (typeof result.ok !== 'boolean') {
+            errors.push('ok must be boolean');
+        }
+        if (!result.summary || typeof result.summary !== 'string') {
+            errors.push('summary is required');
+        }
+        if (result.artifacts && !Array.isArray(result.artifacts)) {
+            errors.push('artifacts must be an array if provided');
+        }
+        else if (Array.isArray(result.artifacts)) {
+            result.artifacts.forEach((artifact, idx) => {
+                if (!artifact || typeof artifact !== 'object') {
+                    errors.push(`artifacts[${idx}] must be an object`);
+                    return;
+                }
+                if (!artifact.kind || !artifact.ref) {
+                    errors.push(`artifacts[${idx}] requires kind and ref`);
+                }
+            });
+        }
+        return errors;
+    }
+    validateMemory(memory) {
+        const errors = [];
+        if (!memory || typeof memory !== 'object') {
+            errors.push('memory must be an object');
+            return errors;
+        }
+        if (typeof memory.memory !== 'string') {
+            errors.push('memory.memory must be a string');
+        }
+        if (!memory.index || typeof memory.index !== 'object') {
+            errors.push('memory.index must be an object');
+        }
+        if (memory.statusLine && typeof memory.statusLine !== 'string') {
+            errors.push('memory.statusLine must be a string if provided');
+        }
+        return errors;
+    }
+    async persistState(state) {
+        if (!this.storeDir)
+            return;
+        await this.ensureStoreDir();
+        const file = this.snapshotPath(state.jobId);
+        if (!file)
+            return;
+        const snapshot = JSON.stringify(state, null, 2);
+        await fs_1.promises.writeFile(file, snapshot, 'utf-8');
+    }
+    async loadState(jobId) {
+        if (!this.storeDir)
+            return null;
+        const file = this.snapshotPath(jobId);
+        if (!file)
+            return null;
+        try {
+            const data = await fs_1.promises.readFile(file, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    async ensureStoreDir() {
+        if (!this.storeDir)
+            return;
+        await fs_1.promises.mkdir(this.storeDir, { recursive: true });
+    }
+    snapshotPath(jobId) {
+        if (!this.storeDir)
+            return undefined;
+        return path_1.default.join(this.storeDir, `${jobId}.json`);
+    }
+    eventsPath(jobId) {
+        if (!this.storeDir)
+            return undefined;
+        return path_1.default.join(this.storeDir, `${jobId}.events.jsonl`);
+    }
+    async logEvent(jobId, event) {
+        if (!this.storeDir)
+            return;
+        await this.ensureStoreDir();
+        const file = this.eventsPath(jobId);
+        if (!file)
+            return;
+        const line = JSON.stringify(event);
+        await fs_1.promises.appendFile(file, `${line}\n`, 'utf-8');
+    }
+    emit(event) {
+        if (!event.at) {
+            event.at = new Date().toISOString();
+        }
+        if (this.onEvent) {
+            this.onEvent(event);
+        }
+        // Persist events only when jobId is present in payload or snapshot is known
+        const jobId = (event.payload && event.payload.jobId) || undefined;
+        if (jobId && this.storeDir) {
+            this.logEvent(jobId, event).catch(() => {
+                /* silent */
+            });
+        }
+    }
+}
+exports.JobRunner = JobRunner;

package/dist/src/agents/reducer.core.d.ts

@@ -12,13 +12,23 @@ export interface AgentReducerConfig {
     /** Default agent name to use if task doesn't specify one */
     defaultAgent: string;
 }
+/**
+ * Options for MapLLM constructor
+ */
+export interface MapLLMOptions {
+    /** Whether to execute a final reduce pass after all chunks (default: true) */
+    finalReduce?: boolean;
+    /** Threshold in bytes to trigger automatic intermediate reduce (optional) */
+    reduceThresholdBytes?: number;
+}
 /**
  * MapLLM - Orchestrateur principal pour le reduce hiérarchique
  */
 export declare class MapLLM {
     private loader;
     private agentConfig?;
-    constructor(loader: NativeLoader);
+    private readonly options;
+    constructor(loader: NativeLoader, options?: MapLLMOptions);
     /**
      * Vérifie si le loader fournit des agents (TaskListLoader)
      */