agentdb 3.0.0-alpha.9 → 3.1.0

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

@@ -0,0 +1,336 @@
+/**
+ * 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
+ */
+/**
+ * Multi-head attention controller for computing parallel attention patterns
+ */
+export class MultiHeadAttentionController {
+    vectorBackend;
+    memoryStore;
+    dimension;
+    config;
+    headProjections;
+    constructor(vectorBackend = null, config = {}) {
+        this.vectorBackend = vectorBackend;
+        this.memoryStore = new Map();
+        this.dimension = 0;
+        this.headProjections = [];
+        this.config = {
+            numHeads: 8,
+            topK: 10,
+            minScore: 0.0,
+            temperature: 1.0,
+            aggregation: 'average',
+            ...config
+        };
+    }
+    /**
+     * Initialize head projections for a given dimension
+     */
+    initializeProjections(dimension) {
+        const numHeads = this.config.numHeads || 8;
+        const headDim = this.config.headDim || Math.floor(dimension / numHeads);
+        this.headProjections = [];
+        // Create random projection matrices for each head
+        // In practice, these would be learned parameters
+        for (let h = 0; h < numHeads; h++) {
+            const projection = new Float32Array(dimension * headDim);
+            // Xavier initialization
+            const scale = Math.sqrt(2.0 / (dimension + headDim));
+            for (let i = 0; i < projection.length; i++) {
+                projection[i] = (Math.random() * 2 - 1) * scale;
+            }
+            this.headProjections.push(projection);
+        }
+    }
+    /**
+     * Add a memory entry to the attention context
+     */
+    addMemory(entry) {
+        if (!entry.id || !entry.embedding || entry.embedding.length === 0) {
+            throw new Error('Memory entry must have id and non-empty embedding');
+        }
+        if (this.dimension === 0) {
+            this.dimension = entry.embedding.length;
+            this.initializeProjections(this.dimension);
+        }
+        else if (entry.embedding.length !== this.dimension) {
+            throw new Error(`Embedding dimension mismatch: expected ${this.dimension}, got ${entry.embedding.length}`);
+        }
+        this.memoryStore.set(entry.id, entry);
+        if (this.vectorBackend) {
+            const embedding = new Float32Array(entry.embedding);
+            this.vectorBackend.insert(entry.id, embedding, entry.metadata);
+        }
+    }
+    /**
+     * Remove a memory entry
+     */
+    removeMemory(id) {
+        return this.memoryStore.delete(id);
+    }
+    /**
+     * Clear all memories
+     */
+    clearMemories() {
+        this.memoryStore.clear();
+        this.dimension = 0;
+        this.headProjections = [];
+    }
+    /**
+     * Project a vector using a head's projection matrix
+     */
+    projectVector(vector, headIndex) {
+        const projection = this.headProjections[headIndex];
+        if (!projection) {
+            // If no projection available, return sliced view
+            const numHeads = this.config.numHeads || 8;
+            const headDim = Math.floor(vector.length / numHeads);
+            const start = headIndex * headDim;
+            return vector.slice(start, start + headDim);
+        }
+        const headDim = this.config.headDim || Math.floor(this.dimension / (this.config.numHeads || 8));
+        const result = new Array(headDim).fill(0);
+        for (let i = 0; i < headDim; i++) {
+            for (let j = 0; j < vector.length; j++) {
+                result[i] += vector[j] * projection[j * headDim + i];
+            }
+        }
+        return result;
+    }
+    /**
+     * 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
+     */
+    async computeMultiHeadAttention(query, 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 { numHeads = 8, topK = 10, minScore = 0.0, temperature = 1.0, aggregation = 'average' } = config;
+        // Handle empty memory
+        if (this.memoryStore.size === 0) {
+            const emptyHeads = Array(numHeads).fill(null).map((_, i) => ({
+                headIndex: i,
+                attended: [...query].slice(i * Math.floor(query.length / numHeads), (i + 1) * Math.floor(query.length / numHeads)),
+                topScores: []
+            }));
+            return {
+                heads: emptyHeads,
+                attended: [...query],
+                executionTimeMs: performance.now() - startTime
+            };
+        }
+        // Validate dimension
+        if (this.dimension > 0 && query.length !== this.dimension) {
+            throw new Error(`Query dimension mismatch: expected ${this.dimension}, got ${query.length}`);
+        }
+        // Initialize projections if needed
+        if (this.headProjections.length === 0) {
+            this.initializeProjections(query.length);
+        }
+        // Compute attention for each head
+        const heads = [];
+        const allScores = new Map();
+        for (let h = 0; h < numHeads; h++) {
+            const headResult = await this.computeHeadAttention(query, h, topK, minScore, temperature);
+            heads.push(headResult);
+            // Aggregate scores across heads
+            for (const score of headResult.topScores) {
+                const existing = allScores.get(score.id) || 0;
+                allScores.set(score.id, existing + score.score);
+            }
+        }
+        // Aggregate attended outputs from all heads
+        const attended = this.aggregateHeadOutputs(query, heads, aggregation);
+        // Sort aggregated scores
+        const aggregatedScores = Array.from(allScores.entries())
+            .map(([id, score]) => ({ id, score: score / numHeads }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK);
+        const executionTimeMs = performance.now() - startTime;
+        return {
+            heads,
+            attended,
+            aggregatedScores,
+            executionTimeMs
+        };
+    }
+    /**
+     * Compute attention for a single head
+     */
+    async computeHeadAttention(query, headIndex, topK, minScore, temperature) {
+        // Project query to head subspace
+        const projectedQuery = this.projectVector(query, headIndex);
+        const scale = 1.0 / Math.sqrt(projectedQuery.length);
+        // Compute scores for all memories
+        const scores = [];
+        for (const [id, entry] of this.memoryStore.entries()) {
+            const projectedKey = this.projectVector(entry.embedding, headIndex);
+            // Scaled dot-product attention
+            let dotProduct = 0;
+            for (let i = 0; i < projectedQuery.length; i++) {
+                dotProduct += projectedQuery[i] * projectedKey[i];
+            }
+            const scaledScore = dotProduct * scale / temperature;
+            scores.push({ id, score: scaledScore, projectedEmbedding: projectedKey });
+        }
+        // Apply softmax
+        const normalizedScores = this.applySoftmax(scores);
+        // Filter and sort
+        const filteredScores = normalizedScores
+            .filter(item => item.normalizedScore >= minScore)
+            .sort((a, b) => b.normalizedScore - a.normalizedScore)
+            .slice(0, topK);
+        // Compute attended output for this head
+        const headDim = projectedQuery.length;
+        const attended = new Array(headDim).fill(0);
+        for (const item of normalizedScores) {
+            for (let i = 0; i < headDim; i++) {
+                attended[i] += item.normalizedScore * item.projectedEmbedding[i];
+            }
+        }
+        return {
+            headIndex,
+            attended,
+            topScores: filteredScores.map(item => ({
+                id: item.id,
+                score: item.normalizedScore
+            }))
+        };
+    }
+    /**
+     * Apply softmax to scores
+     */
+    applySoftmax(items) {
+        if (items.length === 0)
+            return [];
+        const maxScore = Math.max(...items.map(item => item.score));
+        const expScores = items.map(item => ({
+            ...item,
+            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,
+                normalizedScore: 1 / items.length
+            }));
+        }
+        return expScores.map(item => ({
+            id: item.id,
+            normalizedScore: item.expScore / sumExp,
+            projectedEmbedding: item.projectedEmbedding
+        }));
+    }
+    /**
+     * Aggregate outputs from all attention heads
+     */
+    aggregateHeadOutputs(query, heads, strategy) {
+        if (heads.length === 0) {
+            return [...query];
+        }
+        const dimension = query.length;
+        const numHeads = heads.length;
+        const headDim = heads[0]?.attended.length || Math.floor(dimension / numHeads);
+        switch (strategy) {
+            case 'concat':
+                // Concatenate all head outputs (may change dimension)
+                const concatResult = [];
+                for (const head of heads) {
+                    concatResult.push(...head.attended);
+                }
+                // Pad or truncate to original dimension
+                if (concatResult.length < dimension) {
+                    return [...concatResult, ...new Array(dimension - concatResult.length).fill(0)];
+                }
+                return concatResult.slice(0, dimension);
+            case 'max':
+                // Take element-wise max across reconstructed head outputs
+                const maxResult = new Array(dimension).fill(-Infinity);
+                for (const head of heads) {
+                    const reconstructed = this.reconstructFromHead(head.attended, head.headIndex, dimension);
+                    for (let i = 0; i < dimension; i++) {
+                        maxResult[i] = Math.max(maxResult[i], reconstructed[i]);
+                    }
+                }
+                return maxResult.map(v => isFinite(v) ? v : 0);
+            case 'weighted':
+                // Weight by average attention scores
+                const weightedResult = new Array(dimension).fill(0);
+                const weights = [];
+                for (const head of heads) {
+                    const avgScore = head.topScores.reduce((sum, s) => sum + s.score, 0) /
+                        Math.max(1, head.topScores.length);
+                    weights.push(avgScore);
+                }
+                const totalWeight = weights.reduce((sum, w) => sum + w, 0) || 1;
+                for (let h = 0; h < heads.length; h++) {
+                    const reconstructed = this.reconstructFromHead(heads[h].attended, h, dimension);
+                    const weight = weights[h] / totalWeight;
+                    for (let i = 0; i < dimension; i++) {
+                        weightedResult[i] += weight * reconstructed[i];
+                    }
+                }
+                return weightedResult;
+            case 'average':
+            default:
+                // Average across reconstructed head outputs
+                const avgResult = new Array(dimension).fill(0);
+                for (const head of heads) {
+                    const reconstructed = this.reconstructFromHead(head.attended, head.headIndex, dimension);
+                    for (let i = 0; i < dimension; i++) {
+                        avgResult[i] += reconstructed[i] / numHeads;
+                    }
+                }
+                return avgResult;
+        }
+    }
+    /**
+     * Reconstruct full-dimension vector from head output
+     */
+    reconstructFromHead(headOutput, headIndex, targetDim) {
+        // Simple reconstruction by placing head output in appropriate position
+        const numHeads = this.config.numHeads || 8;
+        const headDim = Math.floor(targetDim / numHeads);
+        const result = new Array(targetDim).fill(0);
+        const start = headIndex * headDim;
+        const len = Math.min(headOutput.length, targetDim - start);
+        for (let i = 0; i < len; i++) {
+            result[start + i] = headOutput[i];
+        }
+        return result;
+    }
+    /**
+     * Get statistics about the controller
+     */
+    getStats() {
+        const numHeads = this.config.numHeads || 8;
+        const headDim = this.config.headDim ||
+            (this.dimension > 0 ? Math.floor(this.dimension / numHeads) : 0);
+        return {
+            memoryCount: this.memoryStore.size,
+            dimension: this.dimension,
+            numHeads,
+            headDim,
+            hasVectorBackend: this.vectorBackend !== null
+        };
+    }
+}
+//# sourceMappingURL=MultiHeadAttentionController.js.map

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

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

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

