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

package/dist/src/ruvector/moe-router.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Mixture of Experts (MoE) Router for Dynamic Agent Routing
+ *
+ * Features:
+ * - 8 expert slots for specialized agent types
+ * - Gating network for soft expert selection (top-k)
+ * - Online weight updates via reward signals
+ * - Load balancing with auxiliary loss
+ * - Weight persistence to .swarm/moe-weights.json
+ *
+ * Architecture:
+ * - Input: 384-dim task embedding (from ONNX)
+ * - Hidden: 128-dim layer with ReLU
+ * - Output: 8-dim softmax weights
+ *
+ * @module moe-router
+ */
+/**
+ * Expert type definitions (8 experts)
+ */
+export type ExpertType = 'coder' | 'tester' | 'reviewer' | 'architect' | 'security' | 'performance' | 'researcher' | 'coordinator';
+/**
+ * Expert names in order (index corresponds to expert slot)
+ */
+export declare const EXPERT_NAMES: ExpertType[];
+/**
+ * Number of experts (fixed at 8)
+ */
+export declare const NUM_EXPERTS = 8;
+/**
+ * Input dimension (384 from ONNX MiniLM-L6-v2)
+ */
+export declare const INPUT_DIM = 384;
+/**
+ * Hidden layer dimension
+ */
+export declare const HIDDEN_DIM = 128;
+/**
+ * MoE Router configuration
+ */
+export interface MoERouterConfig {
+    /** Top-k experts to route to (default: 2) */
+    topK: number;
+    /** Learning rate for online updates (default: 0.01) */
+    learningRate: number;
+    /** Temperature for softmax (default: 1.0) */
+    temperature: number;
+    /** Load balancing coefficient (default: 0.01) */
+    loadBalanceCoef: number;
+    /** Path for weight persistence (default: '.swarm/moe-weights.json') */
+    weightsPath: string;
+    /** Auto-save interval in updates (default: 50) */
+    autoSaveInterval: number;
+    /** Enable noise for exploration (default: true) */
+    enableNoise: boolean;
+    /** Noise standard deviation (default: 0.1) */
+    noiseStd: number;
+}
+/**
+ * Expert routing result
+ */
+export interface RoutingResult {
+    /** Selected experts with weights */
+    experts: Array<{
+        name: ExpertType;
+        index: number;
+        weight: number;
+        score: number;
+    }>;
+    /** Raw gating scores (all experts) */
+    allScores: number[];
+    /** Load balance loss */
+    loadBalanceLoss: number;
+    /** Entropy of routing distribution */
+    entropy: number;
+}
+/**
+ * Expert utilization statistics
+ */
+export interface LoadBalanceStats {
+    /** Per-expert utilization (0-1) */
+    utilization: Record<ExpertType, number>;
+    /** Total routing count */
+    totalRoutings: number;
+    /** Per-expert routing count */
+    routingCounts: Record<ExpertType, number>;
+    /** Gini coefficient of load (0 = perfect balance, 1 = all to one) */
+    giniCoefficient: number;
+    /** Coefficient of variation */
+    coefficientOfVariation: number;
+}
+/**
+ * Mixture of Experts Router
+ *
+ * Implements a two-layer gating network:
+ * - Layer 1: Linear(384, 128) + ReLU
+ * - Layer 2: Linear(128, 8) + Softmax
+ *
+ * Uses top-k expert selection with load balancing.
+ */
+export declare class MoERouter {
+    private config;
+    private W1;
+    private b1;
+    private W2;
+    private b2;
+    private hidden;
+    private hiddenWithBias;
+    private hiddenActivated;
+    private logits;
+    private logitsWithBias;
+    private noisyLogits;
+    private probs;
+    private gradW2;
+    private gradb2;
+    private gradW1;
+    private gradb1;
+    private gradHidden;
+    private routingCounts;
+    private totalRoutings;
+    private updateCount;
+    private avgReward;
+    private lastInput;
+    private lastHiddenActivated;
+    private lastProbs;
+    private lastSelectedExperts;
+    constructor(config?: Partial<MoERouterConfig>);
+    /**
+     * Initialize router, loading persisted weights if available
+     */
+    initialize(): Promise<void>;
+    /**
+     * Route task to top-k experts based on embedding
+     *
+     * @param taskEmbedding - 384-dim task embedding from ONNX
+     * @returns Routing result with selected experts and weights
+     */
+    route(taskEmbedding: Float32Array | number[]): RoutingResult;
+    /**
+     * Update expert weights based on reward signal
+     *
+     * Uses REINFORCE-style gradient update:
+     * gradient = reward * d_log_prob / d_weights
+     *
+     * @param expert - Expert that received the reward
+     * @param reward - Reward signal (-1 to 1, positive = good)
+     */
+    updateExpertWeights(expert: ExpertType | number, reward: number): void;
+    /**
+     * Get load balance statistics across all experts
+     */
+    getLoadBalance(): LoadBalanceStats;
+    /**
+     * Get router statistics
+     */
+    getStats(): Record<string, number | string>;
+    /**
+     * Reset all statistics and routing counts
+     */
+    resetStats(): void;
+    /**
+     * Load weights from persistence file
+     */
+    loadWeights(path?: string): Promise<boolean>;
+    /**
+     * Save weights to persistence file
+     */
+    saveWeights(path?: string): Promise<boolean>;
+    /**
+     * Reset weights to random initialization
+     */
+    resetWeights(): void;
+    /**
+     * Select top-k indices from probabilities
+     */
+    private selectTopK;
+    /**
+     * Compute load balance loss for regularization
+     *
+     * Uses auxiliary loss from Switch Transformer:
+     * L_balance = N * sum(f_i * P_i)
+     * where f_i = fraction of tokens routed to expert i
+     *       P_i = average routing probability to expert i
+     */
+    private computeLoadBalanceLoss;
+    /**
+     * Compute Gini coefficient for load distribution
+     */
+    private computeGiniCoefficient;
+}
+/**
+ * Get singleton MoE router instance
+ *
+ * @param config - Optional configuration (only used on first call)
+ * @returns MoE router instance
+ */
+export declare function getMoERouter(config?: Partial<MoERouterConfig>): MoERouter;
+/**
+ * Reset singleton instance (for testing)
+ */
+export declare function resetMoERouter(): void;
+/**
+ * Factory function to create new router
+ */
+export declare function createMoERouter(config?: Partial<MoERouterConfig>): MoERouter;
+//# sourceMappingURL=moe-router.d.ts.map

package/dist/src/ruvector/moe-router.d.ts.map

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