@sparkleideas/cli 3.1.0-alpha.19 → 3.1.0-alpha.21

package/dist/src/ruvector/q-learning-router.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Q-Learning Router for Task Routing
+ *
+ * Uses reinforcement learning to optimize task routing decisions
+ * based on historical performance and context.
+ *
+ * Features:
+ * - Caching for repeated task patterns (LRU cache)
+ * - Optimized state space with feature hashing
+ * - Epsilon decay with exponential annealing
+ * - Experience replay buffer for stable learning
+ * - Model persistence to .swarm/q-learning-model.json
+ *
+ * @module q-learning-router
+ */
+/**
+ * Q-Learning Router Configuration
+ */
+export interface QLearningRouterConfig {
+    /** Learning rate (default: 0.1) */
+    learningRate: number;
+    /** Discount factor (default: 0.99) */
+    gamma: number;
+    /** Initial exploration rate (default: 1.0) */
+    explorationInitial: number;
+    /** Final exploration rate (default: 0.01) */
+    explorationFinal: number;
+    /** Exploration decay steps (default: 10000) */
+    explorationDecay: number;
+    /** Exploration decay type (default: 'exponential') */
+    explorationDecayType: 'linear' | 'exponential' | 'cosine';
+    /** Maximum states in Q-table (default: 10000) */
+    maxStates: number;
+    /** Number of actions/routes (default: 8) */
+    numActions: number;
+    /** Experience replay buffer size (default: 1000) */
+    replayBufferSize: number;
+    /** Mini-batch size for replay (default: 32) */
+    replayBatchSize: number;
+    /** Enable experience replay (default: true) */
+    enableReplay: boolean;
+    /** Route cache size (default: 256) */
+    cacheSize: number;
+    /** Cache TTL in milliseconds (default: 300000 = 5 minutes) */
+    cacheTTL: number;
+    /** Model persistence path (default: '.swarm/q-learning-model.json') */
+    modelPath: string;
+    /** Auto-save interval in updates (default: 100) */
+    autoSaveInterval: number;
+    /** State space dimensionality for feature hashing (default: 64) */
+    stateSpaceDim: number;
+}
+/**
+ * Route decision result
+ */
+export interface RouteDecision {
+    /** Selected route/action */
+    route: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Q-values for all routes */
+    qValues: number[];
+    /** Was exploration used */
+    explored: boolean;
+    /** Route alternatives */
+    alternatives: Array<{
+        route: string;
+        score: number;
+    }>;
+}
+/**
+ * Q-Learning Router for intelligent task routing
+ *
+ * Optimized with:
+ * - LRU cache for repeated task patterns
+ * - Feature hashing for efficient state space
+ * - Exponential epsilon decay
+ * - Prioritized experience replay
+ * - Model persistence
+ */
+export declare class QLearningRouter {
+    private config;
+    private qTable;
+    private epsilon;
+    private stepCount;
+    private updateCount;
+    private avgTDError;
+    private ruvectorEngine;
+    private useNative;
+    private replayBuffer;
+    private replayBufferIdx;
+    private totalExperiences;
+    private routeCache;
+    private cacheOrder;
+    private cacheHits;
+    private cacheMisses;
+    private featureHashCache;
+    constructor(config?: Partial<QLearningRouterConfig>);
+    /**
+     * Initialize the router, attempting to load ruvector native module
+     * and restore persisted model if available
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load model from persistence file
+     */
+    loadModel(path?: string): Promise<boolean>;
+    /**
+     * Save model to persistence file
+     */
+    saveModel(path?: string): Promise<boolean>;
+    /**
+     * Route a task based on its context
+     * Uses LRU cache for repeated task patterns
+     */
+    route(taskContext: string, explore?: boolean): RouteDecision;
+    /**
+     * Get cached route decision (LRU cache)
+     */
+    private getCachedRoute;
+    /**
+     * Cache a route decision (LRU eviction)
+     */
+    private cacheRoute;
+    /**
+     * Invalidate cache (call after significant Q-table updates)
+     */
+    invalidateCache(): void;
+    /**
+     * Update Q-values based on feedback
+     * Includes experience replay for stable learning
+     */
+    update(taskContext: string, action: string, reward: number, nextContext?: string): number;
+    /**
+     * Internal Q-value update
+     */
+    private updateQValue;
+    /**
+     * Add experience to circular replay buffer
+     */
+    private addToReplayBuffer;
+    /**
+     * Perform prioritized experience replay
+     * Samples mini-batch from buffer and updates Q-values
+     */
+    private experienceReplay;
+    /**
+     * Sample a prioritized batch from replay buffer
+     * Uses proportional prioritization
+     */
+    private samplePrioritizedBatch;
+    /**
+     * Calculate epsilon using configured decay strategy
+     */
+    private calculateEpsilon;
+    /**
+     * Get statistics including cache and replay buffer metrics
+     */
+    getStats(): Record<string, number>;
+    /**
+     * Reset the router (clears all learned data)
+     */
+    reset(): void;
+    /**
+     * Export Q-table for persistence
+     */
+    export(): Record<string, {
+        qValues: number[];
+        visits: number;
+    }>;
+    /**
+     * Import Q-table from persistence
+     */
+    import(data: Record<string, {
+        qValues: number[];
+        visits: number;
+    }>): void;
+    /**
+     * Legacy hash function (kept for backward compatibility)
+     */
+    private hashState;
+    /**
+     * Optimized state hashing using feature extraction
+     * Creates a more semantic representation of the task context
+     */
+    private hashStateOptimized;
+    /**
+     * Extract feature vector from task context
+     * Uses keyword matching and n-gram hashing
+     */
+    private extractFeatures;
+    /**
+     * Convert feature vector to state key
+     * Uses locality-sensitive hashing for similar contexts
+     */
+    private featureVectorToKey;
+    /**
+     * MurmurHash3 32-bit implementation for n-gram hashing
+     */
+    private murmurhash3;
+    private getQValues;
+    private getOrCreateEntry;
+    private argmax;
+    private softmaxConfidence;
+    private pruneQTable;
+}
+/**
+ * Factory function
+ */
+export declare function createQLearningRouter(config?: Partial<QLearningRouterConfig>): QLearningRouter;
+//# sourceMappingURL=q-learning-router.d.ts.map

