agentdb 3.0.0-alpha.2 → 3.0.0-alpha.4

package/dist/src/utils/attention-metrics.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Performance Metrics and Monitoring for Attention Mechanisms
+ * Real-time tracking of latency, throughput, and memory usage
+ */
+export interface AttentionMetrics {
+    mechanism: string;
+    operationCount: number;
+    totalLatencyMs: number;
+    avgLatencyUs: number;
+    minLatencyUs: number;
+    maxLatencyUs: number;
+    p50LatencyUs: number;
+    p95LatencyUs: number;
+    p99LatencyUs: number;
+    throughputOpsPerSec: number;
+    memoryUsageBytes: number;
+    peakMemoryBytes: number;
+    allocationCount: number;
+}
+export interface OperationMetrics {
+    startTime: number;
+    endTime: number;
+    latencyUs: number;
+    memoryBefore: number;
+    memoryAfter: number;
+    memoryDelta: number;
+}
+export declare class AttentionMetricsCollector {
+    private metrics;
+    private startMemory;
+    /**
+     * Start measuring an operation
+     */
+    startOperation(mechanism: string): void;
+    /**
+     * End measuring an operation and record metrics
+     */
+    endOperation(mechanism: string, startTime: number): void;
+    /**
+     * Get aggregated metrics for a mechanism
+     */
+    getMetrics(mechanism: string): AttentionMetrics | null;
+    /**
+     * Get all collected metrics
+     */
+    getAllMetrics(): Map<string, AttentionMetrics>;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Export metrics as JSON
+     */
+    exportJSON(): string;
+    /**
+     * Export metrics in markdown format
+     */
+    exportMarkdown(): string;
+}
+/**
+ * Global metrics collector instance
+ */
+export declare const metricsCollector: AttentionMetricsCollector;
+/**
+ * Decorator for measuring function performance
+ */
+export declare function measurePerformance(mechanism: string): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Helper to measure a synchronous operation
+ */
+export declare function measureSync<T>(mechanism: string, operation: () => T): T;
+/**
+ * Helper to measure an async operation
+ */
+export declare function measureAsync<T>(mechanism: string, operation: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=attention-metrics.d.ts.map

package/dist/src/utils/attention-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention-metrics.d.ts","sourceRoot":"","sources":["../../../src/utils/attention-metrics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,yBAAyB;IACpC,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,WAAW,CAAkC;IAErD;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKvC;;OAEG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAqBxD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAiCtD;;OAEG;IACH,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAW9C;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,UAAU,IAAI,MAAM;IAQpB;;OAEG;IACH,cAAc,IAAI,MAAM;CAwCzB;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,2BAAkC,CAAC;AAEhE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,IAEhD,QAAQ,GAAG,EACX,aAAa,MAAM,EACnB,YAAY,kBAAkB,wBAoBjC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,CAAC,GACjB,CAAC,CAYH;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAYZ"}

package/dist/src/utils/attention-metrics.js

@@ -0,0 +1,178 @@
+/**
+ * Performance Metrics and Monitoring for Attention Mechanisms
+ * Real-time tracking of latency, throughput, and memory usage
+ */
+export class AttentionMetricsCollector {
+    metrics = new Map();
+    startMemory = new Map();
+    /**
+     * Start measuring an operation
+     */
+    startOperation(mechanism) {
+        const memoryBefore = process.memoryUsage().heapUsed;
+        this.startMemory.set(mechanism, memoryBefore);
+    }
+    /**
+     * End measuring an operation and record metrics
+     */
+    endOperation(mechanism, startTime) {
+        const endTime = performance.now();
+        const memoryBefore = this.startMemory.get(mechanism) || 0;
+        const memoryAfter = process.memoryUsage().heapUsed;
+        const operationMetrics = {
+            startTime,
+            endTime,
+            latencyUs: (endTime - startTime) * 1000, // Convert ms to µs
+            memoryBefore,
+            memoryAfter,
+            memoryDelta: memoryAfter - memoryBefore,
+        };
+        if (!this.metrics.has(mechanism)) {
+            this.metrics.set(mechanism, []);
+        }
+        this.metrics.get(mechanism).push(operationMetrics);
+        this.startMemory.delete(mechanism);
+    }
+    /**
+     * Get aggregated metrics for a mechanism
+     */
+    getMetrics(mechanism) {
+        const operations = this.metrics.get(mechanism);
+        if (!operations || operations.length === 0) {
+            return null;
+        }
+        const latencies = operations.map(op => op.latencyUs).sort((a, b) => a - b);
+        const memoryDeltas = operations.map(op => op.memoryDelta);
+        const totalLatencyMs = latencies.reduce((sum, lat) => sum + lat, 0) / 1000;
+        const totalTimeMs = operations[operations.length - 1].endTime - operations[0].startTime;
+        // Calculate percentiles
+        const p50Index = Math.floor(latencies.length * 0.5);
+        const p95Index = Math.floor(latencies.length * 0.95);
+        const p99Index = Math.floor(latencies.length * 0.99);
+        return {
+            mechanism,
+            operationCount: operations.length,
+            totalLatencyMs,
+            avgLatencyUs: latencies.reduce((sum, lat) => sum + lat, 0) / latencies.length,
+            minLatencyUs: latencies[0],
+            maxLatencyUs: latencies[latencies.length - 1],
+            p50LatencyUs: latencies[p50Index],
+            p95LatencyUs: latencies[p95Index],
+            p99LatencyUs: latencies[p99Index],
+            throughputOpsPerSec: totalTimeMs > 0 ? (operations.length / totalTimeMs) * 1000 : 0,
+            memoryUsageBytes: operations[operations.length - 1].memoryAfter,
+            peakMemoryBytes: Math.max(...operations.map(op => op.memoryAfter)),
+            allocationCount: memoryDeltas.filter(delta => delta > 0).length,
+        };
+    }
+    /**
+     * Get all collected metrics
+     */
+    getAllMetrics() {
+        const allMetrics = new Map();
+        for (const mechanism of this.metrics.keys()) {
+            const metrics = this.getMetrics(mechanism);
+            if (metrics) {
+                allMetrics.set(mechanism, metrics);
+            }
+        }
+        return allMetrics;
+    }
+    /**
+     * Reset all metrics
+     */
+    reset() {
+        this.metrics.clear();
+        this.startMemory.clear();
+    }
+    /**
+     * Export metrics as JSON
+     */
+    exportJSON() {
+        const allMetrics = {};
+        for (const [mechanism, metrics] of this.getAllMetrics()) {
+            allMetrics[mechanism] = metrics;
+        }
+        return JSON.stringify(allMetrics, null, 2);
+    }
+    /**
+     * Export metrics in markdown format
+     */
+    exportMarkdown() {
+        const lines = [
+            '# Attention Mechanism Performance Metrics',
+            '',
+            '## Summary',
+            '',
+            '| Mechanism | Ops | Avg Latency (µs) | P95 (µs) | P99 (µs) | Throughput (ops/s) | Memory (MB) |',
+            '|-----------|-----|------------------|----------|----------|-------------------|-------------|',
+        ];
+        for (const [mechanism, metrics] of this.getAllMetrics()) {
+            lines.push(`| ${mechanism} | ${metrics.operationCount} | ${metrics.avgLatencyUs.toFixed(2)} | ${metrics.p95LatencyUs.toFixed(2)} | ${metrics.p99LatencyUs.toFixed(2)} | ${metrics.throughputOpsPerSec.toFixed(2)} | ${(metrics.memoryUsageBytes / 1024 / 1024).toFixed(2)} |`);
+        }
+        lines.push('', '## Detailed Metrics', '');
+        for (const [mechanism, metrics] of this.getAllMetrics()) {
+            lines.push(`### ${mechanism}`, '', `- **Operations**: ${metrics.operationCount}`, `- **Total Latency**: ${metrics.totalLatencyMs.toFixed(2)} ms`, `- **Average Latency**: ${metrics.avgLatencyUs.toFixed(2)} µs`, `- **Min Latency**: ${metrics.minLatencyUs.toFixed(2)} µs`, `- **Max Latency**: ${metrics.maxLatencyUs.toFixed(2)} µs`, `- **P50 Latency**: ${metrics.p50LatencyUs.toFixed(2)} µs`, `- **P95 Latency**: ${metrics.p95LatencyUs.toFixed(2)} µs`, `- **P99 Latency**: ${metrics.p99LatencyUs.toFixed(2)} µs`, `- **Throughput**: ${metrics.throughputOpsPerSec.toFixed(2)} ops/sec`, `- **Memory Usage**: ${(metrics.memoryUsageBytes / 1024 / 1024).toFixed(2)} MB`, `- **Peak Memory**: ${(metrics.peakMemoryBytes / 1024 / 1024).toFixed(2)} MB`, `- **Allocations**: ${metrics.allocationCount}`, '');
+        }
+        return lines.join('\n');
+    }
+}
+/**
+ * Global metrics collector instance
+ */
+export const metricsCollector = new AttentionMetricsCollector();
+/**
+ * Decorator for measuring function performance
+ */
+export function measurePerformance(mechanism) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            metricsCollector.startOperation(mechanism);
+            const startTime = performance.now();
+            try {
+                const result = await originalMethod.apply(this, args);
+                metricsCollector.endOperation(mechanism, startTime);
+                return result;
+            }
+            catch (error) {
+                metricsCollector.endOperation(mechanism, startTime);
+                throw error;
+            }
+        };
+        return descriptor;
+    };
+}
+/**
+ * Helper to measure a synchronous operation
+ */
+export function measureSync(mechanism, operation) {
+    metricsCollector.startOperation(mechanism);
+    const startTime = performance.now();
+    try {
+        const result = operation();
+        metricsCollector.endOperation(mechanism, startTime);
+        return result;
+    }
+    catch (error) {
+        metricsCollector.endOperation(mechanism, startTime);
+        throw error;
+    }
+}
+/**
+ * Helper to measure an async operation
+ */
+export async function measureAsync(mechanism, operation) {
+    metricsCollector.startOperation(mechanism);
+    const startTime = performance.now();
+    try {
+        const result = await operation();
+        metricsCollector.endOperation(mechanism, startTime);
+        return result;
+    }
+    catch (error) {
+        metricsCollector.endOperation(mechanism, startTime);
+        throw error;
+    }
+}
+//# sourceMappingURL=attention-metrics.js.map

