Merge pull request #26 from sightmachine/ENG-585_KPI_support

[Eng-585] kpi support

Author: mgoldmansight

docs/commonly_used_data_types/asset_selection.md

@@ -0,0 +1,17 @@
+# Asset Selection
+Asset Selection is used in a few different places in order to tell the API which asset or assets you wish to perform an action on.  Typically it will either select a machine_type or types or specific machines within a machine_type in order to select machine_types it should look like the following:
+```
+asset_selection: {
+    machine_type: ["Lasercut", ...]
+
+}
+```
+
+In order to select machines within a type it should look like the follwoing:
+```
+asset_selection: {
+    machine_type: ["Lasercut"],
+    machine_source: ["JB_AB_Lasercut_1", ...]
+
+}
+```

docs/commonly_used_data_types/data_viz_query.md

@@ -0,0 +1,179 @@
+# Data Vizualation Query
+Data Viz Queries are used whenever the SDK calls our Data Vizualation APIs.  The functions you call via SDK do some work on the query for you so this Query will look slightly different from the one our API uses directly.  We will break down each field in some more detail futher along in this doc but as an example a full Data Viz Query looks like the following:
+```
+{
+  "asset_selection": {
+    "machine_source": [
+      "JB_AB_Lasercut_1"
+    ],
+    "machine_type": [
+      "Lasercut"
+    ]
+  },
+  "d_vars": [
+    {
+      "name": "quality",
+      "aggregate": [
+        "avg"
+      ]
+    }
+  ],
+  "i_vars": [
+    {
+      "name": "endtime",
+      "time_resolution": "day",
+      "query_tz": "America/Los_Angeles",
+      "output_tz": "America/Los_Angeles",
+      "bin_strategy": "user_defined2",
+      "bin_count": 50
+    }
+  ],
+  "time_selection": {
+    "time_type": "relative",
+    "relative_start": 7,
+    "relative_unit": "year",
+    "ctime_tz": "America/Los_Angeles"
+  },
+  "where": [],
+  "db_mode": "sql"
+}
+```
+
+## Asset_selection
+Used to select the asset(s) you want to recieve data from see the [asset_selection doc](/docs/commonly_used_data_types/asset_selection.md) for more information.
+
+## d_vars
+The Dependent variables.  These will change depending on the entity you are trying to access.  But will always be a list in the following form:
+```
+    {
+      "name": "quality",
+      "aggregate": [
+        "avg"
+      ]
+    }
+```
+### name
+This is the name of dependent variable you wish to view.  This typically the name of a value we store on a machine or the name of a KPI.
+
+### aggregate
+This is how you wish to aggregate the data of the named value in the time_resolution you have selected. The options for this are:
+* avg
+* sum
+* min
+* max
+
+## i_vars
+The indepent variables.  These should typically be time based values that are stored on the machine_type you are using. They will always be a list in the following form:
+```
+{
+      "name": "endtime",
+      "time_resolution": "day",
+      "query_tz": "America/Los_Angeles",
+      "output_tz": "America/Los_Angeles",
+      "bin_strategy": "user_defined2",
+      "bin_count": 50
+    }
+```
+### name
+This is the name of idependent varaible you are using.
+
+### time_resolution
+This is optional and is how detailed of a time breakdown you want in the variable the options for time_resolution are as follows:
+* year
+* month
+* week
+* day
+* hour
+* minute
+* second
+
+### query_tz
+This is optional and tells the system what time zone the query is in.
+
+### output_tz
+This is optional and tells the system what time zone to return the data in.
+
+### bin_strategy
+This is optional and tells the sytem how you wish to bin the data.  You have the following options:
+* user_defined2
+* none
+* categorical
+
+### bin_count
+This is optoinal and tels the system how many bins you wish to put the data into.
+
+## time_selection
+This is the time frame you want to grab data from there are two different ways to make this time selection, Relative and Absolute
+
+### Relative Time Selection
+Relative Time Selections goes back from now a certain amount of time based on what you tell it.  The format for this time selection is the following:
+```
+{
+    "time_type": "relative",
+    "relative_start": 7,
+    "relative_unit": "year",
+    "ctime_tz": "America/Los_Angeles"
+}
+```
+#### Time Type
+For a relative time selection this needs to be set to "relative".
+
+#### Relative Start
+The amount of units from now you wish to go back to start your time selection.
+
+#### Relative Unit
+The unit of time you wish to go back from now.  Your options for this are as follows:
+* year
+* month
+* week
+* day
+* hour
+* minute
+* second
+
+#### ctime_tz
+The time zone for your time selection
+
+### Absolute Time Selection
+Absolute Time Selections have a start and end time and will gather data from between the two.  The format for this time selection is as follows:
+```
+{
+  "time_type": "absolute",
+  "start_time": "2023-02-23T08:00:00.000Z",
+  "end_time": "2023-03-01T21:35:35.499Z",
+  "time_zone": "America/Los_Angeles"
+}
+```
+#### Time Type
+For absolute time selecitons this must be set to absolute.
+
+#### Start Time
+The time you wish to start the time selection at.
+
+#### End Time
+The time you wish to end the time selection at.
+
+#### Time Zone
+The time zone for the time selection.
+
+## Where
+This is optional.  It will narrow down the data return based on criteria given. The list will be anded together. This is a list in the following format:
+```
+{
+    "name": "type__part_type",
+    "op": "eq",
+    "value": "EngineBlock"
+}
+```
+
+### Name
+The name of the field you are using in this criteria.
+
+### Op
+The type of operation you are doing.
+
+### Value
+The value to compare with the operation.
+
+## db_mode
+This is optional.  It will default to 'sql' and usually should be but we have a 'mongo' mode as well.  You will likely ever need to set this.

