agentdb 3.0.0-alpha.10 → 3.0.0-alpha.12

package/dist/src/controllers/attention/CrossAttentionController.js

@@ -0,0 +1,325 @@
+/**
+ * CrossAttentionController - Cross-Attention Mechanism for Memory Systems
+ *
+ * Implements cross-attention between a query and different memory contexts,
+ * allowing the system to attend to multiple namespaces or memory sources
+ * and integrate information across them.
+ *
+ * Features:
+ * - Multiple context namespace support
+ * - Query-context integration
+ * - Flexible aggregation strategies
+ * - Efficient retrieval with vector backends
+ */
+/**
+ * Cross-attention controller for computing attention across memory contexts
+ */
+export class CrossAttentionController {
+    vectorBackend;
+    contextStores;
+    dimension;
+    config;
+    constructor(vectorBackend = null, config = {}) {
+        this.vectorBackend = vectorBackend;
+        this.contextStores = new Map();
+        this.dimension = 0;
+        this.config = {
+            topK: 10,
+            minScore: 0.0,
+            temperature: 1.0,
+            aggregation: 'average',
+            ...config
+        };
+    }
+    /**
+     * Add an entry to a specific context namespace
+     */
+    addToContext(contextName, entry) {
+        if (!entry.id || !entry.embedding || entry.embedding.length === 0) {
+            throw new Error('Context entry must have id and non-empty embedding');
+        }
+        if (this.dimension === 0) {
+            this.dimension = entry.embedding.length;
+        }
+        else if (entry.embedding.length !== this.dimension) {
+            throw new Error(`Embedding dimension mismatch: expected ${this.dimension}, got ${entry.embedding.length}`);
+        }
+        if (!this.contextStores.has(contextName)) {
+            this.contextStores.set(contextName, new Map());
+        }
+        this.contextStores.get(contextName).set(entry.id, entry);
+        // Add to vector backend with context metadata
+        if (this.vectorBackend) {
+            const embedding = new Float32Array(entry.embedding);
+            this.vectorBackend.insert(entry.id, embedding, {
+                ...entry.metadata,
+                __context: contextName
+            });
+        }
+    }
+    /**
+     * Remove an entry from a context
+     */
+    removeFromContext(contextName, id) {
+        const store = this.contextStores.get(contextName);
+        if (!store)
+            return false;
+        return store.delete(id);
+    }
+    /**
+     * Clear a specific context
+     */
+    clearContext(contextName) {
+        this.contextStores.delete(contextName);
+    }
+    /**
+     * Clear all contexts
+     */
+    clearAllContexts() {
+        this.contextStores.clear();
+        this.dimension = 0;
+    }
+    /**
+     * List available context namespaces
+     */
+    listContexts() {
+        return Array.from(this.contextStores.keys());
+    }
+    /**
+     * Compute cross-attention between query and a specific context
+     *
+     * @param query - Query vector for attention computation
+     * @param contextName - Name of the context to attend to
+     * @param options - Override default configuration options
+     * @returns Cross-attention result with scores and attended output
+     */
+    async computeCrossAttention(query, contextName, options = {}) {
+        const startTime = performance.now();
+        // Validate input
+        if (!query || !Array.isArray(query)) {
+            throw new Error('Query must be a non-null array');
+        }
+        const config = { ...this.config, ...options };
+        const { topK = 10, minScore = 0.0, temperature = 1.0 } = config;
+        // Get context store
+        const contextStore = this.contextStores.get(contextName);
+        if (!contextStore || contextStore.size === 0) {
+            return {
+                scores: [],
+                attended: [...query],
+                executionTimeMs: performance.now() - startTime
+            };
+        }
+        // Validate query dimension
+        if (this.dimension > 0 && query.length !== this.dimension) {
+            throw new Error(`Query dimension mismatch: expected ${this.dimension}, got ${query.length}`);
+        }
+        // Compute raw attention scores
+        const rawScores = [];
+        const scale = 1.0 / Math.sqrt(query.length);
+        for (const [id, entry] of contextStore.entries()) {
+            const dotProduct = this.computeDotProduct(query, entry.embedding);
+            const scaledScore = dotProduct * scale / temperature;
+            rawScores.push({
+                id,
+                context: contextName,
+                score: scaledScore,
+                embedding: entry.embedding
+            });
+        }
+        // Apply softmax normalization
+        const normalizedScores = this.applySoftmax(rawScores);
+        // Filter by minimum score and take top-k
+        const filteredScores = normalizedScores
+            .filter(item => item.score >= minScore)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+        // Compute attended output
+        const attended = this.computeAttendedOutput(query, normalizedScores);
+        const executionTimeMs = performance.now() - startTime;
+        return {
+            scores: filteredScores.map(item => ({
+                id: item.id,
+                context: item.context,
+                score: item.score,
+                rawScore: item.rawScore
+            })),
+            attended,
+            executionTimeMs
+        };
+    }
+    /**
+     * Compute cross-attention across multiple contexts
+     *
+     * @param query - Query vector for attention computation
+     * @param contextNames - Names of contexts to attend to (all if empty)
+     * @param options - Override default configuration options
+     * @returns Cross-attention result with aggregated output
+     */
+    async computeMultiContextAttention(query, contextNames = [], options = {}) {
+        const startTime = performance.now();
+        // Use all contexts if none specified
+        const contexts = contextNames.length > 0
+            ? contextNames
+            : Array.from(this.contextStores.keys());
+        if (contexts.length === 0) {
+            return {
+                scores: [],
+                attended: [...query],
+                executionTimeMs: performance.now() - startTime
+            };
+        }
+        const config = { ...this.config, ...options };
+        const { aggregation = 'average' } = config;
+        // Compute attention for each context
+        const contextResults = [];
+        for (const contextName of contexts) {
+            const result = await this.computeCrossAttention(query, contextName, options);
+            contextResults.push(result);
+        }
+        // Aggregate results based on strategy
+        const allScores = [];
+        const contextWeights = {};
+        for (let i = 0; i < contextResults.length; i++) {
+            const result = contextResults[i];
+            const contextName = contexts[i];
+            allScores.push(...result.scores);
+            // Compute context weight based on aggregation strategy
+            const totalScore = result.scores.reduce((sum, s) => sum + s.score, 0);
+            contextWeights[contextName] = totalScore;
+        }
+        // Normalize context weights
+        const totalWeight = Object.values(contextWeights).reduce((sum, w) => sum + w, 0);
+        if (totalWeight > 0) {
+            for (const key of Object.keys(contextWeights)) {
+                contextWeights[key] /= totalWeight;
+            }
+        }
+        // Aggregate attended outputs
+        const attended = this.aggregateAttendedOutputs(query, contextResults.map(r => r.attended), Object.values(contextWeights), aggregation);
+        const executionTimeMs = performance.now() - startTime;
+        return {
+            scores: allScores,
+            attended,
+            contextWeights,
+            executionTimeMs
+        };
+    }
+    /**
+     * Compute dot product between two vectors
+     */
+    computeDotProduct(a, b) {
+        let sum = 0;
+        const len = Math.min(a.length, b.length);
+        for (let i = 0; i < len; i++) {
+            sum += a[i] * b[i];
+        }
+        return sum;
+    }
+    /**
+     * Apply softmax normalization to scores
+     */
+    applySoftmax(items) {
+        if (items.length === 0)
+            return [];
+        const maxScore = Math.max(...items.map(item => item.score));
+        const expScores = items.map(item => ({
+            ...item,
+            rawScore: item.score,
+            expScore: Math.exp(item.score - maxScore)
+        }));
+        const sumExp = expScores.reduce((sum, item) => sum + item.expScore, 0);
+        if (sumExp === 0 || !isFinite(sumExp)) {
+            return items.map(item => ({
+                ...item,
+                rawScore: item.score,
+                score: 1 / items.length
+            }));
+        }
+        return expScores.map(item => ({
+            id: item.id,
+            context: item.context,
+            score: item.expScore / sumExp,
+            rawScore: item.rawScore,
+            embedding: item.embedding
+        }));
+    }
+    /**
+     * Compute attended output as weighted sum
+     */
+    computeAttendedOutput(query, normalizedScores) {
+        if (normalizedScores.length === 0) {
+            return [...query];
+        }
+        const dimension = query.length;
+        const attended = new Array(dimension).fill(0);
+        for (const item of normalizedScores) {
+            const weight = item.score;
+            for (let i = 0; i < dimension; i++) {
+                attended[i] += weight * item.embedding[i];
+            }
+        }
+        return attended;
+    }
+    /**
+     * Aggregate attended outputs from multiple contexts
+     */
+    aggregateAttendedOutputs(query, outputs, weights, strategy) {
+        if (outputs.length === 0) {
+            return [...query];
+        }
+        const dimension = query.length;
+        const result = new Array(dimension).fill(0);
+        switch (strategy) {
+            case 'max':
+                for (let i = 0; i < dimension; i++) {
+                    result[i] = Math.max(...outputs.map(o => o[i] || 0));
+                }
+                break;
+            case 'weighted':
+                for (let j = 0; j < outputs.length; j++) {
+                    const weight = weights[j] || (1 / outputs.length);
+                    for (let i = 0; i < dimension; i++) {
+                        result[i] += weight * (outputs[j][i] || 0);
+                    }
+                }
+                break;
+            case 'average':
+            default:
+                for (let j = 0; j < outputs.length; j++) {
+                    for (let i = 0; i < dimension; i++) {
+                        result[i] += (outputs[j][i] || 0) / outputs.length;
+                    }
+                }
+                break;
+        }
+        return result;
+    }
+    /**
+     * Get the total number of entries across all contexts
+     */
+    get totalEntryCount() {
+        let count = 0;
+        for (const store of this.contextStores.values()) {
+            count += store.size;
+        }
+        return count;
+    }
+    /**
+     * Get statistics about the cross-attention controller
+     */
+    getStats() {
+        const contextsInfo = {};
+        for (const [name, store] of this.contextStores.entries()) {
+            contextsInfo[name] = store.size;
+        }
+        return {
+            contextCount: this.contextStores.size,
+            totalEntries: this.totalEntryCount,
+            dimension: this.dimension,
+            hasVectorBackend: this.vectorBackend !== null,
+            contextsInfo
+        };
+    }
+}
+//# sourceMappingURL=CrossAttentionController.js.map

