monomind 2.7.3 → 2.7.5

package/packages/@monomind/cli/dist/src/mcp-tools/coherence/spectral-analyze.js

@@ -1,312 +0,0 @@
-/**
- * Spectral Analysis Tool - pr_spectral_analyze
- *
- * Analyzes stability of systems using spectral graph theory.
- * Computes eigenvalues via power iteration with Hotelling deflation,
- * spectral gap, and stability metrics from the graph Laplacian.
- */
-import { SpectralInputSchema, successResult, errorResult, } from './types.js';
-// Default logger
-const defaultLogger = {
-    debug: (msg, meta) => console.debug(`[pr_spectral_analyze] ${msg}`, meta),
-    info: (msg, meta) => console.info(`[pr_spectral_analyze] ${msg}`, meta),
-    warn: (msg, meta) => console.warn(`[pr_spectral_analyze] ${msg}`, meta),
-    error: (msg, meta) => console.error(`[pr_spectral_analyze] ${msg}`, meta),
-};
-/**
- * Simple deterministic hash to seed initial vectors reproducibly from matrix content
- */
-function matrixHash(matrix) {
-    let hash = 0;
-    for (let i = 0; i < matrix.length; i++) {
-        for (let j = 0; j < matrix[i].length; j++) {
-            // Combine with a simple LCG-style mixing
-            hash = ((hash * 1103515245 + 12345) & 0x7fffffff) ^ (matrix[i][j] * 1000003 | 0);
-        }
-    }
-    return hash;
-}
-/**
- * Power iteration method for finding dominant eigenvalue.
- * Returns both the eigenvalue and the converged eigenvector.
- */
-function powerIteration(matrix, maxIterations = 100, tolerance = 1e-10, seed) {
-    const n = matrix.length;
-    if (n === 0)
-        return { eigenvalue: 0, eigenvector: [] };
-    // Initialize with deterministic vector seeded from matrix content
-    let s = seed ?? matrixHash(matrix);
-    let v = new Array(n).fill(0).map(() => {
-        s = (s * 1103515245 + 12345) & 0x7fffffff;
-        return (s / 0x7fffffff) * 2 - 1;
-    });
-    let eigenvalue = 0;
-    for (let iter = 0; iter < maxIterations; iter++) {
-        // Multiply matrix by vector
-        const w = new Array(n).fill(0);
-        for (let i = 0; i < n; i++) {
-            for (let j = 0; j < n; j++) {
-                w[i] += matrix[i][j] * v[j];
-            }
-        }
-        // Find max component for normalization
-        let maxComponent = 0;
-        for (let i = 0; i < n; i++) {
-            if (Math.abs(w[i]) > Math.abs(maxComponent)) {
-                maxComponent = w[i];
-            }
-        }
-        if (Math.abs(maxComponent) < tolerance)
-            break;
-        // Check convergence
-        const newEigenvalue = maxComponent;
-        if (Math.abs(newEigenvalue - eigenvalue) < tolerance) {
-            return { eigenvalue: newEigenvalue, eigenvector: v };
-        }
-        eigenvalue = newEigenvalue;
-        // Normalize
-        for (let i = 0; i < n; i++) {
-            v[i] = w[i] / maxComponent;
-        }
-    }
-    return { eigenvalue, eigenvector: v };
-}
-/**
- * Compute eigenvalues via repeated power-iteration with Hotelling deflation.
- * Returns only eigenvalues actually computed (up to min(n, maxCount)).
- * For production, consider using a proper numerical library.
- */
-function computeEigenvalues(matrix, maxCount = 10) {
-    const n = matrix.length;
-    if (n === 0)
-        return [];
-    if (n === 1)
-        return [matrix[0][0]];
-    const eigenvalues = [];
-    // Work on a copy so deflation doesn't mutate the original
-    let current = matrix.map(row => [...row]);
-    const count = Math.min(n, maxCount);
-    for (let k = 0; k < count; k++) {
-        const { eigenvalue, eigenvector } = powerIteration(current, 200, 1e-10, matrixHash(current) + k);
-        // If power iteration didn't converge to anything meaningful, stop
-        if (Math.abs(eigenvalue) < 1e-12)
-            break;
-        eigenvalues.push(eigenvalue);
-        // Hotelling deflation: subtract lambda * v * v^T from the matrix
-        // to remove the dominant eigenvalue and find the next one
-        let vNorm = 0;
-        for (let i = 0; i < n; i++)
-            vNorm += eigenvector[i] * eigenvector[i];
-        if (vNorm < 1e-12)
-            break;
-        for (let i = 0; i < n; i++) {
-            for (let j = 0; j < n; j++) {
-                current[i][j] -= eigenvalue * (eigenvector[i] * eigenvector[j]) / vNorm;
-            }
-        }
-    }
-    return eigenvalues.sort((a, b) => Math.abs(b) - Math.abs(a));
-}
-/**
- * Compute the Laplacian matrix from adjacency matrix
- */
-function computeLaplacian(adjacency) {
-    const n = adjacency.length;
-    const laplacian = [];
-    for (let i = 0; i < n; i++) {
-        laplacian[i] = [];
-        let degree = 0;
-        for (let j = 0; j < n; j++) {
-            degree += adjacency[i][j];
-        }
-        for (let j = 0; j < n; j++) {
-            if (i === j) {
-                laplacian[i][j] = degree;
-            }
-            else {
-                laplacian[i][j] = -adjacency[i][j];
-            }
-        }
-    }
-    return laplacian;
-}
-/**
- * Compute spectral gap (difference between first and second eigenvalues)
- */
-function computeSpectralGap(eigenvalues) {
-    if (eigenvalues.length < 2)
-        return 0;
-    // For Laplacian: spectral gap is lambda_2 (first non-zero eigenvalue)
-    // Eigenvalues should be sorted by magnitude
-    const sorted = [...eigenvalues].sort((a, b) => a - b);
-    // Find first significantly non-zero eigenvalue
-    for (let i = 0; i < sorted.length; i++) {
-        if (Math.abs(sorted[i]) > 1e-10) {
-            return sorted[i];
-        }
-    }
-    return sorted.length > 1 ? Math.abs(sorted[1] - sorted[0]) : 0;
-}
-/**
- * Compute stability index based on eigenvalue distribution
- */
-function computeStabilityIndex(eigenvalues) {
-    if (eigenvalues.length === 0)
-        return 0;
-    // Stability based on eigenvalue spread and negativity
-    const maxEig = Math.max(...eigenvalues.map(Math.abs));
-    if (maxEig === 0)
-        return 1;
-    // Count negative eigenvalues (indicate instability in dynamical systems)
-    const negativeCount = eigenvalues.filter(e => e < -1e-10).length;
-    const negativeRatio = negativeCount / eigenvalues.length;
-    // Stability score: higher is more stable
-    // Based on spectral gap and lack of negative eigenvalues
-    const spectralGap = computeSpectralGap(eigenvalues);
-    const normalizedGap = Math.min(spectralGap / maxEig, 1);
-    return (1 - negativeRatio) * (0.5 + 0.5 * normalizedGap);
-}
-/**
- * Get interpretation of spectral analysis results
- */
-function getInterpretation(stable, spectralGap, stabilityIndex) {
-    if (stable && stabilityIndex > 0.8) {
-        return 'System is highly stable with strong connectivity';
-    }
-    if (stable && stabilityIndex > 0.5) {
-        return 'System is stable with moderate connectivity';
-    }
-    if (stable) {
-        return 'System is marginally stable - monitor for changes';
-    }
-    if (spectralGap < 0.01) {
-        return 'System shows instability - agents may be forming isolated clusters';
-    }
-    if (stabilityIndex < 0.3) {
-        return 'System is unstable - coordination patterns are fragmented';
-    }
-    return 'System shows instability patterns - recommend topology adjustment';
-}
-/**
- * Handler for pr_spectral_analyze tool
- */
-async function handler(input, context) {
-    const logger = context?.logger ?? defaultLogger;
-    const startTime = performance.now();
-    try {
-        // Validate input
-        const validationResult = SpectralInputSchema.safeParse(input);
-        if (!validationResult.success) {
-            logger.error('Input validation failed', { error: validationResult.error.message });
-            return errorResult(`Invalid input: ${validationResult.error.message}`);
-        }
-        const { matrix, analyzeType } = validationResult.data;
-        const n = matrix.length;
-        logger.debug('Processing spectral analysis', { matrixSize: n, analyzeType });
-        // Validate square matrix
-        for (let i = 0; i < n; i++) {
-            if (matrix[i].length !== n) {
-                return errorResult(`Matrix must be square. Row ${i} has ${matrix[i].length} elements, expected ${n}`);
-            }
-        }
-        // Check max matrix size from config
-        const maxSize = context?.config?.spectral?.maxMatrixSize ?? 1000;
-        if (n > maxSize) {
-            return errorResult(`Matrix size ${n} exceeds maximum allowed size ${maxSize}`);
-        }
-        let eigenvalues;
-        let spectralGap;
-        let stabilityIndex;
-        // Try to use WASM bridge if available
-        if (context?.bridge?.initialized) {
-            try {
-                logger.debug('Using WASM bridge for spectral analysis');
-                const flatMatrix = new Float32Array(matrix.flat());
-                const result = await context.bridge.analyzeSpectral(flatMatrix, n);
-                eigenvalues = result.eigenvalues;
-                spectralGap = result.spectralGap;
-                stabilityIndex = result.stabilityIndex;
-            }
-            catch (wasmError) {
-                logger.warn('WASM bridge failed, falling back to JS implementation', {
-                    error: wasmError instanceof Error ? wasmError.message : String(wasmError),
-                });
-                // Compute Laplacian for stability analysis
-                const laplacian = computeLaplacian(matrix);
-                eigenvalues = computeEigenvalues(laplacian);
-                spectralGap = computeSpectralGap(eigenvalues);
-                stabilityIndex = computeStabilityIndex(eigenvalues);
-            }
-        }
-        else {
-            // Pure JavaScript fallback
-            logger.debug('Using JavaScript fallback for spectral analysis');
-            const laplacian = computeLaplacian(matrix);
-            eigenvalues = computeEigenvalues(laplacian);
-            spectralGap = computeSpectralGap(eigenvalues);
-            stabilityIndex = computeStabilityIndex(eigenvalues);
-        }
-        // Determine stability based on spectral gap threshold
-        const stabilityThreshold = context?.config?.spectral?.stabilityThreshold ?? 0.1;
-        const stable = spectralGap > stabilityThreshold && stabilityIndex > 0.5;
-        const output = {
-            spectralGap,
-            eigenvalues: eigenvalues.slice(0, 10), // Return top 10 eigenvalues
-            stable,
-            details: {
-                stabilityIndex,
-                interpretation: getInterpretation(stable, spectralGap, stabilityIndex),
-                matrixSize: n,
-                analyzeType,
-            },
-        };
-        const duration = performance.now() - startTime;
-        logger.info('Spectral analysis completed', {
-            stable,
-            spectralGap: spectralGap.toFixed(4),
-            stabilityIndex: stabilityIndex.toFixed(4),
-            durationMs: duration.toFixed(2),
-        });
-        return successResult(output);
-    }
-    catch (error) {
-        const duration = performance.now() - startTime;
-        logger.error('Spectral analysis failed', {
-            error: error instanceof Error ? error.message : String(error),
-            durationMs: duration.toFixed(2),
-        });
-        return errorResult(error instanceof Error ? error : new Error(String(error)));
-    }
-}
-/**
- * pr_spectral_analyze MCP Tool Definition
- */
-export const spectralAnalyzeTool = {
-    name: 'pr_spectral_analyze',
-    description: 'Analyze stability using spectral graph theory. Computes eigenvalues via power iteration with Hotelling deflation, spectral gap, and stability metrics from the graph Laplacian.',
-    category: 'spectral',
-    version: '0.1.3',
-    tags: ['spectral', 'eigenvalues', 'stability', 'graph-theory', 'ai-interpretability'],
-    cacheable: true,
-    cacheTTL: 60000,
-    inputSchema: {
-        type: 'object',
-        properties: {
-            matrix: {
-                type: 'array',
-                items: { type: 'array', items: { type: 'number' } },
-                description: 'Adjacency matrix representing connections (must be square)',
-            },
-            analyzeType: {
-                type: 'string',
-                enum: ['stability', 'clustering', 'connectivity'],
-                default: 'stability',
-                description: 'Type of analysis to perform',
-            },
-        },
-        required: ['matrix'],
-    },
-    handler,
-};
-export default spectralAnalyzeTool;
-//# sourceMappingURL=spectral-analyze.js.map