@ninebix/nmt-system 1.0.0

package/dist/utils/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/utils/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAC7C,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmB;IAG1C,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,UAAU,CAGH;IAGf,OAAO,CAAC,YAAY,CAAsD;IAG1E,OAAO,CAAC,SAAS,CAAsB;IAGvC,OAAO,CAAC,cAAc,CAA2D;IAEjF,OAAO;IAEP;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAOtC;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,KAAK,GAAE,MAAU,GAAG,IAAI;IAMjF;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM;IAOjE;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAKzE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM;IAK/D;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAMtF;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAQtF;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAmB7E;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,aAAa,GAAG,IAAI;IAiCjF;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,MAAM;IASvE;;OAEG;IACG,KAAK,CAAC,CAAC,EACX,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC;IAWb;;;;;OAKG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI;IAI1E;;OAEG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzC;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,YAAY,CAAC;IAyC1C;;OAEG;IACH,QAAQ,IAAI,cAAc;IA6B1B;;OAEG;IACH,YAAY,IAAI,MAAM;IAoCtB,OAAO,CAAC,QAAQ;CAYjB;AAID;;GAEG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,CAE7C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,CAAC,EAAE,MAAM,GACb,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,MAAM,CAEd;AAID;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;CAiCd,CAAC"}

package/dist/utils/metrics.js