docs/entities/kpis.md

@@ -0,0 +1,77 @@
+# KPIs
+
+KPIs are user defined calculated fields in the Sight Machine software.
+
+## Functions
+The SDK has three functions related to KPIs.  The first returns a list of all availible KPis.  The second of which allows a user to see which KPIs are availible for a particular asset.  The third makes use of our Data Visualization api which allows a user to see these KPIs over a timeframe.
+
+### Get KPIs
+This is the first KPI function allowing you to see all KPIs availible to you.  In order to call this function you must first have a logged in client see the [quick start guide](/README.md) for more information on logging in.  Once you have a logged in client you can call the function as follows:
+
+```
+cli.get_kpis()
+```
+This will return a full list of KPIs which will look something like this example:
+```
+[{'name': 'performance', 'display_name': 'Performance', 'formula': '( IdealCycle / Recorded_time ) * 100 if ( Recorded_time > 0 ) else None', 'data_type': '', 'dependencies': [{'aggregate': 'sum', 'name': 'Recorded_time'}, {'aggregate': 'sum', 'name': 'IdealCycle'}]}, ...]
+```
+
+In order to make use of the data viz function you'll need the name of the KPI you wish to get.
+
+### Get KPIs For Asset
+This is the second KPI function allowing you to see which KPIs are availible for a particular asset.  Once you have a logged in client you can call the function as follows:
+
+```
+cli.get_kpis_for_asset(**asset_selection)
+```
+
+For more info on [asset_selection](/docs/commonly_used_data_types/asset_selection.md) click on the previous link.  After a moment the SDK should return a list that looks something like this:
+
+```
+[{'name': 'quality', 'display_name': 'Quality', 'unit': '', 'type': 'continuous', 'data_type': 'float', 'stream_types': [], 'raw_data_field': ''},...]
+```
+
+In order to make use of the data viz function you'll need the name of the KPI you wish to get.
+
+### Get KPI Data Viz
+Once you have the name of the KPI you wish to access and a logged in client you can make a call to the data viz api with the following SDK function call:
+```
+cli.get_kpi_data_viz(machine_source, kpis, i_vars, time_selection, **optional_data_viz_query)
+```
+
+After some time the SDK should return a list that looks something like this:
+```
+[{'i_vals': {'endtime': {'i_pos': 0, 'bin_no': 0, 'bin_min': '2022-10-20T00:00:00-07:00', 'bin_max': '2022-10-20T00:00:00-07:00', 'bin_avg': '2022-10-20T00:00:00-07:00'}}, 'd_vals': {'quality': {'avg': 95.18072289156626}}, '_count': 418, 'kpi_dependencies': {'quality': {'Output': 395.0, 'ScrapQuantity': 20.0}}},...]
+```
+
+There's two ways to call this function you can use a data_viz_query,For more information on [data_viz_queries](/docs/commonly_used_data_types/data_viz_query.md) click on the previous link, or have the function fill out the query for you by passing in a few variable we will now go over one at a time.
+
+#### machine_sources
+This is a list of strings and is the name of machine(s) you wish to run a query on.
+
+#### kpis
+This is a list of the names of all the kpis you wish to run this query on.
+
+#### i_vars
+This is a list, this is the same as the i_vars object in the data_viz_query and is the axis you are querying the kpis against it will look like the following:
+```
+[
+    {
+      "name": "endtime",
+      "time_resolution": "day",
+      "query_tz": "America/Los_Angeles",
+      "output_tz": "America/Los_Angeles"
+    }
+]
+```
+
+#### time_selection
+This is an object, this is the same as the [time_selection](/docs/commonly_used_data_types/data_viz_query.md#time_selection) object in the data_viz_query and more info can be found at that link.  The most common form is the relative time selection and looks like this:
+```
+{
+    "time_type": "relative",
+    "relative_start": 7,
+    "relative_unit": "day",
+    "ctime_tz": "America/Los_Angeles"
+}
+```

docs/entities/machine.md

@@ -0,0 +1,15 @@
+# Machines
+Machines are just that, machines in factories.  The machine object is how the Sight Machine software replesents and is the key to accessing data that we collect from them
+
+## Functions
+
+### get_type_from_machine
+The get_type_from_machine function allows you to get the type of any machine from it's name and is called this way:
+```
+cli.get_type_from_machine(machine_name)
+```
+
+And will return something like the following:
+```
+'Lasercut'
+```

smsdk/client.py

@@ -228,3 +228,53 @@ def get_machine_schema(self, machine_source, types=[], return_mtype=False, **kwa
                             f"Unknow stat schema identified :: machine_type {machine_source} - "
                             f"title_prefix :: {stat.get('display', {}).get('title_prefix', '')}")
         return fields
+    
+    def get_kpis(self, **kwargs):
+        kpis = smsdkentities.get('kpi')
+        base_url = get_url(
+            self.config["protocol"], self.tenant, self.config["site.domain"]
+        )
+        return kpis(self.session, base_url).get_kpis(**kwargs)
+    
+    def get_kpis_for_asset(self, **kwargs):
+        kpis = smsdkentities.get('kpi')
+        base_url = get_url(
+            self.config["protocol"], self.tenant, self.config["site.domain"]
+        )
+        return kpis(self.session, base_url).get_kpis_for_asset(**kwargs)
+    
+    def get_kpi_data_viz(self, machine_sources=None, kpis=None, i_vars=None, time_selection=None, **kwargs):
+        kpi_entity = smsdkentities.get('kpi')
+        if machine_sources:
+            machine_types = []
+            for machine_source in machine_sources:
+                machine_types.append(self.get_type_from_machine(machine_source, **kwargs))
+            kwargs["asset_selection"]= {
+                "machine_source": machine_sources,
+                "machine_type": list(set(machine_types))
+            }
+        
+        if kpis:
+            d_vars = []
+            for kpi in kpis:
+                d_vars.append({"name": kpi, "aggregate": ["avg"]})
+            kwargs['d_vars'] = d_vars
+        
+        if i_vars:
+            kwargs['i_vars'] = i_vars
+        
+        if time_selection:
+            kwargs["time_selection"] = time_selection
+        
+        base_url = get_url(
+            self.config["protocol"], self.tenant, self.config["site.domain"]
+        )
+        return kpi_entity(self.session, base_url).get_kpi_data_viz(**kwargs)
+        
+    def get_type_from_machine(self, machine_source=None, **kwargs):
+        machine = smsdkentities.get('machine')
+        base_url = get_url(
+            self.config["protocol"], self.tenant, self.config["site.domain"]
+        )
+        return machine(self.session, base_url).get_type_from_machine_name(machine_source, **kwargs)
+

smsdk/config/api_endpoints.json

@@ -28,6 +28,13 @@
   },
   "DataViz": {
     "estimate_cycle": "/v1/selector/datavis/estimate/cycle",
-    "estimate_part": "/v1/selector/datavis/estimate/part"
+    "estimate_part": "/v1/selector/datavis/estimate/part",
+    "task": "/v1/datavis/task/async"
+  },
+  "KPI": {
+    "availible_kpis_for_asset": "/v1/selector/datavis/kpi/y_axis"
+  },
+  "Assets": { 
+    "url":"/v1/selector/assets"
   }
 }