agentic-qe 3.7.22 → 3.8.1

package/dist/integrations/browser/qe-dashboard/clustering.js

@@ -0,0 +1,183 @@
+/**
+ * K-Means Clustering and Embedding Utilities (Task 4.6)
+ *
+ * Provides K-Means clustering with K-Means++ initialization and
+ * deterministic pseudo-embedding generation for patterns without
+ * pre-computed vectors.
+ *
+ * @module integrations/browser/qe-dashboard/clustering
+ */
+import { cosineSimilarity } from './wasm-vector-store.js';
+// ============================================================================
+// Embedding Generation
+// ============================================================================
+/**
+ * Dimension for auto-generated embeddings.
+ * Kept small (32) for efficiency in browser contexts.
+ */
+export const EMBEDDING_DIM = 32;
+/**
+ * Generate a deterministic pseudo-embedding from a pattern's text content.
+ *
+ * Uses a simple hash-based approach to produce a stable vector from the
+ * pattern's description and domain. This is a fallback when no real
+ * embedding model is available.
+ *
+ * @param pattern - The pattern to embed
+ * @returns Float32Array embedding of length EMBEDDING_DIM
+ */
+export function generateEmbedding(pattern) {
+    const text = `${pattern.domain} ${pattern.description} ${(pattern.tags || []).join(' ')}`;
+    const embedding = new Float32Array(EMBEDDING_DIM);
+    // Simple deterministic hash-based embedding
+    for (let i = 0; i < text.length; i++) {
+        const charCode = text.charCodeAt(i);
+        const idx = i % EMBEDDING_DIM;
+        // Mix character codes using a simple multiplicative hash
+        embedding[idx] += Math.sin(charCode * (i + 1) * 0.1) * 0.5;
+    }
+    // Normalize to unit length
+    let norm = 0;
+    for (let i = 0; i < embedding.length; i++) {
+        norm += embedding[i] * embedding[i];
+    }
+    norm = Math.sqrt(norm);
+    if (norm > 0) {
+        for (let i = 0; i < embedding.length; i++) {
+            embedding[i] /= norm;
+        }
+    }
+    return embedding;
+}
+/**
+ * Generate a query embedding from a text string
+ */
+export function generateQueryEmbedding(query) {
+    return generateEmbedding({
+        domain: '',
+        description: query,
+    });
+}
+// ============================================================================
+// K-Means Clustering
+// ============================================================================
+/**
+ * K-Means clustering for Float32Array vectors.
+ *
+ * Uses K-Means++ initialization for better centroid placement,
+ * then iterates until convergence or maxIter is reached.
+ *
+ * @param vectors - Array of vectors to cluster
+ * @param k - Number of clusters
+ * @param maxIter - Maximum iterations (default: 50)
+ * @returns Array of cluster assignments (index per vector)
+ */
+export function kMeansClustering(vectors, k, maxIter = 50) {
+    if (vectors.length === 0 || k <= 0) {
+        return [];
+    }
+    const n = vectors.length;
+    const clampedK = Math.min(k, n);
+    const dim = vectors[0].length;
+    // K-Means++ initialization
+    const centroids = initializeCentroids(vectors, clampedK);
+    const assignments = new Array(n).fill(0);
+    for (let iter = 0; iter < maxIter; iter++) {
+        let changed = false;
+        // Assignment step: assign each vector to the nearest centroid
+        for (let i = 0; i < n; i++) {
+            let bestCluster = 0;
+            let bestSim = -Infinity;
+            for (let c = 0; c < clampedK; c++) {
+                const sim = cosineSimilarity(vectors[i], centroids[c]);
+                if (sim > bestSim) {
+                    bestSim = sim;
+                    bestCluster = c;
+                }
+            }
+            if (assignments[i] !== bestCluster) {
+                assignments[i] = bestCluster;
+                changed = true;
+            }
+        }
+        // Convergence check
+        if (!changed) {
+            break;
+        }
+        // Update step: recompute centroids
+        for (let c = 0; c < clampedK; c++) {
+            const newCentroid = new Float32Array(dim);
+            let count = 0;
+            for (let i = 0; i < n; i++) {
+                if (assignments[i] === c) {
+                    for (let d = 0; d < dim; d++) {
+                        newCentroid[d] += vectors[i][d];
+                    }
+                    count++;
+                }
+            }
+            if (count > 0) {
+                for (let d = 0; d < dim; d++) {
+                    newCentroid[d] /= count;
+                }
+                // Normalize centroid
+                let norm = 0;
+                for (let d = 0; d < dim; d++) {
+                    norm += newCentroid[d] * newCentroid[d];
+                }
+                norm = Math.sqrt(norm);
+                if (norm > 0) {
+                    for (let d = 0; d < dim; d++) {
+                        newCentroid[d] /= norm;
+                    }
+                }
+                centroids[c] = newCentroid;
+            }
+        }
+    }
+    return assignments;
+}
+/**
+ * K-Means++ initialization: select initial centroids with probability
+ * proportional to squared distance from nearest existing centroid.
+ */
+function initializeCentroids(vectors, k) {
+    const n = vectors.length;
+    const centroids = [];
+    // Pick first centroid (deterministic: use first vector)
+    centroids.push(new Float32Array(vectors[0]));
+    for (let c = 1; c < k; c++) {
+        // Compute distances to nearest centroid
+        const distances = new Float64Array(n);
+        let totalDist = 0;
+        for (let i = 0; i < n; i++) {
+            let minDist = Infinity;
+            for (const centroid of centroids) {
+                const sim = cosineSimilarity(vectors[i], centroid);
+                const dist = 1 - sim;
+                if (dist < minDist) {
+                    minDist = dist;
+                }
+            }
+            distances[i] = minDist * minDist; // Squared distance
+            totalDist += distances[i];
+        }
+        if (totalDist === 0) {
+            // All points identical to existing centroids; pick sequentially
+            centroids.push(new Float32Array(vectors[c % n]));
+            continue;
+        }
+        // Deterministic selection: pick the point with maximum distance
+        let maxIdx = 0;
+        let maxDist = -1;
+        for (let i = 0; i < n; i++) {
+            if (distances[i] > maxDist) {
+                maxDist = distances[i];
+                maxIdx = i;
+            }
+        }
+        centroids.push(new Float32Array(vectors[maxIdx]));
+    }
+    return centroids;
+}
+//# sourceMappingURL=clustering.js.map