@@ -0,0 +1,387 @@
+/**
+ * Metrics System - Performance and Health Monitoring
+ *
+ * Provides basic metrics collection for monitoring system performance.
+ * Supports counters, gauges, and histograms.
+ *
+ * @module utils/metrics
+ */
+/**
+ * Metrics Collector
+ *
+ * Collects and aggregates system metrics for monitoring.
+ *
+ * @example
+ * ```typescript
+ * const metrics = MetricsCollector.getInstance();
+ *
+ * // Increment a counter
+ * metrics.increment('requests_total', { method: 'GET', path: '/api' });
+ *
+ * // Set a gauge
+ * metrics.gauge('active_connections', 42);
+ *
+ * // Record a timing
+ * metrics.histogram('request_duration_ms', 150);
+ *
+ * // Time an operation
+ * const timer = metrics.startTimer('operation_duration_ms');
+ * await performOperation();
+ * timer();
+ *
+ * // Get snapshot
+ * const snapshot = metrics.snapshot();
+ * ```
+ */
+export class MetricsCollector {
+    static instance;
+    // Storage
+    counters = new Map();
+    gauges = new Map();
+    histograms = new Map();
+    // Health checks
+    healthChecks = new Map();
+    // Timing
+    startTime = Date.now();
+    // Default histogram buckets (latency in ms)
+    defaultBuckets = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+    constructor() { }
+    /**
+     * Get singleton instance
+     */
+    static getInstance() {
+        if (!MetricsCollector.instance) {
+            MetricsCollector.instance = new MetricsCollector();
+        }
+        return MetricsCollector.instance;
+    }
+    /**
+     * Reset all metrics (useful for testing)
+     */
+    reset() {
+        this.counters.clear();
+        this.gauges.clear();
+        this.histograms.clear();
+        this.healthChecks.clear();
+        this.startTime = Date.now();
+    }
+    // ==================== Counters ====================
+    /**
+     * Increment a counter
+     *
+     * @param name - Metric name
+     * @param labels - Optional labels
+     * @param value - Increment value (default: 1)
+     */
+    increment(name, labels, value = 1) {
+        const key = this.buildKey(name, labels);
+        const current = this.counters.get(key) ?? 0;
+        this.counters.set(key, current + value);
+    }
+    /**
+     * Get counter value
+     */
+    getCounter(name, labels) {
+        const key = this.buildKey(name, labels);
+        return this.counters.get(key) ?? 0;
+    }
+    // ==================== Gauges ====================
+    /**
+     * Set a gauge value
+     *
+     * @param name - Metric name
+     * @param value - Current value
+     * @param labels - Optional labels
+     */
+    gauge(name, value, labels) {
+        const key = this.buildKey(name, labels);
+        this.gauges.set(key, value);
+    }
+    /**
+     * Get gauge value
+     */
+    getGauge(name, labels) {
+        const key = this.buildKey(name, labels);
+        return this.gauges.get(key) ?? 0;
+    }
+    /**
+     * Increment a gauge
+     */
+    gaugeIncrement(name, value = 1, labels) {
+        const key = this.buildKey(name, labels);
+        const current = this.gauges.get(key) ?? 0;
+        this.gauges.set(key, current + value);
+    }
+    /**
+     * Decrement a gauge
+     */
+    gaugeDecrement(name, value = 1, labels) {
+        const key = this.buildKey(name, labels);
+        const current = this.gauges.get(key) ?? 0;
+        this.gauges.set(key, current - value);
+    }
+    // ==================== Histograms ====================
+    /**
+     * Record a histogram value
+     *
+     * @param name - Metric name
+     * @param value - Observed value
+     * @param labels - Optional labels
+     */
+    histogram(name, value, labels) {
+        const key = this.buildKey(name, labels);
+        if (!this.histograms.has(key)) {
+            this.histograms.set(key, {
+                values: [],
+                bucketBounds: this.defaultBuckets,
+            });
+        }
+        const hist = this.histograms.get(key);
+        hist.values.push(value);
+        // Keep only last 10000 values to prevent memory issues
+        if (hist.values.length > 10000) {
+            hist.values = hist.values.slice(-10000);
+        }
+    }
+    /**
+     * Get histogram data
+     */
+    getHistogram(name, labels) {
+        const key = this.buildKey(name, labels);
+        const hist = this.histograms.get(key);
+        if (!hist || hist.values.length === 0) {
+            return null;
+        }
+        const sorted = [...hist.values].sort((a, b) => a - b);
+        const buckets = [];
+        let bucketIdx = 0;
+        for (const bound of hist.bucketBounds) {
+            let count = 0;
+            while (bucketIdx < sorted.length && sorted[bucketIdx] <= bound) {
+                count++;
+                bucketIdx++;
+            }
+            buckets.push({ le: bound, count: (buckets[buckets.length - 1]?.count ?? 0) + count });
+        }
+        // +Inf bucket
+        buckets.push({ le: Infinity, count: sorted.length });
+        return {
+            buckets,
+            sum: hist.values.reduce((a, b) => a + b, 0),
+            count: hist.values.length,
+            min: sorted[0],
+            max: sorted[sorted.length - 1],
+        };
+    }
+    /**
+     * Start a timer and return a function to stop it
+     */
+    startTimer(name, labels) {
+        const start = performance.now();
+        return () => {
+            const duration = performance.now() - start;
+            this.histogram(name, duration, labels);
+            return duration;
+        };
+    }
+    /**
+     * Time an async function
+     */
+    async timed(name, fn, labels) {
+        const stop = this.startTimer(name, labels);
+        try {
+            return await fn();
+        }
+        finally {
+            stop();
+        }
+    }
+    // ==================== Health Checks ====================
+    /**
+     * Register a health check
+     *
+     * @param name - Check name
+     * @param check - Async function that returns health status
+     */
+    registerHealthCheck(name, check) {
+        this.healthChecks.set(name, check);
+    }
+    /**
+     * Unregister a health check
+     */
+    unregisterHealthCheck(name) {
+        this.healthChecks.delete(name);
+    }
+    /**
+     * Run all health checks
+     */
+    async checkHealth() {
+        const results = [];
+        let hasUnhealthy = false;
+        let hasDegraded = false;
+        for (const [name, check] of this.healthChecks) {
+            try {
+                const start = performance.now();
+                const result = await check();
+                result.latency = performance.now() - start;
+                results.push(result);
+                if (!result.healthy) {
+                    hasUnhealthy = true;
+                }
+            }
+            catch (error) {
+                results.push({
+                    name,
+                    healthy: false,
+                    message: error instanceof Error ? error.message : 'Check failed',
+                });
+                hasUnhealthy = true;
+            }
+        }
+        // Check latencies for degraded status
+        for (const check of results) {
+            if (check.healthy && check.latency && check.latency > 1000) {
+                hasDegraded = true;
+            }
+        }
+        return {
+            status: hasUnhealthy ? 'unhealthy' : hasDegraded ? 'degraded' : 'healthy',
+            checks: results,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    // ==================== Export ====================
+    /**
+     * Get a snapshot of all metrics
+     */
+    snapshot() {
+        const counters = {};
+        const gauges = {};
+        const histograms = {};
+        for (const [key, value] of this.counters) {
+            counters[key] = value;
+        }
+        for (const [key, value] of this.gauges) {
+            gauges[key] = value;
+        }
+        for (const [key] of this.histograms) {
+            const data = this.getHistogram(key);
+            if (data) {
+                histograms[key] = data;
+            }
+        }
+        return {
+            timestamp: new Date().toISOString(),
+            uptime: Date.now() - this.startTime,
+            counters,
+            gauges,
+            histograms,
+        };
+    }
+    /**
+     * Export metrics in Prometheus format
+     */
+    toPrometheus() {
+        const lines = [];
+        // Counters
+        for (const [key, value] of this.counters) {
+            lines.push(`# TYPE ${key.split('{')[0]} counter`);
+            lines.push(`${key} ${value}`);
+        }
+        // Gauges
+        for (const [key, value] of this.gauges) {
+            lines.push(`# TYPE ${key.split('{')[0]} gauge`);
+            lines.push(`${key} ${value}`);
+        }
+        // Histograms
+        for (const [key] of this.histograms) {
+            const data = this.getHistogram(key);
+            if (data) {
+                const baseName = key.split('{')[0];
+                lines.push(`# TYPE ${baseName} histogram`);
+                for (const bucket of data.buckets) {
+                    const le = bucket.le === Infinity ? '+Inf' : bucket.le.toString();
+                    lines.push(`${baseName}_bucket{le="${le}"} ${bucket.count}`);
+                }
+                lines.push(`${baseName}_sum ${data.sum}`);
+                lines.push(`${baseName}_count ${data.count}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    // ==================== Private ====================
+    buildKey(name, labels) {
+        if (!labels || Object.keys(labels).length === 0) {
+            return name;
+        }
+        const labelStr = Object.entries(labels)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${k}="${v}"`)
+            .join(',');
+        return `${name}{${labelStr}}`;
+    }
+}
+// ==================== Convenience Functions ====================
+/**
+ * Get the global metrics instance
+ */
+export function getMetrics() {
+    return MetricsCollector.getInstance();
+}
+/**
+ * Increment a counter
+ */
+export function incrementCounter(name, labels, value) {
+    getMetrics().increment(name, labels, value);
+}
+/**
+ * Set a gauge
+ */
+export function setGauge(name, value, labels) {
+    getMetrics().gauge(name, value, labels);
+}
+/**
+ * Record a histogram value
+ */
+export function recordHistogram(name, value, labels) {
+    getMetrics().histogram(name, value, labels);
+}
+/**
+ * Start a timer
+ */
+export function startTimer(name, labels) {
+    return getMetrics().startTimer(name, labels);
+}
+// ==================== Pre-defined Metrics ====================
+/**
+ * Standard metric names used across the system
+ */
+export const MetricNames = {
+    // API metrics
+    API_REQUESTS_TOTAL: 'api_requests_total',
+    API_REQUEST_DURATION_MS: 'api_request_duration_ms',
+    API_ERRORS_TOTAL: 'api_errors_total',
+    // Neuron metrics
+    NEURONS_TOTAL: 'neurons_total',
+    NEURONS_CREATED: 'neurons_created_total',
+    NEURON_LOOKUPS: 'neuron_lookups_total',
+    NEURON_LOOKUP_DURATION_MS: 'neuron_lookup_duration_ms',
+    // Inference metrics
+    INFERENCE_REQUESTS: 'inference_requests_total',
+    INFERENCE_DURATION_MS: 'inference_duration_ms',
+    // Learning metrics
+    LEARNING_SESSIONS: 'learning_sessions_total',
+    PATTERNS_LEARNED: 'patterns_learned_total',
+    EXTRACTS_CREATED: 'extracts_created_total',
+    // Attractor metrics
+    ATTRACTORS_TOTAL: 'attractors_total',
+    ATTRACTOR_ACTIVATIONS: 'attractor_activations_total',
+    // Probabilistic metrics
+    SUPERPOSITION_COLLAPSES: 'superposition_collapses_total',
+    EVOLUTION_CYCLES: 'evolution_cycles_total',
+    EVOLUTION_DURATION_MS: 'evolution_duration_ms',
+    // System metrics
+    MEMORY_USAGE_BYTES: 'memory_usage_bytes',
+    ACTIVE_CONNECTIONS: 'active_connections',
+};
+//# sourceMappingURL=metrics.js.map

package/dist/utils/metrics.js.map

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

package/dist/utils/similarity.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Vector Similarity Utilities
+ * @module utils/similarity
+ */
+import type { Embedding384 } from '../types/index.js';
+/**
+ * Compute cosine similarity between two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Similarity value between -1 and 1
+ */
+export declare function cosineSimilarity(a: Embedding384 | number[], b: Embedding384 | number[]): number;
+/**
+ * Compute Euclidean distance between two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Distance value (>= 0)
+ */
+export declare function euclideanDistance(a: Embedding384 | number[], b: Embedding384 | number[]): number;
+/**
+ * Compute dot product of two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Dot product value
+ */
+export declare function dotProduct(a: Embedding384 | number[], b: Embedding384 | number[]): number;
+/**
+ * Normalize a vector to unit length
+ * @param v - Vector to normalize
+ * @returns New normalized vector
+ */
+export declare function normalize(v: Embedding384 | number[]): Float32Array;
+/**
+ * Compute the magnitude (L2 norm) of a vector
+ * @param v - Vector
+ * @returns Magnitude value
+ */
+export declare function magnitude(v: Embedding384 | number[]): number;
+/**
+ * Add two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Sum vector
+ */
+export declare function addVectors(a: Embedding384 | number[], b: Embedding384 | number[]): Float32Array;
+/**
+ * Compute centroid (average) of multiple vectors
+ * @param vectors - Array of vectors
+ * @returns Centroid vector
+ */
+export declare function centroid(vectors: (Embedding384 | number[])[]): Float32Array;
+/**
+ * Convert array to Float32Array embedding
+ * @param arr - Number array
+ * @returns Float32Array
+ */
+export declare function toEmbedding(arr: number[]): Embedding384;
+/**
+ * Convert Float32Array to regular array
+ * @param embedding - Float32Array
+ * @returns Number array
+ */
+export declare function fromEmbedding(embedding: Embedding384): number[];
+//# sourceMappingURL=similarity.d.ts.map

package/dist/utils/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../../src/utils/similarity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,MAAM,CAqB/F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,MAAM,CAYhG;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,MAAM,CAUzF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,YAAY,CAclE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,MAAM,CAM5D;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,YAAY,CAU/F;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,CAAC,YAAY,GAAG,MAAM,EAAE,CAAC,EAAE,GAAG,YAAY,CAuB3E;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,YAAY,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,EAAE,CAE/D"}

package/dist/utils/similarity.js

@@ -0,0 +1,151 @@
+/**
+ * Vector Similarity Utilities
+ * @module utils/similarity
+ */
+/**
+ * Compute cosine similarity between two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Similarity value between -1 and 1
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector length mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const ai = a[i];
+        const bi = b[i];
+        dot += ai * bi;
+        normA += ai * ai;
+        normB += bi * bi;
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denominator === 0)
+        return 0;
+    return dot / denominator;
+}
+/**
+ * Compute Euclidean distance between two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Distance value (>= 0)
+ */
+export function euclideanDistance(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector length mismatch: ${a.length} vs ${b.length}`);
+    }
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        const diff = a[i] - b[i];
+        sum += diff * diff;
+    }
+    return Math.sqrt(sum);
+}
+/**
+ * Compute dot product of two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Dot product value
+ */
+export function dotProduct(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector length mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dot = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+    }
+    return dot;
+}
+/**
+ * Normalize a vector to unit length
+ * @param v - Vector to normalize
+ * @returns New normalized vector
+ */
+export function normalize(v) {
+    let norm = 0;
+    for (let i = 0; i < v.length; i++) {
+        norm += v[i] * v[i];
+    }
+    norm = Math.sqrt(norm);
+    const result = new Float32Array(v.length);
+    if (norm === 0)
+        return result;
+    for (let i = 0; i < v.length; i++) {
+        result[i] = v[i] / norm;
+    }
+    return result;
+}
+/**
+ * Compute the magnitude (L2 norm) of a vector
+ * @param v - Vector
+ * @returns Magnitude value
+ */
+export function magnitude(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) {
+        sum += v[i] * v[i];
+    }
+    return Math.sqrt(sum);
+}
+/**
+ * Add two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Sum vector
+ */
+export function addVectors(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector length mismatch: ${a.length} vs ${b.length}`);
+    }
+    const result = new Float32Array(a.length);
+    for (let i = 0; i < a.length; i++) {
+        result[i] = a[i] + b[i];
+    }
+    return result;
+}
+/**
+ * Compute centroid (average) of multiple vectors
+ * @param vectors - Array of vectors
+ * @returns Centroid vector
+ */
+export function centroid(vectors) {
+    if (vectors.length === 0) {
+        throw new Error('Cannot compute centroid of empty array');
+    }
+    const dim = vectors[0].length;
+    const result = new Float32Array(dim);
+    for (const v of vectors) {
+        if (v.length !== dim) {
+            throw new Error(`Vector length mismatch: expected ${dim}, got ${v.length}`);
+        }
+        for (let i = 0; i < dim; i++) {
+            result[i] += v[i];
+        }
+    }
+    const n = vectors.length;
+    for (let i = 0; i < dim; i++) {
+        result[i] /= n;
+    }
+    return result;
+}
+/**
+ * Convert array to Float32Array embedding
+ * @param arr - Number array
+ * @returns Float32Array
+ */
+export function toEmbedding(arr) {
+    return new Float32Array(arr);
+}
+/**
+ * Convert Float32Array to regular array
+ * @param embedding - Float32Array
+ * @returns Number array
+ */
+export function fromEmbedding(embedding) {
+    return Array.from(embedding);
+}
+//# sourceMappingURL=similarity.js.map

package/dist/utils/similarity.js.map

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

package/dist/utils/uuid.d.ts

@@ -0,0 +1,23 @@
+/**
+ * UUID Generation Utilities
+ * @module utils/uuid
+ */
+import type { UUID } from '../types/index.js';
+/**
+ * Generate a new UUID v4
+ * @returns UUID string
+ */
+export declare function generateUUID(): UUID;
+/**
+ * Validate a UUID string
+ * @param str - String to validate
+ * @returns true if valid UUID
+ */
+export declare function isValidUUID(str: string): boolean;
+/**
+ * Generate multiple UUIDs
+ * @param count - Number of UUIDs to generate
+ * @returns Array of UUID strings
+ */
+export declare function generateUUIDs(count: number): UUID[];
+//# sourceMappingURL=uuid.d.ts.map

package/dist/utils/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../src/utils/uuid.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAEnC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAEnD"}