@grnsft/if 0.3.4 → 0.4.0-beta.0

package/src/builtins/exponent/README.md

@@ -0,0 +1,97 @@
+# Exponent
+
+`exponent` is a generic plugin for calculating exponent of an input param (as base) and another (as the exponent) in an `input` array.
+
+You provide the names of the values you want to use for the exponent calculation, and a name to use to add the exponent result to the output array.
+
+For example, you use `cpu/energy` as base and `network/energy` as and name the result `energy`. `energy` would then be added to every observation in your input array as `cpu/energy` raised by the exponent `network/energy`.
+
+## Parameters
+
+### Plugin config
+
+Three parameters are required in global config: `input-parameter`, `exponent` and `output-parameter`.
+
+`input-parameter`: a string defining the base. Must match an existing key in the `inputs` array
+`exponent`: a number defining the exponent.
+`output-parameter`: a string defining the name to use to add the result of the exponent to the output array.
+
+### Inputs
+
+`input-parameter` and `exponent` must be available in the input array.
+
+## Returns
+
+- `output-parameter`: `input-parameter` raised by `exponent` with the parameter name defined by `output-parameter` in global config.
+
+## Calculation
+
+```pseudocode
+output = input ^ exponent
+```
+
+## Implementation
+
+To run the plugin, you must first create an instance of `Exponent`. Then, you can call `execute()`.
+
+```typescript
+import {Exponent} from 'builtins';
+
+const config = {
+  inputParameter: ['cpu/energy'],
+  exponent: 2
+  outputParameter: 'energy',
+};
+
+const exponent = Exponent(config);
+const result = await exponent.execute([
+  {
+    duration: 3600,
+    timestamp: '2021-01-01T00:00:00Z',
+    'cpu/energy': 0.1,
+    'energy': 0.01,
+  },
+]);
+```
+
+## 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 `exponent`:
+
+```yaml
+name: exponent demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    exponent:
+      method: Exponent
+      path: 'builtin'
+      global-config:
+        input-parameter: 'cpu/energy'
+        exponent: 2
+        output-parameter: 'energy'
+tree:
+  children:
+    child:
+      pipeline:
+        - exponent
+      config:
+        exponent:
+      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 `manifests/examples/test/exponent.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest manifests/examples/test/exponent.yml --output manifests/outputs/exponent.yml
+```
+
+The results will be saved to a new `yaml` file in `manifests/outputs`.

package/src/builtins/interpolation/README.md

@@ -0,0 +1,168 @@
+# Interpolation Plugin
+
+## Overview
+
+Interpolation is a way to infer new data points from a previously known set of points.
+This plugin provides the `y` value at a given `x` by interpolating between known points. You provide a set of known `x`s and `y`s and a target `x`, the plugin returns the `y` for your `x`.
+
+## Usage
+
+To employ the `Interpolation` plugin, adhere to these steps:
+
+1. **Initialize Plugin**: Import the `Interpolation` function and initialize it with global configuration parameters `method`, `x`, `y`, `input-parameter` and `output-parameter`.
+
+2. **Execute Plugin**: Invoke the `execute` method of the initialized plugin instance with an array of input parameters. Each input parameter should include a `timestamp`, `duration` and `[input-parameter]` information.
+
+3. **Result**: The plugin will return an array of plugin parameters enriched with the calculated average carbon intensity for each input.
+
+## Global Config
+
+- `method`: specifies the interpolation method for the data. Acceptable values are 'linear', 'spline', or 'polynomial'. The default method is linear. (optional)
+- `x`: array of x points. Numbers should be in ascending order (required).
+- `y`: array of y points. Numbers should be in ascending order (required).
+- `input-parameter`: a string defining the name to use its value to calculate the interpolation. It should match an existing key in the inputs array (required).
+- `output-parameter`: a string defining the name to use to add the result of interpolation with additional calculation (required).
+
+`x` and `y` arrays must be equal lengths.
+
+## Input Parameters
+
+The plugin expects the following input parameters:
+
+- `timestamp`: a timestamp for the input (required)
+- `duration`: the amount of time, in seconds, that the input covers. (required)
+- `[input-parameter]` - a field whose name matches the string provided to input-parameter in global config (i.e. if the input-parameter in global config is cpu/utilisation then cpu-utilisation must exist in the input data)
+
+## Output
+
+The plugin outputs a value `z` that is the result of looking up the `y` value at `x = 'input-parameter'` using the user-defined interpolation method in `kWh` units. `z` is assigned to a field with a name defined by `output-parameter` in the output data.
+
+## Error Handling
+
+The plugin conducts input validation using the `zod` library and may throw errors if the provided parameters are invalid.
+
+## Plugin Algorithm
+
+1. **Execution**:
+
+   - Validate Global config
+
+     - `method` - validates if the method is one of these methods: `linear`, `spline`, or `polynomial`. If the method isn’t provided, it sets to `linear`.
+     - `x` and `y` should be arrays of numbers, the length should be equal, and elements should be ordered in the ascendant order.
+     - `input-parameter` - validates if the parameter is string.
+     - `output-parameter` - validates if the parameter is string.
+
+   - Iterate through each input, and do corresponding validation and calculation.
+
+   - Validate input parameters
+
+     - `duration` - validate if the duration is a number
+     - `timestamp` - should be in string or date format
+     - `[input-parameter]` - validates whether the parameter name is included in the input, and if its value should be a number within the range of x points.
+
+   - Calculation
+
+     - If the `method` is provided, choose the right way to calculate. For the `linear` and `polynomial` methods, calculate according to their formulas. For spline interpolation, use the npm module `typescript-cubic-spline`.
+
+2. **Output**: Output the provided input along with the calculated `cpu/energy`
+
+### TypeScript Usage
+
+```ts
+const globalConfig = {
+  method: 'linear',
+  x: [0, 10, 50, 100],
+  y: [0.12, 0.32, 0.75, 1.02],
+  'input-parameter': 'cpu/utilization'
+  'output-parameter': 'cpu/energy'
+
+};
+
+const interpolationPlugin = Interpolation(globalConfig);
+
+const inputs = [
+  {
+    timestamp: '2024-04-16T12:00:00Z',
+    duration: 3600,
+    'cpu/utilization': 45
+  },
+];
+
+const results = interpolationPlugin.execute(inputs);
+
+console.log(results);
+```
+
+### Manifest Usage
+
+#### Input
+
+```yaml
+name: interpolation-demo
+description: simple demo of interpolation plugin
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    interpolation:
+      method: Interpolation
+      path: 'builtin'
+      global-config:
+        method: linear
+        x: [0, 10, 50, 100]
+        y: [0.12, 0.32, 0.75, 1.02]
+        input-parameter: 'cpu/utilization'
+        output-parameter: 'cpu/energy'
+tree:
+  children:
+    child:
+      pipeline:
+        - interpolation
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 45
+```
+
+#### Output
+
+```yaml
+name: interpolation-demo
+description: simple demo of interpolation plugin
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    interpolation:
+      method: Interpolation
+      path: 'builtin'
+      global-config:
+        method: linear
+        x: [0, 10, 50, 100]
+        y: [0.12, 0.32, 0.75, 1.02]
+        input-parameter: 'cpu/utilization'
+        output-parameter: 'cpu/energy'
+tree:
+  children:
+    child:
+      pipeline:
+        - interpolation
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 45
+      outputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 45
+          cpu/energy: 0.00069625
+```
+
+You can execute this by passing it to `ie`. Run the impact using the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest ./manifests/examples/interpolation.yml --output ./manifests/outputs/interpolation.yml
+```

