20851: Add replica support. MINOR

Add support to AbstractHowsoClient to include general runtime resource
parameters.  `create_trainee()` and `copy_trainee()` have a new
`runtime` parameter which encapsulates arbitrary client-specific
options.  This structure includes the existing `library_type` and
`resources` parameters, which are now deprecated.  Other client
implementations may add other runtime parameters.

Required code change to implementations of AbstractHowsoClient.
Programs that merely consume the client will work unmodified, with a
deprecation warning if they use the `library_type` or `resources`
parameters; consider migrating these into `runtime`.

howso/client/base.py

@@ -16,7 +16,15 @@
 from howso.utilities.features import serialize_cases
 from howso.utilities.monitors import ProgressTimer
 from .exceptions import HowsoError, UnsupportedArgumentWarning
-from .schemas import HowsoVersion, Project, Reaction, Session, Trainee, TraineeRuntime
+from .schemas import (
+    HowsoVersion,
+    Project,
+    Reaction,
+    Session,
+    Trainee,
+    TraineeRuntime,
+    TraineeRuntimeOptions
+)
 from .typing import (
     CaseIndices,
     Cases,
@@ -292,9 +300,66 @@ def create_trainee(
         overwrite_trainee: bool = False,
         persistence: Persistence = "allow",
         project: t.Optional[str | Project] = None,
-        resources: t.Optional[Mapping[str, t.Any]] = None
+        resources: t.Optional[Mapping[str, t.Any]] = None,
+        runtime: t.Optional[TraineeRuntimeOptions] = None
     ) -> Trainee:
-        """Create a Trainee in the Howso service."""
+        """
+        Create a trainee on the Howso service.
+
+        A trainee can be thought of as "model" in traditional ML sense.
+
+        Implementations of the client may honor different subsets of these
+        parameters.
+
+        Parameters
+        ----------
+        name : str, optional
+            A name to use for the Trainee.
+        features : dict, optional
+            The Trainee feature attributes.
+        id : str or UUID, optional
+            A custom unique identifier to use with the Trainee, if the client
+            implementation supports manually assigning the name.
+        library_type : str, optional
+            The library type of the Trainee, if the client implementation
+            supports dynamically selecting this.
+
+            .. deprecated:: 31.0
+                Pass via `runtime` instead.
+        max_wait_time : int or float, default 30
+            The number of seconds to wait for a trainee to be created
+            and become available before aborting gracefully, if the client
+            supports this.
+
+            Set to `0` (or None) to wait as long as the system-configured maximum for
+            sufficient resources to become available, which is typically 20 minutes.
+        metadata : MutableMapping, optional
+            Arbitrary jsonifiable data to store along with the Trainee.
+        overwrite_trainee : bool, default False
+            If True, and if a trainee with name `trainee.name` already exists,
+            the given trainee will delete the old trainee and create the new
+            trainee.
+        persistence : {"allow", "always", "never"}, default "allow"
+            The requested persistence state of the Trainee.
+        project : str or Project, optional
+            The project to create this Trainee under, if the client
+            implementation supports this project.
+        resources : Mapping, optional
+            Customize the resources provisioned for the Trainee instance.
+
+            .. deprecated:: 80.0
+                Pass via `runtime` instead.
+        runtime : TraineeRuntimeOptions, optional
+            Runtime options used by the Trainee, including the library type
+            and resource and scaling options, if the client implementation
+            supports setting these.  Takes precedence over `library_type` and
+            `resources` if these options are set.
+
+        Returns
+        -------
+        Trainee
+            The trainee object that was created.
+        """
 
     @abstractmethod
     def update_trainee(self, trainee: Mapping | Trainee) -> Trainee:
@@ -331,9 +396,14 @@ def delete_trainee(self, trainee_id: str, *, file_path: t.Optional[Path | str] =
 
     @abstractmethod
     def copy_trainee(
-        self, trainee_id, new_trainee_name=None, *,
-        library_type=None,
-        resources=None,
+        self,
+        trainee_id: str,
+        new_trainee_name: t.Optional[str] = None,
+        new_trainee_id: t.Optional[str] = None,
+        *,
+        library_type: t.Optional[LibraryType] = None,
+        resources: t.Optional[Mapping[str, t.Any]] = None,
+        runtime: t.Optional[TraineeRuntimeOptions] = None
     ) -> Trainee:
         """Copy a trainee in the Howso service."""
 
@@ -3201,20 +3271,20 @@ def react_aggregate(
                         - None
                         - A value, must match exactly.
                         - An array of two numeric values, specifying an inclusive
-                        range. Only applicable to continuous and numeric ordinal
-                        features.
+                          range. Only applicable to continuous and numeric ordinal
+                          features.
                         - An array of string values, must match any of these values
-                        exactly. Only applicable to nominal and string ordinal
-                        features.
+                          exactly. Only applicable to nominal and string ordinal
+                          features.
             - action_num_cases : int, optional
                 The maximum amount of cases to use to calculate prediction stats.
                 If not specified, the limit will be k cases if precision is
-                "similar", or 1000 cases if precision is "exact". Works with or
-                without ``action_condition``.
-                -If ``action_condition`` is set:
-                    If None, will be set to k if precision is "similar" or no limit if precision is "exact".
-                - If ``action_condition`` is not set:
-                    If None, will be set to the Howso default limit of 2000.
+                "similar", or 1000 cases if precision is "exact".
+
+                If this value is not provided, the default depends on ``action_condition``.  If
+                If ``action_condition`` is set, the default is k if precision is "similar" or no
+                limit if precision is "exact".  If ``action_condition`` is not set, the Howso
+                default limit is 2000.
             - action_condition_precision : {"exact", "similar"}, optional
                 The precision to use when selecting cases with the ``action_condition``.
                 If not specified "exact" will be used. Only used if ``action_condition``
@@ -3232,18 +3302,22 @@ def react_aggregate(
                         - None
                         - A value, must match exactly.
                         - An array of two numeric values, specifying an inclusive
-                        range. Only applicable to continuous and numeric ordinal
-                        features.
+                          range. Only applicable to continuous and numeric ordinal
+                          features.
                         - An array of string values, must match any of these values
-                        exactly. Only applicable to nominal and string ordinal
-                        features.
+                          exactly. Only applicable to nominal and string ordinal
+                          features.
             - context_precision_num_cases : int, optional
                 Limit on the number of context cases when ``context_condition_precision`` is set to "similar".
                 If None, will be set to k.
             - context_condition_precision : {"exact", "similar"}, optional
                 The precision to use when selecting cases with the ``context_condition``.
                 If not specified "exact" will be used. Only used if ``context_condition``
                 is not None.
+            - prediction_stats_features : list, optional
+                List of features to use when calculating conditional prediction stats. Should contain all
+                action and context features desired. If ``action_feature`` is also provided, that feature will
+                automatically be appended to this list if it is not already in the list.
             - selected_prediction_stats : list, optional
                 List of stats to output. When unspecified, returns all except the confusion matrix. Allowed values:
 

howso/client/schemas/__init__.py

@@ -2,5 +2,26 @@
 from .project import Project, ProjectDict
 from .reaction import Reaction
 from .session import Session, SessionDict
-from .trainee import Trainee, TraineeDict, TraineeRuntime, TraineeVersion
+from .trainee import (
+    ResourceLimit, Trainee, TraineeDict, TraineeRuntime, TraineeRuntimeOptions, TraineeScaling,
+    TraineeScalingResources, TraineeVersion
+)
 from .version import HowsoVersion
+
+__all__ = [
+    'BaseSchema',
+    'Project',
+    'ProjectDict',
+    'Reaction',
+    'Session',
+    'SessionDict',
+    'ResourceLimit',
+    'Trainee',
+    'TraineeDict',
+    'TraineeRuntime',
+    'TraineeRuntimeOptions',
+    'TraineeScaling',
+    'TraineeScalingResources',
+    'TraineeVersion',
+    'HowsoVersion'
+]

howso/client/schemas/trainee.py

@@ -4,7 +4,7 @@
 import typing as t
 from uuid import UUID
 
-from typing_extensions import NotRequired, TypedDict
+from typing_extensions import NotRequired, ReadOnly, TypedDict
 
 from .base import BaseSchema
 from ..typing import LibraryType, Persistence
@@ -36,18 +36,58 @@ class TraineeVersion(TypedDict, total=False):
     """The Amalgam library version."""
 
 
+class ResourceLimit(TypedDict):
+    """System resource (CPU/Memory) limit."""
+
+    minimum: ReadOnly[NotRequired[int | None]]
+    """Minimum allocated."""
+
+    maximum: ReadOnly[NotRequired[int | None]]
+    """Maximum allocated."""
+
+
+class TraineeScalingResources(TypedDict, total=False):
+    """Resources allocated to a Trainee."""
+
+    cpu: ReadOnly[NotRequired[ResourceLimit | None]]
+    """Trainee CPU limits in millicores."""
+
+    memory: ReadOnly[NotRequired[ResourceLimit | None]]
+    """Trainee memory limits in mebibytes."""
+
+
+class TraineeScaling(TypedDict, total=False):
+    """Trainee runtime scaling options."""
+
+    resources: ReadOnly[NotRequired[TraineeScalingResources | None]]
+    """The CPU and memory resources allocated to the Trainee."""
+
+
+class TraineeRuntimeOptions(TypedDict, total=False):
+    """Runtime options used when creating a Trainee."""
+
+    library_type: ReadOnly[NotRequired[LibraryType | None]]
+    """The Amalgam library type used by the Trainee."""
+
+    scaling: ReadOnly[NotRequired[TraineeScaling | None]]
+    """The runtime scaling options used by the Trainee."""
+
+
 class TraineeRuntime(TypedDict):
     """Trainee runtime details."""
 
-    library_type: LibraryType
+    library_type: ReadOnly[LibraryType]
     """The Amalgam library type used by the Trainee."""
 
-    tracing_enabled: bool
+    tracing_enabled: ReadOnly[bool]
     """If debug tracing is enabled for the Trainee."""
 
-    versions: TraineeVersion
+    versions: ReadOnly[TraineeVersion]
     """The Trainee runtime versions."""
 
+    scaling: ReadOnly[NotRequired[TraineeScaling | None]]
+    """The runtime scaling options used by the Trainee."""
+
 
 class Trainee(BaseSchema[TraineeDict]):
     """

howso/direct/client.py

@@ -36,6 +36,7 @@
     Session,
     Trainee,
     TraineeRuntime,
+    TraineeRuntimeOptions,
     TraineeVersion,
 )
 from howso.client.typing import LibraryType, Persistence
@@ -692,6 +693,7 @@ def create_trainee(  # noqa: C901
         persistence: Persistence = "allow",
         project: t.Optional[str | Project] = None,
         resources: t.Optional[Mapping[str, t.Any]] = None,
+        runtime: t.Optional[TraineeRuntimeOptions] = None,
     ) -> Trainee:
         """
         Create a Trainee on the Howso service.
@@ -709,6 +711,9 @@ def create_trainee(  # noqa: C901
             the name will be used, or a new UUID if no name was provided.
         library_type : {"st", "mt"}, optional
             (Not implemented in this client)
+
+            .. deprecated:: 31.0
+                Pass via `runtime` instead.
         max_wait_time : int or float, optional
             (Not implemented in this client)
         metadata : dict, optional
@@ -723,6 +728,11 @@ def create_trainee(  # noqa: C901
         resources : dict, optional
             (Not implemented in this client)
 
+            .. deprecated:: 31.0
+                Pass via `runtime` instead.
+        runtime : TraineeRuntime, optional
+            (Not implemented in this client)
+
         Returns
         -------
         Trainee
@@ -737,6 +747,15 @@ def create_trainee(  # noqa: C901
         if features is None:
             features = {}
 
+        if library_type is not None:
+            warnings.warn(
+                'The create trainee parameter `library_type` is deprecated and will be removed in '
+                'a future release. Please use `runtime` instead.', DeprecationWarning)
+        if resources is not None:
+            warnings.warn(
+                'The create trainee parameter `resources` is deprecated and will be removed in '
+                'a future release. Please use `runtime` instead.', DeprecationWarning)
+
         # Check that the id is usable for saving later.
         if name:
             for sequence in self.BAD_TRAINEE_NAME_CHARS:
@@ -1129,7 +1148,8 @@ def copy_trainee(
         new_trainee_id: t.Optional[str] = None,
         *,
         library_type: t.Optional[LibraryType] = None,
-        resources: t.Optional[dict] = None,
+        resources: t.Optional[Mapping[str, t.Any]] = None,
+        runtime: t.Optional[TraineeRuntimeOptions] = None
     ) -> Trainee:
         """
         Copies a trainee to a new trainee id in the Howso service.
@@ -1148,11 +1168,22 @@ def copy_trainee(
         library_type : str, optional
             (Not Implemented) The library type of the Trainee. If not specified,
             the new trainee will inherit the value from the original.
+
+            .. deprecated:: 31.0
+                Pass via `runtime` instead.
         resources : dict, optional
             (Not Implemented) Customize the resources provisioned for the
             Trainee instance. If not specified, the new trainee will inherit
             the value from the original.
 
+            .. deprecated:: 31.0
+                Pass via `runtime` instead.
+        runtime : TraineeRuntimeOptions, optional
+            Library type, resource requirements, and other runtime settings
+            for the new Trainee instance.  If not specified, the new trainee
+            will inherit the values from the original.  Not used in this
+            client implementation.
+
         Returns
         -------
         Trainee
@@ -1170,6 +1201,15 @@ def copy_trainee(
         if self.configuration.verbose:
             print(f'Copying Trainee {trainee_id} to {new_trainee_id}')
 
+        if library_type is not None:
+            warnings.warn(
+                'The copy trainee parameter `library_type` is deprecated and will be removed in '
+                'a future release. Please use `runtime` instead.', DeprecationWarning)
+        if resources is not None:
+            warnings.warn(
+                'The copy trainee parameter `resources` is deprecated and will be removed in '
+                'a future release. Please use `runtime` instead.', DeprecationWarning)
+
         is_cloned = self.amlg.clone_entity(
             handle=trainee_id,
             clone_handle=new_trainee_id,