package/dist/src/controllers/attention/CrossAttentionController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CrossAttentionController.js","sourceRoot":"","sources":["../../../../src/controllers/attention/CrossAttentionController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwDH;;GAEG;AACH,MAAM,OAAO,wBAAwB;IAC3B,aAAa,CAAuB;IACpC,aAAa,CAAyC;IACtD,SAAS,CAAS;IAClB,MAAM,CAAuB;IAErC,YACE,gBAAsC,IAAI,EAC1C,SAA+B,EAAE;QAEjC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,aAAa,GAAG,IAAI,GAAG,EAAE,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG;YACZ,IAAI,EAAE,EAAE;YACR,QAAQ,EAAE,GAAG;YACb,WAAW,EAAE,GAAG;YAChB,WAAW,EAAE,SAAS;YACtB,GAAG,MAAM;SACV,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,WAAmB,EAAE,KAAmB;QACnD,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QAED,IAAI,IAAI,CAAC,SAAS,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;QAC1C,CAAC;aAAM,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CACb,0CAA0C,IAAI,CAAC,SAAS,SAAS,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,CAC1F,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QACjD,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,CAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QAE1D,8CAA8C;QAC9C,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,MAAM,SAAS,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACpD,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE;gBAC7C,GAAG,KAAK,CAAC,QAAQ;gBACjB,SAAS,EAAE,WAAW;aACvB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED;;OAEG;IACH,iBAAiB,CAAC,WAAmB,EAAE,EAAU;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,WAAmB;QAC9B,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,gBAAgB;QACd,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,qBAAqB,CACzB,KAAe,EACf,WAAmB,EACnB,UAAgC,EAAE;QAElC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAEpC,iBAAiB;QACjB,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACpD,CAAC;QAED,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;QAC9C,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,GAAG,GAAG,EAAE,WAAW,GAAG,GAAG,EAAE,GAAG,MAAM,CAAC;QAEhE,oBAAoB;QACpB,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACzD,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC7C,OAAO;gBACL,MAAM,EAAE,EAAE;gBACV,QAAQ,EAAE,CAAC,GAAG,KAAK,CAAC;gBACpB,eAAe,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;aAC/C,CAAC;QACJ,CAAC;QAED,2BAA2B;QAC3B,IAAI,IAAI,CAAC,SAAS,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YAC1D,MAAM,IAAI,KAAK,CACb,sCAAsC,IAAI,CAAC,SAAS,SAAS,KAAK,CAAC,MAAM,EAAE,CAC5E,CAAC;QACJ,CAAC;QAED,+BAA+B;QAC/B,MAAM,SAAS,GAA0E,EAAE,CAAC;QAC5F,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAE5C,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC;YACjD,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;YAClE,MAAM,WAAW,GAAG,UAAU,GAAG,KAAK,GAAG,WAAW,CAAC;YACrD,SAAS,CAAC,IAAI,CAAC;gBACb,EAAE;gBACF,OAAO,EAAE,WAAW;gBACpB,KAAK,EAAE,WAAW;gBAClB,SAAS,EAAE,KAAK,CAAC,SAAS;aAC3B,CAAC,CAAC;QACL,CAAC;QAED,8BAA8B;QAC9B,MAAM,gBAAgB,GAAG,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QAEtD,yCAAyC;QACzC,MAAM,cAAc,GAAG,gBAAgB;aACpC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,QAAQ,CAAC;aACtC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;aACjC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAElB,0BAA0B;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;QAErE,MAAM,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAEtD,OAAO;YACL,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAClC,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB,CAAC,CAAC;YACH,QAAQ;YACR,eAAe;SAChB,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,4BAA4B,CAChC,KAAe,EACf,eAAyB,EAAE,EAC3B,UAAgC,EAAE;QAElC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAEpC,qCAAqC;QACrC,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC;YACtC,CAAC,CAAC,YAAY;YACd,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;QAE1C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO;gBACL,MAAM,EAAE,EAAE;gBACV,QAAQ,EAAE,CAAC,GAAG,KAAK,CAAC;gBACpB,eAAe,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;aAC/C,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;QAC9C,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,GAAG,MAAM,CAAC;QAE3C,qCAAqC;QACrC,MAAM,cAAc,GAA2B,EAAE,CAAC;QAClD,KAAK,MAAM,WAAW,IAAI,QAAQ,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;YAC7E,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QAED,sCAAsC;QACtC,MAAM,SAAS,GAA0B,EAAE,CAAC;QAC5C,MAAM,cAAc,GAA2B,EAAE,CAAC;QAElD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/C,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;YACjC,MAAM,WAAW,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YAEhC,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;YAEjC,uDAAuD;YACvD,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACtE,cAAc,CAAC,WAAW,CAAC,GAAG,UAAU,CAAC;QAC3C,CAAC;QAED,4BAA4B;QAC5B,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACjF,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YACpB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC9C,cAAc,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC;YACrC,CAAC;QACH,CAAC;QAED,6BAA6B;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,wBAAwB,CAC5C,KAAK,EACL,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EACnC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,EAC7B,WAAW,CACZ,CAAC;QAEF,MAAM,eAAe,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAEtD,OAAO;YACL,MAAM,EAAE,SAAS;YACjB,QAAQ;YACR,cAAc;YACd,eAAe;SAChB,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,CAAW,EAAE,CAAW;QAChD,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;YAC7B,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;OAEG;IACK,YAAY,CAClB,KAA4E;QAE5E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAElC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5D,MAAM,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnC,GAAG,IAAI;YACP,QAAQ,EAAE,IAAI,CAAC,KAAK;YACpB,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;SAC1C,CAAC,CAAC,CAAC;QAEJ,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QAEvE,IAAI,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACxB,GAAG,IAAI;gBACP,QAAQ,EAAE,IAAI,CAAC,KAAK;gBACpB,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM;aACxB,CAAC,CAAC,CAAC;QACN,CAAC;QAED,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC5B,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,QAAQ,GAAG,MAAM;YAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS;SAC1B,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;OAEG;IACK,qBAAqB,CAC3B,KAAe,EACf,gBAA0D;QAE1D,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;QAC/B,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAE9C,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC;YAC1B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;gBACnC,QAAQ,CAAC,CAAC,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;OAEG;IACK,wBAAwB,CAC9B,KAAe,EACf,OAAmB,EACnB,OAAiB,EACjB,QAAwC;QAExC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAE5C,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,KAAK;gBACR,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;oBACnC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACvD,CAAC;gBACD,MAAM;YAER,KAAK,UAAU;gBACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBACxC,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;oBAClD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;wBACnC,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;oBAC7C,CAAC;gBACH,CAAC;gBACD,MAAM;YAER,KAAK,SAAS,CAAC;YACf;gBACE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;wBACnC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;oBACrD,CAAC;gBACH,CAAC;gBACD,MAAM;QACV,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,IAAI,eAAe;QACjB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC;YAChD,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC;QACtB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,QAAQ;QAON,MAAM,YAAY,GAA2B,EAAE,CAAC;QAChD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC;YACzD,YAAY,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;QAClC,CAAC;QAED,OAAO;YACL,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI;YACrC,YAAY,EAAE,IAAI,CAAC,eAAe;YAClC,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,gBAAgB,EAAE,IAAI,CAAC,aAAa,KAAK,IAAI;YAC7C,YAAY;SACb,CAAC;IACJ,CAAC;CACF"}