package/src/builtins/mock-observations/README.md

@@ -0,0 +1,97 @@
+# Mock Observations Plugin
+
+## Introduction
+
+A plugin for mocking observations (inputs) for testing and demo purposes
+
+## Scope
+
+The mode currently mocks 2 types of observation data:
+
+- Common key-value pairs, that are generated statically and are the same for each generated observation/input (see 'helpers/CommonGenerator.ts')
+- Randomly generated integer values for predefined keys (see 'helpers/RandIntGenerator.ts')
+
+### Plugin global config
+
+- `timestamp-from`, `timestamp-to` and `duration` define time buckets for which to generate observations.
+- `generators` define which fields to generate for each observation
+- `components` define the components for which to generate observations. The observations generated according to `timestamp-from`, `timestamp-to`, `duration` and `generators` will be duplicated for each component.
+
+### Authentication
+
+N/A
+
+### Inputs
+
+The plugin's `global-config` section in the manifest file determines its behaviour.
+'inputs' section is ignored.
+
+### Typescript Usage
+
+```typescript
+const mockObservations = MockObservations({
+  'timestamp-from': '2023-07-06T00:00',
+  'timestamp-to': '2023-07-06T00:10',
+  duration: 60,
+  components: {
+    'instance-type': 'A1',
+  },
+  generators: {
+    common: {
+      region: 'uk-west',
+    },
+  },
+});
+const result = await mockObservations.execute([]);
+```
+
+### manifest Example
+
+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 `ie` and does not have to be done explicitly by the user. The following is an example `manifest` that calls `mock-observation`:
+
+```yaml
+name: mock-observation-demo
+description: example invoking mock-observation plugin
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    mock-observations:
+      kind: plugin
+      method: MockObservations
+      path: 'builtin'
+      global-config:
+        timestamp-from: 2023-07-06T00:00
+        timestamp-to: 2023-07-06T00:10
+        duration: 60
+        components:
+          - instance-type: A1
+          - instance-type: B1
+        generators:
+          common:
+            region: uk-west
+            common-key: common-val
+          randint:
+            cpu/utilization:
+              min: 1
+              max: 99
+            memory/utilization:
+              min: 1
+              max: 99
+tree:
+  children:
+    child:
+      pipeline:
+        - mock-observations
+      inputs:
+```
+
+You can run this example `manifest` by saving it as `manifests/plugins/mock-observation.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest ./examples/manifests/test/mock-observation.yml --output ./examples/outputs/mock-observation
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`.

