@ninebix/nmt-system 1.0.0

package/dist/src/events/progress-tracker.js

@@ -0,0 +1,290 @@
+/**
+ * Progress Tracker - Real-time progress tracking with ETA calculation
+ *
+ * Provides progress monitoring for long-running operations like learning sessions.
+ *
+ * @module events/progress-tracker
+ */
+import { createEvent } from './event-bus.js';
+/**
+ * ProgressTracker - Track and report progress of long-running operations
+ *
+ * Features:
+ * - Real-time progress updates
+ * - Throughput calculation (items/sec)
+ * - ETA estimation with smoothing
+ * - Multi-stage tracking
+ * - Throttled event emission
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ProgressTracker({ eventBus });
+ *
+ * // Start tracking
+ * tracker.startTracking('session-123', 'processing', 100);
+ *
+ * // Update progress
+ * for (let i = 0; i < 100; i++) {
+ *   await processItem(i);
+ *   tracker.updateProgress('session-123', i + 1);
+ * }
+ *
+ * // End tracking
+ * const finalState = tracker.endTracking('session-123');
+ * console.log(`Completed in ${finalState.throughput.toFixed(2)} items/sec`);
+ * ```
+ */
+export class ProgressTracker {
+    sessions = new Map();
+    eventBus;
+    throttleInterval;
+    smoothEta;
+    lastEmitTime = new Map();
+    etaHistory = new Map();
+    constructor(options) {
+        this.eventBus = options?.eventBus ?? null;
+        this.throttleInterval = options?.throttleInterval ?? 100; // 100ms default
+        this.smoothEta = options?.smoothEta ?? true;
+    }
+    /**
+     * Start tracking progress for a session
+     */
+    startTracking(sessionId, stage, total, message) {
+        const now = Date.now();
+        const state = {
+            sessionId,
+            stage,
+            current: 0,
+            total: Math.max(total, 1), // Prevent division by zero
+            startTime: now,
+            lastUpdateTime: now,
+            throughput: 0,
+            eta: 0,
+            percentage: 0,
+            message,
+        };
+        this.sessions.set(sessionId, state);
+        this.etaHistory.set(sessionId, []);
+        this.emitProgressEvent(state, true);
+        return state;
+    }
+    /**
+     * Update progress for a session
+     */
+    updateProgress(sessionId, current, message) {
+        const state = this.sessions.get(sessionId);
+        if (!state) {
+            return null;
+        }
+        const now = Date.now();
+        const elapsed = now - state.startTime;
+        // Update state
+        state.current = Math.min(current, state.total);
+        state.lastUpdateTime = now;
+        // Calculate throughput (items per second)
+        if (elapsed > 0) {
+            state.throughput = (state.current / elapsed) * 1000;
+        }
+        // Calculate percentage
+        state.percentage = (state.current / state.total) * 100;
+        // Calculate ETA
+        if (state.throughput > 0) {
+            const remaining = state.total - state.current;
+            const rawEta = (remaining / state.throughput) * 1000;
+            if (this.smoothEta) {
+                state.eta = this.calculateSmoothedEta(sessionId, rawEta);
+            }
+            else {
+                state.eta = rawEta;
+            }
+        }
+        if (message !== undefined) {
+            state.message = message;
+        }
+        // Emit event (throttled)
+        this.emitProgressEvent(state);
+        return state;
+    }
+    /**
+     * Change the current stage
+     */
+    changeStage(sessionId, newStage, total, message) {
+        const state = this.sessions.get(sessionId);
+        if (!state) {
+            return null;
+        }
+        // Reset for new stage but keep session
+        state.stage = newStage;
+        state.current = 0;
+        state.total = Math.max(total, 1);
+        state.startTime = Date.now();
+        state.lastUpdateTime = state.startTime;
+        state.throughput = 0;
+        state.eta = 0;
+        state.percentage = 0;
+        state.message = message;
+        // Reset ETA history for new stage
+        this.etaHistory.set(sessionId, []);
+        this.emitProgressEvent(state, true);
+        return state;
+    }
+    /**
+     * End tracking for a session
+     */
+    endTracking(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (!state) {
+            return null;
+        }
+        // Final update
+        state.current = state.total;
+        state.percentage = 100;
+        state.eta = 0;
+        const elapsed = Date.now() - state.startTime;
+        if (elapsed > 0) {
+            state.throughput = (state.total / elapsed) * 1000;
+        }
+        // Emit final event
+        this.emitProgressEvent(state, true);
+        // Emit completion event
+        if (this.eventBus) {
+            this.eventBus.publish(createEvent('learning:complete', 'progress-tracker', {
+                sessionId,
+                stage: state.stage,
+                totalItems: state.total,
+                duration: elapsed,
+                throughput: state.throughput,
+            }));
+        }
+        // Clean up
+        this.sessions.delete(sessionId);
+        this.lastEmitTime.delete(sessionId);
+        this.etaHistory.delete(sessionId);
+        return state;
+    }
+    /**
+     * Get current progress for a session
+     */
+    getProgress(sessionId) {
+        return this.sessions.get(sessionId) ?? null;
+    }
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions() {
+        return Array.from(this.sessions.keys());
+    }
+    /**
+     * Check if a session is being tracked
+     */
+    isTracking(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    /**
+     * Calculate ETA for a session
+     */
+    calculateETA(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (!state || state.throughput === 0) {
+            return 0;
+        }
+        const remaining = state.total - state.current;
+        return (remaining / state.throughput) * 1000;
+    }
+    /**
+     * Get formatted time remaining
+     */
+    getFormattedETA(sessionId) {
+        const eta = this.calculateETA(sessionId);
+        if (eta <= 0) {
+            return 'Complete';
+        }
+        const seconds = Math.floor(eta / 1000);
+        const minutes = Math.floor(seconds / 60);
+        const hours = Math.floor(minutes / 60);
+        if (hours > 0) {
+            return `${hours}h ${minutes % 60}m`;
+        }
+        else if (minutes > 0) {
+            return `${minutes}m ${seconds % 60}s`;
+        }
+        else {
+            return `${seconds}s`;
+        }
+    }
+    /**
+     * Set the event bus (for deferred initialization)
+     */
+    setEventBus(eventBus) {
+        this.eventBus = eventBus;
+    }
+    /**
+     * Calculate smoothed ETA using exponential moving average
+     */
+    calculateSmoothedEta(sessionId, rawEta) {
+        const history = this.etaHistory.get(sessionId);
+        if (!history) {
+            return rawEta;
+        }
+        // Keep last 5 ETA values
+        history.push(rawEta);
+        if (history.length > 5) {
+            history.shift();
+        }
+        // Exponential weighted average (more recent values have higher weight)
+        let totalWeight = 0;
+        let weightedSum = 0;
+        for (let i = 0; i < history.length; i++) {
+            const weight = Math.pow(2, i); // 1, 2, 4, 8, 16
+            weightedSum += history[i] * weight;
+            totalWeight += weight;
+        }
+        return weightedSum / totalWeight;
+    }
+    /**
+     * Emit progress event (with throttling)
+     */
+    emitProgressEvent(state, force = false) {
+        if (!this.eventBus) {
+            return;
+        }
+        const now = Date.now();
+        const lastEmit = this.lastEmitTime.get(state.sessionId) ?? 0;
+        // Throttle events unless forced
+        if (!force && now - lastEmit < this.throttleInterval) {
+            return;
+        }
+        this.lastEmitTime.set(state.sessionId, now);
+        const payload = {
+            sessionId: state.sessionId,
+            stage: state.stage,
+            current: state.current,
+            total: state.total,
+            percentage: state.percentage,
+            throughput: state.throughput,
+            eta: state.eta,
+            message: state.message,
+        };
+        this.eventBus.publish(createEvent('learning:progress', 'progress-tracker', payload, state.sessionId));
+    }
+}
+/**
+ * Create a progress tracker instance
+ */
+export function createProgressTracker(options) {
+    return new ProgressTracker(options);
+}
+/**
+ * Singleton progress tracker
+ */
+let globalProgressTracker = null;
+export function getProgressTracker() {
+    if (!globalProgressTracker) {
+        globalProgressTracker = new ProgressTracker();
+    }
+    return globalProgressTracker;
+}
+export function resetProgressTracker() {
+    globalProgressTracker = null;
+}
+//# sourceMappingURL=progress-tracker.js.map

package/dist/src/events/progress-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-tracker.js","sourceRoot":"","sources":["../../../src/events/progress-tracker.ts"],"names":[],"mappings":"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"}

package/dist/src/extensions/clustering/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Clustering Module - Automatic neuron grouping and topic modeling
+ * @module extensions/clustering
+ */
+import type { UUID, INeuronStore } from '../../types/index.js';
+/**
+ * Cluster definition
+ */
+export interface Cluster {
+    id: UUID;
+    name?: string;
+    centroid: Float32Array;
+    members: UUID[];
+    avgSimilarity: number;
+    metadata: {
+        createdAt: string;
+        updatedAt: string;
+        algorithmUsed: string;
+    };
+}
+/**
+ * Clustering result
+ */
+export interface ClusteringResult {
+    clusters: Cluster[];
+    noise?: UUID[];
+    iterations?: number;
+    silhouetteScore?: number;
+}
+/**
+ * K-means options
+ */
+export interface KMeansOptions {
+    k: number;
+    maxIterations?: number;
+    tolerance?: number;
+    initMethod?: 'random' | 'kmeans++';
+}
+/**
+ * DBSCAN options
+ */
+export interface DBSCANOptions {
+    eps: number;
+    minPts: number;
+}
+/**
+ * Community detection options
+ */
+export interface CommunityOptions {
+    resolution?: number;
+    minCommunitySize?: number;
+}
+/**
+ * Clustering Service
+ */
+export declare class ClusteringService {
+    private neuronStore;
+    private clusters;
+    constructor(neuronStore: INeuronStore);
+    /**
+     * K-means clustering
+     */
+    kmeans(options: KMeansOptions): Promise<ClusteringResult>;
+    /**
+     * DBSCAN clustering
+     */
+    dbscan(options: DBSCANOptions): Promise<ClusteringResult>;
+    /**
+     * Hierarchical clustering (Agglomerative)
+     */
+    hierarchical(targetClusters: number, linkage?: 'single' | 'complete' | 'average'): Promise<ClusteringResult>;
+    /**
+     * Get cluster by ID
+     */
+    getCluster(id: UUID): Cluster | undefined;
+    /**
+     * Get all clusters
+     */
+    getAllClusters(): Cluster[];
+    /**
+     * Find cluster for a neuron
+     */
+    findClusterForNeuron(neuronId: UUID): Cluster | undefined;
+    /**
+     * Assign new neuron to nearest cluster
+     */
+    assignToCluster(neuronId: UUID): Promise<Cluster | null>;
+    /**
+     * Get cluster statistics
+     */
+    getStats(): {
+        totalClusters: number;
+        avgClusterSize: number;
+        largestCluster: number;
+        smallestCluster: number;
+    };
+    private getAllNeurons;
+    private getNeuronsByIds;
+    private initRandom;
+    private initKMeansPlusPlus;
+    private findNearestCentroid;
+    private updateCentroids;
+    private buildClusters;
+    private calculateAvgSimilarity;
+    private calculateSilhouette;
+    private regionQuery;
+    private expandCluster;
+    private calculateLinkage;
+}
+/**
+ * Create a ClusteringService instance
+ */
+export declare function createClusteringService(neuronStore: INeuronStore): ClusteringService;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/extensions/clustering/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/extensions/clustering/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,IAAI,EAGJ,YAAY,EACb,MAAM,sBAAsB,CAAC;AAI9B;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,IAAI,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,EAAE,MAAM,CAAC;IACV,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,WAAW,CAAe;IAClC,OAAO,CAAC,QAAQ,CAAqB;gBAEzB,WAAW,EAAE,YAAY;IAKrC;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAwE/D;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmF/D;;OAEG;IACG,YAAY,CAChB,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE,QAAQ,GAAG,UAAU,GAAG,SAAqB,GACrD,OAAO,CAAC,gBAAgB,CAAC;IAgF5B;;OAEG;IACH,UAAU,CAAC,EAAE,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS;IAIzC;;OAEG;IACH,cAAc,IAAI,OAAO,EAAE;IAI3B;;OAEG;IACH,oBAAoB,CAAC,QAAQ,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS;IASzD;;OAEG;IACG,eAAe,CAAC,QAAQ,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IA4B9D;;OAEG;IACH,QAAQ,IAAI;QACV,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc,EAAE,MAAM,CAAC;QACvB,eAAe,EAAE,MAAM,CAAC;KACzB;YAgBa,aAAa;YAYb,eAAe;IAS7B,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,kBAAkB;IAkC1B,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,eAAe;IAsBvB,OAAO,CAAC,aAAa;IA+BrB,OAAO,CAAC,sBAAsB;IAgB9B,OAAO,CAAC,mBAAmB;IA0C3B,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,aAAa;IA0CrB,OAAO,CAAC,gBAAgB;CAuBzB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,YAAY,GAAG,iBAAiB,CAEpF"}