agentic-qe 2.7.4 → 2.8.1

package/dist/nervous-system/adapters/BTSPAdapter.d.ts

@@ -0,0 +1,342 @@
+/**
+ * BTSPAdapter - Behavioral Timescale Synaptic Plasticity Adapter
+ *
+ * Bio-inspired one-shot learning from single examples (vs 32+ examples with RL).
+ * Wraps the WASM-based BTSPLayer and BTSPAssociativeMemory for QE agent integration.
+ *
+ * Key capabilities:
+ * - Learn from single test failure (one-shot association)
+ * - Detect plateau signals (significant learning events)
+ * - EWC-style consolidation for catastrophic forgetting prevention
+ * - Integration with LearningEngine for hybrid RL + BTSP learning
+ *
+ * Reference: Bittner et al. (2017) "Behavioral time scale synaptic plasticity"
+ *
+ * @module nervous-system/adapters/BTSPAdapter
+ */
+import type { TaskExperience } from '../../learning/types.js';
+/**
+ * Configuration for BTSPAdapter
+ */
+export interface BTSPAdapterConfig {
+    /** Number of synapses / input dimension (default: 256) */
+    inputSize: number;
+    /** Output dimension for associative memory (default: 64) */
+    outputSize: number;
+    /** Time constant in milliseconds (default: 2000ms - biological range 1000-3000ms) */
+    tau: number;
+    /** Plateau detection threshold (default: 0.5) */
+    plateauThreshold: number;
+    /** EWC importance weight for consolidation (default: 100) */
+    ewcLambda: number;
+    /** Maximum capacity before consolidation (default: 1000) */
+    maxCapacity: number;
+}
+/**
+ * Result from recall with confidence score
+ */
+export interface RecallResult {
+    /** Retrieved pattern as Float32Array */
+    pattern: Float32Array;
+    /** Confidence score (0-1) based on retrieval quality */
+    confidence: number;
+    /** Latency in milliseconds */
+    latencyMs: number;
+}
+/**
+ * Result from plateau detection
+ */
+export interface PlateauDetectionResult {
+    /** Whether a plateau signal was detected */
+    detected: boolean;
+    /** Magnitude of the learning signal */
+    magnitude: number;
+    /** Prediction error (difference between prediction and actual) */
+    predictionError: number;
+}
+/**
+ * Interface for BTSP one-shot learning capabilities
+ */
+export interface IBTSPLearner {
+    /**
+     * Initialize the BTSP learner (must be called before use)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Associate pattern with target in a single step (one-shot learning)
+     * @param pattern Input pattern to learn
+     * @param target Target value or pattern to associate
+     */
+    associateOneShot(pattern: Float32Array, target: Float32Array | number): void;
+    /**
+     * Batch learning for multiple pattern-target pairs
+     * @param pairs Array of [pattern, target] pairs
+     */
+    associateBatch(pairs: Array<[Float32Array, Float32Array | number]>): void;
+    /**
+     * Retrieve learned association for a query pattern
+     * @param query Query pattern to retrieve association for
+     */
+    recall(query: Float32Array): Float32Array;
+    /**
+     * Retrieve with confidence score indicating retrieval quality
+     * @param query Query pattern to retrieve association for
+     */
+    recallWithConfidence(query: Float32Array): RecallResult;
+    /**
+     * Detect plateau signal (significant learning event)
+     * Used to determine when one-shot learning should occur
+     * @param prediction Current model prediction
+     * @param actual Actual observed value
+     */
+    detectPlateau(prediction: number, actual: number): PlateauDetectionResult;
+    /**
+     * Get current memory capacity utilization
+     */
+    getCapacity(): {
+        used: number;
+        total: number;
+        utilization: number;
+    };
+    /**
+     * Trigger EWC-style consolidation to prevent catastrophic forgetting
+     * Should be called periodically or when capacity is near limit
+     */
+    consolidate(): Promise<void>;
+    /**
+     * Learn from a QE execution experience (integration with LearningEngine)
+     * @param experience Task execution experience from LearningEngine
+     */
+    learnFromExperience(experience: TaskExperience): Promise<void>;
+    /**
+     * One-shot failure learning from test pattern and error signal
+     * @param testPattern Pattern representing the failed test context
+     * @param errorSignal Error signal (negative reward) from failure
+     */
+    learnFromFailure(testPattern: Float32Array, errorSignal: number): void;
+    /**
+     * Check if the adapter is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+/**
+ * BTSPAdapter - Production-ready BTSP one-shot learning adapter
+ *
+ * Provides bio-inspired one-shot learning capabilities for QE agents:
+ * - Single-example learning (vs 32+ examples with traditional RL)
+ * - Sub-millisecond inference (<1ms p95)
+ * - Plateau detection for significant learning signals
+ * - EWC consolidation to prevent catastrophic forgetting
+ *
+ * @example
+ * ```typescript
+ * const adapter = new BTSPAdapter({ inputSize: 256, outputSize: 64 });
+ * await adapter.initialize();
+ *
+ * // One-shot learning from single failure
+ * adapter.learnFromFailure(testPattern, -1.0);
+ *
+ * // Recall learned association
+ * const result = adapter.recallWithConfidence(queryPattern);
+ * console.log(`Confidence: ${result.confidence}`);
+ * ```
+ */
+export declare class BTSPAdapter implements IBTSPLearner {
+    private readonly logger;
+    private readonly config;
+    /** BTSP layer for scalar target associations (pattern -> value) */
+    private btspLayer;
+    /** Associative memory for pattern-to-pattern associations */
+    private associativeMemory;
+    /** Initialization state */
+    private initialized;
+    /** Association counter for capacity tracking */
+    private associationCount;
+    /** Fisher information matrix for EWC consolidation */
+    private fisherDiagonal;
+    /** Stored weights before consolidation */
+    private consolidatedWeights;
+    constructor(config?: Partial<BTSPAdapterConfig>);
+    /**
+     * Initialize WASM module and create BTSP components
+     */
+    initialize(): Promise<void>;
+    /**
+     * Ensure adapter is initialized before operations
+     */
+    private ensureInitialized;
+    /**
+     * Associate pattern with target in a single step (one-shot learning)
+     */
+    associateOneShot(pattern: Float32Array, target: Float32Array | number): void;
+    /**
+     * Batch learning for multiple pattern-target pairs
+     */
+    associateBatch(pairs: Array<[Float32Array, Float32Array | number]>): void;
+    /**
+     * Retrieve learned association for a query pattern
+     */
+    recall(query: Float32Array): Float32Array;
+    /**
+     * Retrieve with confidence score indicating retrieval quality
+     */
+    recallWithConfidence(query: Float32Array): RecallResult;
+    /**
+     * Calculate L2 norm (magnitude) of a pattern
+     */
+    private calculateMagnitude;
+    /**
+     * Detect plateau signal (significant learning event)
+     *
+     * In biological BTSP, a dendritic plateau potential indicates a significant
+     * learning signal. We detect this by measuring prediction error magnitude.
+     */
+    detectPlateau(prediction: number, actual: number): PlateauDetectionResult;
+    /**
+     * Get current memory capacity utilization
+     */
+    getCapacity(): {
+        used: number;
+        total: number;
+        utilization: number;
+    };
+    /**
+     * Trigger EWC-style consolidation to prevent catastrophic forgetting
+     *
+     * Elastic Weight Consolidation (EWC) preserves important synaptic weights
+     * by penalizing changes to weights that were important for previous tasks.
+     */
+    consolidate(): Promise<void>;
+    /**
+     * Learn from a QE execution experience (integration with LearningEngine)
+     *
+     * Converts a TaskExperience into a pattern-target pair for one-shot learning.
+     * Useful for hybrid RL + BTSP learning where significant events trigger
+     * immediate one-shot updates.
+     */
+    learnFromExperience(experience: TaskExperience): Promise<void>;
+    /**
+     * Convert TaskExperience to a fixed-size pattern for BTSP
+     */
+    private experienceToPattern;
+    /**
+     * Simple hash function for string to number
+     */
+    private simpleHash;
+    /**
+     * One-shot failure learning from test pattern and error signal
+     *
+     * Specialized method for learning from test failures, which are
+     * high-value learning signals in QE contexts.
+     */
+    learnFromFailure(testPattern: Float32Array, errorSignal: number): void;
+    /**
+     * Forward pass through BTSP layer (for inference)
+     * Returns the weighted sum based on learned associations
+     */
+    forward(pattern: Float32Array): number;
+    /**
+     * Get the current weights from the BTSP layer
+     */
+    getWeights(): Float32Array;
+    /**
+     * Get the number of synapses (input dimension)
+     */
+    getSize(): number;
+    /**
+     * Reset the BTSP layer to initial state
+     */
+    reset(): void;
+    /**
+     * Check if the adapter is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get adapter statistics
+     */
+    getStats(): {
+        initialized: boolean;
+        associationCount: number;
+        capacity: {
+            used: number;
+            total: number;
+            utilization: number;
+        };
+        config: BTSPAdapterConfig;
+        hasConsolidation: boolean;
+    };
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+    /**
+     * Get the adapter configuration
+     * @returns Configuration object
+     */
+    getConfig(): BTSPAdapterConfig;
+    /**
+     * Get Fisher diagonal for EWC consolidation
+     * @returns Float32Array of Fisher diagonal values
+     */
+    getFisherDiagonal(): Float32Array;
+    /**
+     * Get consolidated weights reference
+     * @returns Float32Array of consolidated weights
+     */
+    getConsolidatedWeights(): Float32Array;
+    /**
+     * Get current association count
+     * @returns Number of stored associations
+     */
+    getAssociationCount(): number;
+    /**
+     * Get all stored associations (for serialization)
+     * Note: This is a placeholder - actual WASM associations may not be directly accessible
+     * @returns Array of pattern-target pairs
+     */
+    getAssociations(): Array<{
+        pattern: Float32Array;
+        target: Float32Array;
+    }>;
+    /**
+     * Restore weights from serialized state
+     * @param weights Float32Array of weights to restore
+     */
+    restoreWeights(weights: Float32Array): void;
+    /**
+     * Restore Fisher diagonal from serialized state
+     * @param fisher Float32Array of Fisher diagonal values
+     */
+    restoreFisherDiagonal(fisher: Float32Array): void;
+    /**
+     * Restore consolidated weights from serialized state
+     * @param weights Float32Array of consolidated weights
+     */
+    restoreConsolidatedWeights(weights: Float32Array): void;
+    /**
+     * Restore association count from serialized state
+     * @param count Number of associations
+     */
+    restoreAssociationCount(count: number): void;
+    /**
+     * Restore associations from serialized state
+     * @param associations Array of pattern-target pairs to restore
+     */
+    restoreAssociations(associations: Array<{
+        pattern: Float32Array;
+        target: Float32Array;
+    }>): void;
+}
+/**
+ * Factory function to create a pre-configured BTSPAdapter for QE agents
+ */
+export declare function createBTSPAdapter(config?: Partial<BTSPAdapterConfig>): BTSPAdapter;
+/**
+ * Default export for convenience
+ */
+export default BTSPAdapter;
+//# sourceMappingURL=BTSPAdapter.d.ts.map

package/dist/nervous-system/adapters/BTSPAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BTSPAdapter.d.ts","sourceRoot":"","sources":["../../../src/nervous-system/adapters/BTSPAdapter.ts"],"names":[],"mappings":"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"}