[PLA-9255] Switching to v3 predictor endpoints.

This involves a change in some endpoint behavior, as well as a complete
change in the payload shape. Backwards comptability is retained, and
some fields/methods/usages have been deprecated in favor of new
versions e.g. a "train" method separate from update.

Author: anoto-moniz

src/citrine/__version__.py

@@ -1 +1 @@
-__version__ = '1.30.3'
+__version__ = '1.31.0'

src/citrine/_rest/engine_resource.py

@@ -0,0 +1,88 @@
+from deprecation import deprecated
+from typing import List, TypeVar
+
+from citrine._rest.resource import Resource, ResourceTypeEnum
+from citrine._serialization import properties
+
+
+Self = TypeVar('Self', bound='Resource')
+
+
+# This class is the base type for the new module endpoints. Currently, it only covers predictors,
+# but should be applicable for others as they're written.
+class EngineResource(Resource[Self]):
+    """Base resource for predictors, including metadata representation."""
+
+    created_by = properties.Optional(properties.UUID, 'metadata.created.user', serializable=False)
+    """:Optional[UUID]: id of the user who created the resource"""
+    create_time = properties.Optional(properties.Datetime, 'metadata.created.time',
+                                      serializable=False)
+    """:Optional[datetime]: date and time at which the resource was created"""
+
+    updated_by = properties.Optional(properties.UUID, 'metadata.updated.user',
+                                     serializable=False)
+    """:Optional[UUID]: id of the user who most recently updated the resource,
+    if it has been updated"""
+    update_time = properties.Optional(properties.Datetime, 'metadata.updated.time',
+                                      serializable=False)
+    """:Optional[datetime]: date and time at which the resource was most recently updated,
+    if it has been updated"""
+
+    archived_by = properties.Optional(properties.UUID, 'metadata.archived.user',
+                                      serializable=False)
+    """:Optional[UUID]: id of the user who archived the resource, if it has been archived"""
+    archive_time = properties.Optional(properties.Datetime, 'metadata.archived.time',
+                                       serializable=False)
+    """:Optional[datetime]: date and time at which the resource was archived,
+    if it has been archived"""
+
+    status = properties.Optional(properties.String(), 'metadata.status.name', serializable=False)
+    """:Optional[str]: short description of the resource's status"""
+    status_info = properties.Optional(properties.List(properties.String()), 'metadata.status.info',
+                                      serializable=False)
+
+    # Due to the way object construction is done at present, __init__ is not executed on Resource
+    # objects, so initializing _archived doesn't work.
+    _archived = properties.Optional(properties.Boolean(), '', default=None, serializable=False,
+                                    deserializable=False)
+
+    _resource_type = ResourceTypeEnum.MODULE
+
+    @property
+    def is_archived(self):
+        """:bool: whether the resource is archived (hidden but not deleted)."""
+        return self.archived_by is not None
+
+    @property
+    @deprecated(deprecated_in="1.31.0", removed_in="2.0.0",
+                details="Please use the 'is_archived' property instead.'")
+    def archived(self):
+        """[DEPRECATED] whether the resource is archived."""
+        return self.is_archived
+
+    @archived.setter
+    @deprecated(deprecated_in="1.31.0", removed_in="2.0.0",
+                details="Please use archive() and restore() on PredictorCollection instead.")
+    def archived(self, value):
+        self._archived = value
+
+    @property
+    @deprecated(deprecated_in="1.25.0", removed_in="2.0.0")
+    def experimental(self) -> bool:
+        """[DEPRECATED] whether the execution is experimental (newer, less well-tested)."""  # noqa - insisting this docstring is a signature
+        return False
+
+    @property
+    @deprecated(deprecated_in="1.25.0", removed_in="2.0.0")
+    def experimental_reasons(self) -> List[str]:
+        """[DEPRECATED] human-readable reasons why the execution is experimental."""
+        return []
+
+    def _post_dump(self, data: dict) -> dict:
+        # Only the data portion of an entity is sent to the server.
+        data = data["data"]
+
+        # Currently, name and description exists on both the data envelope and the config.
+        data["instance"]["name"] = data["name"]
+        data["instance"]["description"] = data["description"]
+        return data

src/citrine/informatics/modules.py

