agentic-qe 2.7.3 → 2.8.0

package/dist/edge/p2p/federated/FederatedCoordinator.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Federated Learning Coordinator
+ *
+ * High-level API for federated learning that coordinates training rounds,
+ * monitors convergence, handles participant failures, and integrates with
+ * AgentChannel for peer communication.
+ *
+ * @module edge/p2p/federated/FederatedCoordinator
+ * @version 1.0.0
+ */
+import type { FederatedConfig, ModelWeights, ModelCheckpoint, TrainingMetrics, PrivacyBudget, FederatedEventHandler } from './types';
+import { ConvergenceStatus } from './types';
+import { GradientAggregator, type GradientAggregatorConfig } from './GradientAggregator';
+import { FederatedRound, type ParticipantInfo } from './FederatedRound';
+import { ModelManager, type ModelManagerConfig } from './ModelManager';
+/**
+ * Coordinator configuration
+ */
+export interface CoordinatorConfig {
+    /** Federated learning configuration */
+    federatedConfig: FederatedConfig;
+    /** Model manager configuration */
+    modelConfig: ModelManagerConfig;
+    /** Gradient aggregator configuration */
+    aggregatorConfig?: Partial<GradientAggregatorConfig>;
+    /** Initial model weights */
+    initialWeights?: ModelWeights;
+    /** Message transport adapter */
+    transport?: TransportAdapter;
+}
+/**
+ * Transport adapter for peer communication
+ */
+export interface TransportAdapter {
+    /** Send message to specific participant */
+    send(participantId: string, message: unknown): Promise<void>;
+    /** Broadcast message to all participants */
+    broadcast(message: unknown): Promise<void>;
+    /** Subscribe to incoming messages */
+    onMessage(handler: (participantId: string, message: unknown) => void): void;
+    /** Get available participants */
+    getAvailableParticipants(): Promise<Map<string, ParticipantInfo>>;
+}
+/**
+ * Training result
+ */
+export interface TrainingResult {
+    /** Whether training completed successfully */
+    success: boolean;
+    /** Final model weights */
+    finalModel: ModelWeights | null;
+    /** Training metrics summary */
+    metrics: TrainingMetrics;
+    /** Final privacy budget status */
+    privacyBudget?: PrivacyBudget;
+    /** Checkpoints created */
+    checkpoints: string[];
+    /** Errors encountered */
+    errors: string[];
+}
+/**
+ * High-level federated learning coordinator
+ *
+ * @example
+ * ```typescript
+ * const coordinator = new FederatedCoordinator({
+ *   federatedConfig: {
+ *     sessionId: 'training-session-1',
+ *     modelId: 'my-model',
+ *     aggregationStrategy: AggregationStrategy.FED_AVG,
+ *     selectionStrategy: SelectionStrategy.RANDOM,
+ *     totalRounds: 100,
+ *     minParticipation: 0.3,
+ *   },
+ *   modelConfig: {
+ *     architecture: modelArchitecture,
+ *     optimizer: { type: 'adam', learningRate: 0.001 },
+ *   },
+ *   transport: channelTransport,
+ * });
+ *
+ * // Start training
+ * coordinator.on(event => console.log(event));
+ * const result = await coordinator.startTraining();
+ * ```
+ */
+export declare class FederatedCoordinator {
+    private config;
+    private federatedConfig;
+    private state;
+    private modelManager;
+    private aggregator;
+    private transport;
+    private eventHandlers;
+    private checkpointIds;
+    private errors;
+    private lossHistory;
+    private accuracyHistory;
+    private roundHistory;
+    constructor(config: CoordinatorConfig);
+    /**
+     * Start federated training
+     */
+    startTraining(): Promise<TrainingResult>;
+    /**
+     * Stop training
+     */
+    stopTraining(reason?: string): void;
+    /**
+     * Pause training (can be resumed)
+     */
+    pauseTraining(): void;
+    /**
+     * Resume training after pause
+     */
+    resumeTraining(): Promise<TrainingResult>;
+    /**
+     * Main training loop
+     */
+    private runTrainingLoop;
+    /**
+     * Run a single training round
+     */
+    private runRound;
+    /**
+     * Update convergence status based on training progress
+     */
+    private updateConvergenceStatus;
+    /**
+     * Check if early stopping should trigger
+     */
+    private shouldStopEarly;
+    /**
+     * Compute variance of an array of numbers
+     */
+    private computeVariance;
+    /**
+     * Get available participants
+     */
+    private getAvailableParticipants;
+    /**
+     * Get minimum required participants
+     */
+    private getMinParticipants;
+    /**
+     * Setup message handling from transport
+     */
+    private setupMessageHandling;
+    /**
+     * Handle incoming message
+     */
+    private handleIncomingMessage;
+    /**
+     * Handle join request
+     */
+    private handleJoinRequest;
+    /**
+     * Handle update submission
+     */
+    private handleUpdateSubmission;
+    /**
+     * Send message to participant
+     */
+    private sendMessage;
+    /**
+     * Broadcast message to all participants
+     */
+    private broadcastMessage;
+    /**
+     * Create a checkpoint of current state
+     */
+    private createCheckpoint;
+    /**
+     * Restore from checkpoint
+     */
+    restoreFromCheckpoint(checkpointId: string): void;
+    /**
+     * Rollback to previous round
+     */
+    rollback(): boolean;
+    /**
+     * Handle round events
+     */
+    private handleRoundEvent;
+    /**
+     * Add event handler
+     */
+    on(handler: FederatedEventHandler): void;
+    /**
+     * Remove event handler
+     */
+    off(handler: FederatedEventHandler): void;
+    /**
+     * Emit event to handlers
+     */
+    private emitEvent;
+    /**
+     * Build training result
+     */
+    private buildTrainingResult;
+    /**
+     * Build training metrics summary
+     */
+    private buildTrainingMetrics;
+    /**
+     * Validate configuration
+     */
+    private validateConfiguration;
+    /**
+     * Get session ID
+     */
+    getSessionId(): string;
+    /**
+     * Check if training is active
+     */
+    isTraining(): boolean;
+    /**
+     * Get current round number
+     */
+    getCurrentRound(): number;
+    /**
+     * Get convergence status
+     */
+    getConvergenceStatus(): ConvergenceStatus;
+    /**
+     * Get current model weights
+     */
+    getModel(): ModelWeights | null;
+    /**
+     * Get model manager
+     */
+    getModelManager(): ModelManager;
+    /**
+     * Get aggregator
+     */
+    getAggregator(): GradientAggregator;
+    /**
+     * Get active round
+     */
+    getActiveRound(): FederatedRound | null;
+    /**
+     * Get training metrics
+     */
+    getMetrics(): TrainingMetrics;
+    /**
+     * Get privacy budget
+     */
+    getPrivacyBudget(): PrivacyBudget | null;
+    /**
+     * Get checkpoints
+     */
+    getCheckpoints(): ModelCheckpoint[];
+    /**
+     * Get configuration
+     */
+    getConfig(): FederatedConfig;
+    /**
+     * Reset coordinator state
+     */
+    reset(): void;
+}
+/**
+ * Create a new federated coordinator
+ */
+export declare function createFederatedCoordinator(config: CoordinatorConfig): FederatedCoordinator;
+/**
+ * Create a minimal federated config
+ */
+export declare function createFederatedConfig(sessionId: string, modelId: string, totalRounds: number, options?: Partial<FederatedConfig>): FederatedConfig;
+//# sourceMappingURL=FederatedCoordinator.d.ts.map

