wizata-dsapi 2.2.0.dev3__tar.gz → 2.2.0.dev6__tar.gz

{wizata_dsapi-2.2.0.dev3 → wizata_dsapi-2.2.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wizata_dsapi
-Version: 2.2.0.dev3
+Version: 2.2.0.dev6
 Summary: Wizata Data Science Toolkit
 Author: Wizata S.A.
 Author-email: info@wizata.com

{wizata_dsapi-2.2.0.dev3 → wizata_dsapi-2.2.0.dev6}/wizata_dsapi/__init__.py

@@ -66,6 +66,9 @@ from .connection import Connection, ConnectionMapping, ConnectionDirection, Tran
 from .connection_types import ConnectionType, CONNECTION_TYPES, TRANSFORM_SCHEMAS, get_connection_type, \
     list_connection_types
 from .product import ProductKind, Product, ProductComponent, BUILTIN_PRODUCT_KINDS, is_valid_product_key
+from .inventory import (InventoryBalance, inventory_mode, INVENTORY_OPTION, INVENTORY_MODES,
+                        INVENTORY_MOVEMENTS, INVENTORY_BALANCES, INVENTORY_STOCK,
+                        PRODUCT_TAG, PRODUCT_MESSAGE_KEY)
 from .dashboard import Dashboard, DashboardType
 from .mobile_asset import MobileAssetTile, MobileAssetTileType, MobileAssetConfig
 from .graylog_log import GraylogLog

{wizata_dsapi-2.2.0.dev3 → wizata_dsapi-2.2.0.dev6}/wizata_dsapi/datapoint.py

@@ -198,6 +198,11 @@ class BusinessType(Enum):
         - "event" represents a state or probability that have a start and stop timestamp.
         - "text" represents a time-series emitted as text/string value.
         - "scoped" represents a time-series with values split by a scope tag (e.g. anomaly probabilities per category).
+        - "inventoryMovement" represents stock movements of a storage twin: each point is a signed quantity
+          (+ in, - out) of one product, named by its ``productKey`` tag (Production Planner).
+
+    The order is the backend's: the SQL selector sends a value's position as the stored
+    integer, so a new value is always appended last.
     """
     TELEMETRY = "telemetry"
     SET_POINTS = "setPoint"
@@ -206,6 +211,7 @@ class BusinessType(Enum):
     EVENT = "event"
     TEXT = "text"
     SCOPED = "scoped"
+    INVENTORY_MOVEMENT = "inventoryMovement"
 
 
 class InputModeType(Enum):

wizata_dsapi-2.2.0.dev6/wizata_dsapi/inventory.py

@@ -0,0 +1,148 @@
+"""
+Production Planner inventory (epic DEV-6044, release 12.2).
+
+Two facts, and stock is derived from both:
+
+- **Movements** are points on a DataPoint of business type ``inventoryMovement``, one
+  per storage Twin and category. Each point is a signed quantity (+ in, - out) in the
+  DataPoint's unit, and its ``productKey`` tag names the product.
+- **Balances** (:class:`InventoryBalance`) are absolute levels counted at a moment
+  ("460 L of coke in the tank at 16:00"), stored in PostgreSQL on the same DataPoint.
+
+A query chooses what it reads with ``options={"inventory": ...}``:
+
+- ``movements`` (the default): the DataPoint's own points, one series per product.
+- ``balances``: the recorded balances, one series per product.
+- ``stock``: the level. Take the last balance before each moment, then add the
+  movements after it. A balance at T already counts every movement at or before T.
+  A product never counted starts from 0.
+
+``Request.products`` keeps only some products. Columns are named
+``<hardwareId>|<productKey>``.
+"""
+
+from datetime import datetime, timezone
+from typing import Optional
+
+#: Request option that chooses what an inventoryMovement DataPoint returns.
+INVENTORY_OPTION = "inventory"
+INVENTORY_MOVEMENTS = "movements"
+INVENTORY_BALANCES = "balances"
+INVENTORY_STOCK = "stock"
+INVENTORY_MODES = (INVENTORY_MOVEMENTS, INVENTORY_BALANCES, INVENTORY_STOCK)
+
+#: Time-series tag that carries the product key on a movement point.
+PRODUCT_TAG = "productKey"
+#: Message key that carries it to the writers (``Scope``, ``EventType`` style).
+PRODUCT_MESSAGE_KEY = "ProductKey"
+
+
+def inventory_mode(options) -> str:
+    """The inventory mode a request's options ask for; ``movements`` when unset."""
+    mode = None
+    if isinstance(options, dict):
+        mode = options.get(INVENTORY_OPTION)
+    if mode is None:
+        return INVENTORY_MOVEMENTS
+    if mode not in INVENTORY_MODES:
+        raise ValueError(f"options.{INVENTORY_OPTION} must be one of {', '.join(INVENTORY_MODES)} "
+                         f"but received {mode!r}"[:300])
+    return mode
+
+
+def _ts_out(value):
+    if value is None:
+        return None
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.isoformat()
+
+
+def _ts_in(value):
+    """A datetime from ISO 8601 or epoch milliseconds; anything else is kept as sent,
+    for the server to refuse with a message that names it."""
+    if value is None or isinstance(value, datetime):
+        return value
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return datetime.fromtimestamp(value / 1000, tz=timezone.utc)
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return value
+
+
+def _uuid_str(value):
+    if value is None or value == "":
+        return None
+    return str(value).lower()
+
+
+class InventoryBalance:
+    """
+    An absolute stock level: ``quantity`` of ``product`` on the inventoryMovement
+    DataPoint ``datapoint`` (a hardware id), true at ``timestamp`` (when it was
+    counted, not when it was recorded: that is ``created_at``).
+
+    PostgreSQL ``"InventoryBalance"``, PK (``datapoint``, ``product``, ``timestamp``).
+    Writing the same key again replaces the quantity.
+
+    On write only:
+
+    - ``twin`` (a Twin hardware id) may replace ``datapoint``. The DataPoint is then
+      the Twin's inventoryMovement DataPoint of the product's category.
+    - ``unit`` (a backend unit id of the product's category) converts ``quantity`` to
+      the DataPoint's unit. It is stored in that unit, so a read never carries ``unit``.
+    """
+
+    @classmethod
+    def route(cls):
+        return "planner/inventory/balances"
+
+    def __init__(self, datapoint: str = None, product: str = None, timestamp=None,
+                 quantity: float = None, unit=None, twin: str = None):
+        self.datapoint: Optional[str] = datapoint
+        self.product: Optional[str] = product
+        self.timestamp: Optional[datetime] = _ts_in(timestamp)
+        self.quantity: Optional[float] = quantity
+        self.unit: Optional[str] = _uuid_str(unit)
+        self.twin: Optional[str] = twin
+        self.created_at: Optional[datetime] = None
+        self.created_by: Optional[str] = None
+        self.updated_at: Optional[datetime] = None
+        self.updated_by: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        obj = {}
+        for name, value in (("datapoint", self.datapoint), ("product", self.product),
+                            ("quantity", self.quantity), ("unit", self.unit),
+                            ("twin", self.twin), ("createdBy", self.created_by),
+                            ("updatedBy", self.updated_by)):
+            if value is not None:
+                obj[name] = value
+        for name, value in (("timestamp", self.timestamp), ("createdAt", self.created_at),
+                            ("updatedAt", self.updated_at)):
+            if value is not None:
+                obj[name] = _ts_out(value) if isinstance(value, datetime) else value
+        return obj
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "InventoryBalance":
+        obj = cls()
+        obj.datapoint = data.get("datapoint")
+        obj.product = data.get("product")
+        obj.timestamp = _ts_in(data.get("timestamp"))
+        obj.quantity = data.get("quantity")
+        obj.unit = _uuid_str(data.get("unit"))
+        obj.twin = data.get("twin")
+        obj.created_at = _ts_in(data.get("createdAt") or data.get("created_at"))
+        obj.created_by = data.get("createdBy") or data.get("created_by")
+        obj.updated_at = _ts_in(data.get("updatedAt") or data.get("updated_at"))
+        obj.updated_by = data.get("updatedBy") or data.get("updated_by")
+        return obj
+
+    def key(self) -> tuple:
+        return self.datapoint, self.product, self.timestamp
+
+    def __repr__(self) -> str:
+        return (f"InventoryBalance(datapoint={self.datapoint!r}, product={self.product!r}, "
+                f"timestamp={self.timestamp!r}, quantity={self.quantity!r})")

{wizata_dsapi-2.2.0.dev3 → wizata_dsapi-2.2.0.dev6}/wizata_dsapi/request.py

@@ -164,6 +164,8 @@ class Request(ApiDto):
     :ivar uuid.UUID twin_id: technical id of wizata_dsapi.Twin registered on template_id.
     :ivar dict filters: filters to apply to the query pre-aggregation. nested dictionary using as first key=datapoint then value=another dictionary with key=operator (gt,lt,gte,lte,eq,neq) and value is the float value to compare too).
     :ivar dict options: dict representing query options.
