agentic-api 1.0.6 → 2.0.31

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

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Native Loaders for MapLLM
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StringNativeLoader = exports.FileNativeLoader = void 0;
+const fs_1 = require("fs");
+/**
+ * FileNativeLoader - Loader pour fichiers avec chunking par lignes
+ */
+class FileNativeLoader {
+    constructor(filePath, strategy = { type: 'lines', size: 50 }) {
+        this.chunks = [];
+        const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        this.chunks = this.createChunks(content, strategy);
+    }
+    async loadNativeChunk(position) {
+        if (position >= this.chunks.length) {
+            throw new Error(`Position ${position} out of bounds (max: ${this.chunks.length - 1})`);
+        }
+        const content = this.chunks[position];
+        const nextPosition = position + 1;
+        const eof = nextPosition >= this.chunks.length;
+        return {
+            content,
+            eof,
+            position: nextPosition
+        };
+    }
+    createChunks(content, strategy) {
+        switch (strategy.type) {
+            case 'lines':
+                return this.chunkByLines(content, strategy.size);
+            case 'paragraphs':
+                return this.chunkByParagraphs(content, strategy.size);
+            default:
+                throw new Error(`Unsupported chunk strategy: ${strategy.type}`);
+        }
+    }
+    chunkByLines(content, linesPerChunk) {
+        const lines = content.split('\n');
+        const chunks = [];
+        for (let i = 0; i < lines.length; i += linesPerChunk) {
+            const chunkLines = lines.slice(i, i + linesPerChunk);
+            const chunkContent = chunkLines.join('\n').trim();
+            if (chunkContent) {
+                chunks.push(chunkContent);
+            }
+        }
+        return chunks;
+    }
+    chunkByParagraphs(content, paragraphsPerChunk) {
+        const paragraphs = content.split(/\n\s*\n/).filter(p => p.trim());
+        const chunks = [];
+        for (let i = 0; i < paragraphs.length; i += paragraphsPerChunk) {
+            const chunkParagraphs = paragraphs.slice(i, i + paragraphsPerChunk);
+            const chunkContent = chunkParagraphs.join('\n\n').trim();
+            if (chunkContent) {
+                chunks.push(chunkContent);
+            }
+        }
+        return chunks;
+    }
+}
+exports.FileNativeLoader = FileNativeLoader;
+/**
+ * StringNativeLoader - Loader pour contenu en mémoire
+ */
+class StringNativeLoader {
+    constructor(content, strategy = { type: 'lines', size: 50 }) {
+        this.chunks = [];
+        this.chunks = this.createChunks(content, strategy);
+    }
+    async loadNativeChunk(position) {
+        if (position >= this.chunks.length) {
+            throw new Error(`Position ${position} out of bounds (max: ${this.chunks.length - 1})`);
+        }
+        const content = this.chunks[position];
+        const nextPosition = position + 1;
+        const eof = nextPosition >= this.chunks.length;
+        return {
+            content,
+            eof,
+            position: nextPosition
+        };
+    }
+    createChunks(content, strategy) {
+        switch (strategy.type) {
+            case 'lines':
+                return this.chunkByLines(content, strategy.size);
+            case 'paragraphs':
+                return this.chunkByParagraphs(content, strategy.size);
+            default:
+                throw new Error(`Unsupported chunk strategy: ${strategy.type}`);
+        }
+    }
+    chunkByLines(content, linesPerChunk) {
+        const lines = content.split('\n');
+        const chunks = [];
+        for (let i = 0; i < lines.length; i += linesPerChunk) {
+            const chunkLines = lines.slice(i, i + linesPerChunk);
+            const chunkContent = chunkLines.join('\n').trim();
+            if (chunkContent) {
+                chunks.push(chunkContent);
+            }
+        }
+        return chunks;
+    }
+    chunkByParagraphs(content, paragraphsPerChunk) {
+        const paragraphs = content.split(/\n\s*\n/).filter(p => p.trim());
+        const chunks = [];
+        for (let i = 0; i < paragraphs.length; i += paragraphsPerChunk) {
+            const chunkParagraphs = paragraphs.slice(i, i + paragraphsPerChunk);
+            const chunkContent = chunkParagraphs.join('\n\n').trim();
+            if (chunkContent) {
+                chunks.push(chunkContent);
+            }
+        }
+        return chunks;
+    }
+}
+exports.StringNativeLoader = StringNativeLoader;

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

