Move the sum plugin into builtins

manifests/plugins/sum/success.yml

@@ -6,7 +6,7 @@ initialize:
   plugins:
     sum:
       method: Sum
-      path: "@grnsft/if-plugins"
+      path: "builtin"
       global-config:
         input-parameters: ["cpu/energy", "network/energy"]
         output-parameter: "energy"

src/__tests__/unit/builtins/sum.test.ts

@@ -0,0 +1,123 @@
+import {Sum} from '../../../builtins/sum';
+
+import {ERRORS} from '../../../util/errors';
+
+const {InputValidationError, ConfigNotFoundError} = ERRORS;
+
+describe('lib/sum: ', () => {
+  describe('Sum: ', () => {
+    const globalConfig = {
+      'input-parameters': ['cpu/energy', 'network/energy', 'memory/energy'],
+      'output-parameter': 'energy',
+    };
+    const sum = Sum(globalConfig);
+
+    describe('init: ', () => {
+      it('successfully initalized.', () => {
+        expect(sum).toHaveProperty('metadata');
+        expect(sum).toHaveProperty('execute');
+      });
+    });
+
+    describe('execute(): ', () => {
+      it('successfully applies Sum strategy to given input.', () => {
+        expect.assertions(1);
+
+        const expectedResult = [
+          {
+            duration: 3600,
+            'cpu/energy': 1,
+            'network/energy': 1,
+            'memory/energy': 1,
+            energy: 3,
+            timestamp: '2021-01-01T00:00:00Z',
+          },
+        ];
+
+        const result = sum.execute([
+          {
+            timestamp: '2021-01-01T00:00:00Z',
+            duration: 3600,
+            'cpu/energy': 1,
+            'network/energy': 1,
+            'memory/energy': 1,
+          },
+        ]);
+
+        expect(result).toStrictEqual(expectedResult);
+      });
+
+      it('throws an error when global config is not provided.', () => {
+        const expectedMessage = 'Global config is not provided.';
+        const config = undefined;
+        const sum = Sum(config!);
+
+        expect.assertions(1);
+
+        try {
+          sum.execute([
+            {
+              timestamp: '2021-01-01T00:00:00Z',
+              duration: 3600,
+              'cpu/energy': 1,
+              'network/energy': 1,
+              'memory/energy': 1,
+            },
+          ]);
+        } catch (error) {
+          expect(error).toStrictEqual(new ConfigNotFoundError(expectedMessage));
+        }
+      });
+
+      it('throws an error on missing params in input.', () => {
+        const expectedMessage = 'cpu/energy is missing from the input array.';
+
+        expect.assertions(1);
+
+        try {
+          sum.execute([
+            {
+              duration: 3600,
+              timestamp: '2021-01-01T00:00:00Z',
+            },
+          ]);
+        } catch (error) {
+          expect(error).toStrictEqual(
+            new InputValidationError(expectedMessage)
+          );
+        }
+      });
+
+      it('returns a result with input params not related to energy.', () => {
+        expect.assertions(1);
+        const newConfig = {
+          'input-parameters': ['carbon', 'other-carbon'],
+          'output-parameter': 'carbon-sum',
+        };
+        const sum = Sum(newConfig);
+
+        const data = [
+          {
+            duration: 3600,
+            timestamp: '2021-01-01T00:00:00Z',
+            carbon: 1,
+            'other-carbon': 2,
+          },
+        ];
+        const response = sum.execute(data);
+
+        const expectedResult = [
+          {
+            duration: 3600,
+            carbon: 1,
+            'other-carbon': 2,
+            'carbon-sum': 3,
+            timestamp: '2021-01-01T00:00:00Z',
+          },
+        ];
+
+        expect(response).toEqual(expectedResult);
+      });
+    });
+  });
+});

src/builtins/index.ts

@@ -1,4 +1,5 @@
 export {GroupBy} from './group-by';
 export {TimeSync} from './time-sync';
+export {Sum} from './sum';
 export {SciEmbodied} from './sci-embodied';
 export {Sci} from './sci';

src/builtins/sum/README.md