@@ -31,9 +31,7 @@ def get_type(cls, data) -> Type['Module']:
         """Return the subtype."""
         from citrine.informatics.design_spaces import DesignSpace
         from citrine.informatics.processors import Processor
-        from citrine.informatics.predictors import Predictor
         return {
             'DESIGN_SPACE': DesignSpace,
-            'PROCESSOR': Processor,
-            'PREDICTOR': Predictor
+            'PROCESSOR': Processor
         }[data['module_type']].get_type(data)

src/citrine/informatics/predictors/auto_ml_predictor.py

@@ -1,17 +1,16 @@
 import warnings
 from typing import List, Optional
 
-from citrine._rest.resource import Resource, ResourceTypeEnum
+from citrine._rest.engine_resource import EngineResource
 from citrine._serialization import properties as _properties
 from citrine.informatics.data_sources import DataSource
 from citrine.informatics.descriptors import Descriptor
 from citrine.informatics.predictors import Predictor
-from citrine._rest.ai_resource_metadata import AIResourceMetadata
 
 __all__ = ['AutoMLPredictor']
 
 
-class AutoMLPredictor(Resource['AutoMLPredictor'], Predictor, AIResourceMetadata):
+class AutoMLPredictor(EngineResource['AutoMLPredictor'], Predictor):
     """A predictor interface that builds a single ML model.
 
     The model uses the set of inputs to predict the output(s).
@@ -41,15 +40,12 @@ class AutoMLPredictor(Resource['AutoMLPredictor'], Predictor, AIResourceMetadata
 
     """
 
-    _resource_type = ResourceTypeEnum.MODULE
-
-    inputs = _properties.List(_properties.Object(Descriptor), 'config.inputs')
-    outputs = _properties.List(_properties.Object(Descriptor), 'config.outputs')
+    inputs = _properties.List(_properties.Object(Descriptor), 'data.instance.inputs')
+    outputs = _properties.List(_properties.Object(Descriptor), 'data.instance.outputs')
     training_data = _properties.List(_properties.Object(DataSource),
-                                     'config.training_data', default=[])
+                                     'data.instance.training_data', default=[])
 