package/dist/edge/p2p/federated/FederatedCoordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FederatedCoordinator.d.ts","sourceRoot":"","sources":["../../../../src/edge/p2p/federated/FederatedCoordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,eAAe,EAEf,eAAe,EACf,aAAa,EAIb,qBAAqB,EAQtB,MAAM,SAAS,CAAC;AACjB,OAAO,EAGL,iBAAiB,EAQlB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,kBAAkB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,EAAE,cAAc,EAAoB,KAAK,eAAe,EAAkB,MAAM,kBAAkB,CAAC;AAC1G,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAA2B,MAAM,gBAAgB,CAAC;AAMhG;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,eAAe,EAAE,eAAe,CAAC;IAEjC,kCAAkC;IAClC,WAAW,EAAE,kBAAkB,CAAC;IAEhC,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAErD,4BAA4B;IAC5B,cAAc,CAAC,EAAE,YAAY,CAAC;IAE9B,gCAAgC;IAChC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D,4CAA4C;IAC5C,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C,qCAAqC;IACrC,SAAS,CAAC,OAAO,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAE5E,iCAAiC;IACjC,wBAAwB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;CACnE;AAwCD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IAEjB,0BAA0B;IAC1B,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;IAEhC,+BAA+B;IAC/B,OAAO,EAAE,eAAe,CAAC;IAEzB,kCAAkC;IAClC,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB,yBAAyB;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,YAAY,CAAsB;gBAE9B,MAAM,EAAE,iBAAiB;IAqDrC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC;IAsE9C;;OAEG;IACH,YAAY,CAAC,MAAM,GAAE,MAAmC,GAAG,IAAI;IAmB/D;;OAEG;IACH,aAAa,IAAI,IAAI;IAMrB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,cAAc,CAAC;IAkC/C;;OAEG;YACW,eAAe;IAgC7B;;OAEG;YACW,QAAQ;IA0GtB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA+D/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAuBvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;YACW,wBAAwB;IAStC;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAU1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAM5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkB7B;;OAEG;YACW,iBAAiB;IAO/B;;OAEG;YACW,sBAAsB;IAKpC;;OAEG;YACW,WAAW;IAMzB;;OAEG;YACW,gBAAgB;IAU9B;;OAEG;YACW,gBAAgB;IAqB9B;;OAEG;IACH,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAYjD;;OAEG;IACH,QAAQ,IAAI,OAAO;IAQnB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiExB;;OAEG;IACH,EAAE,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAIxC;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAOzC;;OAEG;IACH,OAAO,CAAC,SAAS;IAcjB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA8B5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkC7B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,oBAAoB,IAAI,iBAAiB;IAIzC;;OAEG;IACH,QAAQ,IAAI,YAAY,GAAG,IAAI;IAI/B;;OAEG;IACH,eAAe,IAAI,YAAY;IAI/B;;OAEG;IACH,aAAa,IAAI,kBAAkB;IAInC;;OAEG;IACH,cAAc,IAAI,cAAc,GAAG,IAAI;IAIvC;;OAEG;IACH,UAAU,IAAI,eAAe;IAI7B;;OAEG;IACH,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAOxC;;OAEG;IACH,cAAc,IAAI,eAAe,EAAE;IAInC;;OAEG;IACH,SAAS,IAAI,eAAe;IAI5B;;OAEG;IACH,KAAK,IAAI,IAAI;CA2Bd;AAMD;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAE1F;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GACjC,eAAe,CAQjB"}