claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
206 lines • 5.9 kB
TypeScript
/**
* 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