agentic-api 2.0.31 → 2.0.491

package/dist/src/rag/embeddings.js

@@ -33,55 +33,15 @@ class Embeddings {
         }
     }
     /**
-     * Retourne le prochain ID documentaire stable et met à jour metadata.docLastID.
-     * Pré-conditions: this.mapping et this.metadata sont chargés.
+     * Extrait et sauvegarde les use cases d'un document
+     * Utilise la fonction standalone pour la compatibilité
+     *
+     * @param document Document parsé
+     * @returns Les queries extraites avec leur coût
+     * @deprecated Utiliser extractAndSaveDocumentUseCases de usecase.ts directement
      */
-    getNextID() {
-        // Si non initialisé, partir du plus grand ID du mapping
-        if (this.metadata.docLastID == null || this.metadata.docLastID <= 0) {
-            const maxFromMapping = Object.keys(this.mapping.mapping || {})
-                .map(k => parseInt(k, 10))
-                .filter(n => !isNaN(n))
-                .reduce((a, b) => Math.max(a, b), 999);
-            this.metadata.docLastID = maxFromMapping + 1;
-        }
-        else {
-            this.metadata.docLastID = this.metadata.docLastID + 1;
-        }
-        const next = this.metadata.docLastID;
-        this.saveMetadata(this.metadata);
-        return next;
-    }
-    /**
-     * Retourne l'ID documentaire pour un fichier. Si non trouvé, attribue un nouvel ID.
-     * Stratégie: utiliser le mapping id -> "filename#section-0".
-     */
-    getOrAssignDocumentID(file) {
-        const base = path_1.default.basename(file, path_1.default.extname(file));
-        // Chercher un ID existant dans le mapping (section-0 comme ancrage documentaire)
-        const found = Object.entries(this.mapping.mapping || {}).find(([id, ref]) => {
-            return typeof ref === 'string' && ref.startsWith(`${base}#section-0`);
-        });
-        if (found) {
-            return parseInt(found[0], 10);
-        }
-        // Sinon, générer un nouvel ID documentaire
-        return this.getNextID();
-    }
     async extractAndSaveDocumentUseCases(document) {
-        const { queries, cost } = await (0, usecase_1.extractDocumentUseCases)(document);
-        const filename = path_1.default.basename(document.filename, path_1.default.extname(document.filename));
-        const docQueries = {
-            type: 'use-cases',
-            version: this.config.version,
-            tag: this.config.tag,
-            source: document.filename,
-            file: (0, utils_1.toSlug)(filename) + '.json',
-            cost,
-            queries
-        };
-        (0, usecase_1.saveUseCases)(docQueries, this.config);
-        return docQueries;
+        return (0, usecase_1.extractAndSaveDocumentUseCases)(document, this.config.baseDir, this.config.version, this.config.tag);
     }
     /**
      * Charge les documents du RAG
@@ -102,6 +62,7 @@ class Embeddings {
             //   throw error;
             // }
             const content = (0, fs_1.readFileSync)(filePath, 'utf8');
+            // getSections() validera que l'ID est présent dans le matter
             const parsedDocument = (0, parser_1.getSections)(content, file);
             return parsedDocument;
         }
@@ -117,7 +78,7 @@ class Embeddings {
      */
     async loadDocumentUseCases(document) {
         const filename = path_1.default.basename(document.filename, path_1.default.extname(document.filename));
-        return (0, usecase_1.loadUseCases)((0, utils_1.toSlug)(filename) + '.json', this.config);
+        return (0, usecase_1.loadUseCases)((0, utils_1.toSlug)(filename) + '.query.json', this.config);
     }
     async listDocumentsOnRAG() {
         const filesWithSection = Object.values(this.mapping?.mapping || {});
@@ -204,6 +165,81 @@ class Embeddings {
         }
         return this.vectorsIndex !== null && this.metadata !== null && this.mapping !== null;
     }
