agentic-api 1.0.6 → 2.0.31

package/dist/src/rag/embeddings.js

@@ -0,0 +1,466 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Embeddings = void 0;
+const hnswlib_node_1 = require("hnswlib-node");
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const types_1 = require("./types");
+const parser_1 = require("./parser");
+const utils_1 = require("../utils");
+const usecase_1 = require("./usecase");
+class Embeddings {
+    constructor(config) {
+        this.vectorsIndex = null;
+        this.metadata = null;
+        this.mapping = null;
+        this.config = config;
+        this.vectorsFile = path_1.default.join(config.baseDir, types_1.RAG_FILES.VECTORS);
+        this.space = config.dimensions || 1536;
+        this.distance = config.distance || 'cosine';
+        this.inmemory = config.inmemory || false;
+        this.debug = false;
+        // Charger l'index existant si disponible et pas en mode inmemory
+        if (!this.inmemory && (0, fs_1.existsSync)(this.vectorsFile)) {
+            this.loadIndex();
+        }
+        // Charger les métadonnées et mapping si disponibles
+        if (!this.inmemory) {
+            this.loadMetadata();
+            this.loadMapping();
+        }
+    }
+    /**
+     * Retourne le prochain ID documentaire stable et met à jour metadata.docLastID.
+     * Pré-conditions: this.mapping et this.metadata sont chargés.
+     */
+    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;
+    }
+    /**
+     * Charge les documents du RAG
+     * IMPORTANT: C'est le document produit pour le RAG, ce n'est pas le document source!
+     * @param file Le fichier à charger depuis git
+     */
+    async loadDocumentOnRAG(file) {
+        try {
+            // The document is always in the baseDir!
+            const filePath = path_1.default.join(this.config.baseDir, file);
+            // ✅ FIX: Vérifier l'existence du fichier avant de le lire
+            // if (!existsSync(filePath)) {
+            //   const error = new Error(`ENOENT: no such file or directory, open '${filePath}'`);
+            //   (error as any).code = 'ENOENT';
+            //   (error as any).errno = -2;
+            //   (error as any).syscall = 'open';
+            //   (error as any).path = filePath;
+            //   throw error;
+            // }
+            const content = (0, fs_1.readFileSync)(filePath, 'utf8');
+            const parsedDocument = (0, parser_1.getSections)(content, file);
+            return parsedDocument;
+        }
+        catch (error) {
+            console.error('Erreur lors du chargement du document:', error);
+            throw error;
+        }
+    }
+    /**
+     * Charge les use cases d'un document
+     * @param document Le document de référence pour le RAG `loadDocumentOnRAG(file)`
+     * @returns Les use cases du document
+     */
+    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);
+    }
+    async listDocumentsOnRAG() {
+        const filesWithSection = Object.values(this.mapping?.mapping || {});
+        const files = new Set(filesWithSection.map(f => f.replace(/#.*$/, '')));
+        return Array.from(files).map(filename => filename.endsWith('.md') ? filename : filename + '.md');
+    }
+    /**
+     * Recherche par similarité dans l'index
+     */
+    searchKnn(vectors, options = {}) {
+        const startTime = Date.now();
+        const { neighbors = 5, ef = 250 } = options;
+        if (!this.vectorsIndex) {
+            return {
+                results: [],
+                searchTime: Date.now() - startTime
+            };
+        }
+        // Configurer ef pour la recherche
+        this.vectorsIndex.setEf(ef);
+        const result = this.vectorsIndex.searchKnn(vectors, neighbors);
+        if (!result || !result.neighbors || !result.neighbors.length) {
+            return {
+                results: [],
+                searchTime: Date.now() - startTime
+            };
+        }
+        const ids = result.neighbors;
+        const scores = result.distances.map(s => parseFloat((1 - s).toFixed(3)));
+        if (this.debug) {
+            console.log('Scores de recherche KNN:', scores);
+        }
+        const results = ids.map((id, idx) => {
+            const ref = this.mapping?.mapping[id.toString()] || '';
+            const docRef = this.metadata?.documents[id.toString()];
+            return {
+                id,
+                ref,
+                score: scores[idx],
+                content: docRef?.content || ''
+            };
+        }).filter(r => r.ref && r.content);
+        return {
+            results,
+            searchTime: Date.now() - startTime
+        };
+    }
+    /**
+     * Recherche sémantique avec OpenAI
+     */
+    async semanticSearch(question, options = {}) {
+        const startTime = Date.now();
+        const openai = (0, utils_1.openaiInstance)();
+        // Créer l'embedding de la question
+        const embedding = await openai.embeddings.create({
+            model: 'text-embedding-3-small',
+            input: question,
+            dimensions: this.space,
+            encoding_format: 'float',
+        });
+        const queryVector = (0, parser_1.l2Normalize)(embedding.data[0].embedding);
+        // Rechercher dans l'index
+        const result = this.searchKnn(queryVector, options);
+        // Mettre à jour le temps total (incluant l'appel OpenAI)
+        result.searchTime = Date.now() - startTime;
+        return result;
+    }
+    /**
+     * Obtient les métadonnées du RAG
+     * @returns Les métadonnées du RAG
+     */
+    getMetadata() {
+        return this.metadata;
+    }
+    getMapping() {
+        return this.mapping;
+    }
+    /**
+     * Vérifie si l'index est prêt
+     */
+    isReady() {
+        if (this.inmemory) {
+            return this.vectorsIndex !== null;
+        }
+        return this.vectorsIndex !== null && this.metadata !== null && this.mapping !== null;
+    }
+    /**
+     * Réinitialise l'index
+     */
+    resetKnn() {
+        this.vectorsIndex = new hnswlib_node_1.HierarchicalNSW(this.distance, this.space);
+        this.metadata = null;
+        this.mapping = null;
+    }
+    /**
+     * Crée un nouvel index HierarchicalNSW avec documents parsés
+     * ou met à jour l'index existant avec de nouveaux documents
+     */
+    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 = {};
+        const documentReferences = {};
+        // Si c'est une mise à jour, charger l'état existant
+        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...`);
+        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;
+            if (!sections.length) {
+                console.log(`❌ Aucune section trouvée dans ${filename}`);
+                continue;
+            }
+            // Traiter chaque section
+            for (let index = 0; index < sections.length; index++) {
+                const section = sections[index];
+                const hasEnoughContent = section.lines > 2;
+                if (!hasEnoughContent) {
+                    continue;
+                }
+                // 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) {
+                    console.log(`Section ${ref} déjà indexée, ignorée`);
+                    continue;
+                }
+                // Créer l'embedding de la section
+                const embedding = await openai.embeddings.create({
+                    model: "text-embedding-3-small",
+                    input: prepare(section.content),
+                    dimensions: this.space,
+                    encoding_format: "float",
+                });
+                const normalizedVectors = (0, parser_1.l2Normalize)(embedding.data[0].embedding);
+                // Stocker avec le nouveau format d'ID
+                vectors[startId] = normalizedVectors;
+                documentRefs[startId] = ref;
+                // Créer la référence de document
+                documentReferences[startId] = {
+                    filename: filename + '.md',
+                    sectionIndex: index,
+                    ref,
+                    title: section.title || `Section ${index}`,
+                    content: section.content,
+                    metadata: doc.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
+        const newVectors = Object.keys(vectors).filter(id => vectors[id]);
+        const totalVectors = Object.keys(documentRefs).length;
+        if (newVectors.length === 0 && !isUpdate) {
+            throw new Error('Aucun vecteur à indexer');
+        }
+        if (!this.vectorsIndex || !isUpdate) {
+            // Créer un nouvel index
+            const allowReplaceDeleted = true;
+            this.vectorsIndex = new hnswlib_node_1.HierarchicalNSW(this.distance, this.space);
+            console.log(`Initialisation de l'index pour ${totalVectors} entrées (ef:${ef}, m:${m})`);
+            this.vectorsIndex.initIndex(totalVectors + 100, m, ef, 0, allowReplaceDeleted);
+            // Ajouter tous les vecteurs
+            for (const item of Object.keys(documentRefs)) {
+                const id = parseInt(item);
+                const vector = vectors[item] || this.getVectorFromExistingIndex(id);
+                if (vector) {
+                    this.vectorsIndex.addPoint(vector, id);
+                }
+            }
+        }
+        else {
+            //
+            // FIXME this is not working, ids must be restored from de RAGMapping ids <=> documentRefs  
+            // Mettre à jour l'index existant
+            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);
+            }
+        }
+        // Sauvegarder l'index
+        if (!this.inmemory) {
+            this.vectorsIndex.writeIndexSync(this.vectorsFile);
+            console.log('Index sauvegardé:', this.vectorsFile);
+        }
+        // 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 = {
+            version,
+            tag,
+            createdAt: new Date().toISOString(),
+            config: this.config,
+            documents: documentReferences,
+            checkpoint: {
+                branch: options?.branch || '',
+                hash: options?.lastCommit || ''
+            },
+            stats: {
+                totalDocuments: documents.length,
+                totalSections: totalVectors,
+                vectorDimensions: this.space,
+                indexSize: `${Math.round(totalVectors * this.space * 4 / 1024 / 1024)}MB`
+            },
+            files: {
+                vectorsFile: types_1.RAG_FILES.VECTORS,
+                mappingFile: types_1.RAG_FILES.MAPPING,
+                queriesFile: types_1.RAG_FILES.QUERIES
+            }
+        };
+        this.saveMetadata(metadata);
+    }
+    /**
+     * Charge l'index HierarchicalNSW existant
+     */
+    loadIndex() {
+        try {
+            this.vectorsIndex = new hnswlib_node_1.HierarchicalNSW(this.distance, this.space);
+            this.vectorsIndex.readIndexSync(this.vectorsFile);
+            if (this.debug) {
+                console.log('Index HierarchicalNSW chargé:', this.vectorsFile);
+            }
+        }
+        catch (error) {
+            console.error('Erreur lors du chargement de l\'index:', error);
+            this.vectorsIndex = null;
+        }
+    }
+    /**
+     * Charge les métadonnées du fichier rag-metadata.json
+     */
+    loadMetadata() {
+        const metadataFile = path_1.default.join(this.config.baseDir, types_1.RAG_FILES.METADATA);
+        if ((0, fs_1.existsSync)(metadataFile)) {
+            try {
+                this.metadata = JSON.parse((0, fs_1.readFileSync)(metadataFile, 'utf8'));
+                if (this.debug) {
+                    console.log('Métadonnées RAG chargées:', metadataFile);
+                }
+            }
+            catch (error) {
+                console.error('Erreur lors du chargement des métadonnées:', error);
+                throw error;
+            }
+        }
+    }
+    /**
+     * Charge le mapping des IDs
+     */
+    loadMapping() {
+        const mappingFile = path_1.default.join(this.config.baseDir, types_1.RAG_FILES.MAPPING);
+        if ((0, fs_1.existsSync)(mappingFile)) {
+            try {
+                this.mapping = JSON.parse((0, fs_1.readFileSync)(mappingFile, 'utf8'));
+                if (this.debug) {
+                    console.log('Mapping RAG chargé:', mappingFile);
+                }
+            }
+            catch (error) {
+                console.error('Erreur lors du chargement du mapping:', error);
+                throw error;
+            }
+        }
+    }
+    /**
+     * 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);
+        }
+    }
+    /**
+     * Récupère un vecteur depuis l'index existant (pour les mises à jour)
+     */
+    getVectorFromExistingIndex(id) {
+        // Cette méthode devrait être implémentée si hnswlib-node le permet
+        // Pour l'instant, on retourne null
+        return null;
+    }
+}
+exports.Embeddings = Embeddings;

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