package/dist/integrations/browser/qe-dashboard/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * QE Dashboard - Browser-based intelligence dashboard (Task 4.6)
+ *
+ * Provides WASM-accelerated vector storage and pattern exploration
+ * for visualizing QE intelligence data in the browser.
+ *
+ * @module integrations/browser/qe-dashboard
+ */
+export { WasmVectorStore, cosineSimilarity, type SearchResult, type StoreStats, } from './wasm-vector-store.js';
+export { kMeansClustering, generateEmbedding, generateQueryEmbedding, EMBEDDING_DIM, type EmbeddablePattern, } from './clustering.js';
+export { PatternExplorer, type Pattern, type PatternCluster, type DomainStats, type DashboardData, } from './pattern-explorer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/integrations/browser/qe-dashboard/index.js

@@ -0,0 +1,15 @@
+/**
+ * QE Dashboard - Browser-based intelligence dashboard (Task 4.6)
+ *
+ * Provides WASM-accelerated vector storage and pattern exploration
+ * for visualizing QE intelligence data in the browser.
+ *
+ * @module integrations/browser/qe-dashboard
+ */
+// Vector Store
+export { WasmVectorStore, cosineSimilarity, } from './wasm-vector-store.js';
+// Clustering
+export { kMeansClustering, generateEmbedding, generateQueryEmbedding, EMBEDDING_DIM, } from './clustering.js';
+// Pattern Explorer
+export { PatternExplorer, } from './pattern-explorer.js';
+//# sourceMappingURL=index.js.map

package/dist/integrations/browser/qe-dashboard/pattern-explorer.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 } from './wasm-vector-store.js';
+export { kMeansClustering } from './clustering.js';
+/** A QE pattern for exploration */
+export interface Pattern {
+    /** Unique pattern identifier */
+    id: string;
+    /** Domain the pattern belongs to */
+    domain: string;
+    /** Human-readable description */
+    description: string;
+    /** Confidence score (0..1) */
+    confidence: number;
+    /** Embedding vector (optional - will be auto-generated if missing) */
+    embedding?: Float32Array;
+    /** Tags for filtering */
+    tags?: string[];
+    /** Timestamp of pattern creation */
+    createdAt?: number;
+    /** Whether the pattern was successful */
+    success?: boolean;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** A cluster of similar patterns */
+export interface PatternCluster {
+    /** Cluster index */
+    id: number;
+    /** Centroid vector of the cluster */
+    centroid: Float32Array;
+    /** Patterns assigned to this cluster */
+    patterns: Pattern[];
+    /** Dominant domain in this cluster */
+    dominantDomain: string;
+    /** Average confidence within the cluster */
+    avgConfidence: number;
+    /** Intra-cluster cohesion (average similarity to centroid) */
+    cohesion: number;
+}
+/** Statistics about a domain */
+export interface DomainStats {
+    /** Domain name */
+    domain: string;
+    /** Number of patterns in this domain */
+    patternCount: number;
+    /** Average confidence across patterns */
+    avgConfidence: number;
+    /** Success rate (fraction of successful patterns) */
+    successRate: number;
+    /** Most recent pattern timestamp */
+    latestTimestamp: number;
+    /** Top tags in this domain */
+    topTags: Array<{
+        tag: string;
+        count: number;
+    }>;
+}
+/** Aggregated dashboard data */
+export interface DashboardData {
+    /** Total number of loaded patterns */
+    totalPatterns: number;
+    /** Number of distinct domains */
+    domainCount: number;
+    /** Overall average confidence */
+    avgConfidence: number;
+    /** Overall success rate */
+    successRate: number;
+    /** Per-domain statistics */
+    domainStats: DomainStats[];
+    /** Confidence distribution histogram (10 bins) */
+    confidenceHistogram: number[];
+    /** Recent pattern activity (last 30 days if timestamps present) */
+    recentActivity: number;
+    /** Vector store statistics */
+    storeStats: {
+        totalVectors: number;
+        dimensions: number;
+        wasmActive: boolean;
+        memoryBytes: number;
+    };
+}
+/**
+ * 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 declare class PatternExplorer {
+    private store;
+    private patterns;
+    private embeddings;
+    constructor(store?: WasmVectorStore);
+    /** Initialize the explorer (loads WASM backend if available) */
+    initialize(): Promise<void>;
+    /**
+     * 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: Pattern[]): void;
+    /**
+     * 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: string, k: number): Pattern[];
+    /**
+     * 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: number): PatternCluster[];
+    /** Get distribution statistics per domain */
+    getDomainDistribution(): DomainStats[];
+    /** Get aggregated health dashboard data */
+    getHealthDashboardData(): DashboardData;
+    /** Get a pattern by id */
+    getPattern(id: string): Pattern | undefined;
+    /** Get total number of loaded patterns */
+    get patternCount(): number;
+    /** Clear all patterns and reset the explorer */
+    clear(): void;
+    private buildClusters;
+    private computeNormalizedCentroid;
+    private findDominantDomain;
+    private computeDomainStats;
+}
+//# sourceMappingURL=pattern-explorer.d.ts.map

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