claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
410 lines (343 loc) • 11.6 kB
text/typescript
/**
* Sparse Inference Bridge for Performance Optimizer
*
* Provides efficient trace analysis using sparse inference techniques
* from ruvector-sparse-inference-wasm for processing large performance traces.
*/
import type {
SparseBridgeInterface,
TraceSpan,
} from '../types.js';
/**
* WASM module status
*/
type WasmModuleStatus = 'unloaded' | 'loading' | 'ready' | 'error';
/**
* Sparse encoding configuration
*/
interface SparseEncodingConfig {
maxDimensions: number;
sparsityRatio: number;
hashBuckets: number;
featureExtraction: 'auto' | 'manual' | 'learned';
}
/**
* Default sparse encoding configuration
*/
const DEFAULT_SPARSE_CONFIG: SparseEncodingConfig = {
maxDimensions: 1024,
sparsityRatio: 0.1,
hashBuckets: 256,
featureExtraction: 'auto',
};
/**
* Sparse Inference Bridge Implementation
*
* Provides efficient trace analysis capabilities:
* - Sparse encoding of trace spans for memory efficiency
* - Anomaly detection using sparse representations
* - Critical path analysis using dependency graphs
*/
export class PerfSparseBridge implements SparseBridgeInterface {
readonly name = 'perf-optimizer-sparse';
readonly version = '0.1.0';
private status: WasmModuleStatus = 'unloaded';
private config: SparseEncodingConfig;
private featureHashes: Map<string, number> = new Map();
private encodingCache: Map<string, Float32Array> = new Map();
constructor(config?: Partial<SparseEncodingConfig>) {
this.config = { ...DEFAULT_SPARSE_CONFIG, ...config };
}
async init(): Promise<void> {
if (this.status === 'ready') return;
if (this.status === 'loading') return;
this.status = 'loading';
try {
// Try to load WASM module
// Dynamic import of optional WASM module - use string literal to avoid type error
const modulePath = '@claude-flow/ruvector-upstream';
const wasmModule = await import(/* @vite-ignore */ modulePath).catch(() => null);
if (wasmModule) {
// Initialize with WASM module
this.status = 'ready';
} else {
// Use mock implementation
this.initializeFeatureHashes();
this.status = 'ready';
}
} catch (error) {
this.status = 'error';
throw error;
}
}
async destroy(): Promise<void> {
this.featureHashes.clear();
this.encodingCache.clear();
this.status = 'unloaded';
}
isReady(): boolean {
return this.status === 'ready';
}
/**
* Encode traces into sparse representation
*
* Uses feature hashing and sparse encoding to efficiently
* represent trace spans for downstream analysis.
*/
async encodeTraces(spans: TraceSpan[]): Promise<Float32Array> {
if (!this.isReady()) {
throw new Error('Sparse bridge not initialized');
}
// Check cache
const cacheKey = this.computeCacheKey(spans);
const cached = this.encodingCache.get(cacheKey);
if (cached) return cached;
const encoding = new Float32Array(this.config.maxDimensions);
const nonZeroCount = Math.floor(this.config.maxDimensions * this.config.sparsityRatio);
for (const span of spans) {
// Extract features from span
const features = this.extractSpanFeatures(span);
// Hash features to sparse dimensions
for (const [feature, value] of Object.entries(features)) {
const hash = this.hashFeature(feature);
const dim = hash % this.config.maxDimensions;
// Accumulate with collision handling
encoding[dim] += value;
}
}
// Normalize and apply sparsification
this.normalizeEncoding(encoding);
this.sparsify(encoding, nonZeroCount);
// Cache result
this.encodingCache.set(cacheKey, encoding);
if (this.encodingCache.size > 1000) {
// LRU eviction
const firstKey = this.encodingCache.keys().next().value;
if (firstKey) this.encodingCache.delete(firstKey);
}
return encoding;
}
/**
* Detect anomalies in encoded traces
*
* Uses sparse representations to identify outliers and anomalous patterns.
*/
async detectAnomalies(encoded: Float32Array, threshold: number): Promise<number[]> {
if (!this.isReady()) {
throw new Error('Sparse bridge not initialized');
}
const anomalyIndices: number[] = [];
// Compute statistics
let sum = 0;
let sumSq = 0;
let nonZeroCount = 0;
for (let i = 0; i < encoded.length; i++) {
if (encoded[i] !== 0) {
sum += encoded[i];
sumSq += encoded[i] * encoded[i];
nonZeroCount++;
}
}
if (nonZeroCount === 0) return anomalyIndices;
const mean = sum / nonZeroCount;
const variance = (sumSq / nonZeroCount) - (mean * mean);
const stdDev = Math.sqrt(Math.max(0, variance));
// Detect anomalies using z-score
for (let i = 0; i < encoded.length; i++) {
if (encoded[i] !== 0) {
const zScore = Math.abs((encoded[i] - mean) / (stdDev + 1e-8));
if (zScore > threshold) {
anomalyIndices.push(i);
}
}
}
return anomalyIndices;
}
/**
* Analyze critical path in traces
*
* Uses dependency analysis to identify the critical path through
* the trace spans.
*/
async analyzeCriticalPath(encoded: Float32Array): Promise<string[]> {
if (!this.isReady()) {
throw new Error('Sparse bridge not initialized');
}
// Find dimensions with highest values (representing critical operations)
const indexedValues: Array<{ index: number; value: number }> = [];
for (let i = 0; i < encoded.length; i++) {
if (encoded[i] > 0) {
indexedValues.push({ index: i, value: encoded[i] });
}
}
// Sort by value descending
indexedValues.sort((a, b) => b.value - a.value);
// Map back to operation names using reverse hash lookup
const criticalPath: string[] = [];
const reverseHashes = new Map<number, string>();
for (const [feature, hash] of this.featureHashes) {
const dim = hash % this.config.maxDimensions;
if (!reverseHashes.has(dim)) {
reverseHashes.set(dim, feature);
}
}
for (const { index } of indexedValues.slice(0, 10)) {
const feature = reverseHashes.get(index);
if (feature) {
criticalPath.push(feature);
} else {
criticalPath.push(`operation_${index}`);
}
}
return criticalPath;
}
/**
* Analyze trace patterns for bottleneck detection
*/
analyzePatterns(spans: TraceSpan[]): {
patterns: Map<string, number>;
hotspots: string[];
dependencies: Map<string, string[]>;
} {
const patterns = new Map<string, number>();
const hotspots: string[] = [];
const dependencies = new Map<string, string[]>();
// Build span tree
const spanMap = new Map<string, TraceSpan>();
for (const span of spans) {
spanMap.set(span.spanId, span);
}
// Analyze patterns
for (const span of spans) {
// Track operation patterns
const pattern = `${span.serviceName}:${span.operationName}`;
patterns.set(pattern, (patterns.get(pattern) ?? 0) + 1);
// Identify hotspots (slow operations)
if (span.duration > 100) {
hotspots.push(span.spanId);
}
// Build dependency graph
if (span.parentSpanId) {
const parent = spanMap.get(span.parentSpanId);
if (parent) {
const parentKey = `${parent.serviceName}:${parent.operationName}`;
const deps = dependencies.get(pattern) ?? [];
if (!deps.includes(parentKey)) {
deps.push(parentKey);
dependencies.set(pattern, deps);
}
}
}
}
return { patterns, hotspots, dependencies };
}
// ============================================================================
// Private Methods
// ============================================================================
private initializeFeatureHashes(): void {
// Pre-compute hashes for common features
const commonFeatures = [
'duration', 'error', 'cpu', 'memory', 'io', 'network',
'database', 'cache', 'http', 'grpc', 'sql', 'redis',
];
for (const feature of commonFeatures) {
this.featureHashes.set(feature, this.hashString(feature));
}
}
private extractSpanFeatures(span: TraceSpan): Record<string, number> {
const features: Record<string, number> = {};
// Duration features
features[`duration_${this.bucketize(span.duration, [10, 50, 100, 500, 1000])}`] = 1;
features['duration_raw'] = Math.log1p(span.duration) / 10;
// Service and operation
features[`service:${span.serviceName}`] = 1;
features[`operation:${span.operationName}`] = 1;
// Status
features[`status:${span.status}`] = 1;
if (span.status === 'error') {
features['has_error'] = 1;
}
// Attributes
for (const [key, value] of Object.entries(span.attributes)) {
if (typeof value === 'number') {
features[`attr:${key}`] = Math.tanh(value / 100);
} else if (typeof value === 'string') {
features[`attr:${key}:${value.slice(0, 20)}`] = 1;
} else if (typeof value === 'boolean') {
features[`attr:${key}:${value}`] = 1;
}
}
// Events
if (span.events) {
features['event_count'] = span.events.length / 10;
for (const event of span.events) {
features[`event:${event.name}`] = 1;
}
}
return features;
}
private hashFeature(feature: string): number {
// Check cache
const cached = this.featureHashes.get(feature);
if (cached !== undefined) return cached;
// Compute hash
const hash = this.hashString(feature);
this.featureHashes.set(feature, hash);
return hash;
}
private hashString(str: string): number {
let hash = 0;
for (let i = 0; i < str.length; i++) {
const char = str.charCodeAt(i);
hash = ((hash << 5) - hash) + char;
hash = hash & hash;
}
return Math.abs(hash);
}
private bucketize(value: number, thresholds: number[]): string {
for (let i = 0; i < thresholds.length; i++) {
if (value < thresholds[i]) {
return `lt${thresholds[i]}`;
}
}
return `gte${thresholds[thresholds.length - 1]}`;
}
private normalizeEncoding(encoding: Float32Array): void {
let norm = 0;
for (let i = 0; i < encoding.length; i++) {
norm += encoding[i] * encoding[i];
}
norm = Math.sqrt(norm);
if (norm > 0) {
for (let i = 0; i < encoding.length; i++) {
encoding[i] /= norm;
}
}
}
private sparsify(encoding: Float32Array, keepCount: number): void {
// Find threshold to keep top-k values
const absValues = Array.from(encoding).map(Math.abs);
absValues.sort((a, b) => b - a);
const threshold = absValues[Math.min(keepCount - 1, absValues.length - 1)] ?? 0;
// Zero out values below threshold
for (let i = 0; i < encoding.length; i++) {
if (Math.abs(encoding[i]) < threshold) {
encoding[i] = 0;
}
}
}
private computeCacheKey(spans: TraceSpan[]): string {
if (spans.length === 0) return 'empty';
if (spans.length > 100) {
// Sample for large span sets
return `${spans.length}_${spans[0].traceId}_${spans[spans.length - 1].traceId}`;
}
return spans.map(s => s.spanId).join('_');
}
}
/**
* Create a new sparse bridge instance
*/
export function createPerfSparseBridge(config?: Partial<SparseEncodingConfig>): PerfSparseBridge {
return new PerfSparseBridge(config);
}