package/dist/src/utils/attention-metrics.js.map

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

package/dist/src/utils/vector-math.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared Vector Math Utilities
+ *
+ * Eliminates 8+ duplicate cosineSimilarity implementations across controllers.
+ * Uses 4x loop unrolling from WASMVectorSearch for best JS performance.
+ * Future: WASM SIMD acceleration via P2.2.
+ */
+/**
+ * Cosine similarity with 4x loop unrolling for optimal JS performance.
+ * Handles both number[] and Float32Array inputs.
+ */
+export declare function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number;
+/**
+ * Batch cosine similarity: compute similarity of query against multiple vectors.
+ */
+export declare function batchCosineSimilarity(query: ArrayLike<number>, corpus: ArrayLike<number>[]): number[];
+/**
+ * Convert distance metric to similarity score (0-1).
+ */
+export declare function distanceToSimilarity(distance: number, metric?: 'cosine' | 'l2' | 'ip'): number;
+/**
+ * Serialize embedding to Buffer for storage.
+ */
+export declare function serializeEmbedding(embedding: Float32Array): Buffer;
+/**
+ * Deserialize embedding from Buffer.
+ */
+export declare function deserializeEmbedding(buffer: Buffer): Float32Array;
+//# sourceMappingURL=vector-math.d.ts.map