@@ -0,0 +1,91 @@
+# Sum
+
+`sum` is a generic plugin for doing arithmetic sums of two or more values in an `input` array.
+
+You provide the names of the values you want to sum, and a name to use to add the sum to the output array.
+
+For example, you could add `cpu/energy` and `network/energy` and name the result `energy`. `energy` would then be added to every observation in your input array as the sum of `cpu/energy` and `network/energy`.
+
+## Parameters
+
+### Plugin config
+
+Two parameters are required in global config: `input-parameters` and `output-parameter`.
+
+`input-parameters`: an array of strings. Each string should match an existing key in the `inputs` array
+`output-parameter`: a string defining the name to use to add the result of summing the input parameters to the output array.
+
+### Inputs
+
+All of `input-parameters` must be available in the input array.
+
+## Returns
+
+- `output-parameter`: the sum of all `input-parameters` with the parameter name defined by `output-parameter` in global config.
+
+## Calculation
+
+```pseudocode
+output = input0 + input1 + input2 ... inputN
+```
+
+## Implementation
+
+To run the plugin, you must first create an instance of `Sum`. Then, you can call `execute()`.
+
+```typescript
+const config = {
+  inputParameters: ['cpu/energy', 'network/energy'],
+  outputParameter: 'energy',
+};
+
+const sum = Sum(config);
+const result = sum.execute([
+  {
+    timestamp: '2021-01-01T00:00:00Z',
+    duration: 3600,
+    'cpu/energy': 0.001,
+    'memory/energy': 0.0005,
+  },
+]);
+```
+
+## Example manifest
+
+IF users will typically call the plugin as part of a pipeline defined in a manifest file. In this case, instantiating the plugin is handled by and does not have to be done explicitly by the user. The following is an example manifest that calls `sum`:
+
+```yaml
+name: sum demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    sum:
+      method: Sum
+      path: 'builtin'
+      global-config:
+        input-parameters: ['cpu/energy', 'network/energy']
+        output-parameter: 'energy'
+tree:
+  children:
+    child:
+      pipeline:
+        - sum
+      config:
+        sum:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          cpu/energy: 0.001
+          network/energy: 0.001
+```
+
+You can run this example by saving it as `./examples/manifests/sum.yml` and executing the following command from the project root:
+
+```sh
+ie --manifest ./examples/manifests/sum.yml --output ./examples/outputs/sum.yml
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`.

src/builtins/sum/index.ts

@@ -0,0 +1,85 @@
+import {z} from 'zod';
+
+import {ExecutePlugin, PluginParams} from '../../types/interface';
+
+import {validate} from '../../util/validations';
+import {ERRORS} from '../../util/errors';
+
+import {SumConfig} from './types';
+
+const {InputValidationError, ConfigNotFoundError} = ERRORS;
+
+export const Sum = (globalConfig: SumConfig): ExecutePlugin => {
+  const metadata = {
+    kind: 'execute',
+  };
+
+  /**
+   * Calculate the sum of each input-paramters.
+   */
+  const execute = (inputs: PluginParams[]) => {
+    const safeGlobalConfig = validateGlobalConfig();
+    const inputParameters = safeGlobalConfig['input-parameters'];
+    const outputParameter = safeGlobalConfig['output-parameter'];
+
+    return inputs.map(input => {
+      const safeInput = validateSingleInput(input, inputParameters);
+
+      return {
+        ...input,
+        [outputParameter]: calculateSum(safeInput, inputParameters),
+      };
+    });
+  };
+
+  /**
+   * Checks global config value are valid.
+   */
+  const validateGlobalConfig = () => {
+    if (!globalConfig) {
+      throw new ConfigNotFoundError('Global config is not provided.');
+    }
+
+    const globalConfigSchema = z.object({
+      'input-parameters': z.array(z.string()),
+      'output-parameter': z.string().min(1),
+    });
+
+    return validate<z.infer<typeof globalConfigSchema>>(
+      globalConfigSchema,
+      globalConfig
+    );
+  };
+
+  /**
+   * Checks for required fields in input.
+   */
+  const validateSingleInput = (
+    input: PluginParams,
+    inputParameters: string[]
+  ) => {
+    inputParameters.forEach(metricToSum => {
+      if (!input[metricToSum]) {
+        throw new InputValidationError(
+          `${metricToSum} is missing from the input array.`
+        );
+      }
+    });
+
+    return input;
+  };
+
+  /**
+   * Calculates the sum of the energy components.
+   */
+  const calculateSum = (input: PluginParams, inputParameters: string[]) =>
+    inputParameters.reduce(
+      (accumulator, metricToSum) => accumulator + input[metricToSum],
+      0
+    );
+
+  return {
+    metadata,
+    execute,
+  };
+};

src/builtins/sum/types.ts

@@ -0,0 +1,4 @@
+export type SumConfig = {
+  'input-parameters': string[];
+  'output-parameter': string;
+};

src/util/errors.ts

@@ -9,6 +9,7 @@ const CUSTOM_ERRORS = [
   'PluginCredentialError',
   'PluginInitalizationError',
   'WriteFileError',
+  'ConfigNotFoundError',
 ] as const;
 
 type CustomErrors = {