package/dist/src/controllers/attention/MultiHeadAttentionController.d.ts

@@ -0,0 +1,137 @@
+/**
+ * MultiHeadAttentionController - Multi-Head Attention for Memory Systems
+ *
+ * Implements multi-head attention that projects queries and memory entries
+ * into multiple subspaces, computes attention in each, and aggregates the
+ * results. This allows the model to attend to different aspects of the
+ * information simultaneously.
+ *
+ * Features:
+ * - Configurable number of attention heads
+ * - Multiple aggregation strategies (average, max, concat)
+ * - Per-head dimension control
+ * - Parallel attention computation
+ */
+import type { VectorBackend } from '../../backends/VectorBackend.js';
+/**
+ * Configuration for multi-head attention computation
+ */
+export interface MultiHeadAttentionConfig {
+    /** Number of attention heads */
+    numHeads?: number;
+    /** Dimension per head (auto-calculated if not specified) */
+    headDim?: number;
+    /** Number of top results to return per head */
+    topK?: number;
+    /** Minimum attention score threshold (0-1) */
+    minScore?: number;
+    /** Temperature for softmax scaling */
+    temperature?: number;
+    /** Aggregation strategy for combining head outputs */
+    aggregation?: 'average' | 'max' | 'concat' | 'weighted';
+}
+/**
+ * Attention output from a single head
+ */
+export interface HeadAttentionOutput {
+    /** Head index */
+    headIndex: number;
+    /** Attended output from this head */
+    attended: number[];
+    /** Top attention scores for this head */
+    topScores: {
+        id: string;
+        score: number;
+    }[];
+}
+/**
+ * Result of multi-head attention computation
+ */
+export interface MultiHeadAttentionResult {
+    /** Per-head attention outputs */
+    heads: HeadAttentionOutput[];
+    /** Aggregated attended output */
+    attended: number[];
+    /** Overall top scores across all heads */
+    aggregatedScores?: {
+        id: string;
+        score: number;
+    }[];
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * Memory entry with embedding for multi-head attention
+ */
+export interface MemoryEntry {
+    id: string;
+    embedding: number[];
+    content?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Multi-head attention controller for computing parallel attention patterns
+ */
+export declare class MultiHeadAttentionController {
+    private vectorBackend;
+    private memoryStore;
+    private dimension;
+    private config;
+    private headProjections;
+    constructor(vectorBackend?: VectorBackend | null, config?: MultiHeadAttentionConfig);
+    /**
+     * Initialize head projections for a given dimension
+     */
+    private initializeProjections;
+    /**
+     * Add a memory entry to the attention context
+     */
+    addMemory(entry: MemoryEntry): void;
+    /**
+     * Remove a memory entry
+     */
+    removeMemory(id: string): boolean;
+    /**
+     * Clear all memories
+     */
+    clearMemories(): void;
+    /**
+     * Project a vector using a head's projection matrix
+     */
+    private projectVector;
+    /**
+     * Compute multi-head attention for a query vector
+     *
+     * @param query - Query vector for attention computation
+     * @param options - Override default configuration options
+     * @returns Multi-head attention result with per-head outputs and aggregated result
+     */
+    computeMultiHeadAttention(query: number[], options?: MultiHeadAttentionConfig): Promise<MultiHeadAttentionResult>;
+    /**
+     * Compute attention for a single head
+     */
+    private computeHeadAttention;
+    /**
+     * Apply softmax to scores
+     */
+    private applySoftmax;
+    /**
+     * Aggregate outputs from all attention heads
+     */
+    private aggregateHeadOutputs;
+    /**
+     * Reconstruct full-dimension vector from head output
+     */
+    private reconstructFromHead;
+    /**
+     * Get statistics about the controller
+     */
+    getStats(): {
+        memoryCount: number;
+        dimension: number;
+        numHeads: number;
+        headDim: number;
+        hasVectorBackend: boolean;
+    };
+}
+//# sourceMappingURL=MultiHeadAttentionController.d.ts.map

package/dist/src/controllers/attention/MultiHeadAttentionController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultiHeadAttentionController.d.ts","sourceRoot":"","sources":["../../../../src/controllers/attention/MultiHeadAttentionController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,WAAW,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,UAAU,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,yCAAyC;IACzC,SAAS,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,iCAAiC;IACjC,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnD,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,qBAAa,4BAA4B;IACvC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,eAAe,CAAiB;gBAGtC,aAAa,GAAE,aAAa,GAAG,IAAW,EAC1C,MAAM,GAAE,wBAA6B;IAgBvC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAsBnC;;OAEG;IACH,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIjC;;OAEG;IACH,aAAa,IAAI,IAAI;IAMrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAsBrB;;;;;;OAMG;IACG,yBAAyB,CAC7B,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,wBAAwB,CAAC;IAmFpC;;OAEG;YACW,oBAAoB;IAwDlC;;OAEG;IACH,OAAO,CAAC,YAAY;IA2BpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAyE5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;OAEG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,OAAO,CAAC;KAC3B;CAaF"}