agentic-api 2.0.31 → 2.0.491

package/dist/src/rag/rag.examples.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSpecificRAG = buildSpecificRAG;
+exports.searchInRAG = searchInRAG;
+exports.searchInDefaultRAG = searchInDefaultRAG;
+exports.exampleUsage = exampleUsage;
+const rag_manager_1 = require("./rag.manager");
+/**
+ * Exemples d'utilisation du gestionnaire multi-RAG
+ */
+/**
+ * Construit un RAG spécifique avec des documents
+ */
+async function buildSpecificRAG(ragManager, ragName, documents, ragConfig) {
+    console.log(`🔄 Construction du RAG: ${ragName}`);
+    try {
+        await ragManager.build(ragName, documents, ragConfig);
+        console.log(`✅ RAG '${ragName}' construit avec succès`);
+    }
+    catch (error) {
+        console.error(`❌ Erreur lors de la construction de '${ragName}':`, error);
+        throw error;
+    }
+}
+/**
+ * Recherche dans un RAG spécifique
+ */
+async function searchInRAG(ragManager, ragName, query, options = {}) {
+    try {
+        const embeddings = ragManager.load(ragName);
+        const results = await embeddings.semanticSearch(query, {
+            neighbors: options.neighbors || 5,
+            debug: options.debug || false
+        });
+        if (options.debug) {
+            console.log(`🔍 Recherche dans '${ragName}': ${results.results.length} résultats`);
+        }
+        return results;
+    }
+    catch (error) {
+        console.error(`❌ Erreur lors de la recherche dans '${ragName}':`, error);
+        throw error;
+    }
+}
+/**
+ * Recherche dans le RAG par défaut
+ */
+async function searchInDefaultRAG(ragManager, query, options = {}) {
+    const defaultRAG = ragManager.getDefault();
+    if (!defaultRAG) {
+        throw new Error('Aucun RAG par défaut défini');
+    }
+    return searchInRAG(ragManager, defaultRAG, query, options);
+}
+/**
+ * Exemple d'utilisation complète
+ */
+async function exampleUsage(baseDir) {
+    console.log('🚀 Exemple d\'utilisation du gestionnaire multi-RAG');
+    console.log(`📁 Répertoire de base: ${baseDir}`);
+    // Initialiser le gestionnaire
+    const ragManagerConfig = {
+        baseDir,
+        maxArchives: 5
+    };
+    const ragManager = rag_manager_1.RAGManager.get(ragManagerConfig);
+    // Créer quelques RAG par défaut
+    const defaultRAGs = [
+        {
+            name: 'procedures-stable',
+            config: {
+                baseDir: '',
+                dimensions: 1536,
+                distance: 'cosine',
+                version: '1.0',
+                hnswConfig: { ef: 200, m: 64 }
+            }
+        },
+        {
+            name: 'procedures-draft',
+            config: {
+                baseDir: '',
+                dimensions: 1536,
+                distance: 'cosine',
+                version: '1.0',
+                hnswConfig: { ef: 200, m: 32 }
+            }
+        }
+    ];
+    for (const rag of defaultRAGs) {
+        try {
+            ragManager.getStatus(rag.name);
+            console.log(`✅ RAG déjà existant: ${rag.name}`);
+        }
+        catch (error) {
+            // RAG n'existe pas, le créer
+            const tempPath = await ragManager.create(rag.name);
+            console.log(`✅ RAG créé: ${rag.name} (temp: ${tempPath})`);
+        }
+    }
+    // Définir 'procedures-stable' comme RAG par défaut
+    await ragManager.setDefault('procedures-stable');
+    // Lister les RAG disponibles
+    const rags = ragManager.list();
+    console.log(`📋 RAG disponibles: ${rags.map((r) => r.name).join(', ')}`);
+    // Obtenir les statistiques
+    const stats = ragManager.getStats();
+    console.log('📊 Statistiques des RAG:');
+    stats.forEach(stat => {
+        console.log(`  • ${stat.name}: ${stat.status} (${stat.isValid ? 'valide' : 'invalide'})`);
+        if (stat.metadata) {
+            console.log(`    - Sections: ${stat.metadata.totalSections}`);
+            console.log(`    - Dimensions: ${stat.metadata.vectorDimensions}`);
+            console.log(`    - Taille: ${stat.metadata.indexSize}`);
+        }
+        if (stat.error) {
+            console.log(`    - Erreur: ${stat.error}`);
+        }
+    });
+    // Exemple de recherche (nécessite des RAG construits)
+    try {
+        const results = await searchInDefaultRAG(ragManager, 'procédure de réparation', {
+            neighbors: 3,
+            debug: true
+        });
+        console.log(`🔍 Résultats de recherche: ${results.results.length} trouvés`);
+    }
+    catch (error) {
+        console.log('⚠️ Recherche impossible (RAG non construit):', error instanceof Error ? error.message : error);
+    }
+    // Exemple de recherche dans un RAG spécifique
+    const availableRAGs = rags.filter((r) => r.status === 'active');
+    if (availableRAGs.length > 0) {
+        const targetRAG = availableRAGs[0].name;
+        console.log(`🎯 Recherche dans '${targetRAG}': "maintenance"`);
+        try {
+            const results = await searchInRAG(ragManager, targetRAG, 'maintenance', {
+                neighbors: 2,
+                debug: true
+            });
+            console.log(`✅ ${results.results.length} résultats dans '${targetRAG}'`);
+        }
+        catch (error) {
+            console.log(`⚠️ Erreur: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    else {
+        console.log('⚠️ Aucun RAG actif disponible pour la recherche');
+    }
+    console.log('\n🎉 Exemple terminé !');
+}

package/dist/src/rag/rag.manager.d.ts

@@ -0,0 +1,383 @@
+import { RAGManagerConfig, RAGRegistryEntry, RAGConfig, ParsedDocument, DocumentQueries } from './types';
+import { Embeddings } from './embeddings';
+/**
+ * Gestionnaire multi-RAG stateless pour gérer plusieurs index RAG
+ */
+export declare class RAGManager {
+    private config;
+    private registryFile;
+    private cachedRegistry;
+    private lastLoadTime;
+    /**
+     * Map des embeddings chargés pour permettre les updates réactifs
+     * Note: Pour une meilleure gestion mémoire, appeler cleanDeadReferences() périodiquement
+     */
+    private loadedEmbeddings;
+    private constructor();
+    static get(config: RAGManagerConfig): RAGManager;
+    /**
+     * Nettoie le cache des instances (utile pour les tests)
+     */
+    static clearCache(): void;
+    /**
+     * Crée les dossiers nécessaires s'ils n'existent pas
+     */
+    private ensureDirectories;
+    /**
+     * Charge le registre depuis le fichier JSON et scan les dossiers
+     */
+    private loadRegistry;
+    /**
+     * Scanne les dossiers pour découvrir les RAG existants
+     */
+    private scanDirectoriesForRAGs;
+    /**
+     * Vérifie si un RAG existe dans le registre (peu importe son statut)
+     * Recherche par clé du dictionnaire OU par entry.name
+     */
+    exists(name: string): boolean;
+    /**
+     * Obtient le registre en cache ou le recharge si nécessaire
+     */
+    private getRegistry;
+    /**
+     * Sauvegarde le registre dans le fichier JSON
+     */
+    private saveRegistry;
+    /**
+     * Notifie les embeddings chargés de se mettre à jour
+     *
+     * @param name Nom du RAG à mettre à jour
+     * @param opts Options de mise à jour (action: 'rename' pour renommer un document)
+     *
+     * FIXME: Gérer le cas où l'embedding est en cours d'exécution (recherche/indexation)
+     * Actuellement, l'update est appelé immédiatement sans vérifier si l'embedding est busy.
+     * Solutions possibles:
+     * - Ajouter un flag `isBusy` dans Embeddings
+     * - Implémenter une queue d'updates
+     * - Utiliser un système de locks
+     *
+     * @example
+     * ```typescript
+     * // Après un build
+     * this.notifyUpdate('procedures-stable');
+     *
+     * // Après un rename de document
+     * this.notifyUpdate('procedures-stable', {
+     *   action: 'rename',
+     *   oldFile: 'old.md',
+     *   newFile: 'new.md'
+     * });
+     * ```
+     */
+    private notifyUpdate;
+    /**
+     * Génère un nom d'archive avec timestamp YYYMMDD
+     */
+    private generateArchiveName;
+    /**
+     * Archive un RAG existant
+     */
+    private archive;
+    /**
+     * Charge la configuration depuis le fichier metadata
+     */
+    private loadConfig;
+    /**
+     * Sauvegarde les métadonnées RAG dans un dossier
+     *
+     * @param dirPath Chemin du dossier où sauvegarder les métadonnées
+     * @param metadata Métadonnées complètes du RAG
+     * @private
+     */
+    private saveMetadata;
+    /**
+     * Sauvegarde le mapping RAG dans un dossier
+     *
+     * @param dirPath Chemin du dossier où sauvegarder le mapping
+     * @param mapping Mapping ID → ref des sections
+     * @param buildResult Résultat de la construction pour les métadonnées du mapping
+     * @private
+     */
+    private saveMapping;
+    /**
+     * Nettoie les anciennes archives d'un RAG
+     */
+    private cleanOldArchives;
+    /**
+     * Récupère l'entrée d'un RAG dans le registre
+     *
+     * @param name Nom du RAG
+     * @returns L'entrée du registre ou undefined si non trouvé
+     */
+    getEntry(name: string): RAGRegistryEntry | undefined;
+    /**
+     * Crée un nouveau RAG dans le registre et retourne le chemin temporaire
+     *
+     * Le registre stocke:
+     * - configPath: le tempPath (source de construction)
+     * - destDir: le chemin de destination finale
+     * - status: 'building'
+     * - description: label descriptif court (optionnel)
+     *
+     * Après build(), configPath sera remplacé par destDir et status = 'active'
+     *
+     * @param name Nom du RAG
+     * @param options Options de création
+     * @returns Chemin du dossier temporaire créé
+     *
+     * @example
+     * ```typescript
+     * // Création simple
+     * await ragManager.create('my-rag', { description: 'Mon RAG' });
+     *
+     * // Création avec fork
+     * await ragManager.create('child-rag', {
+     *   description: 'PR validation',
+     *   fork: 'parent-rag',
+     *   exclude: ['modif-1.md', 'modif-2.md']
+     * });
+     * ```
+     */
+    create(name: string, options?: string | {
+        description?: string;
+        fork?: string;
+        exclude?: string[];
+        checkpoint?: string;
+    }): Promise<string>;
+    /**
+     * Sauvegarde un document dans le dossier de construction d'un RAG
+     *
+     * Le registre est consulté pour trouver le dossier (configPath en mode building)
+     *
+     * @param name Nom du RAG
+     * @param filename Nom du fichier (ex: 'my-document.md')
+     * @param content Contenu markdown avec front-matter
+     *
+     * @example
+     * ```typescript
+     * await ragManager.create('my-rag');
+     * ragManager.addDocument('my-rag', 'procedure.md', markdownContent);
+     * ```
+     */
+    addDocument(name: string, filename: string, content: string): void;
+    /**
+     * Prépare un RAG enfant en copiant les documents d'un RAG parent
+     *
+     * Cette méthode fork un RAG existant en copiant tous ses documents:
+     * - `filename.md` - Fichier markdown original
+     * - `filename.md.sha` - Empreinte SHA du fichier original
+     * - `filename.enhanced.md` - Version enrichie (si disponible)
+     * - `filename.query.json` - Métadonnées et use cases (si disponible)
+     *
+     * Les fichiers d'index (vectors.dat, mapping.json, metadata.json) ne sont PAS copiés
+     * car ils seront reconstruits par build()
+     *
+     * @param fromRagName Nom du RAG parent
+     * @param toRagName Nom du RAG enfant (doit déjà exister via create())
+     * @param options Options de fork
+     * @returns Objet avec le nombre de documents et fichiers copiés
+     *
+     * @example
+     * ```typescript
+     * // Créer le RAG enfant
+     * await ragManager.create('rule-validation-1', 'PR validation');
+     *
+     * // Fork depuis le parent en excluant les fichiers modifiés
+     * const result = await ragManager.fork('rule-editor', 'rule-validation-1', {
+     *   exclude: ['modif-1.md', 'modif-2.md']
+     * });
+     * console.log(`✅ ${result.documents} documents copiés (${result.files} fichiers)`);
+     *
+     * // Ajouter les documents modifiés
+     * ragManager.addDocument('rule-validation-1', 'modif-1.md', newContent1);
+     * ragManager.addDocument('rule-validation-1', 'modif-2.md', newContent2);
+     *
+     * // Builder l'index
+     * await ragManager.build('rule-validation-1', allDocs);
+     * ```
+     */
+    fork(fromRagName: string, toRagName: string, options?: {
+        exclude?: string[];
+    }): {
+        documents: number;
+        files: number;
+    };
+    /**
+     * [USAGE INTERNE] Copie tous les documents d'un RAG parent vers un RAG destination
+     *
+     * Cette méthode copie tous les fichiers associés aux documents indexés:
+     * - `filename.md` - Fichier markdown original
+     * - `filename.md.sha` - Empreinte SHA du fichier original
+     * - `filename.enhanced.md` - Version enrichie (si disponible)
+     * - `filename.query.json` - Métadonnées et use cases (si disponible)
+     *
+     * @private
+     * @param fromRagName Nom du RAG source
+     * @param toRagName Nom du RAG destination
+     * @param excludes Liste des fichiers à ne PAS copier (ex: ['procedure-1.md', 'procedure-2.md'])
+     * @returns Objet avec le nombre de documents copiés et le nombre de fichiers copiés
+     */
+    private addDocumentFrom;
+    /**
+     * Compare le contenu d'un document avec celui stocké dans le RAG
+     *
+     * @param name Nom du RAG
+     * @param file Nom du fichier (ex: 'ppe-budget.md')
+     * @param content Contenu à comparer
+     * @returns true si identique, false sinon
+     */
+    documentEqual(name: string, file: string, content: string): boolean;
+    /**
+     * Charge les use cases d'un document depuis un RAG
+     *
+     * @param name Nom du RAG
+     * @param filename Nom du fichier de base (ex: 'procedure.md')
+     * @returns Les use cases du document
+     *
+     * @example
+     * ```typescript
+     * const queries = ragManager.loadUseCases('my-rag', 'procedure.md');
+     * console.log(`${queries.queries.length} use cases trouvés`);
+     * ```
+     */
+    loadUseCases(name: string, filename: string): DocumentQueries;
+    /**
+     * Construit un RAG de manière atomique
+     *
+     * Utilise le registre pour trouver le dossier de construction (configPath)
+     * et la destination finale (destDir)
+     *
+     * @param name Nom du RAG
+     * @param documents Documents parsés (optionnel, sinon charge depuis configPath)
+     * @param ragConfig Configuration optionnelle du RAG
+     */
+    build(name: string, documents?: ParsedDocument[], ragConfig?: Partial<RAGConfig>): Promise<void>;
+    /**
+     * Charge tous les documents depuis un dossier
+     * Version interne qui prend un chemin direct
+     *
+     * @param baseDir Chemin du dossier
+     * @param endsWith Extension des fichiers à charger
+     * @returns Liste des documents parsés et validés
+     */
+    private _loadDocumentsFromPath;
+    /**
+     * Charge tous les documents depuis un dossier du RAG
+     * Version publique qui utilise le nom du RAG
+     *
+     * @param name Nom du RAG
+     * @param endsWith Extension des fichiers à charger (par défaut '.enhanced.md')
+     * @returns Liste des documents parsés et validés
+     */
+    private loadDocumentsFromDir;
+    /**
+     * Supprime un RAG du registre
+     */
+    delete(name: string, archiveFlag?: boolean): Promise<void>;
+    /**
+     * Renomme un document dans un RAG existant
+     *
+     * Cette méthode renomme tous les fichiers associés à un document:
+     * - `oldFile.md` → `newFile.md`
+     * - `oldFile.md.sha` → `newFile.md.sha`
+     * - `oldFile.enhanced.md` → `newFile.enhanced.md`
+     * - `oldFile.query.json` → `newFile.query.json`
+     *
+     * Et met à jour les références dans les fichiers JSON (mapping, metadata, queries)
+     *
+     * @param ragName Nom du RAG concerné
+     * @param oldFile Ancien nom du fichier (ex: 'old-name.md')
+     * @param newFile Nouveau nom du fichier (ex: 'new-name.md')
+     *
+     * @example
+     * ```typescript
+     * ragManager.renameDocument('rule-validation-1', 'old-procedure.md', 'new-procedure.md');
+     * ```
+     */
+    renameDocument(ragName: string, oldFile: string, newFile: string): void;
+    /**
+     * Met à jour les références d'un fichier dans les JSON du RAG
+     *
+     * @param configPath Chemin du RAG
+     * @param oldFile Ancien nom du fichier
+     * @param newFile Nouveau nom du fichier
+     * @private
+     */
+    private updateJSONReferences;
+    /**
+     * Renomme un RAG existant
+     *
+     * @param from Nom actuel du RAG
+     * @param to Nouveau nom du RAG
+     * @param description Description optionnelle du RAG
+     * @throws Error si le nom est trop court, si une collision existe, ou si le RAG source n'existe pas
+     *
+     * @example
+     * ```typescript
+     * await ragManager.rename('old-name', 'new-name', 'Description mise à jour');
+     * ```
+     */
+    rename(from: string, to: string, description?: string): Promise<void>;
+    /**
+     * Met à jour le statut d'un RAG
+     *
+     * @param name Nom du RAG
+     * @param status Nouveau statut ('active' ou 'paused')
+     * @throws Error si le RAG n'existe pas ou si le statut est invalide
+     *
+     * @example
+     * ```typescript
+     * ragManager.updateStatus('knowledge', 'paused');
+     * ```
+     */
+    pause(name: string): void;
+    unpause(name: string): void;
+    /**
+     * Nettoie les embeddings chargés obsolètes (plus vieux que maxAge)
+     * Utile pour libérer de la mémoire
+     *
+     * @param maxAge Âge maximum en millisecondes (défaut: 1 heure)
+     */
+    cleanDeadReferences(maxAge?: number): void;
+    /**
+     * Obtient le nombre d'embeddings actuellement chargés
+     */
+    getLoadedCount(): number;
+    /**
+     * Charge un RAG par son nom et l'enregistre pour les updates réactifs
+     *
+     * Permet le chargement si:
+     * - Statut = 'active' : RAG complètement prêt
+     * - Statut = 'building' : RAG en construction mais déjà utilisable (recherche partielle)
+     */
+    load(name: string): Embeddings;
+    /**
+     * Vérifie l'état d'un RAG
+     */
+    verify(name: string): boolean;
+    /**
+     * Liste tous les RAG disponibles
+     */
+    list(): RAGRegistryEntry[];
+    /**
+     * Obtient le statut d'un RAG
+     */
+    getStatus(name: string): RAGRegistryEntry;
+    /**
+     * Obtient la configuration d'un RAG depuis son metadata
+     */
+    getConfig(name: string): RAGConfig;
+    /**
+     * Définit le RAG par défaut
+     */
+    setDefault(name: string): Promise<void>;
+    /**
+     * Obtient le RAG par défaut
+     */
+    getDefault(): string;
+    /**
+     * Obtient les statistiques de tous les RAG
+     */
+    getStats(): any[];
+}