+    /**
+     * Met à jour l'embedding avec une nouvelle configuration
+     * Recharge l'index, les métadonnées et le mapping depuis les nouveaux fichiers
+     *
+     * Cette méthode est appelée par RAGManager.notifyUpdate() quand un RAG est modifié
+     *
+     * FIXME: Gérer le cas où l'embedding est en cours d'exécution (recherche/indexation)
+     * Actuellement, l'update est appliqué immédiatement sans vérifier si l'embedding est busy.
+     * Solutions possibles:
+     * - Ajouter un flag `isBusy` pour bloquer les updates pendant une recherche
+     * - Implémenter une queue d'updates avec retry
+     * - Utiliser un système de locks/mutex
+     *
+     * @param newConfig Nouvelle configuration RAG
+     *
+     * @example
+     * ```typescript
+     * // Appelé automatiquement par RAGManager après un build ou rename
+     * embedding.update(newConfig);
+     * ```
+     */
+    update(newConfig) {
+        // Sauvegarder l'ancienne config pour rollback en cas d'erreur
+        const oldConfig = this.config;
+        const oldVectorsFile = this.vectorsFile;
+        console.log(`\n   🔧 Embeddings.update() appelé`);
+        console.log(`      Ancien baseDir: ${oldConfig.baseDir}`);
+        console.log(`      Nouveau baseDir: ${newConfig.baseDir}`);
+        try {
+            // Mettre à jour la configuration
+            this.config = newConfig;
+            this.vectorsFile = path_1.default.join(newConfig.baseDir, types_1.RAG_FILES.VECTORS);
+            this.space = newConfig.dimensions || 1536;
+            this.distance = newConfig.distance || 'cosine';
+            console.log(`      Nouveau vectorsFile: ${this.vectorsFile}`);
+            console.log(`      Fichier existe: ${(0, fs_1.existsSync)(this.vectorsFile)}`);
+            // Recharger l'index si ce n'est pas en mode inmemory
+            if (!this.inmemory) {
+                // Vérifier que les fichiers existent
+                if (!(0, fs_1.existsSync)(this.vectorsFile)) {
+                    throw new Error(`Fichier d'index manquant: ${this.vectorsFile}`);
+                }
+                console.log(`      📥 Rechargement de l'index...`);
+                // Recharger l'index
+                this.loadIndex();
+                console.log(`      📥 Rechargement des métadonnées et mapping...`);
+                // Recharger les métadonnées et le mapping
+                this.loadMetadata();
+                this.loadMapping();
+                console.log(`      ✅ Embedding mis à jour avec nouvelle config: ${newConfig.baseDir}`);
+            }
+        }
+        catch (error) {
+            // Rollback en cas d'erreur
+            console.error('❌ Erreur lors de la mise à jour de l\'embedding, rollback:', error);
+            this.config = oldConfig;
+            this.vectorsFile = oldVectorsFile;
+            this.space = oldConfig.dimensions || 1536;
+            this.distance = oldConfig.distance || 'cosine';
+            // Essayer de recharger l'ancienne config
+            try {
+                if (!this.inmemory && (0, fs_1.existsSync)(this.vectorsFile)) {
+                    this.loadIndex();
+                    this.loadMetadata();
+                    this.loadMapping();
+                }
+            }
+            catch (rollbackError) {
+                console.error('❌ Erreur critique lors du rollback:', rollbackError);
+                // Réinitialiser complètement en dernier recours
+                this.resetKnn();
+            }
+            throw new Error(`Impossible de mettre à jour l'embedding: ${error}`);
+        }
+    }
     /**
      * Réinitialise l'index
      */