@@ -0,0 +1,117 @@
+/**
+ * SelfAttentionController - Self-Attention Mechanism for Memory Systems
+ *
+ * Implements self-attention over stored memory entries, allowing the system
+ * to compute attention scores that determine which memories are most relevant
+ * to a given query vector.
+ *
+ * Features:
+ * - Scaled dot-product attention
+ * - Softmax normalization
+ * - Top-k filtering with minimum score threshold
+ * - Efficient batch processing for large memory sets
+ */
+import type { VectorBackend } from '../../backends/VectorBackend.js';
+/**
+ * Configuration for self-attention computation
+ */
+export interface SelfAttentionConfig {
+    /** Number of top results to return */
+    topK?: number;
+    /** Minimum attention score threshold (0-1) */
+    minScore?: number;
+    /** Temperature for softmax scaling */
+    temperature?: number;
+    /** Whether to return attention weights */
+    returnWeights?: boolean;
+}
+/**
+ * Individual attention score for a memory entry
+ */
+export interface AttentionScore {
+    /** Memory entry ID */
+    id: string;
+    /** Computed attention score (0-1 after softmax) */
+    score: number;
+    /** Raw similarity score before softmax */
+    rawScore?: number;
+}
+/**
+ * Result of self-attention computation
+ */
+export interface SelfAttentionResult {
+    /** Attention scores for each memory entry */
+    scores: AttentionScore[];
+    /** Attended output vector (weighted sum of values) */
+    attended: number[];
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+}
+/**
+ * Memory entry with embedding for attention computation
+ */
+export interface MemoryEntry {
+    id: string;
+    embedding: number[];
+    content?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * Self-attention controller for computing attention over memory entries
+ */
+export declare class SelfAttentionController {
+    private vectorBackend;
+    private memoryStore;
+    private dimension;
+    private config;
+    constructor(vectorBackend?: VectorBackend | null, config?: SelfAttentionConfig);
+    /**
+     * Add a memory entry to the attention context
+     */
+    addMemory(entry: MemoryEntry): void;
+    /**
+     * Remove a memory entry from the attention context
+     */
+    removeMemory(id: string): boolean;
+    /**
+     * Clear all memory entries
+     */
+    clearMemories(): void;
+    /**
+     * Compute self-attention for a query vector
+     *
+     * @param query - Query vector for attention computation
+     * @param options - Override default configuration options
+     * @returns Self-attention result with scores and attended output
+     */
+    computeAttention(query: number[], options?: SelfAttentionConfig): Promise<SelfAttentionResult>;
+    /**
+     * Compute dot product between two vectors
+     */
+    private computeDotProduct;
+    /**
+     * Apply softmax normalization to scores
+     */
+    private applySoftmax;
+    /**
+     * Compute attended output as weighted sum of memory embeddings
+     */
+    private computeAttendedOutput;
+    /**
+     * Get the number of memories in the attention context
+     */
+    get memoryCount(): number;
+    /**
+     * Get the embedding dimension
+     */
+    get embeddingDimension(): number;
+    /**
+     * Get statistics about the attention controller
+     */
+    getStats(): {
+        memoryCount: number;
+        dimension: number;
+        hasVectorBackend: boolean;
+    };
+}
+//# sourceMappingURL=SelfAttentionController.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SelfAttentionController.d.ts","sourceRoot":"","sources":["../../../../src/controllers/attention/SelfAttentionController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,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,uBAAuB;IAClC,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAsB;gBAGlC,aAAa,GAAE,aAAa,GAAG,IAAW,EAC1C,MAAM,GAAE,mBAAwB;IAclC;;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;IAKrB;;;;;;OAMG;IACG,gBAAgB,CACpB,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,mBAAmB,CAAC;IA8D/B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IASzB;;OAEG;IACH,OAAO,CAAC,YAAY;IAoCpB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAqB7B;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED;;OAEG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,OAAO,CAAC;KAC3B;CAOF"}

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

@@ -0,0 +1,205 @@
+/**
+ * SelfAttentionController - Self-Attention Mechanism for Memory Systems
+ *
+ * Implements self-attention over stored memory entries, allowing the system
+ * to compute attention scores that determine which memories are most relevant
+ * to a given query vector.
+ *
+ * Features:
+ * - Scaled dot-product attention
+ * - Softmax normalization
+ * - Top-k filtering with minimum score threshold
+ * - Efficient batch processing for large memory sets
+ */
+/**
+ * Self-attention controller for computing attention over memory entries
+ */
+export class SelfAttentionController {
+    vectorBackend;
+    memoryStore;
+    dimension;
+    config;
+    constructor(vectorBackend = null, config = {}) {
+        this.vectorBackend = vectorBackend;
+        this.memoryStore = new Map();
+        this.dimension = 0;
+        this.config = {
+            topK: 10,
+            minScore: 0.0,
+            temperature: 1.0,
+            returnWeights: false,
+            ...config
+        };
+    }
+    /**
+     * Add a memory entry to the attention context
+     */
+    addMemory(entry) {
+        if (!entry.id || !entry.embedding || entry.embedding.length === 0) {
+            throw new Error('Memory 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}`);
+        }
+        this.memoryStore.set(entry.id, entry);
+        // Also add to vector backend if available
+        if (this.vectorBackend) {
+            const embedding = new Float32Array(entry.embedding);
+            this.vectorBackend.insert(entry.id, embedding, entry.metadata);
+        }
+    }
+    /**
+     * Remove a memory entry from the attention context
+     */
+    removeMemory(id) {
+        return this.memoryStore.delete(id);
+    }
+    /**
+     * Clear all memory entries
+     */
+    clearMemories() {
+        this.memoryStore.clear();
+        this.dimension = 0;
+    }
+    /**
+     * Compute self-attention for a query vector
+     *
+     * @param query - Query vector for attention computation
+     * @param options - Override default configuration options
+     * @returns Self-attention result with scores and attended output
+     */
+    async computeAttention(query, 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;
+        // Handle empty memory case
+        if (this.memoryStore.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 using scaled dot-product
+        const rawScores = [];
+        const scale = 1.0 / Math.sqrt(query.length);
+        for (const [id, entry] of this.memoryStore.entries()) {
+            const dotProduct = this.computeDotProduct(query, entry.embedding);
+            const scaledScore = dotProduct * scale / temperature;
+            rawScores.push({ id, 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 (weighted sum of values)
+        const attended = this.computeAttendedOutput(query, normalizedScores);
+        const executionTimeMs = performance.now() - startTime;
+        return {
+            scores: filteredScores.map(item => ({
+                id: item.id,
+                score: item.score,
+                rawScore: item.rawScore
+            })),
+            attended,
+            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 [];
+        // Find max for numerical stability
+        const maxScore = Math.max(...items.map(item => item.score));
+        // Compute exp(score - max) for each item
+        const expScores = items.map(item => ({
+            ...item,
+            rawScore: item.score,
+            expScore: Math.exp(item.score - maxScore)
+        }));
+        // Compute sum for normalization
+        const sumExp = expScores.reduce((sum, item) => sum + item.expScore, 0);
+        // Handle edge case where sum is 0 or very small
+        if (sumExp === 0 || !isFinite(sumExp)) {
+            return items.map(item => ({
+                ...item,
+                rawScore: item.score,
+                score: 1 / items.length
+            }));
+        }
+        // Normalize to get probabilities
+        return expScores.map(item => ({
+            id: item.id,
+            score: item.expScore / sumExp,
+            rawScore: item.rawScore,
+            embedding: item.embedding
+        }));
+    }
+    /**
+     * Compute attended output as weighted sum of memory embeddings
+     */
+    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;
+    }
+    /**
+     * Get the number of memories in the attention context
+     */
+    get memoryCount() {
+        return this.memoryStore.size;
+    }
+    /**
+     * Get the embedding dimension
+     */
+    get embeddingDimension() {
+        return this.dimension;
+    }
+    /**
+     * Get statistics about the attention controller
+     */
+    getStats() {
+        return {
+            memoryCount: this.memoryStore.size,
+            dimension: this.dimension,
+            hasVectorBackend: this.vectorBackend !== null
+        };
+    }
+}
+//# sourceMappingURL=SelfAttentionController.js.map