-    typ = _properties.String('config.type', default='AutoML', deserializable=False)
-    module_type = _properties.String('module_type', default='PREDICTOR')
+    typ = _properties.String('data.instance.type', default='AutoML', deserializable=False)
 
     def __init__(self,
                  name: str,
@@ -78,10 +74,6 @@ def __init__(self,
         elif output is not None:
             self.outputs = [output]
 
-    def _post_dump(self, data: dict) -> dict:
-        data['display_name'] = data['config']['name']
-        return data
-
     @property
     def output(self) -> Optional[Descriptor]:
         """[DEPRECATED] Get the first output descriptor."""

src/citrine/informatics/predictors/chemical_formula_featurizer.py

@@ -1,16 +1,14 @@
 from typing import List, Optional
 
-from citrine._rest.resource import Resource, ResourceTypeEnum
+from citrine._rest.engine_resource import EngineResource
 from citrine._serialization import properties as _properties
 from citrine.informatics.descriptors import ChemicalFormulaDescriptor, Descriptor
 from citrine.informatics.predictors import Predictor
-from citrine._rest.ai_resource_metadata import AIResourceMetadata
 
 __all__ = ['ChemicalFormulaFeaturizer']
 
 
-class ChemicalFormulaFeaturizer(Resource['ChemicalFormulaFeaturizer'],
-                                Predictor, AIResourceMetadata):
+class ChemicalFormulaFeaturizer(EngineResource['ChemicalFormulaFeaturizer'], Predictor):
     """
     A featurizer for chemical formulae. Inspired by Magpie.
 
@@ -132,16 +130,13 @@ class ChemicalFormulaFeaturizer(Resource['ChemicalFormulaFeaturizer'],
 
     """
 
-    _resource_type = ResourceTypeEnum.MODULE
+    input_descriptor = _properties.Object(Descriptor, 'data.instance.input')
+    features = _properties.List(_properties.String, 'data.instance.features')
+    excludes = _properties.List(_properties.String, 'data.instance.excludes')
+    powers = _properties.List(_properties.Integer, 'data.instance.powers')
 
-    input_descriptor = _properties.Object(Descriptor, 'config.input')
-    features = _properties.List(_properties.String, 'config.features')
-    excludes = _properties.List(_properties.String, 'config.excludes')
-    powers = _properties.List(_properties.Integer, 'config.powers')
-
-    typ = _properties.String('config.type', default='ChemicalFormulaFeaturizer',
+    typ = _properties.String('data.instance.type', default='ChemicalFormulaFeaturizer',
                              deserializable=False)
-    module_type = _properties.String('module_type', default='PREDICTOR')
 
     def __init__(self,
                  name: str,
@@ -158,9 +153,5 @@ def __init__(self,
         self.excludes = excludes if excludes is not None else []
         self.powers = powers if powers is not None else [1]
 
-    def _post_dump(self, data: dict) -> dict:
-        data['display_name'] = data['config']['name']
-        return data
-
     def __str__(self):
         return '<ChemicalFormulaFeaturizer {!r}>'.format(self.name)

src/citrine/informatics/predictors/expression_predictor.py

@@ -1,15 +1,14 @@
 from typing import Mapping
 
-from citrine._rest.resource import Resource
+from citrine._rest.engine_resource import EngineResource
 from citrine._serialization import properties as _properties
 from citrine.informatics.descriptors import RealDescriptor
 from citrine.informatics.predictors import Predictor
-from citrine._rest.ai_resource_metadata import AIResourceMetadata
 
 __all__ = ['ExpressionPredictor']
 
 
-class ExpressionPredictor(Resource['ExpressionPredictor'], Predictor, AIResourceMetadata):
+class ExpressionPredictor(EngineResource['ExpressionPredictor'], Predictor):
     """A predictor that computes an output from an expression and set of bounded inputs.
 
     For a discussion of expression syntax and a list of allowed symbols,
@@ -31,13 +30,13 @@ class ExpressionPredictor(Resource['ExpressionPredictor'], Predictor, AIResource
 
     """
 
-    expression = _properties.String('config.expression')
-    output = _properties.Object(RealDescriptor, 'config.output')
+    expression = _properties.String('data.instance.expression')
+    output = _properties.Object(RealDescriptor, 'data.instance.output')
     aliases = _properties.Mapping(_properties.String, _properties.Object(RealDescriptor),
-                                  'config.aliases')
+                                  'data.instance.aliases')
 
-    typ = _properties.String('config.type', default='AnalyticExpression', deserializable=False)
-    module_type = _properties.String('module_type', default='PREDICTOR')
+    typ = _properties.String('data.instance.type',
+                             default='AnalyticExpression', deserializable=False)
 
     def __init__(self,
                  name: str,
@@ -52,9 +51,5 @@ def __init__(self,
         self.output: RealDescriptor = output
         self.aliases: Mapping[str, RealDescriptor] = aliases
 
-    def _post_dump(self, data: dict) -> dict:
-        data['display_name'] = data['config']['name']
-        return data
-
     def __str__(self):
         return '<ExpressionPredictor {!r}>'.format(self.name)

src/citrine/informatics/predictors/graph_predictor.py

@@ -1,16 +1,15 @@
 from typing import List, Optional, Union
 from uuid import UUID
 
-from citrine._rest.resource import Resource, ResourceTypeEnum
+from citrine._rest.engine_resource import EngineResource
 from citrine._serialization import properties as _properties
 from citrine.informatics.data_sources import DataSource
 from citrine.informatics.predictors import Predictor
-from citrine._rest.ai_resource_metadata import AIResourceMetadata
 
 __all__ = ['GraphPredictor']
 
 
-class GraphPredictor(Resource['GraphPredictor'], Predictor, AIResourceMetadata):
+class GraphPredictor(EngineResource['GraphPredictor'], Predictor):
     """A predictor interface that stitches other predictors together.
 
     Parameters
@@ -32,17 +31,14 @@ class GraphPredictor(Resource['GraphPredictor'], Predictor, AIResourceMetadata):
 
     """
 
-    _resource_type = ResourceTypeEnum.MODULE
-
     predictors = _properties.List(_properties.Union(
-        [_properties.UUID, _properties.Object(Predictor)]), 'config.predictors')
+        [_properties.UUID, _properties.Object(Predictor)]), 'data.instance.predictors')
     # the default seems to be defined in instances, not the class itself
     # this is tested in test_graph_default_training_data
     training_data = _properties.List(_properties.Object(DataSource),
-                                     'config.training_data', default=[])
+                                     'data.instance.training_data', default=[])
 
-    typ = _properties.String('config.type', default='Graph', deserializable=False)
-    module_type = _properties.String('module_type', default='PREDICTOR')
+    typ = _properties.String('data.instance.type', default='Graph', deserializable=False)
 
     def __init__(self,
                  name: str,
@@ -56,32 +52,19 @@ def __init__(self,
         self.training_data: List[DataSource] = training_data or []
 
     def _post_dump(self, data: dict) -> dict:
-        data['display_name'] = data['config']['name']
-        for i, predictor in enumerate(data['config']['predictors']):
+        data = super()._post_dump(data)
+        for i, predictor in enumerate(data['instance']['predictors']):
             if isinstance(predictor, dict):
                 # embedded predictors are not modules, so only serialize their config
-                data['config']['predictors'][i] = predictor['config']
+                data['instance']['predictors'][i] = predictor['instance']
         return data
 
     @classmethod
     def _pre_build(cls, data: dict) -> dict:
-        for i, predictor in enumerate(data['config']['predictors']):
-            if isinstance(predictor, dict):
-                data['config']['predictors'][i] = \
-                    GraphPredictor.stuff_predictor_into_envelope(predictor)
+        for i, predictor_data in enumerate(data['data']['instance']['predictors']):
+            if isinstance(predictor_data, dict):
+                data['data']['instance']['predictors'][i] = Predictor.wrap_instance(predictor_data)
         return data
 
-    @staticmethod
-    def stuff_predictor_into_envelope(predictor: dict) -> dict:
-        """Insert a serialized embedded predictor into a module envelope.
-
-        This facilitates deserialization.
-        """
-        return dict(
-            module_type='PREDICTOR',
-            config=predictor,
-            archived=False
-        )
-
     def __str__(self):
         return '<GraphPredictor {!r}>'.format(self.name)

src/citrine/informatics/predictors/ingredient_fractions_predictor.py

@@ -1,16 +1,14 @@
 from typing import Set
 
-from citrine._rest.resource import Resource, ResourceTypeEnum
+from citrine._rest.engine_resource import EngineResource
 from citrine._serialization import properties as _properties
 from citrine.informatics.descriptors import FormulationDescriptor
 from citrine.informatics.predictors import Predictor
-from citrine._rest.ai_resource_metadata import AIResourceMetadata
 
 __all__ = ['IngredientFractionsPredictor']
 
 
-class IngredientFractionsPredictor(Resource["IngredientFractionsPredictor"],
-                                   Predictor, AIResourceMetadata):
+class IngredientFractionsPredictor(EngineResource["IngredientFractionsPredictor"], Predictor):
     """A predictor interface that computes ingredient fractions.
 
     Parameters
@@ -27,13 +25,10 @@ class IngredientFractionsPredictor(Resource["IngredientFractionsPredictor"],
 
     """
 
-    _resource_type = ResourceTypeEnum.MODULE
+    input_descriptor = _properties.Object(FormulationDescriptor, 'data.instance.input')
+    ingredients = _properties.Set(_properties.String, 'data.instance.ingredients')
 
-    input_descriptor = _properties.Object(FormulationDescriptor, 'config.input')
-    ingredients = _properties.Set(_properties.String, 'config.ingredients')
-
-    module_type = _properties.String('module_type', default='PREDICTOR')
-    typ = _properties.String('config.type', default='IngredientFractions',
+    typ = _properties.String('data.instance.type', default='IngredientFractions',
                              deserializable=False)
 
     def __init__(self,
@@ -47,9 +42,5 @@ def __init__(self,
         self.input_descriptor: FormulationDescriptor = input_descriptor
         self.ingredients: Set[str] = ingredients
 
-    def _post_dump(self, data: dict) -> dict:
-        data['display_name'] = data['config']['name']
-        return data
-
     def __str__(self):
         return '<IngredientFractionsPredictor {!r}>'.format(self.name)