@epfml/discojs 2.1.2-p20240723143623.0 → 2.1.2-p20240723160120.0

package/dist/aggregator/base.d.ts

@@ -1,5 +1,6 @@
 import { Map, Set } from 'immutable';
-import type { client, Model, AsyncInformant } from '../index.js';
+import type { client } from '../index.js';
+import { EventEmitter } from '../utils/event_emitter.js';
 export declare enum AggregationStep {
     ADD = 0,
     UPDATE = 1,
@@ -8,12 +9,13 @@ export declare enum AggregationStep {
 /**
  * Main, abstract, aggregator class whose role is to buffer contributions and to produce
  * a result based off their aggregation, whenever some defined condition is met.
+ *
+ * Emits an event whenever an aggregation step is performed.
+ * Users wait for this event to fetch the aggregation result.
  */
-export declare abstract class Base<T> {
-    /**
-     * The Model whose weights are updated on aggregation.
-     */
-    protected _model?: Model | undefined;
+export declare abstract class Base<T> extends EventEmitter<{
+    'aggregation': T;
+}> {
     /**
      * The round cut-off for contributions.
      */
@@ -33,19 +35,6 @@ export declare abstract class Base<T> {
      * of all active nodes, depending on the aggregation scheme.
      */
     protected contributions: Map<number, Map<client.NodeID, T>>;
-    /**
-     * Emits the aggregation event whenever an aggregation step is performed.
-     * Triggers the resolve of the result promise and the preparation for the
-     * next aggregation round.
-     */
-    private readonly eventEmitter;
-    protected informant?: AsyncInformant<T>;
-    /**
-     * The result promise which, on resolve, will contain the current aggregation result.
-     * This promise should be fetched by any object making use of an aggregator, in order
-     * to await upon aggregation.
-     */
-    protected result: Promise<T>;
     /**
      * The current aggregation round, used for assessing whether a node contribution is recent enough
      * or not.
@@ -59,10 +48,6 @@ export declare abstract class Base<T> {
      */
     protected _communicationRound: number;
     constructor(
-    /**
-     * The Model whose weights are updated on aggregation.
-     */
-    _model?: Model | undefined, 
     /**
      * The round cut-off for contributions.
      */
@@ -85,7 +70,6 @@ export declare abstract class Base<T> {
      * Must store the aggregation's result in the aggregator's result promise.
      */
     abstract aggregate(): void;
-    registerObserver(informant: AsyncInformant<T>): void;
     /**
      * Returns whether the given round is recent enough, dependent on the
      * aggregator's round cutoff.
@@ -99,11 +83,6 @@ export declare abstract class Base<T> {
      * @param from The node which triggered the logging message
      */
     log(step: AggregationStep, from?: client.NodeID): void;
-    /**
-     * Sets the aggregator's model.
-     * @param model The new model
-     */
-    setModel(model: Model): void;
     /**
      * Adds a node's id to the set of active nodes. A node represents an active neighbor
      * peer/client within the network, whom we are communicating with during this aggregation
@@ -130,27 +109,12 @@ export declare abstract class Base<T> {
      * @param round The new round
      */
     setRound(round: number): void;
-    /**
-     * Emits the event containing the aggregation result, which allows the result
-     * promise to resolve and for the next aggregation round to take place.
-     * @param aggregated The aggregation result
-     */
-    protected emit(aggregated: T): void;
     /**
      * Updates the aggregator's state to proceed to the next communication round.
      * If all communication rounds were performed, proceeds to the next aggregation round
      * and empties the collection of stored contributions.
      */
     nextRound(): void;
-    private makeResult;
-    /**
-     * Aggregation steps are performed asynchronously, yet can be awaited upon when required.
-     * This function gives access to the current aggregation result's promise, which will
-     * eventually resolve and contain the result of the very next aggregation step, at the
-     * time of the function call.
-     * @returns The promise containing the aggregation result
-     */
-    receiveResult(): Promise<T>;
     /**
      * Constructs the payloads sent to other nodes as contribution.
      * @param base Object from which the payload is computed
@@ -170,10 +134,6 @@ export declare abstract class Base<T> {
      * the amount of all active nodes times the number of communication rounds.
      */
     get size(): number;
-    /**
-     * The aggregator's current model.
-     */
-    get model(): Model | undefined;
     /**
      * The current communication round.
      */

package/dist/aggregator/base.js

@@ -9,9 +9,11 @@ export var AggregationStep;
 /**
  * Main, abstract, aggregator class whose role is to buffer contributions and to produce
  * a result based off their aggregation, whenever some defined condition is met.
+ *
+ * Emits an event whenever an aggregation step is performed.
+ * Users wait for this event to fetch the aggregation result.
  */
-export class Base {
-    _model;
+export class Base extends EventEmitter {
     roundCutoff;
     communicationRounds;
     /**
@@ -26,19 +28,6 @@ export class Base {
      */
     // communication round -> NodeID -> T
     contributions;
-    /**
-     * Emits the aggregation event whenever an aggregation step is performed.
-     * Triggers the resolve of the result promise and the preparation for the
-     * next aggregation round.
-     */
-    eventEmitter = new EventEmitter();
-    informant;
-    /**
-     * The result promise which, on resolve, will contain the current aggregation result.
-     * This promise should be fetched by any object making use of an aggregator, in order
-     * to await upon aggregation.
-     */
-    result;
     /**
      * The current aggregation round, used for assessing whether a node contribution is recent enough
      * or not.
@@ -52,10 +41,6 @@ export class Base {
      */
     _communicationRound = 0;
     constructor(
-    /**
-     * The Model whose weights are updated on aggregation.
-     */
-    _model, 
     /**
      * The round cut-off for contributions.
      */
@@ -64,21 +49,14 @@ export class Base {
      * The number of communication rounds occurring during any given aggregation round.
      */
     communicationRounds = 1) {
-        this._model = _model;
+        super();
         this.roundCutoff = roundCutoff;
         this.communicationRounds = communicationRounds;
         this.contributions = Map();
         this._nodes = Set();
-        // Make the initial result promise
-        this.result = this.makeResult();
         // On every aggregation, update the object's state to match the current aggregation
         // and communication rounds.
-        this.eventEmitter.on('aggregation', () => {
-            this.nextRound();
-        });
-    }
-    registerObserver(informant) {
-        this.informant = informant;
+        this.on('aggregation', () => this.nextRound());
     }
     /**
      * Returns whether the given round is recent enough, dependent on the
@@ -115,13 +93,6 @@ export class Base {
             }
         }
     }
-    /**
-     * Sets the aggregator's model.
-     * @param model The new model
-     */
-    setModel(model) {
-        this._model = model;
-    }
     /**
      * Adds a node's id to the set of active nodes. A node represents an active neighbor
      * peer/client within the network, whom we are communicating with during this aggregation
@@ -162,14 +133,6 @@ export class Base {
             this._round = round;
         }
     }
-    /**
-     * Emits the event containing the aggregation result, which allows the result
-     * promise to resolve and for the next aggregation round to take place.
-     * @param aggregated The aggregation result
-     */
-    emit(aggregated) {
-        this.eventEmitter.emit('aggregation', aggregated);
-    }
     /**
      * Updates the aggregator's state to proceed to the next communication round.
      * If all communication rounds were performed, proceeds to the next aggregation round
@@ -181,25 +144,6 @@ export class Base {
             this._round++;
             this.contributions = Map();
         }
-        this.result = this.makeResult();
-        this.informant?.update();
-    }
-    async makeResult() {
-        return await new Promise((resolve) => {
-            this.eventEmitter.once('aggregation', (w) => {
-                resolve(w);
-            });
-        });
-    }
-    /**
-     * Aggregation steps are performed asynchronously, yet can be awaited upon when required.
-     * This function gives access to the current aggregation result's promise, which will
-     * eventually resolve and contain the result of the very next aggregation step, at the
-     * time of the function call.
-     * @returns The promise containing the aggregation result
-     */
-    async receiveResult() {
-        return await this.result;
     }
     /**
      * The set of node ids, representing our neighbors within the network.
@@ -223,12 +167,6 @@ export class Base {
             .map((m) => m.size)
             .reduce((totalSize, size) => totalSize + size) ?? 0;
     }
-    /**
-     * The aggregator's current model.
-     */
-    get model() {
-        return this._model;
-    }
     /**
      * The current communication round.
      */

package/dist/aggregator/get.d.ts

@@ -1,8 +1,6 @@
 import type { Task } from '../index.js';
 import { aggregator } from '../index.js';
-import type { Model } from "../index.js";
 type AggregatorOptions = Partial<{
-    model: Model;
     scheme: Task['trainingInformation']['scheme'];
     roundCutOff: number;
     threshold: number;

package/dist/aggregator/get.js

@@ -25,7 +25,7 @@ export function getAggregator(task, options = {}) {
             if (scheme === 'decentralized') {
                 // If options are not specified, we default to expecting a contribution from all peers, so we set the threshold to 100%
                 options = {
-                    model: undefined, roundCutOff: undefined, threshold: 1, thresholdType: 'relative',
+                    roundCutOff: undefined, threshold: 1, thresholdType: 'relative',
                     ...options
                 };
             }
@@ -34,15 +34,15 @@ export function getAggregator(task, options = {}) {
                 // so we set the aggregation threshold to 1 contribution
                 // If scheme == 'local' then we only expect our own contribution
                 options = {
-                    model: undefined, roundCutOff: undefined, threshold: 1, thresholdType: 'absolute',
+                    roundCutOff: undefined, threshold: 1, thresholdType: 'absolute',
                     ...options
                 };
             }
-            return new aggregator.MeanAggregator(options.model, options.roundCutOff, options.threshold, options.thresholdType);
+            return new aggregator.MeanAggregator(options.roundCutOff, options.threshold, options.thresholdType);
         case 'secure':
             if (scheme !== 'decentralized') {
                 throw new Error('secure aggregation is currently supported for decentralized only');
             }
-            return new aggregator.SecureAggregator(options.model, task.trainingInformation.maxShareValue);
+            return new aggregator.SecureAggregator(task.trainingInformation.maxShareValue);
     }
 }

package/dist/aggregator/mean.d.ts

@@ -1,6 +1,6 @@
 import type { Map } from "immutable";
 import { Base as Aggregator } from "./base.js";
-import type { Model, WeightsContainer, client } from "../index.js";
+import type { WeightsContainer, client } from "../index.js";
 type ThresholdType = 'relative' | 'absolute';
 /**
  * Mean aggregator whose aggregation step consists in computing the mean of the received weights.
@@ -27,7 +27,7 @@ export declare class MeanAggregator extends Aggregator<WeightsContainer> {
      * If 0 then only accept contributions from the current round,
      * if 1 then the current round and the previous one, etc.
      */
-    constructor(model?: Model, roundCutoff?: number, threshold?: number, thresholdType?: ThresholdType);
+    constructor(roundCutoff?: number, threshold?: number, thresholdType?: ThresholdType);
     /** Checks whether the contributions buffer is full. */
     isFull(): boolean;
     add(nodeId: client.NodeID, contribution: WeightsContainer, round: number, currentContributions?: number): boolean;

package/dist/aggregator/mean.js

@@ -26,12 +26,12 @@ export class MeanAggregator extends Aggregator {
      * If 0 then only accept contributions from the current round,
      * if 1 then the current round and the previous one, etc.
      */
-    constructor(model, roundCutoff = 0, threshold = 1, thresholdType) {
+    constructor(roundCutoff = 0, threshold = 1, thresholdType) {
         if (threshold <= 0)
             throw new Error("threshold must be strictly positive");
         if (threshold > 1 && (!Number.isInteger(threshold)))
             throw new Error("absolute thresholds must be integral");
-        super(model, roundCutoff, 1);
+        super(roundCutoff, 1);
         this.#threshold = threshold;
         if (threshold < 1) {
             // Throw exception if threshold and thresholdType are conflicting
@@ -81,7 +81,6 @@ export class MeanAggregator extends Aggregator {
             ? AggregationStep.UPDATE
             : AggregationStep.ADD, nodeId);
         this.contributions = this.contributions.setIn([0, nodeId], contribution);
-        this.informant?.update();
         if (this.isFull())
             this.aggregate();
         return true;
@@ -92,9 +91,7 @@ export class MeanAggregator extends Aggregator {
             throw new Error("aggregating without any contribution");
         this.log(AggregationStep.AGGREGATE);
         const result = aggregation.avg(currentContributions.values());
-        if (this.model !== undefined)
-            this.model.weights = result;
-        this.emit(result);
+        this.emit('aggregation', result);
     }
     makePayloads(weights) {
         // Communicate our local weights to every other node, be it a peer or a server

package/dist/aggregator/secure.d.ts

@@ -1,6 +1,6 @@
 import { Map, List } from "immutable";
 import { Base as Aggregator } from "./base.js";
-import type { Model, WeightsContainer, client } from "../index.js";
+import type { WeightsContainer, client } from "../index.js";
 /**
  * Aggregator implementing secure multi-party computation for decentralized learning.
  * An aggregation consists of two communication rounds:
@@ -10,7 +10,7 @@ import type { Model, WeightsContainer, client } from "../index.js";
  */
 export declare class SecureAggregator extends Aggregator<WeightsContainer> {
     private readonly maxShareValue;
-    constructor(model?: Model, maxShareValue?: number);
+    constructor(maxShareValue?: number);
     aggregate(): void;
     add(nodeId: client.NodeID, contribution: WeightsContainer, round: number, communicationRound?: number): boolean;
     isFull(): boolean;

package/dist/aggregator/secure.js

@@ -11,8 +11,8 @@ import { aggregation } from "../index.js";
  */
 export class SecureAggregator extends Aggregator {
     maxShareValue;
-    constructor(model, maxShareValue = 100) {
-        super(model, 0, 2);
+    constructor(maxShareValue = 100) {
+        super(0, 2);
         this.maxShareValue = maxShareValue;
     }
     aggregate() {
@@ -24,7 +24,7 @@ export class SecureAggregator extends Aggregator {
                 if (currentContributions === undefined)
                     throw new Error("aggregating without any contribution");
                 const result = aggregation.sum(currentContributions.values());
-                this.emit(result);
+                this.emit('aggregation', result);
                 break;
             }
             // Average the received partial sums
@@ -33,9 +33,7 @@ export class SecureAggregator extends Aggregator {
                 if (currentContributions === undefined)
                     throw new Error("aggregating without any contribution");
                 const result = aggregation.avg(currentContributions.values());
-                if (this.model !== undefined)
-                    this.model.weights = result;
-                this.emit(result);
+                this.emit('aggregation', result);
                 break;
             }
             default:
@@ -56,7 +54,6 @@ export class SecureAggregator extends Aggregator {
             ? AggregationStep.UPDATE
             : AggregationStep.ADD, nodeId);
         this.contributions = this.contributions.setIn([communicationRound, nodeId], contribution);
-        this.informant?.update();
         if (this.isFull())
             this.aggregate();
         return true;

package/dist/client/base.d.ts

@@ -67,8 +67,9 @@ export declare abstract class Base {
      * Communication callback called the end of every training round.
      * @param _weights The most recent local weight updates
      * @param _round The current training round
+     * @returns aggregated weights or the local weights upon error
      */
-    onRoundEndCommunication(_weights: WeightsContainer, _round: number): Promise<void>;
+    abstract onRoundEndCommunication(_weights: WeightsContainer, _round: number): Promise<WeightsContainer>;
     get nbOfParticipants(): number;
     get ownId(): NodeID;
     get server(): EventConnection;

package/dist/client/base.js

@@ -64,12 +64,6 @@ export class Base {
      * @param _round The current training round
      */
     async onRoundBeginCommunication(_weights, _round) { }
-    /**
-     * Communication callback called the end of every training round.
-     * @param _weights The most recent local weight updates
-     * @param _round The current training round
-     */
-    async onRoundEndCommunication(_weights, _round) { }
     // Number of contributors to a collaborative session
     // If decentralized, it should be the number of peers
     // If federated, it should the number of participants excluding the server

package/dist/client/decentralized/base.d.ts

@@ -1,4 +1,4 @@
-import { type WeightsContainer } from '../../index.js';
+import type { WeightsContainer } from "../../index.js";
 import { Client } from '../index.js';
 /**
  * Represents a decentralized client in a network of peers. Peers coordinate each other with the
@@ -45,5 +45,5 @@ export declare class Base extends Client {
      * @param round
      */
     private receivePayloads;
-    onRoundEndCommunication(weights: WeightsContainer, round: number): Promise<void>;
+    onRoundEndCommunication(weights: WeightsContainer, round: number): Promise<WeightsContainer>;
 }

package/dist/client/decentralized/base.js

@@ -1,5 +1,5 @@
 import { Map, Set } from 'immutable';
-import { serialization } from '../../index.js';
+import { serialization } from "../../index.js";
 import { Client } from '../index.js';
 import { type } from '../messages.js';
 import { timeout } from '../utils.js';
@@ -133,7 +133,7 @@ export class Base extends Client {
         }
         // Store the promise for the current round's aggregation result.
         // We will await for it to resolve at the end of the round when exchanging weight updates.
-        this.aggregationResult = this.aggregator.receiveResult();
+        this.aggregationResult = new Promise((resolve) => this.aggregator.once('aggregation', resolve));
     }
     /**
      * At each communication rounds, awaits peers contributions and add them to the client's aggregator.
@@ -163,12 +163,15 @@ export class Base extends Client {
         });
     }
     async onRoundEndCommunication(weights, round) {
-        let result = weights;
+        if (this.aggregationResult === undefined) {
+            throw new TypeError('aggregation result promise is undefined');
+        }
         // Perform the required communication rounds. Each communication round consists in sending our local payload,
         // followed by an aggregation step triggered by the receipt of other payloads, and handled by the aggregator.
         // A communication round's payload is the aggregation result of the previous communication round. The first
         // communication round simply sends our training result, i.e. model weights updates. This scheme allows for
         // the aggregator to define any complex multi-round aggregation mechanism.
+        let result = weights;
         for (let r = 0; r < this.aggregator.communicationRounds; r++) {
             // Generate our payloads for this communication round and send them to all ready connected peers
             if (this.connections !== undefined) {
@@ -198,9 +201,6 @@ export class Base extends Client {
                     throw new Error('error while sending weights');
                 }
             }
-            if (this.aggregationResult === undefined) {
-                throw new TypeError('aggregation result promise is undefined');
-            }
             // Wait for aggregation before proceeding to the next communication round.
             // The current result will be used as payload for the eventual next communication round.
             try {
@@ -211,7 +211,7 @@ export class Base extends Client {
             }
             catch (e) {
                 if (this.isDisconnected) {
-                    return;
+                    return weights;
                 }
                 console.error(e);
                 break;
@@ -219,10 +219,11 @@ export class Base extends Client {
             // There is at least one communication round remaining
             if (r < this.aggregator.communicationRounds - 1) {
                 // Reuse the aggregation result
-                this.aggregationResult = this.aggregator.receiveResult();
+                this.aggregationResult = new Promise((resolve) => this.aggregator.once('aggregation', resolve));
             }
         }
         // Reset the peers list for the next round
         this.aggregator.resetNodes();
+        return await this.aggregationResult;
     }
 }

package/dist/client/federated/base.d.ts

@@ -28,7 +28,7 @@ export declare class Base extends Client {
      */
     disconnect(): Promise<void>;
     onRoundBeginCommunication(): Promise<void>;
-    onRoundEndCommunication(weights: WeightsContainer, round: number): Promise<void>;
+    onRoundEndCommunication(weights: WeightsContainer, round: number): Promise<WeightsContainer>;
     /**
      * Send a message containing our local weight updates to the federated server.
      * And waits for the server to reply with the most recent aggregated weights

package/dist/client/federated/base.js

@@ -68,7 +68,7 @@ export class Base extends Client {
     }
     onRoundBeginCommunication() {
         // Prepare the result promise for the incoming round
-        this.aggregationResult = this.aggregator.receiveResult();
+        this.aggregationResult = new Promise((resolve) => this.aggregator.once('aggregation', resolve));
         return Promise.resolve();
     }
     async onRoundEndCommunication(weights, round) {
@@ -90,6 +90,7 @@ export class Base extends Client {
             console.info(`[${this.ownId}] Server result is either stale or not received`);
             this.aggregator.nextRound();
         }
+        return await this.aggregationResult;
     }
     /**
      * Send a message containing our local weight updates to the federated server.

package/dist/client/local.d.ts

@@ -1,3 +1,5 @@
-import { Base } from './base.js';
+import { WeightsContainer } from "../weights/weights_container.js";
+import { Base } from "./base.js";
 export declare class Local extends Base {
+    onRoundEndCommunication(weights: WeightsContainer): Promise<WeightsContainer>;
 }

package/dist/client/local.js

@@ -1,3 +1,6 @@
-import { Base } from './base.js';
+import { Base } from "./base.js";
 export class Local extends Base {
+    onRoundEndCommunication(weights) {
+        return Promise.resolve(weights);
+    }
 }

package/dist/default_tasks/cifar10.js

@@ -30,8 +30,7 @@ export const cifar10 = {
                 IMAGE_W: 224,
                 LABEL_LIST: ['airplane', 'automobile', 'bird', 'cat', 'deer', 'dog', 'frog', 'horse', 'ship', 'truck'],
                 scheme: 'decentralized',
-                noiseScale: undefined,
-                clippingRadius: 20,
+                privacy: { clippingRadius: 20, noiseScale: 1 },
                 decentralizedSecure: true,
                 minimumReadyPeers: 3,
                 maxShareValue: 100,

package/dist/default_tasks/mnist.js

@@ -30,8 +30,6 @@ export const mnist = {
                 preprocessingFunctions: [data.ImagePreprocessing.Resize, data.ImagePreprocessing.Normalize],
                 LABEL_LIST: ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'],
                 scheme: 'decentralized',
-                noiseScale: undefined,
-                clippingRadius: undefined,
                 decentralizedSecure: true,
                 minimumReadyPeers: 3,
                 maxShareValue: 100,

package/dist/default_tasks/simple_face.js

@@ -29,8 +29,6 @@ export const simpleFace = {
                 IMAGE_W: 200,
                 LABEL_LIST: ['child', 'adult'],
                 scheme: 'federated', // secure aggregation not yet implemented for federated
-                noiseScale: undefined,
-                clippingRadius: undefined,
                 tensorBackend: 'tfjs'
             }
         };

package/dist/default_tasks/titanic.js

@@ -63,8 +63,6 @@ export const titanic = {
                     'Survived'
                 ],
                 scheme: 'federated', // secure aggregation not yet implemented for FeAI
-                noiseScale: undefined,
-                clippingRadius: undefined,
                 tensorBackend: 'tfjs'
             }
         };

package/dist/index.d.ts

@@ -5,7 +5,6 @@ export * as privacy from './privacy.js';
 export * as client from './client/index.js';
 export * as aggregator from './aggregator/index.js';
 export { WeightsContainer, aggregation } from './weights/index.js';
-export { AsyncInformant } from './async_informant.js';
 export { Logger, ConsoleLogger } from './logging/index.js';
 export { Memory, type ModelInfo, type Path, type ModelSource, Empty as EmptyMemory } from './memory/index.js';
 export { Disco, RoundLogs } from './training/index.js';

package/dist/index.js

@@ -5,7 +5,6 @@ export * as privacy from './privacy.js';
 export * as client from './client/index.js';
 export * as aggregator from './aggregator/index.js';
 export { WeightsContainer, aggregation } from './weights/index.js';
-export { AsyncInformant } from './async_informant.js';
 export { ConsoleLogger } from './logging/index.js';
 export { Memory, Empty as EmptyMemory } from './memory/index.js';
 export { Disco } from './training/index.js';

package/dist/privacy.d.ts

@@ -1,11 +1,9 @@
-import type { Task, WeightsContainer } from './index.js';
+import type { WeightsContainer } from "./index.js";
+/** Scramble weights */
+export declare function addNoise(weights: WeightsContainer, deviation: number): WeightsContainer;
 /**
- * Add task-parametrized Gaussian noise to and clip the weights update between the previous and current rounds.
- * The previous round's weights are the last weights pulled from server/peers.
- * The current round's weights are obtained after a single round of training, from the previous round's weights.
- * @param updatedWeights weights from the current round
- * @param staleWeights weights from the previous round
- * @param task the task
- * @returns the noised weights for the current round
- */
-export declare function addDifferentialPrivacy(updatedWeights: WeightsContainer, staleWeights: WeightsContainer, task: Task): WeightsContainer;
+ * Keep weights' norm within radius
+ *
+ * @param radius maximum norm
+ **/
+export declare function clipNorm(weights: WeightsContainer, radius: number): Promise<WeightsContainer>;