@agentic-qe/v3 3.0.0-alpha.5 → 3.0.0-alpha.7

package/src/neural-optimizer/types.ts

@@ -1,481 +0,0 @@
-/**
- * Agentic QE v3 - Neural Topology Optimizer Types
- * ADR-034: RL-based swarm topology optimization
- *
- * Defines types for neural network-based topology optimization using
- * reinforcement learning with value networks and experience replay.
- */
-
-// ============================================================================
-// Topology Types
-// ============================================================================
-
-/**
- * Agent in the swarm topology
- */
-export interface TopologyAgent {
-  /** Unique agent identifier */
-  readonly id: string;
-
-  /** Agent type (coordinator, worker, specialist, etc.) */
-  readonly type: string;
-
-  /** Agent domain specialization */
-  readonly domain?: string;
-
-  /** Current agent status */
-  readonly status: 'idle' | 'active' | 'busy' | 'offline';
-
-  /** Agent capabilities */
-  readonly capabilities?: string[];
-
-  /** Performance metrics */
-  readonly metrics?: AgentMetrics;
-}
-
-/**
- * Agent performance metrics
- */
-export interface AgentMetrics {
-  /** Tasks completed */
-  tasksCompleted: number;
-
-  /** Average task duration in ms */
-  avgTaskDurationMs: number;
-
-  /** Success rate (0-1) */
-  successRate: number;
-
-  /** Current load (0-1) */
-  currentLoad: number;
-}
-
-/**
- * Connection between agents in topology
- */
-export interface TopologyConnection {
-  /** Source agent ID */
-  readonly from: string;
-
-  /** Target agent ID */
-  readonly to: string;
-
-  /** Connection weight (strength) */
-  weight: number;
-
-  /** Connection latency in ms */
-  latencyMs?: number;
-
-  /** Connection capacity (messages/second) */
-  capacity?: number;
-
-  /** Whether connection is active */
-  active: boolean;
-}
-
-/**
- * Swarm topology structure
- */
-export interface SwarmTopology {
-  /** All agents in the topology */
-  readonly agents: TopologyAgent[];
-
-  /** All connections between agents */
-  readonly connections: TopologyConnection[];
-
-  /** Topology type */
-  readonly type: 'mesh' | 'hierarchical' | 'ring' | 'star' | 'custom';
-
-  /** Topology metadata */
-  readonly metadata?: Record<string, unknown>;
-
-  /** Add a connection */
-  addConnection(from: string, to: string, weight?: number): void;
-
-  /** Remove a connection */
-  removeConnection(from: string, to: string): boolean;
-
-  /** Update connection weight */
-  updateConnectionWeight(from: string, to: string, delta: number): void;
-
-  /** Add an agent */
-  addAgent(agent: TopologyAgent): void;
-
-  /** Remove an agent */
-  removeAgent(agentId: string): boolean;
-
-  /** Get agent by ID */
-  getAgent(agentId: string): TopologyAgent | undefined;
-
-  /** Get connections for an agent */
-  getAgentConnections(agentId: string): TopologyConnection[];
-}
-
-// ============================================================================
-// Optimizer Configuration
-// ============================================================================
-
-/**
- * Neural topology optimizer configuration
- */
-export interface TopologyOptimizerConfig {
-  /** Number of input features for state representation */
-  inputSize: number;
-
-  /** Hidden layer size for value network */
-  hiddenSize: number;
-
-  /** Number of possible topology actions */
-  numActions: number;
-
-  /** Learning rate for value updates (alpha) */
-  learningRate: number;
-
-  /** Discount factor for future rewards (gamma) */
-  gamma: number;
-
-  /** Exploration rate for epsilon-greedy (epsilon) */
-  epsilon: number;
-
-  /** Minimum exploration rate */
-  minEpsilon: number;
-
-  /** Exploration decay rate */
-  epsilonDecay: number;
-
-  /** Weight for communication efficiency in reward */
-  efficiencyWeight: number;
-
-  /** Weight for load balancing in reward */
-  loadBalanceWeight: number;
-
-  /** Weight for latency in reward */
-  latencyWeight: number;
-
-  /** Experience replay buffer size */
-  replayBufferSize: number;
-
-  /** Batch size for training from replay buffer */
-  batchSize: number;
-
-  /** Time step for simulation */
-  dt: number;
-
-  /** Target network update frequency (steps) */
-  targetUpdateFrequency: number;
-
-  /** Minimum experiences before training */
-  minExperiencesForTraining: number;
-}
-
-/**
- * Default optimizer configuration
- */
-export const DEFAULT_OPTIMIZER_CONFIG: TopologyOptimizerConfig = {
-  inputSize: 16,
-  hiddenSize: 64,
-  numActions: 5,
-  learningRate: 0.001,
-  gamma: 0.99,
-  epsilon: 0.3,
-  minEpsilon: 0.01,
-  epsilonDecay: 0.995,
-  efficiencyWeight: 0.3,
-  loadBalanceWeight: 0.2,
-  latencyWeight: 0.2,
-  replayBufferSize: 10000,
-  batchSize: 32,
-  dt: 1.0,
-  targetUpdateFrequency: 100,
-  minExperiencesForTraining: 100,
-};
-
-// ============================================================================
-// Topology Actions
-// ============================================================================
-
-/**
- * Actions that can be taken to modify topology
- */
-export type TopologyAction =
-  | { type: 'add_connection'; from: string; to: string; weight?: number }
-  | { type: 'remove_connection'; from: string; to: string }
-  | { type: 'strengthen_connection'; from: string; to: string; delta: number }
-  | { type: 'weaken_connection'; from: string; to: string; delta: number }
-  | { type: 'no_op' };
-
-/**
- * Action type enumeration
- */
-export type ActionType = TopologyAction['type'];
-
-/**
- * All action types
- */
-export const ACTION_TYPES: readonly ActionType[] = [
-  'add_connection',
-  'remove_connection',
-  'strengthen_connection',
-  'weaken_connection',
-  'no_op',
-] as const;
-
-/**
- * Convert action to index
- */
-export function actionToIndex(action: TopologyAction): number {
-  switch (action.type) {
-    case 'add_connection': return 0;
-    case 'remove_connection': return 1;
-    case 'strengthen_connection': return 2;
-    case 'weaken_connection': return 3;
-    case 'no_op': return 4;
-  }
-}
-
-/**
- * Convert index to action type
- */
-export function indexToActionType(idx: number): ActionType {
-  return ACTION_TYPES[idx % ACTION_TYPES.length];
-}
-
-// ============================================================================
-// State Representation
-// ============================================================================
-
-/**
- * Topology state for RL
- */
-export interface TopologyState {
-  /** Number of agents */
-  agentCount: number;
-
-  /** Number of connections */
-  connectionCount: number;
-
-  /** Graph density (connections / max possible) */
-  density: number;
-
-  /** Average degree */
-  avgDegree: number;
-
-  /** Minimum degree (approximates min-cut) */
-  minDegree: number;
-
-  /** Average connection weight */
-  avgWeight: number;
-
-  /** Weight variance */
-  weightVariance: number;
-
-  /** Average agent load */
-  avgLoad: number;
-
-  /** Load variance (lower is better balanced) */
-  loadVariance: number;
-
-  /** Average latency */
-  avgLatency: number;
-
-  /** Number of idle agents */
-  idleAgents: number;
-
-  /** Number of overloaded agents (load > 0.8) */
-  overloadedAgents: number;
-
-  /** Clustering coefficient */
-  clusteringCoefficient: number;
-
-  /** Current simulation time */
-  time: number;
-
-  /** Additional feature slots */
-  extra: number[];
-}
-
-// ============================================================================
-// Experience Replay
-// ============================================================================
-
-/**
- * Experience tuple for replay buffer
- */
-export interface Experience {
-  /** State before action */
-  state: number[];
-
-  /** Action taken (index) */
-  actionIdx: number;
-
-  /** Reward received */
-  reward: number;
-
-  /** State after action */
-  nextState: number[];
-
-  /** Whether episode ended */
-  done: boolean;
-
-  /** TD error for prioritized replay */
-  tdError: number;
-
-  /** Timestamp */
-  timestamp: number;
-}
-
-// ============================================================================
-// Optimization Results
-// ============================================================================
-
-/**
- * Result of a single optimization step
- */
-export interface OptimizationResult {
-  /** Action taken */
-  action: TopologyAction;
-
-  /** Reward received */
-  reward: number;
-
-  /** New estimated min-cut */
-  newMinCut: number;
-
-  /** Communication efficiency metric */
-  communicationEfficiency: number;
-
-  /** Load balance metric */
-  loadBalance: number;
-
-  /** TD error from value update */
-  tdError: number;
-
-  /** Current exploration rate */
-  epsilon: number;
-
-  /** Value estimate before action */
-  valueBefore: number;
-
-  /** Value estimate after action */
-  valueAfter: number;
-}
-
-/**
- * Optimization statistics over multiple steps
- */
-export interface OptimizationStats {
-  /** Total optimization steps */
-  totalSteps: number;
-
-  /** Total episodes */
-  episodes: number;
-
-  /** Cumulative reward */
-  cumulativeReward: number;
-
-  /** Average reward per step */
-  avgReward: number;
-
-  /** Average TD error */
-  avgTdError: number;
-
-  /** Actions taken by type */
-  actionCounts: Record<ActionType, number>;
-
-  /** Min-cut improvement over time */
-  minCutHistory: number[];
-
-  /** Reward history */
-  rewardHistory: number[];
-
-  /** Current exploration rate */
-  currentEpsilon: number;
-}
-
-// ============================================================================
-// Model Export/Import
-// ============================================================================
-
-/**
- * Exported model format
- */
-export interface ExportedModel {
-  /** Model type identifier */
-  type: 'neural-topology-optimizer';
-
-  /** Model version */
-  version: string;
-
-  /** Configuration used */
-  config: TopologyOptimizerConfig;
-
-  /** Value network weights */
-  valueNetwork: {
-    wHidden: number[][];
-    bHidden: number[];
-    wOutput: number[];
-    bOutput: number;
-  };
-
-  /** Target network weights (if using target network) */
-  targetNetwork?: {
-    wHidden: number[][];
-    bHidden: number[];
-    wOutput: number[];
-    bOutput: number;
-  };
-
-  /** Training statistics */
-  stats: OptimizationStats;
-
-  /** Export timestamp */
-  exportedAt: string;
-}
-
-// ============================================================================
-// Value Network Interface
-// ============================================================================
-
-/**
- * Value network interface
- */
-export interface IValueNetwork {
-  /** Estimate value of a state */
-  estimate(state: number[]): number;
-
-  /** Update weights using TD error */
-  update(state: number[], tdError: number, lr: number): void;
-
-  /** Copy weights from another network */
-  copyFrom(other: IValueNetwork): void;
-
-  /** Export weights */
-  export(): { wHidden: number[][]; bHidden: number[]; wOutput: number[]; bOutput: number };
-
-  /** Import weights */
-  import(weights: { wHidden: number[][]; bHidden: number[]; wOutput: number[]; bOutput: number }): void;
-}
-
-// ============================================================================
-// Replay Buffer Interface
-// ============================================================================
-
-/**
- * Replay buffer interface
- */
-export interface IReplayBuffer {
-  /** Add experience to buffer */
-  push(experience: Experience): void;
-
-  /** Sample experiences for training */
-  sample(batchSize: number): Experience[];
-
-  /** Get buffer length */
-  readonly length: number;
-
-  /** Clear buffer */
-  clear(): void;
-
-  /** Update priorities (for prioritized replay) */
-  updatePriorities(indices: number[], priorities: number[]): void;
-}