@@ -0,0 +1,16 @@
+import { StatefulReducerConfig, StatefulReduceResult, StatefulProcessOptions, ChunkLoader } from "./reducer.types";
+/**
+ * Main function to process a document using the stateful agent reduce pattern
+ *
+ * @param sessionId - Session ID for the discussion/document to process
+ * @param config - Stateful reducer configuration
+ * @param loader - ChunkLoader interface for loading content chunks
+ * @param options - Additional options
+ * @returns Promise resolving to the stateful reduce result
+ */
+export declare function statefulReduceProcess<T = any>(sessionId: string, config: StatefulReducerConfig, loader: ChunkLoader, options?: StatefulProcessOptions): Promise<StatefulReduceResult<T>>;
+/**
+ * Legacy function name for backward compatibility
+ * @deprecated Use statefulReduceProcess instead
+ */
+export declare function agentReduceProcess<T = any>(sessionId: string, config: any, loader: ChunkLoader, options?: any): Promise<any>;

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

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statefulReduceProcess = statefulReduceProcess;
+exports.agentReduceProcess = agentReduceProcess;
+const execute_1 = require("../execute");
+const reducer_tools_1 = require("./reducer.tools");
+/**
+ * Main function to process a document using the stateful agent reduce pattern
+ *
+ * @param sessionId - Session ID for the discussion/document to process
+ * @param config - Stateful reducer configuration
+ * @param loader - ChunkLoader interface for loading content chunks
+ * @param options - Additional options
+ * @returns Promise resolving to the stateful reduce result
+ */
+async function statefulReduceProcess(sessionId, config, loader, options = {}) {
+    const { stdout = process.stdout, maxIterations = 50, model = (0, execute_1.modelConfig)("MEDIUM"), verbose = config.verbose || false } = options;
+    // Create the stateful reducer tools
+    const { statefulReduceProcessChunk, toolStatefulReduceProcessChunk } = (0, reducer_tools_1.createStatefulReduceTools)(loader, config);
+    // Create initial agent configuration with dynamic system prompt
+    let agentConfig = {
+        name: "statefulReducer",
+        model,
+        publicDescription: "Agent that processes large content using stateful reducer pattern with digest replacement",
+        instructions: `${config.systemTemplate.replace('{{reducerContent}}', '')}
+
+IMPORTANT: Always use sessionId="${sessionId}" and template="${config.templates ? Object.keys(config.templates)[0] : 'semantic'}" when calling statefulReduceProcessChunk.
+Start with position=0 and continue with the nextPosition returned by the tool.`,
+        tools: [toolStatefulReduceProcessChunk],
+        toolLogic: {
+            statefulReduceProcessChunk: (args, context) => statefulReduceProcessChunk(args, context)
+        }
+    };
+    // Track the conversation and results
+    let position = 0;
+    let iterations = 0;
+    let finalDigest;
+    let allMessages = [];
+    let totalUsage = { prompt: 0, completion: 0, total: 0, cost: 0 };
+    let compressionHistory = [];
+    if (verbose) {
+        console.log(`🚀 statefulReduceProcess: Starting stateful reduce process for session: ${sessionId}`);
+    }
+    // Process the document iteratively with stateful pattern
+    while (iterations < maxIterations) {
+        iterations++;
+        const templateName = config.templates ? Object.keys(config.templates)[0] : 'semantic';
+        const query = iterations === 1
+            ? `Process the session "${sessionId}" with template "${templateName}" starting from position 0 using stateful reducer pattern.`
+            : `Continue processing from position ${position} with stateful reducer pattern.`;
+        if (verbose) {
+            console.log(`📝 statefulReduceProcess: Iteration ${iterations}: Processing from position ${position}`);
+        }
+        try {
+            // Execute the agent for this iteration
+            const result = await (0, execute_1.executeAgent)([agentConfig], {
+                query,
+                home: "statefulReducer",
+                stdout,
+                verbose
+            });
+            // Accumulate usage
+            if (result.usage) {
+                totalUsage.prompt += result.usage.prompt || 0;
+                totalUsage.completion += result.usage.completion || 0;
+                totalUsage.total += result.usage.total || 0;
+                totalUsage.cost += result.usage.cost || 0;
+            }
+            // Add messages to our conversation log
+            if (result.messages) {
+                allMessages.push(...result.messages);
+            }
+            // Parse the last tool result to get next position and check for EOF
+            const lastMessage = result.messages?.[result.messages.length - 1];
+            if (lastMessage?.role === 'tool') {
+                try {
+                    const toolResult = JSON.parse(lastMessage.content);
+                    if (toolResult.eof) {
+                        finalDigest = toolResult.finalDigest;
+                        if (verbose) {
+                            console.log(`✅ Stateful document processing complete after ${iterations} iterations`);
+                            console.log(`📊 Final digest size: ${toolResult.metadata?.finalDigestSize || 'unknown'} chars`);
+                        }
+                        break;
+                    }
+                    // Update position for next iteration
+                    position = toolResult.nextPosition || position;
+                    // Update agent configuration with new system prompt (STATEFUL)
+                    if (toolResult.systemPrompt) {
+                        agentConfig.instructions = toolResult.systemPrompt;
+                        if (verbose) {
+                            console.log(`🔄 System prompt updated for iteration ${iterations + 1}`);
+                        }
+                    }
+                    // Track compression if applied
+                    if (toolResult.compressionApplied) {
+                        compressionHistory.push(toolResult.compressionRatio || 0.8);
+                    }
+                }
+                catch (error) {
+                    if (verbose) {
+                        console.error(`❌ Error parsing tool result:`, error);
+                    }
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            if (verbose) {
+                console.error(`❌ Error in iteration ${iterations}:`, error);
+            }
+            throw error;
+        }
+    }
+    if (iterations >= maxIterations) {
+        throw new Error(`Maximum iterations (${maxIterations}) reached without completion`);
+    }
+    if (finalDigest === undefined) {
+        throw new Error("Processing completed but no final digest was produced");
+    }
+    return {
+        finalDigest: finalDigest,
+        iterations,
+        compressionHistory,
+        metadata: {
+            totalChunks: iterations,
+            finalDigestSize: typeof finalDigest === 'string' ? finalDigest.length : JSON.stringify(finalDigest).length,
+            averageCompressionRatio: compressionHistory.length > 0
+                ? compressionHistory.reduce((a, b) => a + b, 0) / compressionHistory.length
+                : 1.0,
+            sessionId
+        },
+        messages: allMessages
+    };
+}
+/**
+ * Legacy function name for backward compatibility
+ * @deprecated Use statefulReduceProcess instead
+ */
+async function agentReduceProcess(sessionId, config, loader, options = {}) {
+    console.warn('agentReduceProcess is deprecated. Use statefulReduceProcess instead.');
+    return statefulReduceProcess(sessionId, config, loader, options);
+}

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

@@ -0,0 +1,29 @@
+import { Tool } from "../types";
+import { StatefulReducerConfig, ChunkLoader } from "./reducer.types";
+/**
+ * Creates the stateful agent reduce tools with proper configuration
+ *
+ * @param loader - ChunkLoader interface for loading content chunks
+ * @param config - Stateful reducer configuration
+ * @returns Object containing the tool function and tool definition
+ */
+export declare function createStatefulReduceTools(loader: ChunkLoader, config: StatefulReducerConfig): {
+    statefulReduceProcessChunk: (args: any, context: any) => Promise<{
+        role: string;
+        name: string;
+        content: string;
+    }>;
+    toolStatefulReduceProcessChunk: Tool;
+};
+/**
+ * Legacy function name for backward compatibility
+ * @deprecated Use createStatefulReduceTools instead
+ */
+export declare function createAgentReduceTools(loader: ChunkLoader, config: any): {
+    statefulReduceProcessChunk: (args: any, context: any) => Promise<{
+        role: string;
+        name: string;
+        content: string;
+    }>;
+    toolStatefulReduceProcessChunk: Tool;
+};

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

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStatefulReduceTools = createStatefulReduceTools;
+exports.createAgentReduceTools = createAgentReduceTools;
+const reducer_core_1 = require("./reducer.core");
+/**
+ * Creates the tool definition for stateful agent reduce content processing
+ */
+const createStatefulReduceTool = () => ({
+    type: "function",
+    function: {
+        strict: true,
+        name: "statefulReduceProcessChunk",
+        description: `
+This tool processes large content with a STATEFUL reducer pattern using digest replacement.
+
+## Core Principles (STATEFUL)
+1. Each call processes ONE chunk and updates internal digest state
+2. First chunk: creates initial digest
+3. Subsequent chunks: digest + reduce → REPLACES previous digest (no accumulation)
+4. Continue calling until you receive "eof": true
+5. System prompt is dynamically updated with current digest
+
+## Parameters
+- **sessionId** *(string)* - Session ID for the discussion/document to process
+- **template** *(string)* - Processing template to apply
+- **position** *(number)* - Byte offset to resume reading (0 for first call)
+
+## Workflow (Stateful)
+1. Load chunk from position
+2. If first chunk: digest → update system prompt
+3. If subsequent: digest + reduce with current state → REPLACE digest → update system prompt
+4. Return current digest and continue until EOF
+    `,
+        parameters: {
+            type: "object",
+            properties: {
+                sessionId: {
+                    type: "string",
+                    description: "Session ID for the discussion/document to process"
+                },
+                template: {
+                    type: "string",
+                    description: "Processing template to apply",
+                    enum: ["facts", "compress", "semantic", "minutes", "custom", "weather", "aliments", "mobilite"]
+                },
+                position: {
+                    type: "number",
+                    description: "Current position in the document (0 for first call)"
+                }
+            },
+            required: ["sessionId", "template", "position"],
+            additionalProperties: false,
+        }
+    }
+});
+/**
+ * Creates the stateful agent reduce tools with proper configuration
+ *
+ * @param loader - ChunkLoader interface for loading content chunks
+ * @param config - Stateful reducer configuration
+ * @returns Object containing the tool function and tool definition
+ */
+function createStatefulReduceTools(loader, config) {
+    const toolStatefulReduceProcessChunk = createStatefulReduceTool();
+    // Stateful engine instance - maintains state across calls
+    let engine = null;
+    /**
+     * Stateful reduce process chunk tool implementation
+     */
+    const statefulReduceProcessChunk = async (args, context) => {
+        const { sessionId, template, position } = args;
+        if (!sessionId) {
+            throw new Error("Session ID is required for stateful reduce processing");
+        }
+        // Initialize engine on first call
+        if (!engine) {
+            engine = new reducer_core_1.StatefulReducerEngine(config);
+            engine.setSessionId(sessionId);
+            if (config.verbose) {
+                console.log(`🚀 STATEFUL TOOL: Initialized engine for session ${sessionId}`);
+            }
+        }
+        if (config.verbose) {
+            console.log(`🔄 STATEFUL TOOL: Loading chunk from position ${position} for session ${sessionId}`);
+        }
+        // Load the chunk using the external loader
+        const chunk = await loader.loadNativeChunk(sessionId, position);
+        if (!chunk || !chunk.content) {
+            throw new Error("Failed to load content chunk");
+        }
+        // Update engine position
+        engine.updatePosition(chunk.position);
+        // Check if template exists
+        if (!config.templates || !config.templates[template]) {
+            return {
+                role: "assistant",
+                name: "statefulReduceProcessChunk",
+                content: JSON.stringify({
+                    error: `Missing template '${template}'. Available templates: ${Object.keys(config.templates || {}).join(', ')}`,
+                    nextPosition: position,
+                    eof: false,
+                    systemPrompt: engine.getSystemPrompt()
+                })
+            };
+        }
+        // If this is EOF, return the final result
+        if (chunk.eof && chunk.content.includes('EOF')) {
+            engine.setEof(true);
+            const finalResult = engine.getFinalResult();
+            return {
+                role: "assistant",
+                name: "statefulReduceProcessChunk",
+                content: JSON.stringify({
+                    finalDigest: finalResult.finalDigest,
+                    nextPosition: chunk.position,
+                    eof: true,
+                    systemPrompt: engine.getSystemPrompt(),
+                    metadata: finalResult.metadata,
+                    instructions: "This is the final result. The document processing is complete."
+                })
+            };
+        }
+        // Process chunk with stateful engine
+        const currentDigest = await engine.processChunk(chunk.content);
+        const state = engine.getState();
+        // Return current state and instructions for next iteration
+        return {
+            role: "assistant",
+            name: "statefulReduceProcessChunk",
+            content: JSON.stringify({
+                currentDigest,
+                nextPosition: chunk.position,
+                eof: chunk.eof,
+                systemPrompt: engine.getSystemPrompt(),
+                template,
+                iteration: state.iteration,
+                chunkCount: state.chunkCount,
+                instructions: state.iteration === 1
+                    ? `Premier digest créé. Continue avec le chunk suivant.`
+                    : `Digest mis à jour (remplacement). Continue avec le chunk suivant.`
+            })
+        };
+    };
+    return {
+        statefulReduceProcessChunk,
+        toolStatefulReduceProcessChunk
+    };
+}
+/**
+ * Legacy function name for backward compatibility
+ * @deprecated Use createStatefulReduceTools instead
+ */
+function createAgentReduceTools(loader, config) {
+    console.warn('createAgentReduceTools is deprecated. Use createStatefulReduceTools instead.');
+    return createStatefulReduceTools(loader, config);
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Types for the MapLLM reducer functionality
+ */
+import type { AgentModel } from '../types';
+export interface NativeLoader {
+    loadNativeChunk(position: number): Promise<{
+        content: string;
+        eof: boolean;
+        position: number;
+    }>;
+}
+export interface StatefulReducerConfig {
+    /** Prompt for analyzing individual content chunks */
+    digestPrompt: string;
+    /** Prompt for synthesizing/fusing current analysis with previous results */
+    reducePrompt: string;
+    /** Modulo for reducing the digest */
+    reduceModulo?: number;
+}
+export interface StructuredOutputFormat {
+    /** Schema name for the structured output */
+    name: string;
+    /** JSON Schema definition */
+    schema: Record<string, any>;
+    /** Whether to enforce strict mode */
+    strict?: boolean;
+}
+export interface MapLLMReduceResult {
+    /** Accumulator - string for text mode, object for structured output */
+    acc: string | Record<string, any>;
+    continue?: boolean;
+    maxIterations?: boolean;
+    /** OpenAI structured output format configuration */
+    format?: StructuredOutputFormat;
+    /** Model configuration */
+    model?: AgentModel;
+    verbose?: boolean;
+    /** Processing metadata */
+    metadata?: {
+        iterations: number;
+        averageChunkSize: number;
+        /** Processing time in milliseconds */
+        processingTimeMs: number;
+    };
+}
+export interface ChunkStrategy {
+    type: 'lines' | 'pages' | 'paragraphs' | 'overlap';
+    size: number;
+    overlap?: number;
+}

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

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Types for the MapLLM reducer functionality
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,47 @@
+import { SimulatorConfig, SimulationOptions, SimulationResult } from './simulator.types';
+export declare class AgentSimulator {
+    private config;
+    private executor;
+    private lastExecution?;
+    constructor(config: SimulatorConfig);
+    /**
+     * Exécuter la simulation complète
+     *
+     * Format de la query passée à l'agent testé :
+     * - Message initial : réponse du simulateur après analyse du scenario
+     * - 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)
+     */
+    executeSimulation(options: SimulationOptions): Promise<SimulationResult>;
+    /**
+     * Compter les occurrences d'une action dans le dernier ExecutionResult
+     * @param name Nom exact de l'action (ex: 'lookupMfilesIntervenant', 'lookupKnowledge', 'sendInternalEmail')
+     * @returns { firstPos, count, total } où:
+     *  - firstPos: index de la première occurrence (ou -1 si absente)
+     *  - count: nombre d'occurrences de cette action
+     *  - total: nombre total d'actions du même type (fonction vs transfert)
+     */
+    executionActionCount(name: string): {
+        firstPos: number;
+        count: number;
+        total: number;
+    };
+    /**
+     * Fonction d'affichage pour les tests - n'altère pas la structure originale
+     * Crée une version simplifiée pour l'affichage avec juste les noms des actions
+     */
+    printSimulationResult(result: SimulationResult): {
+        summary: any;
+        execution: any;
+    };
+    private isSimulationComplete;
+    private parseSimulationResult;
+    private extractConversationalPart;
+    /**
+     * Générer le rapport final en cas de timeout
+     */
+    private generateTimeoutReport;
+}

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

@@ -0,0 +1,26 @@
+import { SimulatorConfig, ExecutionContext } from './simulator.types';
+export declare class AgentExecutor {
+    private config;
+    private simulatorAgent;
+    constructor(config: SimulatorConfig);
+    /**
+     * Initialiser les contextes agent et simulateur
+     */
+    initializeContexts(): Promise<ExecutionContext>;
+    /**
+     * ✅ Exécuter l'agent testé et retourner sa réponse (extraction de agent-vs-agent.ts)
+     */
+    executeAgent(context: ExecutionContext, query: string): Promise<string>;
+    /**
+     * ✅ Exécuter le simulateur et retourner sa réponse (extraction de client-simulator.ts)
+     */
+    executeSimulator(context: ExecutionContext, query: string): Promise<string>;
+    /**
+     * ✅ Récupérer le dernier message de l'agent testé (extraction de agent-vs-agent.ts ligne 168-191)
+     */
+    private getLastAgentMessage;
+    /**
+     * ✅ Récupérer le dernier message du simulateur (extraction de client-simulator.ts)
+     */
+    private getLastAssistantMessage;
+}