package/dist/src/utils/vector-math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-math.d.ts","sourceRoot":"","sources":["../../../src/utils/vector-math.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAsBnF;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,CAErG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,GAAG,IAAI,GAAG,IAAe,GAAG,MAAM,CAOxG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,CAElE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAKjE"}

package/dist/src/utils/vector-math.js

@@ -0,0 +1,66 @@
+/**
+ * Shared Vector Math Utilities
+ *
+ * Eliminates 8+ duplicate cosineSimilarity implementations across controllers.
+ * Uses 4x loop unrolling from WASMVectorSearch for best JS performance.
+ * Future: WASM SIMD acceleration via P2.2.
+ */
+/**
+ * Cosine similarity with 4x loop unrolling for optimal JS performance.
+ * Handles both number[] and Float32Array inputs.
+ */
+export function cosineSimilarity(a, b) {
+    const len = Math.min(a.length, b.length);
+    if (len === 0)
+        return 0;
+    let dot = 0, magA = 0, magB = 0;
+    // 4x loop unrolling
+    const unrolled = len - (len % 4);
+    for (let i = 0; i < unrolled; i += 4) {
+        dot += a[i] * b[i] + a[i + 1] * b[i + 1] + a[i + 2] * b[i + 2] + a[i + 3] * b[i + 3];
+        magA += a[i] * a[i] + a[i + 1] * a[i + 1] + a[i + 2] * a[i + 2] + a[i + 3] * a[i + 3];
+        magB += b[i] * b[i] + b[i + 1] * b[i + 1] + b[i + 2] * b[i + 2] + b[i + 3] * b[i + 3];
+    }
+    // Handle remainder
+    for (let i = unrolled; i < len; i++) {
+        dot += a[i] * b[i];
+        magA += a[i] * a[i];
+        magB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(magA) * Math.sqrt(magB);
+    return denom === 0 ? 0 : dot / denom;
+}
+/**
+ * Batch cosine similarity: compute similarity of query against multiple vectors.
+ */
+export function batchCosineSimilarity(query, corpus) {
+    return corpus.map(vec => cosineSimilarity(query, vec));
+}
+/**
+ * Convert distance metric to similarity score (0-1).
+ */
+export function distanceToSimilarity(distance, metric = 'cosine') {
+    switch (metric) {
+        case 'cosine': return 1 - distance;
+        case 'l2': return 1 / (1 + distance);
+        case 'ip': return distance; // inner product is already a similarity
+        default: return 1 - distance;
+    }
+}
+/**
+ * Serialize embedding to Buffer for storage.
+ */
+export function serializeEmbedding(embedding) {
+    return Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+}
+/**
+ * Deserialize embedding from Buffer.
+ */
+export function deserializeEmbedding(buffer) {
+    const ab = new ArrayBuffer(buffer.length);
+    const view = new Uint8Array(ab);
+    for (let i = 0; i < buffer.length; i++)
+        view[i] = buffer[i];
+    return new Float32Array(ab);
+}
+//# sourceMappingURL=vector-math.js.map

package/dist/src/utils/vector-math.js.map

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

package/examples/README.md

@@ -0,0 +1,105 @@
+# AgentDB Examples
+
+Practical examples demonstrating how to use AgentDB programmatically.
+
+## Prerequisites
+
+```bash
+npm install agentdb@alpha
+```
+
+## Examples
+
+### 1. quickstart.js - Basic Usage
+
+Simple example showing database initialization and version checking.
+
+```bash
+node examples/quickstart.js
+```
+
+**What it demonstrates**:
+- Creating a database instance
+- Accessing package version
+- Basic error handling
+
+### 2. reflexion-memory.js _(Coming in alpha.3)_
+
+Store and retrieve episodic memories using the Reflexion pattern.
+
+**Features**:
+- Episode storage
+- Similarity-based retrieval
+- Pattern recognition
+
+### 3. skill-library.js _(Coming in alpha.3)_
+
+Manage reusable skills with version control.
+
+**Features**:
+- Skill storage
+- Version management
+- Skill retrieval
+
+### 4. causal-reasoning.js _(Coming in alpha.3)_
+
+Build causal graphs for explainable AI decisions.
+
+**Features**:
+- Causal edge creation
+- Counterfactual reasoning
+- Causal path queries
+
+## Current Limitations (Alpha.2)
+
+**Note**: The programmatic API is under active development. For alpha.2:
+
+1. **Use CLI for initialization**:
+   ```bash
+   npx agentdb@alpha init --db ./my-database.db
+   ```
+
+2. **Schemas not auto-created**: You must run `agentdb init` before using the database programmatically
+
+3. **Limited examples**: More comprehensive examples coming in alpha.3
+
+## Recommended Workflow (Alpha.2)
+
+### Step 1: Initialize via CLI
+```bash
+npx agentdb@alpha init --db ./agent-memory.db --dimensions 384
+```
+
+### Step 2: Use programmatically
+```javascript
+import { createDatabase } from 'agentdb';
+
+const db = await createDatabase('./agent-memory.db');
+// Database is ready to use
+```
+
+## Coming in Alpha.3
+
+- ✅ Auto-initialization: `AgentDB.create(config)` factory method
+- ✅ Complete examples for all features
+- ✅ TypeScript examples
+- ✅ Integration examples
+
+## Get Help
+
+- **Documentation**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+- **Issues**: https://github.com/ruvnet/agentic-flow/issues
+- **CLI Help**: `npx agentdb@alpha --help`
+
+## Contributing Examples
+
+Have a cool example? Submit a PR!
+
+1. Create your example in `/examples/your-example.js`
+2. Add documentation to this README
+3. Ensure it works with current alpha version
+4. Submit PR with description
+
+---
+
+**Note**: These examples are for AgentDB v2.0 alpha. The API may change before stable release.