agentic-qe 3.7.21 → 3.8.0

package/dist/integrations/browser/qe-dashboard/pattern-explorer.js

@@ -0,0 +1,260 @@
+/**
+ * Pattern Explorer for QE Dashboard (Task 4.6)
+ *
+ * Provides pattern exploration, similarity clustering, and visualization
+ * data preparation for the browser-based QE intelligence dashboard.
+ *
+ * Features:
+ * - Load and index patterns into the vector store
+ * - Similarity search across patterns
+ * - K-Means clustering for visualization
+ * - Domain distribution analysis
+ * - Health dashboard data aggregation
+ *
+ * No browser-specific APIs: works in Node.js for testing.
+ *
+ * @module integrations/browser/qe-dashboard/pattern-explorer
+ */
+import { WasmVectorStore, cosineSimilarity, } from './wasm-vector-store.js';
+import { generateEmbedding, generateQueryEmbedding, kMeansClustering, } from './clustering.js';
+// Re-export kMeansClustering for external consumers
+export { kMeansClustering } from './clustering.js';
+// ============================================================================
+// PatternExplorer
+// ============================================================================
+/**
+ * Pattern exploration and visualization data preparation.
+ *
+ * Loads QE patterns into a vector store, provides similarity search,
+ * clustering, domain distribution, and aggregated dashboard data.
+ *
+ * @example
+ * ```typescript
+ * const explorer = new PatternExplorer();
+ * await explorer.initialize();
+ *
+ * explorer.loadPatterns(patterns);
+ *
+ * // Find similar patterns
+ * const similar = explorer.searchSimilar('authentication testing', 5);
+ *
+ * // Cluster for visualization
+ * const clusters = explorer.clusterPatterns(4);
+ *
+ * // Dashboard data
+ * const dashboard = explorer.getHealthDashboardData();
+ * ```
+ */
+export class PatternExplorer {
+    store;
+    patterns = new Map();
+    embeddings = new Map();
+    constructor(store) {
+        this.store = store ?? new WasmVectorStore();
+    }
+    /** Initialize the explorer (loads WASM backend if available) */
+    async initialize() {
+        await this.store.initialize();
+    }
+    /**
+     * Load patterns into the explorer
+     *
+     * Each pattern is embedded (using provided embedding or auto-generated)
+     * and indexed in the vector store for similarity search.
+     */
+    loadPatterns(patterns) {
+        for (const pattern of patterns) {
+            const embedding = pattern.embedding ?? generateEmbedding(pattern);
+            this.patterns.set(pattern.id, pattern);
+            this.embeddings.set(pattern.id, embedding);
+            this.store.add(pattern.id, embedding, {
+                domain: pattern.domain,
+                confidence: pattern.confidence,
+                success: pattern.success,
+                tags: pattern.tags,
+                createdAt: pattern.createdAt,
+            }, pattern.domain);
+        }
+    }
+    /**
+     * Search for patterns similar to a text query
+     *
+     * @param query - Natural language query string
+     * @param k - Number of results to return
+     * @returns Array of matched patterns ordered by similarity
+     */
+    searchSimilar(query, k) {
+        const queryEmb = generateQueryEmbedding(query);
+        const results = this.store.search(queryEmb, k);
+        return results
+            .map((r) => this.patterns.get(r.id))
+            .filter((p) => p !== undefined);
+    }
+    /**
+     * Cluster patterns into groups using K-Means
+     *
+     * @param numClusters - Number of clusters to create
+     * @returns Array of PatternCluster with centroid, members, and statistics
+     */
+    clusterPatterns(numClusters) {
+        const patternList = Array.from(this.patterns.values());
+        if (patternList.length === 0)
+            return [];
+        const vectors = patternList.map((p) => this.embeddings.get(p.id) ?? generateEmbedding(p));
+        const assignments = kMeansClustering(vectors, numClusters);
+        return this.buildClusters(patternList, vectors, assignments);
+    }
+    /** Get distribution statistics per domain */
+    getDomainDistribution() {
+        const domainMap = new Map();
+        for (const pattern of this.patterns.values()) {
+            if (!domainMap.has(pattern.domain)) {
+                domainMap.set(pattern.domain, []);
+            }
+            domainMap.get(pattern.domain).push(pattern);
+        }
+        const stats = [];
+        for (const [domain, patterns] of domainMap) {
+            stats.push(this.computeDomainStats(domain, patterns));
+        }
+        stats.sort((a, b) => b.patternCount - a.patternCount);
+        return stats;
+    }
+    /** Get aggregated health dashboard data */
+    getHealthDashboardData() {
+        const allPatterns = Array.from(this.patterns.values());
+        const totalPatterns = allPatterns.length;
+        const avgConfidence = totalPatterns > 0
+            ? allPatterns.reduce((sum, p) => sum + p.confidence, 0) / totalPatterns
+            : 0;
+        const successCount = allPatterns.filter((p) => p.success === true).length;
+        const successTotal = allPatterns.filter((p) => p.success !== undefined).length;
+        const successRate = successTotal > 0 ? successCount / successTotal : 0;
+        const domainStats = this.getDomainDistribution();
+        const confidenceHistogram = new Array(10).fill(0);
+        for (const p of allPatterns) {
+            confidenceHistogram[Math.min(Math.floor(p.confidence * 10), 9)]++;
+        }
+        const thirtyDaysAgo = Date.now() - 30 * 24 * 60 * 60 * 1000;
+        const recentActivity = allPatterns.filter((p) => (p.createdAt || 0) > thirtyDaysAgo).length;
+        const storeInfo = this.store.getStats();
+        return {
+            totalPatterns,
+            domainCount: domainStats.length,
+            avgConfidence,
+            successRate,
+            domainStats,
+            confidenceHistogram,
+            recentActivity,
+            storeStats: {
+                totalVectors: storeInfo.totalVectors,
+                dimensions: storeInfo.dimensions,
+                wasmActive: storeInfo.wasmActive,
+                memoryBytes: storeInfo.memoryBytes,
+            },
+        };
+    }
+    /** Get a pattern by id */
+    getPattern(id) {
+        return this.patterns.get(id);
+    }
+    /** Get total number of loaded patterns */
+    get patternCount() {
+        return this.patterns.size;
+    }
+    /** Clear all patterns and reset the explorer */
+    clear() {
+        this.patterns.clear();
+        this.embeddings.clear();
+        this.store.clear();
+    }
+    // ==========================================================================
+    // Private helpers
+    // ==========================================================================
+    buildClusters(patternList, vectors, assignments) {
+        const clusterMap = new Map();
+        for (let i = 0; i < assignments.length; i++) {
+            const cid = assignments[i];
+            if (!clusterMap.has(cid)) {
+                clusterMap.set(cid, { patterns: [], vectors: [] });
+            }
+            const entry = clusterMap.get(cid);
+            entry.patterns.push(patternList[i]);
+            entry.vectors.push(vectors[i]);
+        }
+        const clusters = [];
+        for (const [id, { patterns, vectors: vecs }] of clusterMap) {
+            const centroid = this.computeNormalizedCentroid(vecs);
+            const dominantDomain = this.findDominantDomain(patterns);
+            const avgConfidence = patterns.reduce((s, p) => s + p.confidence, 0) / patterns.length;
+            let cohesionSum = 0;
+            for (const v of vecs) {
+                cohesionSum += cosineSimilarity(v, centroid);
+            }
+            clusters.push({
+                id,
+                centroid,
+                patterns,
+                dominantDomain,
+                avgConfidence,
+                cohesion: vecs.length > 0 ? cohesionSum / vecs.length : 0,
+            });
+        }
+        clusters.sort((a, b) => b.patterns.length - a.patterns.length);
+        return clusters;
+    }
+    computeNormalizedCentroid(vectors) {
+        const dim = vectors[0].length;
+        const centroid = new Float32Array(dim);
+        for (const v of vectors) {
+            for (let d = 0; d < dim; d++)
+                centroid[d] += v[d];
+        }
+        for (let d = 0; d < dim; d++)
+            centroid[d] /= vectors.length;
+        let norm = 0;
+        for (let d = 0; d < dim; d++)
+            norm += centroid[d] * centroid[d];
+        norm = Math.sqrt(norm);
+        if (norm > 0) {
+            for (let d = 0; d < dim; d++)
+                centroid[d] /= norm;
+        }
+        return centroid;
+    }
+    findDominantDomain(patterns) {
+        const counts = new Map();
+        for (const p of patterns) {
+            counts.set(p.domain, (counts.get(p.domain) || 0) + 1);
+        }
+        let best = '';
+        let max = 0;
+        for (const [domain, count] of counts) {
+            if (count > max) {
+                max = count;
+                best = domain;
+            }
+        }
+        return best;
+    }
+    computeDomainStats(domain, patterns) {
+        const patternCount = patterns.length;
+        const avgConfidence = patterns.reduce((s, p) => s + p.confidence, 0) / patternCount;
+        const successCount = patterns.filter((p) => p.success === true).length;
+        const successTotal = patterns.filter((p) => p.success !== undefined).length;
+        const successRate = successTotal > 0 ? successCount / successTotal : 0;
+        const latestTimestamp = patterns.reduce((max, p) => Math.max(max, p.createdAt || 0), 0);
+        const tagCounts = new Map();
+        for (const p of patterns) {
+            for (const tag of p.tags || []) {
+                tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
+            }
+        }
+        const topTags = Array.from(tagCounts.entries())
+            .map(([tag, count]) => ({ tag, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 5);
+        return { domain, patternCount, avgConfidence, successRate, latestTimestamp, topTags };
+    }
+}
+//# sourceMappingURL=pattern-explorer.js.map

package/dist/integrations/browser/qe-dashboard/wasm-vector-store.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Browser-side WASM Vector Store for QE Dashboard (Task 4.6)
+ *
+ * Provides a vector store that attempts to load `rvlite` for WASM-based
+ * vector search. When unavailable, falls back to a lightweight in-memory
+ * vector store with cosine similarity search and namespace support.
+ *
+ * Design Goals:
+ * - No browser-specific APIs (must work in Node.js for testing)
+ * - All WASM imports are optional with TypeScript fallback
+ * - Efficient cosine similarity computation
+ * - Namespace-scoped vector storage
+ *
+ * @module integrations/browser/qe-dashboard/wasm-vector-store
+ */
+/** Result of a similarity search */
+export interface SearchResult {
+    /** Unique identifier for the matched vector */
+    id: string;
+    /** Cosine similarity score (0..1 for normalized vectors, -1..1 otherwise) */
+    similarity: number;
+    /** Metadata associated with the vector */
+    metadata: Record<string, unknown>;
+    /** Namespace the vector belongs to */
+    namespace?: string;
+}
+/** Statistics about the vector store */
+export interface StoreStats {
+    /** Total number of vectors stored */
+    totalVectors: number;
+    /** Number of distinct namespaces */
+    namespaceCount: number;
+    /** Vectors per namespace */
+    namespaceSizes: Record<string, number>;
+    /** Dimensionality of stored vectors (0 if empty) */
+    dimensions: number;
+    /** Whether the WASM backend is active */
+    wasmActive: boolean;
+    /** Approximate memory usage in bytes */
+    memoryBytes: number;
+}
+/**
+ * Compute cosine similarity between two vectors
+ *
+ * cosine_similarity = dot(a, b) / (||a|| * ||b||)
+ *
+ * Optimized to accept pre-computed norms for repeated queries.
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array, normA?: number, normB?: number): number;
+/**
+ * Browser-side vector store with optional WASM acceleration.
+ *
+ * Tries to load `rvlite` for WASM-based vector search. When unavailable,
+ * uses a pure TypeScript in-memory implementation with cosine similarity.
+ *
+ * @example
+ * ```typescript
+ * const store = new WasmVectorStore();
+ * await store.initialize();
+ *
+ * // Add vectors
+ * store.add('pattern-1', new Float32Array([0.1, 0.2, 0.3]), { domain: 'testing' });
+ * store.add('pattern-2', new Float32Array([0.4, 0.5, 0.6]), { domain: 'coverage' });
+ *
+ * // Search
+ * const results = store.search(new Float32Array([0.1, 0.2, 0.3]), 5);
+ * console.log(results[0].id); // 'pattern-1'
+ * console.log(results[0].similarity); // ~1.0
+ * ```
+ */
+export declare class WasmVectorStore {
+    private vectors;
+    private wasmModule;
+    private dimensions;
+    private initialized;
+    /**
+     * Initialize the vector store
+     *
+     * Attempts to load the WASM backend. Falls back to TypeScript if unavailable.
+     * Safe to call multiple times (idempotent).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Add a vector with optional metadata and namespace
+     *
+     * @param id - Unique identifier for the vector
+     * @param vector - The vector data as Float32Array
+     * @param metadata - Optional key-value metadata
+     * @param namespace - Optional namespace for scoped queries (default: 'default')
+     * @throws Error if vector dimensions are inconsistent
+     */
+    add(id: string, vector: Float32Array, metadata?: Record<string, unknown>, namespace?: string): void;
+    /**
+     * Search for the k most similar vectors to a query
+     *
+     * @param query - The query vector
+     * @param k - Number of results to return
+     * @param namespace - Optional namespace filter (searches all if omitted)
+     * @returns Array of SearchResult sorted by descending similarity
+     */
+    search(query: Float32Array, k: number, namespace?: string): SearchResult[];
+    /**
+     * Remove a vector by id
+     *
+     * @param id - The vector id to remove
+     * @returns true if the vector was found and removed, false otherwise
+     */
+    remove(id: string): boolean;
+    /**
+     * Check if a vector exists
+     *
+     * @param id - The vector id to check
+     * @returns true if a vector with this id exists
+     */
+    has(id: string): boolean;
+    /**
+     * Get the number of stored vectors
+     */
+    get size(): number;
+    /**
+     * Clear all vectors, optionally within a specific namespace
+     *
+     * @param namespace - If provided, only clear vectors in this namespace
+     */
+    clear(namespace?: string): void;
+    /**
+     * Get store statistics
+     *
+     * @returns StoreStats with counts, dimensions, memory usage, etc.
+     */
+    getStats(): StoreStats;
+    /**
+     * Get all vector ids, optionally filtered by namespace
+     *
+     * @param namespace - Optional namespace filter
+     * @returns Array of vector ids
+     */
+    getIds(namespace?: string): string[];
+    /**
+     * Whether the WASM backend is loaded
+     */
+    get isWasmActive(): boolean;
+}
+//# sourceMappingURL=wasm-vector-store.d.ts.map

package/dist/integrations/browser/qe-dashboard/wasm-vector-store.js

@@ -0,0 +1,277 @@
+/**
+ * Browser-side WASM Vector Store for QE Dashboard (Task 4.6)
+ *
+ * Provides a vector store that attempts to load `rvlite` for WASM-based
+ * vector search. When unavailable, falls back to a lightweight in-memory
+ * vector store with cosine similarity search and namespace support.
+ *
+ * Design Goals:
+ * - No browser-specific APIs (must work in Node.js for testing)
+ * - All WASM imports are optional with TypeScript fallback
+ * - Efficient cosine similarity computation
+ * - Namespace-scoped vector storage
+ *
+ * @module integrations/browser/qe-dashboard/wasm-vector-store
+ */
+// ============================================================================
+// Math Utilities
+// ============================================================================
+/**
+ * Compute the L2 norm of a vector
+ */
+function l2Norm(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) {
+        sum += v[i] * v[i];
+    }
+    return Math.sqrt(sum);
+}
+/**
+ * Compute cosine similarity between two vectors
+ *
+ * cosine_similarity = dot(a, b) / (||a|| * ||b||)
+ *
+ * Optimized to accept pre-computed norms for repeated queries.
+ */
+export function cosineSimilarity(a, b, normA, normB) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dot = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+    }
+    const na = normA ?? l2Norm(a);
+    const nb = normB ?? l2Norm(b);
+    if (na === 0 || nb === 0) {
+        return 0;
+    }
+    return dot / (na * nb);
+}
+/**
+ * Attempt to load the rvlite WASM module
+ * Returns null if unavailable (expected in most environments)
+ */
+async function tryLoadRvlite() {
+    try {
+        // Dynamic import - will fail gracefully if rvlite is not installed
+        const rvlite = await import('rvlite');
+        if (rvlite && typeof rvlite.add === 'function') {
+            return rvlite;
+        }
+        return null;
+    }
+    catch {
+        // Expected: rvlite is not installed in most environments
+        return null;
+    }
+}
+// ============================================================================
+// WasmVectorStore
+// ============================================================================
+/**
+ * Browser-side vector store with optional WASM acceleration.
+ *
+ * Tries to load `rvlite` for WASM-based vector search. When unavailable,
+ * uses a pure TypeScript in-memory implementation with cosine similarity.
+ *
+ * @example
+ * ```typescript
+ * const store = new WasmVectorStore();
+ * await store.initialize();
+ *
+ * // Add vectors
+ * store.add('pattern-1', new Float32Array([0.1, 0.2, 0.3]), { domain: 'testing' });
+ * store.add('pattern-2', new Float32Array([0.4, 0.5, 0.6]), { domain: 'coverage' });
+ *
+ * // Search
+ * const results = store.search(new Float32Array([0.1, 0.2, 0.3]), 5);
+ * console.log(results[0].id); // 'pattern-1'
+ * console.log(results[0].similarity); // ~1.0
+ * ```
+ */
+export class WasmVectorStore {
+    vectors = new Map();
+    wasmModule = null;
+    dimensions = 0;
+    initialized = false;
+    /**
+     * Initialize the vector store
+     *
+     * Attempts to load the WASM backend. Falls back to TypeScript if unavailable.
+     * Safe to call multiple times (idempotent).
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.wasmModule = await tryLoadRvlite();
+        this.initialized = true;
+    }
+    /**
+     * Add a vector with optional metadata and namespace
+     *
+     * @param id - Unique identifier for the vector
+     * @param vector - The vector data as Float32Array
+     * @param metadata - Optional key-value metadata
+     * @param namespace - Optional namespace for scoped queries (default: 'default')
+     * @throws Error if vector dimensions are inconsistent
+     */
+    add(id, vector, metadata = {}, namespace = 'default') {
+        if (vector.length === 0) {
+            throw new Error('Cannot add zero-length vector');
+        }
+        // Enforce consistent dimensionality
+        if (this.dimensions === 0) {
+            this.dimensions = vector.length;
+        }
+        else if (vector.length !== this.dimensions) {
+            throw new Error(`Dimension mismatch: expected ${this.dimensions}, got ${vector.length}`);
+        }
+        // Delegate to WASM if available
+        if (this.wasmModule) {
+            this.wasmModule.add(id, vector, namespace);
+            // Still keep in JS map for metadata lookups
+        }
+        const norm = l2Norm(vector);
+        this.vectors.set(id, { vector, metadata, namespace, norm });
+    }
+    /**
+     * Search for the k most similar vectors to a query
+     *
+     * @param query - The query vector
+     * @param k - Number of results to return
+     * @param namespace - Optional namespace filter (searches all if omitted)
+     * @returns Array of SearchResult sorted by descending similarity
+     */
+    search(query, k, namespace) {
+        if (query.length === 0) {
+            return [];
+        }
+        if (this.vectors.size === 0) {
+            return [];
+        }
+        // Dimension check for query
+        if (this.dimensions > 0 && query.length !== this.dimensions) {
+            throw new Error(`Query dimension mismatch: expected ${this.dimensions}, got ${query.length}`);
+        }
+        const queryNorm = l2Norm(query);
+        const results = [];
+        for (const [id, entry] of this.vectors) {
+            // Namespace filter
+            if (namespace !== undefined && entry.namespace !== namespace) {
+                continue;
+            }
+            const similarity = cosineSimilarity(query, entry.vector, queryNorm, entry.norm);
+            results.push({
+                id,
+                similarity,
+                metadata: { ...entry.metadata },
+                namespace: entry.namespace,
+            });
+        }
+        // Sort by descending similarity
+        results.sort((a, b) => b.similarity - a.similarity);
+        return results.slice(0, Math.max(0, k));
+    }
+    /**
+     * Remove a vector by id
+     *
+     * @param id - The vector id to remove
+     * @returns true if the vector was found and removed, false otherwise
+     */
+    remove(id) {
+        if (this.wasmModule) {
+            this.wasmModule.remove(id);
+        }
+        const existed = this.vectors.delete(id);
+        // Reset dimensions if store is now empty
+        if (this.vectors.size === 0) {
+            this.dimensions = 0;
+        }
+        return existed;
+    }
+    /**
+     * Check if a vector exists
+     *
+     * @param id - The vector id to check
+     * @returns true if a vector with this id exists
+     */
+    has(id) {
+        return this.vectors.has(id);
+    }
+    /**
+     * Get the number of stored vectors
+     */
+    get size() {
+        return this.vectors.size;
+    }
+    /**
+     * Clear all vectors, optionally within a specific namespace
+     *
+     * @param namespace - If provided, only clear vectors in this namespace
+     */
+    clear(namespace) {
+        if (namespace === undefined) {
+            this.vectors.clear();
+            this.dimensions = 0;
+        }
+        else {
+            for (const [id, entry] of this.vectors) {
+                if (entry.namespace === namespace) {
+                    this.vectors.delete(id);
+                }
+            }
+            if (this.vectors.size === 0) {
+                this.dimensions = 0;
+            }
+        }
+    }
+    /**
+     * Get store statistics
+     *
+     * @returns StoreStats with counts, dimensions, memory usage, etc.
+     */
+    getStats() {
+        const namespaceSizes = {};
+        let memoryBytes = 0;
+        for (const [, entry] of this.vectors) {
+            const ns = entry.namespace;
+            namespaceSizes[ns] = (namespaceSizes[ns] || 0) + 1;
+            // Approximate: Float32Array bytes + metadata overhead
+            memoryBytes += entry.vector.byteLength + 128;
+        }
+        return {
+            totalVectors: this.vectors.size,
+            namespaceCount: Object.keys(namespaceSizes).length,
+            namespaceSizes,
+            dimensions: this.dimensions,
+            wasmActive: this.wasmModule !== null,
+            memoryBytes,
+        };
+    }
+    /**
+     * Get all vector ids, optionally filtered by namespace
+     *
+     * @param namespace - Optional namespace filter
+     * @returns Array of vector ids
+     */
+    getIds(namespace) {
+        if (namespace === undefined) {
+            return Array.from(this.vectors.keys());
+        }
+        const ids = [];
+        for (const [id, entry] of this.vectors) {
+            if (entry.namespace === namespace) {
+                ids.push(id);
+            }
+        }
+        return ids;
+    }
+    /**
+     * Whether the WASM backend is loaded
+     */
+    get isWasmActive() {
+        return this.wasmModule !== null;
+    }
+}
+//# sourceMappingURL=wasm-vector-store.js.map