Source: backend/models/modelFolderSuggestion.js

  1. /**
  2.  * @fileoverview Diese Datei enthält die Implementierung einer Engine zur Ordner-Vorschlagserstellung.
  3.  * Sie ermöglicht die Berechnung von Ähnlichkeiten zwischen Dokument- und Ordner-Embeddings 
  4.  * und gibt passende Ordner-Vorschläge zurück.
  5.  * 
  6.  * @author Lennart, Luca
  7.  * Die Funktionen wurden mit Unterstützung von KI-Tools angepasst und optimiert.
  8.  * @module modelFolderSuggestion
  9.  */
  11. const { performance } = require('perf_hooks');
  12. const db = require('../../ConnectPostgres');
  13. const vectorOps = require('./modelVectorOperations');
  15. /**
  16.  * Eine Engine zur Berechnung von Ordner-Vorschlägen basierend auf Dokument-Embeddings.
  17.  * 
  18.  * @class FolderSuggestionEngine
  19.  * @property {number} similarityThreshold - Der Ähnlichkeitsschwellenwert für Vorschläge.
  20.  * @property {number} maxSuggestions - Maximale Anzahl an Ordner-Vorschlägen.
  21.  * @property {Map} similarityCache - Cache zur Speicherung berechneter Ähnlichkeiten.
  22.  * @property {Object} metrics - Statistik-Daten zur Performance-Messung.
  23.  */
  24. class FolderSuggestionEngine {
  25.     constructor(options = {}) {
  26.         this.similarityThreshold = options.similarityThreshold || 0.75;
  27.         this.maxSuggestions = options.maxSuggestions || 3;
  28.         this.similarityCache = new Map();
  30.         this.metrics = {
  31.             totalRequests: 0,
  32.             successfulRequests: 0,
  33.             failedRequests: 0,
  34.             averageResponseTime: 0,
  35.             lastError: null
  36.         };
  37.     }
  39.     /**
  40.      * Gibt eine Liste empfohlener Ordner für ein gegebenes Dokument-Embedding zurück.
  41.      * 
  42.      * @async
  43.      * @method getSuggestedFolders
  44.      * @memberof FolderSuggestionEngine
  45.      * @param {Object} params - Parameter-Objekt.
  46.      * @param {number[]} params.docEmbedding - Das Embedding des Dokuments.
  47.      * @param {number} params.userId - Die Benutzer-ID.
  48.      * @returns {Promise<Object>} Ein Objekt mit den empfohlenen Ordnern und der Verarbeitungszeit.
  49.      * @throws {Error} Falls die Vorschlagsberechnung fehlschlägt.
  50.      * @example
  51.      * const suggestions = await folderEngine.getSuggestedFolders({ docEmbedding, userId: 123 });
  52.      * console.log(suggestions);
  53.      */
  54.     async getSuggestedFolders({ docEmbedding, userId }) {
  55.         const startTime = performance.now();
  56.         this.metrics.totalRequests++;
  58.         const cacheKey = `folder_suggestions:${userId}:${this._hashEmbedding(docEmbedding)}`;
  60.         try {
  61.             if (this.similarityCache.has(cacheKey)) {
  62.                 return this.similarityCache.get(cacheKey);
  63.             }
  65.             const foldersData = await this._getFolderData(userId);
  67.             if (foldersData.rows.length === 0) {
  68.                 const result = {
  69.                     suggestedFolders: [],
  70.                     processingTime: performance.now() - startTime
  71.                 };
  72.                 this._cacheResult(cacheKey, result);
  73.                 return result;
  74.             }
  76.             const suggestions = await this._processSuggestions(
  77.                 docEmbedding,
  78.                 foldersData.rows
  79.             );
  81.             const result = {
  82.                 suggestedFolders: suggestions.slice(0, this.maxSuggestions),
  83.                 processingTime: performance.now() - startTime
  84.             };
  86.             this._cacheResult(cacheKey, result);
  88.             this.metrics.successfulRequests++;
  89.             this.metrics.averageResponseTime =
  90.                 (this.metrics.averageResponseTime * (this.metrics.successfulRequests - 1) +
  91.                     (performance.now() - startTime)) / this.metrics.successfulRequests;
  93.             return result;
  95.         } catch (error) {
  96.             this.metrics.failedRequests++;
  97.             this.metrics.lastError = error.message;
  98.             throw error;
  99.         }
  100.     }
  102.     /**
  103.      * Berechnet die Ähnlichkeit zwischen zwei Embeddings unter Verwendung vordefinierter Methoden.
  104.      * 
  105.      * @async
  106.      * @method _calculateSimilarity
  107.      * @memberof FolderSuggestionEngine
  108.      * @param {number[]} embedding1 - Erstes Embedding.
  109.      * @param {number[]} embedding2 - Zweites Embedding.
  110.      * @param {string} [cacheKey=null] - Optionaler Cache-Schlüssel für schnelleren Zugriff.
  111.      * @returns {Promise<number>} Der berechnete Ähnlichkeitswert zwischen 0 und 1.
  112.      */
  113.     async _calculateSimilarity(embedding1, embedding2, cacheKey = null) {
  114.         if (cacheKey && this.similarityCache.has(cacheKey)) {
  115.             return this.similarityCache.get(cacheKey);
  116.         }
  118.         try {
  119.             const similarity = vectorOps.calculateSimilarity(embedding1, embedding2);
  121.             if (cacheKey && similarity > this.similarityThreshold * 0.8) {
  122.                 this.similarityCache.set(cacheKey, similarity);
  123.             }
  125.             return similarity;
  126.         } catch (error) {
  127.             console.error('Error calculating similarity:', error);
  128.             return 0;
  129.         }
  130.     }
  132.     /**
  133.      * Verarbeitet die Ordner-Daten und berechnet passende Vorschläge basierend auf Ähnlichkeiten.
  134.      * 
  135.      * @async
  136.      * @method _processSuggestions
  137.      * @memberof FolderSuggestionEngine
  138.      * @param {number[]} docEmbedding - Das Embedding des Dokuments.
  139.      * @param {Array<Object>} folders - Liste der verfügbaren Ordner mit ihren Embeddings.
  140.      * @returns {Promise<Array<Object>>} Eine sortierte Liste der besten Ordner-Vorschläge.
  141.      */
  142.     async _processSuggestions(docEmbedding, folders) {
  143.         const suggestions = [];
  145.         try {
  146.             for (const folder of folders) {
  147.                 const similarity = await this._calculateSimilarity(
  148.                     docEmbedding,
  149.                     folder.embedding,
  150.                     folder.folder_id
  151.                 );
  153.                 // Remove the similarity threshold check to get all suggestions
  154.                 suggestions.push({
  155.                     folderId: folder.folder_id,
  156.                     folderName: folder.folder_name,
  157.                     similarity: parseFloat(similarity.toFixed(4)),
  158.                     fileCount: folder.file_count,
  159.                     parentId: folder.parent_folder_id,
  160.                     recentFiles: folder.recent_files,
  161.                     confidence: this._calculateConfidence(similarity, folder)
  162.                 });
  163.             }
  165.             // Nach Ähnlichkeit sortieren und die besten Vorschläge auswählen
  166.             return suggestions
  167.                 .sort((a, b) => b.similarity - a.similarity)
  168.                 .slice(0, this.maxSuggestions);  // immer maxSuggestions number of folders zurückgeben
  169.         } catch (error) {
  170.             console.error('Error processing suggestions:', error);
  171.             return [];
  172.         }
  173.     }
  175.     /**
  176.      * Ruft die verfügbaren Ordnerdaten für einen bestimmten Benutzer aus der Datenbank ab.
  177.      * 
  178.      * @async
  179.      * @method _getFolderData
  180.      * @memberof FolderSuggestionEngine
  181.      * @param {number} userId - Die Benutzer-ID.
  182.      * @returns {Promise<Object>} Ordnerdaten inklusive Embeddings, Datei-Anzahl und letzte Dateien.
  183.      */
  184.     async _getFolderData(userId) {
  185.         const query = `
  186.             WITH RankedFiles AS (
  187.                 SELECT 
  188.                     f.folder_id,
  189.                     f.folder_name,
  190.                     f.embedding,
  191.                     f.parent_folder_id,
  192.                     fl.file_name,
  193.                     ROW_NUMBER() OVER (PARTITION BY f.folder_id ORDER BY fl.created_at DESC) as rn
  194.                 FROM main.folders f
  195.                 LEFT JOIN main.files fl ON f.folder_id = fl.folder_id
  196.                 WHERE f.user_id = $1 
  197.                 AND f.embedding IS NOT NULL
  198.             )
  199.             SELECT 
  200.                 folder_id,
  201.                 folder_name,
  202.                 embedding,
  203.                 parent_folder_id,
  204.                 COUNT(file_name) as file_count,
  205.                 array_agg(
  206.                     CASE WHEN rn <= 5 THEN file_name ELSE NULL END
  207.                 ) FILTER (WHERE rn <= 5) as recent_files
  208.             FROM RankedFiles
  209.             GROUP BY folder_id, folder_name, embedding, parent_folder_id
  210.         `;
  212.         return await db.query(query, [userId]);
  213.     }
  215.     /**
  216.      * Berechnet einen Konfidenzwert für einen Ordner-Vorschlag basierend auf mehreren Faktoren.
  217.      * 
  218.      * @method _calculateConfidence
  219.      * @memberof FolderSuggestionEngine
  220.      * @param {number} similarity - Der berechnete Ähnlichkeitswert.
  221.      * @param {Object} folder - Das Ordner-Objekt mit Metadaten.
  222.      * @returns {number} Der berechnete Konfidenzwert (zwischen 0 und 1).
  223.      */
  224.     _calculateConfidence(similarity, folder) {
  225.         const baseFactor = 0.7;
  226.         const fileCountFactor = Math.min(folder.file_count / 10, 0.2);
  227.         const recentFilesFactor = folder.recent_files?.length ? 0.1 : 0;
  229.         return similarity;
  230.     }
  232.     /**
  233.  * Erstellt einen eindeutigen Hash-Wert für ein Embedding, um es im Cache zu speichern.
  234.  * 
  235.  * @method _hashEmbedding
  236.  * @memberof FolderSuggestionEngine
  237.  * @param {number[]} embedding - Das Embedding als Array von Zahlen.
  238.  * @returns {string} Ein Base64-gekürzter Hash-String.
  239.  */
  240.     _hashEmbedding(embedding) {
  241.         return Buffer.from(embedding.join(',')).toString('base64').slice(0, 10);
  242.     }
  244.     /**
  245.  * Speichert ein Ergebnis im Cache und entfernt alte Einträge, falls der Cache zu groß wird.
  246.  * 
  247.  * @method _cacheResult
  248.  * @memberof FolderSuggestionEngine
  249.  * @param {string} key - Der Cache-Schlüssel.
  250.  * @param {Object} value - Das zu speichernde Ergebnis.
  251.  */
  252.     _cacheResult(key, value) {
  253.         this.similarityCache.set(key, value);
  254.         if (this.similarityCache.size > 1000) {
  255.             const firstKey = this.similarityCache.keys().next().value;
  256.             this.similarityCache.delete(firstKey);
  257.         }
  258.     }
  259. }
  261. module.exports = new FolderSuggestionEngine({
  262.     similarityThreshold: 0.75,
  263.     maxSuggestions: 3
  264. });