@@ -0,0 +1,12 @@
+export * from './types';
+export * from './parser';
+export * from './embeddings';
+export * from './usecase';
+/**
+ * Configuration par défaut pour le RAG
+ */
+/**
+ * Gestionnaire RAG principal
+ */
+export declare class RAGManager {
+}

package/dist/src/rag/index.js

@@ -0,0 +1,40 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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;
+__exportStar(require("./types"), exports);
+__exportStar(require("./parser"), exports);
+__exportStar(require("./embeddings"), exports);
+__exportStar(require("./usecase"), 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;

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

@@ -0,0 +1,45 @@
+type LuceneConfig = any;
+export interface LuceneIndexDocument {
+    id: string;
+    query: string;
+    service: string;
+    filename: string;
+}
+export declare class LuceneManager {
+    private miniSearch;
+    private config;
+    private indexFile;
+    constructor(config: LuceneConfig, baseDir: string);
+    /**
+     * Traitement des termes pour la recherche
+     */
+    private processTerm;
+    /**
+     * Charge un index existant
+     */
+    private loadIndex;
+    /**
+     * Construit l'index Lucene à partir des fichiers de requêtes
+     */
+    buildIndex(queriesDir?: string): Promise<void>;
+    /**
+     * Sauvegarde l'index
+     */
+    private saveIndex;
+    /**
+     * Recherche dans l'index Lucene
+     */
+    /**
+     * Obtient les statistiques de l'index
+     */
+    getStats(): {
+        totalDocuments: number;
+        totalServices: number;
+        indexSize: string;
+    };
+    /**
+     * Vérifie si l'index est prêt
+     */
+    isReady(): boolean;
+}
+export {};