package/src/builtins/multiply/README.md

@@ -0,0 +1,94 @@
+# Multiply
+
+`multiply` is a generic plugin for multiplying two or more values in an `input` array.
+
+You provide the names of the values you want to multiply, and a name to use to append the product to the output array.
+
+For example, you could multiply `cpu/energy` and `network/energy` and name the result `energy-product`. `energy-product` would then be added to every observation in your input array as the product 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 product of the input parameters to the output array.
+
+### Inputs
+
+All of `input-parameters` must be available in the input array.
+
+## Returns
+
+- `output-parameter`: the product 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 `Multiply`. Then, you can call `execute()`.
+
+```typescript
+import {Multiply} from 'builtins';
+
+const config = {
+  inputParameters: ['cpu/energy', 'network/energy'],
+  outputParameter: 'energy-product',
+};
+
+const mult = Multiply(config);
+const result = await mult.execute([
+  {
+    duration: 3600,
+    timestamp: '2021-01-01T00:00:00Z',
+    '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 `ie` and does not have to be done explicitly by the user. The following is an example manifest that calls `multiply`:
+
+```yaml
+name: multiply-demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    multiply:
+      method: Multiply
+      path: 'builtin'
+      global-config:
+        input-parameters: ['cpu/energy', 'network/energy']
+        output-parameter: 'energy-product'
+tree:
+  children:
+    child:
+      pipeline:
+        - multiply
+      config:
+        multiply:
+      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/test/multiply.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest ./examples/manifests/test/multiply.yml --output ./examples/outputs/multiply.yml
+```
+
+The results will be saved to a new `yaml` file in `./examples/outputs`

package/src/builtins/regex/README.md

@@ -0,0 +1,91 @@
+# Regex
+
+`regex` is a generic plugin to match part of one string in an `input` and extract it into an output.
+
+You provide the name of the value you want to match, and a name to use to add the regex to the output array.
+
+For example, `boavizta-cpu` need `cpu/name` to work, however `cloud-metadata` returns `physical-processor` which usually contains a long string of processors that the instance could be separated by `,`, like so:
+
+```
+Intel® Xeon® Platinum 8272CL,Intel® Xeon® 8171M 2.1 GHz,Intel® Xeon® E5-2673 v4 2.3 GHz,Intel® Xeon® E5-2673 v3 2.4 GHz
+```
+
+## Parameters
+
+### Plugin config
+
+- `parameter` - a parameter by a specific configured string
+- `match` - a regex by which needs to match the `parameter`
+- `output` - output parameter name in the input
+
+### Inputs
+
+- `parameter` - as input parameter, must be available in the input array
+
+## Returns
+
+- `output`: the first match of `parameter` with the parameter name with `match` defined in global config.
+
+## Implementation
+
+To run the plugin, you must first create an instance of `Regex`. Then, you can call `execute()`.
+
+```typescript
+
+const globalConfig = {
+  parameter: 'physical-processor',
+  match: '^[^,]+',
+  output: 'cpu/name',
+};
+const regex = Regex(globalConfig);
+
+const input = [
+  {
+    timestamp: '2021-01-01T00:00:00Z',
+    duration: 3600,
+    'physical-processor':
+      'Intel® Xeon® Platinum 8272CL,Intel® Xeon® 8171M 2.1 GHz,Intel® Xeon® E5-2673 v4 2.3 GHz,Intel® Xeon® E5-2673 v3 2.4 GHz',
+  },
+];
+```
+
+## 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 `if` and does not have to be done explicitly by the user. The following is an example manifest that calls `regex`:
+
+```yaml
+name: regex-demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    regex:
+      method: Regex
+      path: 'builtin'
+      global-config:
+        parameter: physical-processor
+        match: ^[^,]+
+        output: cpu/name
+tree:
+  children:
+    child:
+      pipeline:
+        - regex
+      config:
+        regex:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          physical-processor: Intel® Xeon® Platinum 8272CL,Intel® Xeon® 8171M 2.1 GHz,Intel® Xeon® E5-2673 v4 2.3 GHz,Intel® Xeon® E5-2673 v3 2.4 GHz
+```
+
+You can run this example by saving it as `manifests/plugins/regex.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+if --manifest manifests/examples/regex.yml --output manifests/outputs/regex.yml
+```
+
+The results will be saved to a new `yaml` file in `manifests/outputs`.

package/src/builtins/sci/README.md

@@ -0,0 +1,89 @@
+# SCI (software carbon intensity)
+
+[SCI](https://sci-guide.greensoftware.foundation/) represents the amount of carbon emitted per [functional unit](https://sci-guide.greensoftware.foundation/R/).
+
+## Parameters
+
+### Plugin global config
+
+- `functional-unit`: the name of the functional unit in which to express the carbon impact (required)
+
+
+### Inputs
+
+
+- `carbon`: total carbon in gCO2eq (required)
+- `functional-unit`: whatever `functional-unit` you define in global config also has to be present in each input, for example if you provide `functional-unit: requests` in global config, `requests` must be present in your input data.
+
+## Returns
+
+- `sci`: carbon expressed in terms of the given functional unit
+
+## Calculation
+
+SCI is calculated as:
+
+```pseudocode
+sci = carbon / functional unit
+```
+
+
+## IF Implementation
+
+To run the plugin, you must first create an instance of `Sci`. Then, you can call `execute()` to return `sci`.
+
+```typescript
+import {Sci} from 'builtins';
+
+const sci = Sci({'functional-unit': 'requests'});
+const results = await sci.execute(
+  [
+    {
+      'carbon': 5'
+      duration: 1,
+      requests: 100,
+    },
+  ]
+);
+```
+
+## 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 `ie` and does not have to be done explicitly by the user.
+
+The following is an example `manifest` that calls `sci`:
+
+```yaml
+name: sci-demo
+description: example invoking sci plugin
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    sci:
+      method: Sci
+      path: 'builtin'
+      global-config:
+        functional-unit: 'requests'
+tree:
+  children:
+    child:
+      pipeline:
+        - sci
+      config:
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          carbon: 5
+          duration: 1
+          requests: 100
+```
+
+You can run this example `manifest` by saving it as `./manifests/plugins/sci.yml` and executing the following command from the project root:
+
+```sh
+npm i -g @grnsft/if
+ie --manifest manifests/plugins/sci.yml --output manifests/outputs/sci.yml
+```
+
+The results will be saved to a new `yaml` file.