package/dist/src/ruvector/q-learning-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"q-learning-router.d.ts","sourceRoot":"","sources":["../../../src/ruvector/q-learning-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mCAAmC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,gBAAgB,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,oBAAoB,EAAE,QAAQ,GAAG,aAAa,GAAG,QAAQ,CAAC;IAC1D,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,gBAAgB,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,YAAY,EAAE,OAAO,CAAC;IACtB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2BAA2B;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,yBAAyB;IACzB,YAAY,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AA+GD;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,YAAY,CAAoB;IACxC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,gBAAgB,CAAK;IAG7B,OAAO,CAAC,UAAU,CAAsC;IACxD,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,WAAW,CAAK;IAGxB,OAAO,CAAC,gBAAgB,CAAwC;gBAEpD,MAAM,GAAE,OAAO,CAAC,qBAAqB,CAAM;IAKvD;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAcjC;;OAEG;IACG,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAgChD;;OAEG;IACG,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsChD;;;OAGG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,OAAc,GAAG,aAAa;IAsDlE;;OAEG;IACH,OAAO,CAAC,cAAc;IAqBtB;;OAEG;IACH,OAAO,CAAC,UAAU;IAiBlB;;OAEG;IACH,eAAe,IAAI,IAAI;IAKvB;;;OAGG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM;IAwDzF;;OAEG;IACH,OAAO,CAAC,YAAY;IA0BpB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAwB9B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;OAEG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAyBlC;;OAEG;IACH,KAAK,IAAI,IAAI;IAsBb;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAW/D;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAazE;;OAEG;IACH,OAAO,CAAC,SAAS;IAWjB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAgDvB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAsB1B;;OAEG;IACH,OAAO,CAAC,WAAW;IAyBnB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,WAAW;CASpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,GAAG,eAAe,CAE9F"}