+    :ivar list scopes: scope filters for SCOPED datapoints.
+    :ivar list products: product keys to keep on inventoryMovement datapoints (all when None).
     """
 
     @classmethod
@@ -198,7 +200,8 @@ class Request(ApiDto):
                  field=None,
                  bucket=None,
                  tags=None,
-                 scopes=None):
+                 scopes=None,
+                 products=None):
         if request_id is None:
             request_id = uuid.uuid4()
         self.request_id = request_id
@@ -242,6 +245,7 @@ class Request(ApiDto):
         self.bucket = bucket
         self.tags = tags
         self.scopes = scopes
+        self.products = products
 
         self.null = null
 
@@ -623,6 +627,8 @@ class Request(ApiDto):
             query['tags'] = self.tags
         if self.scopes is not None:
             query['scopes'] = self.scopes
+        if self.products is not None:
+            query['products'] = self.products
 
         if self.target_feat is not None:
             query["target_feat"] = {
@@ -644,6 +650,17 @@ class Request(ApiDto):
 
         return query
 
+    @staticmethod
+    def _object(value, section: str) -> dict:
+        """
+        A section of the body that must be a JSON object. Anything else is the caller's
+        mistake, refused as a ValueError naming it (the DS API answers 400) - it used to
+        reach ``.keys()`` and fail as an AttributeError, answered 500.
+        """
+        if not isinstance(value, dict):
+            raise ValueError(f"'{section}' must be an object, got {type(value).__name__}: {value!r}"[:300])
+        return value
+
     def from_json(self, json_data):
         if "id" in json_data.keys():
             self.request_id = uuid.UUID(json_data["id"])
@@ -654,6 +671,7 @@ class Request(ApiDto):
         datapoints = []
         if "equipments_list" in json_data.keys():
             for equipment in json_data["equipments_list"]:
+                self._object(equipment, "equipments_list")
                 if "datapoints" not in equipment.keys():
                     raise KeyError("no 'datapoints' have been provided for equipment with id '" +
                                    str(equipment["id"]) + "'")
@@ -674,6 +692,7 @@ class Request(ApiDto):
             self._datapoints = []
 
         if "timeframe" in json_data.keys():
+            self._object(json_data["timeframe"], "timeframe")
             if "start" not in json_data["timeframe"].keys():
                 raise KeyError("No 'start time' have been selected, please set it up and re-try.")
 
@@ -695,6 +714,7 @@ class Request(ApiDto):
 
         if "aggregations" not in json_data.keys():
             raise KeyError("No 'aggregations' have been selected, please set it up and re-try.")
+        self._object(json_data["aggregations"], "aggregations")
 
         if "agg_method" not in json_data["aggregations"].keys():
             self.aggregation = None
@@ -744,6 +764,13 @@ class Request(ApiDto):
         if "scopes" in json_data.keys():
             self.scopes = json_data["scopes"]
 
+        if "products" in json_data.keys():
+            products = json_data["products"]
+            if products is not None and (not isinstance(products, list)
+                                         or not all(isinstance(p, str) for p in products)):
+                raise ValueError(f"'products' must be a list of product keys, got {products!r}"[:300])
+            self.products = products
+
         if "connections" in json_data.keys():
             self.connections = json_data["connections"]
 
@@ -751,7 +778,7 @@ class Request(ApiDto):
             self.null = json_data["null"]
 
         if "target_feat" in json_data.keys():
-            self.target_feat = json_data["target_feat"]
+            self.target_feat = self._object(json_data["target_feat"], "target_feat")
             if "sensor" not in self.target_feat.keys():
                 raise KeyError("No 'sensor' have been declared inside the target feature, this is a technical error.")
             if "operator" not in self.target_feat.keys():

wizata_dsapi-2.2.0.dev6/wizata_dsapi/version.py

@@ -0,0 +1 @@
+__version__ = "2.2.0.dev6"

{wizata_dsapi-2.2.0.dev3 → wizata_dsapi-2.2.0.dev6}/wizata_dsapi/wizata_dsapi_client.py

@@ -55,6 +55,7 @@ from .version import __version__
 import ast
 from .deployment import Deployment, DeploymentStatus
 from .product import ProductKind, Product, ProductComponent
+from .inventory import InventoryBalance
 from .api_config import _registry
 
 from .streamlit_utils import get_streamlit_token, get_streamlit_domain
@@ -773,7 +774,8 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
                        field=None,
                        bucket: str = None,
                        tags: dict = None,
-                       scopes: list = None) -> Request:
+                       scopes: list = None,
+                       products: list = None) -> Request:
         """
         Build the Request behind a time-series query.
 
