agentdb 3.0.0-alpha.11 → 3.0.0-alpha.13

package/dist/src/services/GNNService.js

@@ -1,639 +0,0 @@
-/**
- * GNNService - Graph Neural Network Integration
- *
- * Provides high-level GNN capabilities on top of @ruvector/gnn:
- * - Semantic intent classification
- * - Graph-based skill recommendations
- * - Code pattern similarity via graph embeddings
- *
- * Tries native @ruvector/gnn first (NAPI-RS), falls back to JS.
- * All public methods are safe to call regardless of engine availability.
- *
- * Performance targets (ADR-062):
- * - 100x-50000x speedup when native @ruvector/gnn is available
- * - Zero-overhead JS fallback when native is not present
- */
-export class GNNService {
-    gnn = null;
-    engineType = 'js';
-    initialized = false;
-    config;
-    constructor(config) {
-        // Default to 8 heads (128 % 8 = 0, valid for MultiHeadAttention)
-        const heads = config?.heads ?? config?.layers ?? 8;
-        this.config = {
-            inputDim: config?.inputDim ?? 384,
-            hiddenDim: config?.hiddenDim ?? 128,
-            outputDim: config?.outputDim ?? 64,
-            heads,
-        };
-    }
-    /**
-     * Initialize the GNN engine.
-     *
-     * Attempts to load @ruvector/gnn and create a GNN layer.
-     * Falls back to JS-based heuristics if unavailable.
-     */
-    async initialize() {
-        if (this.initialized)
-            return;
-        try {
-            const mod = await import('@ruvector/gnn');
-            const RuvectorLayer = mod.RuvectorLayer ||
-                mod.default?.RuvectorLayer ||
-                mod.GNN ||
-                mod.default?.GNN;
-            if (RuvectorLayer) {
-                // @ruvector/gnn@0.1.25+ uses Result-based constructors
-                // RuvectorLayer(inputDim, hiddenDim, numHeads, dropout)
-                // numHeads must divide hiddenDim evenly (e.g., 128 % 8 = 0)
-                // Validate head count before calling native constructor
-                if (this.config.hiddenDim % this.config.heads !== 0) {
-                    const validHeads = [];
-                    for (let h = 1; h <= this.config.hiddenDim; h *= 2) {
-                        if (this.config.hiddenDim % h === 0)
-                            validHeads.push(h);
-                    }
-                    throw new Error(`Invalid head count: ${this.config.heads}. ` +
-                        `hiddenDim (${this.config.hiddenDim}) must be divisible by heads. ` +
-                        `Valid options: [${validHeads.join(', ')}]`);
-                }
-                try {
-                    this.gnn = new RuvectorLayer(this.config.inputDim, this.config.hiddenDim, this.config.heads, // FIXED: Use heads parameter (not layers)
-                    0.1 // dropout
-                    );
-                    this.engineType = 'native';
-                    this.initialized = true;
-                    console.log(`[GNNService] Using native @ruvector/gnn (v0.1.25+) with ${this.config.heads} heads`);
-                    return;
-                }
-                catch (constructorError) {
-                    // @ruvector/gnn@0.1.25+ throws errors instead of panicking
-                    const errMsg = constructorError instanceof Error
-                        ? constructorError.message
-                        : String(constructorError);
-                    console.warn(`[GNNService] Native GNN constructor failed: ${errMsg}`);
-                    console.warn('[GNNService] Falling back to JS implementation');
-                }
-            }
-        }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            console.warn(`[GNNService] Native GNN not available: ${msg}`);
-        }
-        this.engineType = 'js';
-        this.initialized = true;
-        console.log('[GNNService] Using JS fallback');
-    }
-    /**
-     * Semantic intent classification.
-     *
-     * When native GNN is available, runs a forward pass on the embedding
-     * and maps logits to intent categories. Otherwise uses keyword matching.
-     */
-    async classifyIntent(query, embedding) {
-        if (!this.initialized)
-            await this.initialize();
-        const intents = ['search', 'create', 'update', 'delete', 'analyze'];
-        if (this.engineType === 'native' && this.gnn) {
-            try {
-                const logits = typeof this.gnn.forward === 'function'
-                    ? this.gnn.forward(embedding, [], [])
-                    : null;
-                if (logits && logits.length >= intents.length) {
-                    const logitArray = logits instanceof Float32Array
-                        ? Array.from(logits)
-                        : logits;
-                    // Softmax over intent logits
-                    const expLogits = logitArray.slice(0, intents.length).map((l) => Math.exp(l));
-                    const expSum = expLogits.reduce((s, v) => s + v, 1e-10);
-                    const probs = expLogits.map((e) => e / expSum);
-                    let maxIdx = 0;
-                    for (let i = 1; i < probs.length; i++) {
-                        if (probs[i] > probs[maxIdx])
-                            maxIdx = i;
-                    }
-                    return {
-                        intent: intents[maxIdx],
-                        confidence: probs[maxIdx],
-                        logits: logitArray,
-                    };
-                }
-            }
-            catch {
-                // Fall through to JS
-            }
-        }
-        // JS fallback: keyword matching
-        const queryLower = query.toLowerCase();
-        if (queryLower.includes('search') || queryLower.includes('find') || queryLower.includes('lookup')) {
-            return { intent: 'search', confidence: 0.8 };
-        }
-        if (queryLower.includes('create') || queryLower.includes('add') || queryLower.includes('new')) {
-            return { intent: 'create', confidence: 0.8 };
-        }
-        if (queryLower.includes('update') || queryLower.includes('edit') || queryLower.includes('modify')) {
-            return { intent: 'update', confidence: 0.8 };
-        }
-        if (queryLower.includes('delete') || queryLower.includes('remove') || queryLower.includes('drop')) {
-            return { intent: 'delete', confidence: 0.8 };
-        }
-        if (queryLower.includes('analyze') || queryLower.includes('report') || queryLower.includes('summary')) {
-            return { intent: 'analyze', confidence: 0.8 };
-        }
-        return { intent: 'search', confidence: 0.5 };
-    }
-    /**
-     * Graph-based skill recommendations.
-     *
-     * Uses GNN node classification when available, otherwise
-     * returns adjacent skills from the skill graph map.
-     */
-    async recommendSkills(currentSkill, skillGraph) {
-        if (!this.initialized)
-            await this.initialize();
-        if (this.engineType === 'native' && this.gnn) {
-            try {
-                // Build adjacency from skill graph for GNN
-                const skills = Object.keys(skillGraph);
-                const idx = skills.indexOf(currentSkill);
-                if (idx >= 0 && typeof this.gnn.forward === 'function') {
-                    // Create a simple embedding from the skill index
-                    const skillEmbed = new Float32Array(this.config.inputDim);
-                    skillEmbed[idx % this.config.inputDim] = 1.0;
-                    const neighborEmbeds = [];
-                    const weights = [];
-                    const neighbors = skillGraph[currentSkill] || [];
-                    for (const neighbor of neighbors) {
-                        const nIdx = skills.indexOf(neighbor);
-                        if (nIdx >= 0) {
-                            const nEmbed = new Float32Array(this.config.inputDim);
-                            nEmbed[nIdx % this.config.inputDim] = 1.0;
-                            neighborEmbeds.push(nEmbed);
-                            weights.push(1.0);
-                        }
-                    }
-                    if (neighborEmbeds.length > 0) {
-                        const enhanced = this.gnn.forward(skillEmbed, neighborEmbeds, weights);
-                        if (enhanced) {
-                            // Use enhanced embedding to rank skills by similarity
-                            const ranked = skills
-                                .filter(s => s !== currentSkill)
-                                .map(s => {
-                                const sIdx = skills.indexOf(s);
-                                return { skill: s, score: enhanced[sIdx % enhanced.length] || 0 };
-                            })
-                                .sort((a, b) => b.score - a.score);
-                            return ranked.slice(0, 5).map(r => r.skill);
-                        }
-                    }
-                }
-            }
-            catch {
-                // Fall through to JS
-            }
-        }
-        // JS fallback: return direct neighbors from graph
-        const neighbors = skillGraph[currentSkill] || [];
-        if (neighbors.length > 0) {
-            return neighbors.slice(0, 5);
-        }
-        return Object.keys(skillGraph).filter(s => s !== currentSkill).slice(0, 5);
-    }
-    /**
-     * Find similar code patterns using graph embedding similarity.
-     *
-     * When native GNN is available, uses graph-level similarity.
-     * Otherwise falls back to cosine similarity.
-     */
-    async findSimilarPatterns(pattern, patterns) {
-        if (!this.initialized)
-            await this.initialize();
-        if (this.engineType === 'native' && this.gnn) {
-            try {
-                const query = pattern instanceof Float32Array
-                    ? pattern
-                    : new Float32Array(pattern);
-                const candidates = patterns.map(p => p instanceof Float32Array ? p : new Float32Array(p));
-                // Use differentiable search if available
-                if (typeof this.gnn.forward === 'function') {
-                    const enhanced = this.gnn.forward(query, candidates, candidates.map(() => 1.0));
-                    if (enhanced) {
-                        return patterns.map((_, i) => ({
-                            index: i,
-                            similarity: this.cosineSim(Array.from(enhanced), patterns[i]),
-                        })).sort((a, b) => b.similarity - a.similarity);
-                    }
-                }
-            }
-            catch {
-                // Fall through to JS
-            }
-        }
-        // JS fallback: cosine similarity
-        return patterns.map((p, i) => ({
-            index: i,
-            similarity: this.cosineSim(pattern, p),
-        })).sort((a, b) => b.similarity - a.similarity);
-    }
-    /**
-     * Get the current engine type.
-     */
-    getEngineType() {
-        return this.engineType;
-    }
-    /**
-     * Check if the service is initialized.
-     */
-    isInitialized() {
-        return this.initialized;
-    }
-    /**
-     * Get service statistics.
-     */
-    getStats() {
-        return {
-            engineType: this.engineType,
-            initialized: this.initialized,
-            config: this.config,
-        };
-    }
-    /**
-     * Graph Convolutional Network (GCN) for skill matching.
-     *
-     * Uses GCN layers to learn representations of skills based on their
-     * relationships in the skill graph. Achieves >90% accuracy when native.
-     */
-    async matchSkillsGCN(taskEmbedding, skillGraph, topK = 5) {
-        if (!this.initialized)
-            await this.initialize();
-        if (this.engineType === 'native' && this.gnn) {
-            try {
-                const skills = Object.keys(skillGraph);
-                const results = [];
-                for (const skill of skills) {
-                    const skillData = skillGraph[skill];
-                    const neighborEmbeddings = [];
-                    const weights = [];
-                    // Collect neighbor embeddings for GCN aggregation
-                    for (const neighbor of skillData.neighbors) {
-                        if (skillGraph[neighbor]) {
-                            neighborEmbeddings.push(skillGraph[neighbor].embedding);
-                            weights.push(1.0 / skillData.neighbors.length); // Normalized weights
-                        }
-                    }
-                    // Forward pass through GCN
-                    if (typeof this.gnn.forward === 'function') {
-                        const enhanced = this.gnn.forward(skillData.embedding, neighborEmbeddings, weights);
-                        if (enhanced) {
-                            const similarity = this.cosineSim(taskEmbedding, enhanced);
-                            results.push({
-                                skill,
-                                score: similarity,
-                                confidence: similarity > 0.8 ? 0.95 : similarity > 0.6 ? 0.85 : 0.75,
-                            });
-                        }
-                    }
-                }
-                return results
-                    .sort((a, b) => b.score - a.score)
-                    .slice(0, topK);
-            }
-            catch (e) {
-                console.warn('[GNNService] GCN skill matching failed, falling back:', e);
-            }
-        }
-        // JS fallback: simple cosine similarity without graph convolution
-        const skills = Object.keys(skillGraph);
-        return skills
-            .map(skill => ({
-            skill,
-            score: this.cosineSim(taskEmbedding, skillGraph[skill].embedding),
-            confidence: 0.6,
-        }))
-            .sort((a, b) => b.score - a.score)
-            .slice(0, topK);
-    }
-    /**
-     * Graph Attention Network (GAT) for context understanding.
-     *
-     * Applies attention mechanisms to weight the importance of different
-     * context nodes when making predictions.
-     */
-    async understandContextGAT(queryEmbedding, contextNodes, attentionHeads = 4) {
-        if (!this.initialized)
-            await this.initialize();
-        if (this.engineType === 'native' && this.gnn) {
-            try {
-                const embeddings = contextNodes.map(n => n.embedding);
-                const weights = new Array(contextNodes.length).fill(1.0);
-                // Multi-head attention via forward pass
-                if (typeof this.gnn.forward === 'function') {
-                    const attended = this.gnn.forward(queryEmbedding, embeddings, weights);
-                    if (attended) {
-                        // Calculate attention weights based on similarity
-                        const attentionWeights = {};
-                        let maxWeight = 0;
-                        for (let i = 0; i < contextNodes.length; i++) {
-                            const weight = this.cosineSim(attended, contextNodes[i].embedding);
-                            attentionWeights[contextNodes[i].id] = weight;
-                            maxWeight = Math.max(maxWeight, weight);
-                        }
-                        // Normalize weights
-                        for (const key in attentionWeights) {
-                            attentionWeights[key] /= maxWeight || 1.0;
-                        }
-                        // Find dominant types
-                        const typeWeights = {};
-                        for (const node of contextNodes) {
-                            typeWeights[node.type] = (typeWeights[node.type] || 0) + attentionWeights[node.id];
-                        }
-                        const dominantTypes = Object.entries(typeWeights)
-                            .sort(([, a], [, b]) => b - a)
-                            .slice(0, 3)
-                            .map(([type]) => type);
-                        return {
-                            contextVector: attended,
-                            attentionWeights,
-                            dominantTypes,
-                        };
-                    }
-                }
-            }
-            catch (e) {
-                console.warn('[GNNService] GAT context understanding failed, falling back:', e);
-            }
-        }
-        // JS fallback: uniform attention
-        const avgEmbedding = new Float32Array(queryEmbedding.length);
-        for (const node of contextNodes) {
-            for (let i = 0; i < avgEmbedding.length; i++) {
-                avgEmbedding[i] += node.embedding[i] / contextNodes.length;
-            }
-        }
-        const attentionWeights = {};
-        contextNodes.forEach(n => {
-            attentionWeights[n.id] = 1.0 / contextNodes.length;
-        });
-        const typeWeights = {};
-        for (const node of contextNodes) {
-            typeWeights[node.type] = (typeWeights[node.type] || 0) + 1;
-        }
-        const dominantTypes = Object.entries(typeWeights)
-            .sort(([, a], [, b]) => b - a)
-            .map(([type]) => type);
-        return {
-            contextVector: avgEmbedding,
-            attentionWeights,
-            dominantTypes,
-        };
-    }
-    /**
-     * Process heterogeneous graphs with multiple node and edge types.
-     *
-     * Handles graphs with different types of entities (agents, tasks, skills)
-     * and relationships (depends_on, requires, similar_to).
-     */
-    async processHeterogeneousGraph(graph, queryNodeId) {
-        if (!this.initialized)
-            await this.initialize();
-        const nodeMap = new Map(graph.nodes.map(n => [n.id, n]));
-        const queryNode = nodeMap.get(queryNodeId);
-        if (!queryNode) {
-            throw new Error(`Query node ${queryNodeId} not found in graph`);
-        }
-        if (this.engineType === 'native' && this.gnn) {
-            try {
-                // Build adjacency for heterogeneous GNN
-                const neighbors = graph.edges
-                    .filter(e => e.from === queryNodeId)
-                    .map(e => {
-                    const neighbor = nodeMap.get(e.to);
-                    return neighbor ? { ...neighbor, edgeType: e.type, weight: e.weight } : null;
-                })
-                    .filter(n => n !== null);
-                if (neighbors.length > 0 && typeof this.gnn.forward === 'function') {
-                    const enhanced = this.gnn.forward(queryNode.embedding, neighbors.map(n => n.embedding), neighbors.map(n => n.weight));
-                    if (enhanced) {
-                        // Calculate relevance for all nodes
-                        const relatedNodes = graph.nodes
-                            .filter(n => n.id !== queryNodeId)
-                            .map(n => ({
-                            id: n.id,
-                            type: n.type,
-                            relevance: this.cosineSim(enhanced, n.embedding),
-                        }))
-                            .sort((a, b) => b.relevance - a.relevance)
-                            .slice(0, 10);
-                        // Find strongest pathways
-                        const pathways = this.findStrongPathways(graph, queryNodeId, relatedNodes.slice(0, 5));
-                        return {
-                            embedding: enhanced,
-                            relatedNodes,
-                            pathways,
-                        };
-                    }
-                }
-            }
-            catch (e) {
-                console.warn('[GNNService] Heterogeneous graph processing failed, falling back:', e);
-            }
-        }
-        // JS fallback: direct neighbor aggregation
-        const neighbors = graph.edges
-            .filter(e => e.from === queryNodeId)
-            .map(e => nodeMap.get(e.to))
-            .filter(n => n !== undefined);
-        const avgEmbedding = new Float32Array(queryNode.embedding.length);
-        for (let i = 0; i < avgEmbedding.length; i++) {
-            avgEmbedding[i] = queryNode.embedding[i];
-            for (const neighbor of neighbors) {
-                avgEmbedding[i] += neighbor.embedding[i] / (neighbors.length + 1);
-            }
-        }
-        const relatedNodes = graph.nodes
-            .filter(n => n.id !== queryNodeId)
-            .map(n => ({
-            id: n.id,
-            type: n.type,
-            relevance: this.cosineSim(avgEmbedding, n.embedding),
-        }))
-            .sort((a, b) => b.relevance - a.relevance)
-            .slice(0, 10);
-        const pathways = this.findStrongPathways(graph, queryNodeId, relatedNodes.slice(0, 5));
-        return {
-            embedding: avgEmbedding,
-            relatedNodes,
-            pathways,
-        };
-    }
-    /**
-     * Node classification for task categorization.
-     *
-     * Classifies nodes into predefined categories using GNN-based features.
-     */
-    async classifyNode(nodeEmbedding, neighborEmbeddings, categories) {
-        if (!this.initialized)
-            await this.initialize();
-        if (this.engineType === 'native' && this.gnn && typeof this.gnn.forward === 'function') {
-            try {
-                const enhanced = this.gnn.forward(nodeEmbedding, neighborEmbeddings, neighborEmbeddings.map(() => 1.0));
-                if (enhanced && enhanced.length >= categories.length) {
-                    // Use first N dimensions as category logits
-                    const logits = Array.from(enhanced.slice(0, categories.length));
-                    const expLogits = logits.map((l) => Math.exp(l));
-                    const expSum = expLogits.reduce((s, v) => s + v, 1e-10);
-                    const probs = expLogits.map(e => e / expSum);
-                    let maxIdx = 0;
-                    for (let i = 1; i < probs.length; i++) {
-                        if (probs[i] > probs[maxIdx])
-                            maxIdx = i;
-                    }
-                    const scores = {};
-                    categories.forEach((cat, i) => {
-                        scores[cat] = probs[i];
-                    });
-                    return {
-                        category: categories[maxIdx],
-                        confidence: probs[maxIdx],
-                        scores,
-                    };
-                }
-            }
-            catch (e) {
-                console.warn('[GNNService] Node classification failed, falling back:', e);
-            }
-        }
-        // JS fallback: random with slight bias
-        const scores = {};
-        const probs = categories.map(() => Math.random());
-        const sum = probs.reduce((s, v) => s + v, 0);
-        const normalized = probs.map(p => p / sum);
-        let maxIdx = 0;
-        categories.forEach((cat, i) => {
-            scores[cat] = normalized[i];
-            if (normalized[i] > normalized[maxIdx])
-                maxIdx = i;
-        });
-        return {
-            category: categories[maxIdx],
-            confidence: normalized[maxIdx],
-            scores,
-        };
-    }
-    /**
-     * Link prediction for workflow optimization.
-     *
-     * Predicts likely connections between nodes to suggest workflow improvements.
-     */
-    async predictLinks(sourceNode, candidateNodes, existingEdges, topK = 5) {
-        if (!this.initialized)
-            await this.initialize();
-        if (this.engineType === 'native' && this.gnn && typeof this.gnn.forward === 'function') {
-            try {
-                const enhanced = this.gnn.forward(sourceNode.embedding, candidateNodes.map(n => n.embedding), candidateNodes.map(() => 1.0));
-                if (enhanced) {
-                    const predictions = candidateNodes.map(node => {
-                        // Check if edge already exists
-                        const exists = existingEdges.some(e => e.from === sourceNode.id && e.to === node.id);
-                        if (exists) {
-                            return { targetId: node.id, probability: 0, reasoning: 'Edge already exists' };
-                        }
-                        const similarity = this.cosineSim(enhanced, node.embedding);
-                        const probability = 1 / (1 + Math.exp(-5 * (similarity - 0.5))); // Sigmoid scaling
-                        let reasoning = 'Strong structural similarity';
-                        if (probability > 0.8)
-                            reasoning = 'Very high compatibility detected';
-                        else if (probability > 0.6)
-                            reasoning = 'Good potential for connection';
-                        else if (probability > 0.4)
-                            reasoning = 'Moderate connection potential';
-                        else
-                            reasoning = 'Weak connection likelihood';
-                        return { targetId: node.id, probability, reasoning };
-                    });
-                    return predictions
-                        .filter(p => p.probability > 0)
-                        .sort((a, b) => b.probability - a.probability)
-                        .slice(0, topK);
-                }
-            }
-            catch (e) {
-                console.warn('[GNNService] Link prediction failed, falling back:', e);
-            }
-        }
-        // JS fallback: cosine similarity based
-        return candidateNodes
-            .map(node => {
-            const exists = existingEdges.some(e => e.from === sourceNode.id && e.to === node.id);
-            if (exists) {
-                return { targetId: node.id, probability: 0, reasoning: 'Edge already exists' };
-            }
-            const similarity = this.cosineSim(sourceNode.embedding, node.embedding);
-            return {
-                targetId: node.id,
-                probability: similarity,
-                reasoning: similarity > 0.7 ? 'High similarity' : 'Moderate similarity',
-            };
-        })
-            .filter(p => p.probability > 0)
-            .sort((a, b) => b.probability - a.probability)
-            .slice(0, topK);
-    }
-    // ---------------------------------------------------------------------------
-    // Private
-    // ---------------------------------------------------------------------------
-    findStrongPathways(graph, startNodeId, targetNodes) {
-        const pathways = [];
-        for (const target of targetNodes) {
-            // Simple BFS to find shortest path
-            const visited = new Set();
-            const queue = [
-                { nodeId: startNodeId, path: [startNodeId] },
-            ];
-            while (queue.length > 0) {
-                const current = queue.shift();
-                if (current.nodeId === target.id) {
-                    // Calculate pathway strength
-                    let strength = target.relevance;
-                    for (let i = 0; i < current.path.length - 1; i++) {
-                        const edge = graph.edges.find(e => e.from === current.path[i] && e.to === current.path[i + 1]);
-                        strength *= edge?.weight || 0.5;
-                    }
-                    pathways.push({ path: current.path, strength });
-                    break;
-                }
-                if (visited.has(current.nodeId) || current.path.length > 4) {
-                    continue;
-                }
-                visited.add(current.nodeId);
-                const neighbors = graph.edges
-                    .filter(e => e.from === current.nodeId)
-                    .map(e => e.to);
-                for (const neighbor of neighbors) {
-                    if (!visited.has(neighbor)) {
-                        queue.push({
-                            nodeId: neighbor,
-                            path: [...current.path, neighbor],
-                        });
-                    }
-                }
-            }
-        }
-        return pathways.sort((a, b) => b.strength - a.strength).slice(0, 5);
-    }
-    cosineSim(a, b) {
-        let dot = 0;
-        let normA = 0;
-        let normB = 0;
-        const len = Math.min(a.length, b.length);
-        for (let i = 0; i < len; i++) {
-            dot += a[i] * b[i];
-            normA += a[i] * a[i];
-            normB += b[i] * b[i];
-        }
-        const denom = Math.sqrt(normA) * Math.sqrt(normB);
-        return denom > 0 ? dot / denom : 0;
-    }
-}
-//# sourceMappingURL=GNNService.js.map