@@ -215,13 +251,18 @@ class Embeddings {
     /**
      * Crée un nouvel index HierarchicalNSW avec documents parsés
      * ou met à jour l'index existant avec de nouveaux documents
+     *
+     * @returns IndexBuildResult contenant les données nécessaires pour créer les métadonnées RAG
+     *
+     * Note: Cette méthode ne sauvegarde plus les métadonnées directement.
+     * RAGManager est responsable de créer et sauvegarder les métadonnées
+     * à partir du résultat retourné.
      */
     async indexFromDocuments(documents, options) {
         const ef = options?.ef || this.config.hnswConfig?.ef || 200;
         const m = options?.m || this.config.hnswConfig?.m || 32;
         const isUpdate = options?.update || false;
         const prepare = options?.prepare || ((input) => input);
-        let startId = this.config.startId || 1000;
         const openai = (0, utils_1.openaiInstance)();
         const vectors = {};
         const documentRefs = {};
@@ -230,19 +271,19 @@ class Embeddings {
         if (isUpdate && this.mapping && this.metadata) {
             Object.assign(documentRefs, this.mapping.mapping);
             Object.assign(documentReferences, this.metadata.documents);
-            // Trouver le prochain ID disponible
-            const existingIds = Object.keys(documentRefs).map(id => parseInt(id));
-            startId = existingIds.length ? Math.max(...existingIds) + 1 : startId;
         }
-        console.log(`Traitement de ${documents.length} documents...`);
+        if (this.debug)
+            console.log(`Traitement de ${documents.length} documents...`);
         for (const doc of documents) {
             const filename = path_1.default.basename(doc.filename, path_1.default.extname(doc.filename));
             process.stdout.write(`Traitement: ${filename}`);
-            const { sections } = doc;
+            const { sections, matter } = doc;
             if (!sections.length) {
                 console.log(`❌ Aucune section trouvée dans ${filename}`);
                 continue;
             }
+            // ID de base du document
+            const baseId = matter.id;
             // Traiter chaque section
             for (let index = 0; index < sections.length; index++) {
                 const section = sections[index];
@@ -250,10 +291,14 @@ class Embeddings {
                 if (!hasEnoughContent) {
                     continue;
                 }
+                // ✅ NOUVEAU: ID calculé = matter.id * 100 + sectionIndex
+                // Permet de supprimer facilement toutes les sections d'un document
+                // en recherchant les IDs entre (matter.id * 100) et (matter.id * 100 + 99)
+                // Limite: 100 sections par document (0-99)
+                const vectorId = baseId * 100 + index;
                 // Vérifier si cette section existe déjà (pour les mises à jour)
                 const ref = `${filename}#section-${index}`;
-                const existingId = Object.keys(documentRefs).find(id => documentRefs[id] === ref);
-                if (isUpdate && existingId) {
+                if (isUpdate && documentRefs[vectorId]) {
                     console.log(`Section ${ref} déjà indexée, ignorée`);
                     continue;
                 }
@@ -266,24 +311,19 @@ class Embeddings {
                 });
                 const normalizedVectors = (0, parser_1.l2Normalize)(embedding.data[0].embedding);
                 // Stocker avec le nouveau format d'ID
-                vectors[startId] = normalizedVectors;
-                documentRefs[startId] = ref;
+                vectors[vectorId] = normalizedVectors;
+                documentRefs[vectorId] = ref;
                 // Créer la référence de document
-                documentReferences[startId] = {
+                documentReferences[vectorId] = {
                     filename: filename + '.md',
                     sectionIndex: index,
                     ref,
                     title: section.title || `Section ${index}`,
                     content: section.content,
-                    metadata: doc.matter
+                    metadata: matter
                 };
-                startId++;
                 process.stdout.write(hasEnoughContent ? ':' : '.');
             }
-            //
-            // let enough room for new sections on future updates
-            const pad = 20 - sections.length;
-            startId += pad;
             console.log(' done');
         }
         // Créer ou mettre à jour l'index HierarchicalNSW
@@ -308,16 +348,13 @@ class Embeddings {
             }
         }
         else {
-            //
-            // FIXME this is not working, ids must be restored from de RAGMapping ids <=> documentRefs  
-            // Mettre à jour l'index existant
+            // Mettre à jour l'index existant avec de nouveaux vecteurs
             console.log(`Mise à jour de l'index avec ${newVectors.length} nouveaux vecteurs`);
-            const replaceDeleted = true;
             for (const item of newVectors) {
                 const id = parseInt(item);
-                // le point existant n’apparaît plus
-                this.vectorsIndex.markDelete(id);
-                this.vectorsIndex.addPoint(vectors[item], id, replaceDeleted);
+                // Pour les nouveaux vecteurs, on les ajoute simplement sans markDelete
+                // car ils n'existaient pas auparavant dans l'index
+                this.vectorsIndex.addPoint(vectors[item], id);
             }
         }
         // Sauvegarder l'index
@@ -328,26 +365,14 @@ class Embeddings {
         // Créer le tag de version
         const tag = this.config.tag || (0, types_1.generateVersionTag)();
         const version = this.config.version || '1.0';
-        // Créer et sauvegarder le mapping
-        const mapping = {
-            type: 'mapping',
-            version,
-            tag,
-            mapping: documentRefs,
-            createdAt: new Date().toISOString()
-        };
-        this.saveMapping(mapping);
-        // Créer et sauvegarder les métadonnées
-        const metadata = {
+        // ✅ Assigner les métadonnées en mémoire pour que les méthodes comme listDocumentsOnRAG() fonctionnent
+        // Même si on ne sauvegarde plus sur disque, les données doivent être en mémoire
+        this.metadata = {
             version,
             tag,
             createdAt: new Date().toISOString(),
             config: this.config,
             documents: documentReferences,
-            checkpoint: {
-                branch: options?.branch || '',
-                hash: options?.lastCommit || ''
-            },
             stats: {
                 totalDocuments: documents.length,
                 totalSections: totalVectors,
@@ -360,7 +385,22 @@ class Embeddings {
                 queriesFile: types_1.RAG_FILES.QUERIES
             }
         };
-        this.saveMetadata(metadata);
+        this.mapping = {
+            type: 'mapping',
+            version,
+            tag,
+            mapping: documentRefs,
+            createdAt: new Date().toISOString()
+        };
+        // ✅ Retourner les données pour que RAGManager gère les métadonnées sur disque
+        return {
+            totalVectors,
+            vectorDimensions: this.space,
+            documents: documentReferences,
+            mapping: documentRefs,
+            tag,
+            version
+        };
     }
     /**
      * Charge l'index HierarchicalNSW existant
@@ -414,46 +454,9 @@ class Embeddings {
             }
         }
     }
-    /**
-     * Sauvegarde les métadonnées dans rag-metadata.json
-     */
-    saveMetadata(metadata) {
-        // Toujours assigner les métadonnées en mémoire
-        this.metadata = metadata;
-        // En mode inmemory, on ne sauvegarde pas sur disque
-        if (this.inmemory)
-            return;
-        const metadataFile = path_1.default.join(this.config.baseDir, types_1.RAG_FILES.METADATA);
-        try {
-            (0, fs_1.writeFileSync)(metadataFile, JSON.stringify(metadata, null, 2), 'utf8');
-            if (this.debug) {
-                console.log('Métadonnées sauvegardées:', metadataFile);
-            }
-        }
-        catch (error) {
-            console.error('Erreur lors de la sauvegarde des métadonnées:', error);
-        }
-    }
-    /**
-     * Sauvegarde le mapping des IDs
-     */
-    saveMapping(mapping) {
-        // Toujours assigner le mapping en mémoire
-        this.mapping = mapping;
-        // En mode inmemory, on ne sauvegarde pas sur disque
-        if (this.inmemory)
-            return;
-        const mappingFile = path_1.default.join(this.config.baseDir, types_1.RAG_FILES.MAPPING);
-        try {
-            (0, fs_1.writeFileSync)(mappingFile, JSON.stringify(mapping, null, 2), 'utf8');
-            if (this.debug) {
-                console.log('Mapping sauvegardé:', mappingFile);
-            }
-        }
-        catch (error) {
-            console.error('Erreur lors de la sauvegarde du mapping:', error);
-        }
-    }
+    // ❌ SUPPRIMÉ : saveMetadata() et saveMapping()
+    // Ces méthodes ont été déplacées vers RAGManager pour une meilleure séparation des responsabilités
+    // RAGManager est maintenant responsable de la gestion complète du cycle de vie des métadonnées
     /**
      * Récupère un vecteur depuis l'index existant (pour les mises à jour)
      */

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

@@ -2,11 +2,11 @@ export * from './types';
 export * from './parser';
 export * from './embeddings';
 export * from './usecase';
+export * from './rag.manager';
+export * from './rag.examples';
+import { RAGConfig } from './types';
 /**
  * Configuration par défaut pour le RAG
  */
-/**
- * Gestionnaire RAG principal
- */
-export declare class RAGManager {
-}
+declare const DEFAULT_RAG_CONFIG: Partial<RAGConfig>;
+export { DEFAULT_RAG_CONFIG };

package/dist/src/rag/index.js

@@ -14,27 +14,24 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RAGManager = void 0;
+exports.DEFAULT_RAG_CONFIG = void 0;
 __exportStar(require("./types"), exports);
 __exportStar(require("./parser"), exports);
 __exportStar(require("./embeddings"), exports);
 __exportStar(require("./usecase"), exports);
+__exportStar(require("./rag.manager"), exports);
+__exportStar(require("./rag.examples"), exports);
 /**
  * Configuration par défaut pour le RAG
  */
-// const DEFAULT_RAG_CONFIG: Partial<RAGConfig> = {
-//   vectorsFile: 'hnsw-vectors',
-//   dimensions: 1536,
-//   distance: 'cosine',
-//   filterInput: '',
-//   hnswConfig: {
-//     ef: 200,
-//     m: 32
-//   }
-// };
-/**
- * Gestionnaire RAG principal
- */
-class RAGManager {
-}
-exports.RAGManager = RAGManager;
+const DEFAULT_RAG_CONFIG = {
+    dimensions: 1536,
+    distance: 'cosine',
+    version: '1.0',
+    startId: 1000,
+    hnswConfig: {
+        ef: 200,
+        m: 32
+    }
+};
+exports.DEFAULT_RAG_CONFIG = DEFAULT_RAG_CONFIG;

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

@@ -4,7 +4,8 @@ import { ParsedDocument, DocumentSection } from './types';
  *
  * @param content Contenu du document
  * @param filename Nom du fichier (pour le titre par défaut)
- * @returns Sections et header du document
+ * @returns Sections et header du document avec matter validé
+ * @throws Error si le matter est invalide après traitement
  */
 export declare function getSections(content: string, filename: string): ParsedDocument;
 /**

package/dist/src/rag/parser.js

@@ -12,6 +12,7 @@ exports.sectionParseValues = sectionParseValues;
 exports.sectionParseKey = sectionParseKey;
 exports.removeThinkingBlocks = removeThinkingBlocks;
 const fs_1 = require("fs");
+const types_1 = require("./types");
 const path_1 = __importDefault(require("path"));
 const rules_1 = require("../rules");
 /**
@@ -19,7 +20,8 @@ const rules_1 = require("../rules");
  *
  * @param content Contenu du document
  * @param filename Nom du fichier (pour le titre par défaut)
- * @returns Sections et header du document
+ * @returns Sections et header du document avec matter validé
+ * @throws Error si le matter est invalide après traitement
  */
 function getSections(content, filename) {
     // IMPORTANT: Cette fonction traite les fichiers transformés par RAGGenerator 
@@ -27,16 +29,8 @@ function getSections(content, filename) {
     // Vérifier si le contenu contient un front-matter, 
     // celui-ci contient le nom du fichier d'origine et le nom du service!
     let { matter, content: contentWithoutMatter } = (0, rules_1.matterParse)(content);
-    // imprimer une alarm
-    if (matter?.mergeBase && matter?.createdBy) {
-        console.log('🔔 No standard matter found in file:', matter);
-    }
-    // S'assurer que matter contient au minimum filename et title
-    matter = {
-        ...matter,
-        filename,
-        title: matter.title || filename // Utiliser le filename comme titre par défaut
-    };
+    // Valider le matter (throw si invalide)
+    (0, types_1.isValidRAGMatter)(matter);
     content = contentWithoutMatter || content;
     //
     // le contenu est toujours sans le front-matter!
@@ -58,8 +52,7 @@ function getSections(content, filename) {
         title: sectionParseKey('titre', content) || undefined
     }))
         .filter(section => section.lines > 2); // Filtrer les sections trop courtes
-    //
-    // le matter contient les informations du fichier d'origine! (service, responssable, fichier, etc.)
+    // Retourner le document parsé avec matter validé
     return {
         filename,
         sections,
@@ -84,7 +77,11 @@ const getDocumentBySection = (id, ids, prefix) => {
         throw new Error('Invalid document id :' + fullname);
     }
     const content = (0, fs_1.readFileSync)(path_1.default.join(prefix, filename), 'utf8');
-    const { sections } = getSections(content, filename);
+    const { sections, matter } = getSections(content, filename);
+    // Vérifier que l'ID du matter correspond à l'ID demandé
+    if (matter.id !== id) {
+        console.warn(`❌ Document ID mismatch: ${matter.title} - expected ${id}, got ${matter.id}`);
+    }
     if (!sections.length) {
         return {
             source: fullname,

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

@@ -0,0 +1,27 @@
+import { ParsedDocument, RAGConfig } from './types';
+import { RAGManager } from './rag.manager';
+/**
+ * Exemples d'utilisation du gestionnaire multi-RAG
+ */
+/**
+ * Construit un RAG spécifique avec des documents
+ */
+export declare function buildSpecificRAG(ragManager: RAGManager, ragName: string, documents: ParsedDocument[], ragConfig?: Partial<RAGConfig>): Promise<void>;
+/**
+ * Recherche dans un RAG spécifique
+ */
+export declare function searchInRAG(ragManager: RAGManager, ragName: string, query: string, options?: {
+    neighbors?: number;
+    debug?: boolean;
+}): Promise<any>;
+/**
+ * Recherche dans le RAG par défaut
+ */
+export declare function searchInDefaultRAG(ragManager: RAGManager, query: string, options?: {
+    neighbors?: number;
+    debug?: boolean;
+}): Promise<any>;
+/**
+ * Exemple d'utilisation complète
+ */
+export declare function exampleUsage(baseDir: string): Promise<void>;