@@ -816,6 +818,9 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
         if scopes is not None:
             request.scopes = scopes
 
+        if products is not None:
+            request.products = products
+
         if options is not None:
             request.options = options
 
@@ -847,7 +852,8 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
               field=None,
               bucket: str = None,
               tags: dict = None,
-              scopes: list = None) -> pandas.DataFrame:
+              scopes: list = None,
+              products: list = None) -> pandas.DataFrame:
         """
         Query a dataframe from API.
         :param agg_method:
@@ -864,13 +870,15 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
         :param field: by default 'value' if none, accept str or list (e.g. value, reliability, eventId, ...)
         :param bucket: specify on which bucket the query applies.
         :param scopes: list of scope filters for SCOPED datapoints (e.g. ["normal", {"vibration": {"gte": 0.6}}]).
+        :param products: product keys to keep on inventoryMovement datapoints (all when None).
+            ``options={"inventory": "movements" | "balances" | "stock"}`` chooses what they return.
         :return: dataframe
         """
         return self._query(request=self._build_request(
             datapoints=datapoints, start=start, end=end, interval=interval,
             agg_method=agg_method, template=template, twin=twin, null=null,
             filters=filters, options=options, group=group, field=field,
-            bucket=bucket, tags=tags, scopes=scopes))
+            bucket=bucket, tags=tags, scopes=scopes, products=products))
 
     def batch_query(self,
                     step: timedelta,
@@ -2867,6 +2875,54 @@ class WizataDSAPIClient(ApiInterface, ApiDtoInterface):
             "PUT", f"planner/products/{self._planner_key(product)}/components/", body=body)
         return [ProductComponent.from_dict(c) for c in response.json()]
 
