howso-engine 67.2.0__tar.gz → 68.0.0__tar.gz

{howso_engine-67.2.0 → howso_engine-68.0.0}/LICENSE-3RD-PARTY.txt

@@ -1,10 +1,10 @@
 Faker
-40.41.0
+40.42.0
 MIT License
 joke2k
 https://github.com/joke2k/faker
 Faker is a Python package that generates fake data for you.
-/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/faker-40.41.0.dist-info/licenses/LICENSE.txt
+/home/runner/.pyenv/versions/3.14.8/lib/python3.14/site-packages/faker-40.42.0.dist-info/licenses/LICENSE.txt
 Copyright (c) 2012 Daniele Faraglia
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

{howso_engine-67.2.0/howso_engine.egg-info → howso_engine-68.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howso-engine
-Version: 67.2.0
+Version: 68.0.0
 Summary: The Howso Engine™ is a natively and fully explainable ML engine, serving as an alternative to black box AI neural networks.
 Author: Howso Incorporated
 Author-email: support@howso.com
@@ -705,7 +705,7 @@ Requires-Dist: sacremoses
 Requires-Dist: semantic-version~=2.0
 Requires-Dist: typing-extensions~=4.9
 Requires-Dist: urllib3>=2.6.3
-Requires-Dist: amalgam-lang==35.1.0
+Requires-Dist: amalgam-lang==35.1.1
 Provides-Extra: dev
 Requires-Dist: dill~=0.0; extra == "dev"
 Requires-Dist: flake8-docstrings; extra == "dev"

{howso_engine-67.2.0 → howso_engine-68.0.0}/howso/client/base.py

@@ -4425,6 +4425,7 @@ class AbstractHowsoClient(ABC):
         action_features: Collection[str] | None = None,
         case_indices: Collection[CaseIndices] | None = None,
         conditions: list[Mapping] | None = None,
+        context_features: Collection[str] | None = None,
         details: Mapping[str, bool] | None = None,
         distance_contributions: bool = False,
         familiarity_conviction_addition: bool = False,
@@ -4482,6 +4483,10 @@ class AbstractHowsoClient(ABC):
                     - An array of string values, must match any of these values
                       exactly. Only applicable to nominal and string ordinal
                       features.
+        context_features : Collection of str, optional
+            List of features names to use as contexts in queries. If unspecified,
+            the default is all trained features when using trained cases and
+            all given features and their derived features when using new_cases.
         details : dict of str to bool, optional
             Ignored if action features are not specified.
             If details are specified, the response will contain the requested
@@ -4532,6 +4537,10 @@ class AbstractHowsoClient(ABC):
             parameter. Only one of ``case_indices``, ``conditions``, or
             ``new_cases`` may be specified.
 
+            When using a time-series Trainee, derived feature values will be
+            computed for the given data for each group if no derived feature
+            values are given.
+
             >>> [ [[1, 2, 3], [4, 5, 6], [7, 8, 9]], # Group 1
             >>>   [[1, 2, 3]] ] # Group 2
         p_value_of_addition : bool, default False
@@ -4572,16 +4581,28 @@ class AbstractHowsoClient(ABC):
             serialized_cases = []
             for group in new_cases:
                 if features is None:
-                    features = internals.get_features_from_data(group)
+                    features = internals.get_features_from_data(group, data_parameter="new_cases")
                 serialized_cases.append(serialize_cases(group, features, feature_attributes,
                                                         tokenizer=self._tokenizer))  # pyright: ignore[reportAttributeAccessIssue]
 
+            if (
+                features is None
+                or not isinstance(serialized_cases[0][0], Sized)
+                or len(features) != len(serialized_cases[0][0])
+            ):
+                raise HowsoError(
+                    "The number of provided values in `new_cases` "
+                    "does not match the number of features in "
+                    "`features`."
+                )
+
         if self.configuration.verbose:
             print(f"Reacting to a set of cases on Trainee with id: {trainee_id}")
         result = self.execute(trainee_id, "react_group", {
             "action_features": action_features,
             "case_indices": case_indices,
             "conditions": conditions,
+            "context_features": context_features,
             "details": details,
             "distance_contributions": distance_contributions,
             "residual_contributions": residual_contributions,

{howso_engine-67.2.0 → howso_engine-68.0.0}/howso/client/schemas/group_reaction.py

@@ -16,6 +16,7 @@ _VT = TypeVar("_VT")
 
 GroupDetail: TypeAlias = Literal[
     "categorical_action_probabilities",  # A dict of feature name to dict of class to probability for each group
+    "context_features",  # a list of the context feature names
     "influential_cases", # a list of dicts for each group
     "feature_full_residuals", # a map of residuals for each action feature for each group
 ]
@@ -42,6 +43,9 @@ class GroupDetails(TypedDict, total=False):
     categorical_action_probabilities: list[dict[str, dict[Any, float]]]
     """The categorical action probabilities for each nominal action feature for each group."""
 
+    context_features: list[str]
+    """The list of context features used in the GroupReaction."""
+
     influential_cases: list[pd.DataFrame]
     """The collection of influential cases to each group."""
 
@@ -110,6 +114,10 @@ class GroupReaction(Mapping[GroupProperty, PropertyValue]):
                     self._details.update(
                         {"categorical_action_probabilities": internals.update_caps_maps(data[computed_detail], attributes)}
                     )
+                elif computed_detail == "context_features":
+                    self._details.update(
+                        {"context_features": data["context_features"]}
+                    )
                 else:
                     # Currently the only possible detail here is feature_full_residuals
                     self._details.update({computed_detail: pd.DataFrame(data[computed_detail])})

{howso_engine-67.2.0 → howso_engine-68.0.0}/howso/client/typing.py

@@ -246,37 +246,26 @@ class FeatureTimeSeries(TypedDict, total=False):
     """
 
 class ProtectedValueMultiplier(TypedDict):
-    """A single protected value paired with its case-weight multiplier."""
+    """A single feature value paired with its case-weight multiplier."""
 
     value: Any
-    """The feature value to protect during data distillation."""
+    """The feature value whose cases are reweighted during data distillation."""
 
     multiplier: float
     """The case-weight multiplier applied to cases holding this value."""
 
 
 class FeatureRareValueConfig(TypedDict):
-    """A rare-value preservation configuration for a single feature."""
+    """A computed rare-value preservation configuration for a single feature."""
 
-    protected_values_multipliers: list[ProtectedValueMultiplier]
-    """The protected values and their individual case-weight multipliers."""
-
-    unprotected_multiplier: NotRequired[float]
-    """The case-weight multiplier applied to all non-protected values of the feature."""
-
-
-class DeferredFeatureValueConfig(TypedDict):
+    value_weight_multipliers: list[ProtectedValueMultiplier]
     """
-    Rare values marked for protection whose case-weight multipliers are not yet computed.
+    The case-weight multipliers of the feature's values, as written to the feature's attributes.
 
-    Written to a feature's ``preserve_rare_values`` attribute when protected values are
-    supplied without a ``max_distilled_cases`` value; the multipliers are resolved later
-    in the stack.
+    Rare values are listed with multipliers above 1 and the values that fund them with
+    multipliers below 1. A value that is not listed keeps a multiplier of 1.
     """
 
-    protected_values: list[Any]
-    """The feature values to protect during data distillation."""
-
 
 class FeatureAttributes(TypedDict):
     """
@@ -507,14 +496,6 @@ class FeatureAttributes(TypedDict):
     post_process: NotRequired[str]
     """Custom Amalgam code that is called on resulting values of this feature during react operations."""
 
-    preserve_rare_values: NotRequired[FeatureRareValueConfig | DeferredFeatureValueConfig]
-    """
-    Configuration for preserving rare values during data distillation.
-
-    Either a fully-computed config with case-weight multipliers, or a deferred config
-    listing only the protected values (when multipliers have not yet been computed).
-    """
-
     recursive_matching: NotRequired[bool]
     """
     Whether operations work recursively on feature values.
@@ -564,6 +545,15 @@ class FeatureAttributes(TypedDict):
     unique: NotRequired[bool]
     """Flag feature as only having unique values. Only applicable to nominal features."""
 
+    value_weight_multipliers: NotRequired[list[ProtectedValueMultiplier]]
+    """
+    Case-weight multipliers applied at train time to cases holding the listed values of this feature.
+
+    A value that is not listed keeps a multiplier of 1. Rare value preservation writes multipliers
+    above 1 for the rare values and below 1 for the values that fund them, so that the total case
+    weight of the feature is unchanged.
+    """
+
 
 class TaskProgress(TypedDict):
     details: str
@@ -609,13 +599,39 @@ Persistence: TypeAlias = Literal["allow", "always", "never"]
 """Valid values for ``persistence`` parameters."""
 
 PreserveRareValuesMap: TypeAlias = dict[str, list[Any]]
-"""Map of feature name to a list of values to protect during data distillation."""
+"""Map of feature name to a list of values to protect during data distillation, their multipliers to be computed."""
+
+PreserveRareValuesCaps: TypeAlias = Union[Sequence[str], Mapping[str, float]]
+"""
+Features whose significant values keep part of their case weight when funding rare value preservation.
+
+A sequence of feature names applies the default cap to each; a mapping gives each feature the largest
+share of its weight a significant value may give up.
+"""
 
 PreserveRareValuesConfig: TypeAlias = dict[str, list[ProtectedValueMultiplier]]
-"""Map of feature name to a list of protected values with case-weight multipliers."""
+"""Map of feature name to a list of rare values with the case-weight multipliers they should receive."""
 
 FullPreserveRareValuesConfig: TypeAlias = dict[str, FeatureRareValueConfig]
-"""Map of feature name to a complete rare-value configuration (protected and unprotected multipliers)."""
+"""Map of feature name to a complete rare-value configuration, with every multiplier computed."""
+
+FeatureRareValues: TypeAlias = Union[Sequence[Any], Sequence[ProtectedValueMultiplier], FeatureRareValueConfig]
+"""
+The rare value specification of one feature in ``preserve_rare_values``.
+
+A sequence of values to protect, whose multipliers are computed; a sequence of values paired with
+the multipliers they should receive, with the multipliers of the feature's other values computed to
+fund them; or a complete configuration with a ``value_weight_multipliers`` list, used as given.
+"""
+
+PreserveRareValues: TypeAlias = Union[Mapping[str, FeatureRareValues], Sequence[str], Literal["all", "off"]]
+"""
+The accepted forms of ``preserve_rare_values``.
+
+A mapping specifies the rare values of each feature; a sequence of feature names protects every
+rare value candidate of those features; "all" does so for every nominal feature; "off" disables
+rare value preservation, including its suggestion.
+"""
 
 Precision: TypeAlias = Literal["exact", "similar"]
 """Valid values for ``precision`` parameters."""

{howso_engine-67.2.0 → howso_engine-68.0.0}/howso/engine/trainee.py

@@ -3388,6 +3388,7 @@ class Trainee(BaseTrainee):
         action_features: Collection[str] | None = None,
         case_indices: Collection[CaseIndices] | None = None,
         conditions: list[Mapping] | None = None,
+        context_features: Collection[str] | None = None,
         details: Mapping[str, bool] | None = None,
         distance_contributions: bool = False,
         familiarity_conviction_addition: bool = False,
@@ -3445,6 +3446,10 @@ class Trainee(BaseTrainee):
                     - An array of string values, must match any of these values
                       exactly. Only applicable to nominal and string ordinal
                       features.
+        context_features : Collection of str, optional
+            List of features names to use as contexts in queries. If unspecified,
+            the default is all trained features when using trained cases and
+            all given features and their derived features when using new_cases.
         details : dict of str to bool, optional
             Ignored if action features are not specified.
             If details are specified, the response will contain the requested
@@ -3495,6 +3500,10 @@ class Trainee(BaseTrainee):
             parameter. Only one of ``case_indices``, ``conditions``, or
             ``new_cases`` may be specified.
 
+            When using a time-series Trainee, derived feature values will be
+            computed for the given data for each group if no derived feature
+            values are given.
+
             Example::
 
                 new_cases = [
@@ -3533,6 +3542,7 @@ class Trainee(BaseTrainee):
                 action_features=action_features,
                 case_indices=case_indices,
                 conditions=conditions,
+                context_features=context_features,
                 details=details,
                 features=features,
                 filter_fanout_values=filter_fanout_values,

{howso_engine-67.2.0 → howso_engine-68.0.0}/howso/howso-engine/version.json

@@ -1,10 +1,10 @@
 {
-  "version": "120.2.0",
+  "version": "121.0.2",
   "dependencies": {
-    "amalgam": "82.0.1"
+    "amalgam": "82.1.1"
   },
   "display_title": "",
   "build_date": "",
-  "sha": "9c99e0928e7682cd58069ef5fe715670f8f8f0a3",
-  "url": "https://github.com/howsoai/howso-engine/releases/tag/120.2.0"
+  "sha": "6956725209ccdee206cbb68d964436c0e31d9358",
+  "url": "https://github.com/howsoai/howso-engine/releases/tag/121.0.2"
 }

{howso_engine-67.2.0 → howso_engine-68.0.0}/howso/utilities/__init__.py

@@ -57,7 +57,7 @@ from howso.utilities.utilities import (  # noqa: F401
     format_confusion_matrix,
     get_hash,
     get_kwargs,
-    get_optimized_max_chunk_size,
+    get_optimized_partition_size,
     is_null_value,
     is_valid_datetime_format,
     is_valid_uuid,
@@ -130,7 +130,7 @@ __all__ = [
     "format_dataframe",
     "get_hash",
     "get_kwargs",
-    "get_optimized_max_chunk_size",
+    "get_optimized_partition_size",
     "infer_fanout_feature_config",
     "infer_feature_attributes",
     "is_null_value",

{howso_engine-67.2.0 → howso_engine-68.0.0}/howso/utilities/feature_attributes/abstract_data.py

@@ -78,6 +78,8 @@ class InferFeatureAttributesAbstractData(InferFeatureAttributesBase):
 
     def __call__(self, **kwargs) -> SingleTableFeatureAttributes:
         """Process and return feature attributes."""
+        self._validate_rare_value_parameters(kwargs.get("preserve_rare_values"),
+                                             kwargs.get("preserve_rare_values_caps"))
         # For Spark compute types, multiprocessing is less-performant.
         # If we're working with the SparkDataFrameData ADC, unless the user
         # specifically sets `max_workers`, we want "sharding" disabled.