+    # Production Planner - inventory balances (epic DEV-6044)
+
+    def set_inventory_balances(self, balances: list) -> list:
+        """
+        Record absolute stock levels (a count, an ERP figure). Writing the same
+        (datapoint, product, timestamp) again replaces the quantity.
+
+        :param balances: list of InventoryBalance (or dicts). Each names its
+            inventoryMovement DataPoint by ``datapoint``, or by ``twin`` (the DataPoint
+            of the product's category on that Twin). ``unit`` converts the quantity to
+            the DataPoint's unit.
+        :return: the stored balances, quantities in the DataPoint's unit.
+        """
+        body = [b.to_dict() if isinstance(b, InventoryBalance) else b for b in balances]
+        response = self._planner_request("POST", "planner/inventory/balances/", body=body)
+        return [InventoryBalance.from_dict(b) for b in response.json()]
+
+    def search_inventory_balances(self, search_query=None) -> PagedQueryResult:
+        """
+        List recorded balances, newest first by default.
+
+        :param search_query: SearchQuery or dict; filters on ``datapoint`` and
+            ``product`` (eq / in) and ``timestamp`` (gte / gt / lt / lte).
+        :return: PagedQueryResult with InventoryBalance results.
+        """
+        if search_query is None:
+            search_query = SearchQuery()
+        elif isinstance(search_query, dict):
+            search_query = SearchQuery.from_dict(search_query)
+        response = self._planner_request("POST", "planner/inventory/balances/search",
+                                         body=search_query.to_dict())
+        return PagedQueryResult.from_dict(response.json(), dto_class=InventoryBalance)
+
+    def delete_inventory_balance(self, datapoint: str, product: str, timestamp):
+        """
+        Delete one recorded balance (a count entered by mistake).
+
+        :param timestamp: datetime or ISO string, exactly as stored.
+        """
+        if isinstance(timestamp, datetime.datetime):
+            if timestamp.tzinfo is None:
+                timestamp = timestamp.replace(tzinfo=datetime.timezone.utc)
+            timestamp = timestamp.isoformat()
+        self._planner_request("DELETE", "planner/inventory/balances/",
+                              params={"datapoint": datapoint, "product": product,
+                                      "timestamp": timestamp},
+                              expected=(204,))
+
 
 def api() -> WizataDSAPIClient:
     """

{wizata_dsapi-2.2.0.dev3 → wizata_dsapi-2.2.0.dev6}/wizata_dsapi.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wizata_dsapi
-Version: 2.2.0.dev3
+Version: 2.2.0.dev6
 Summary: Wizata Data Science Toolkit
 Author: Wizata S.A.
 Author-email: info@wizata.com

{wizata_dsapi-2.2.0.dev3 → wizata_dsapi-2.2.0.dev6}/wizata_dsapi.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ wizata_dsapi/graylog_log.py
 wizata_dsapi/group_system.py
 wizata_dsapi/ilogger.py
 wizata_dsapi/insight.py
+wizata_dsapi/inventory.py
 wizata_dsapi/mlmodel.py
 wizata_dsapi/mobile_asset.py
 wizata_dsapi/model_toolkit.py

wizata_dsapi-2.2.0.dev3/wizata_dsapi/version.py

@@ -1 +0,0 @@
-__version__ = "2.2.0.dev3"