wandb 0.19.10__py3-none-win_amd64.whl → 0.19.11__py3-none-win_amd64.whl

wandb/automations/__init__.py

@@ -1,12 +1,13 @@
+import wandb
 from wandb._pydantic import IS_PYDANTIC_V2
 
-from . import _filters as filters
-from . import actions, automations, events, scopes
-from .actions import ActionType, DoNothing, DoNotification, DoWebhook
-from .automations import Automation, NewAutomation, PreparedAutomation
+from .actions import ActionType, DoNothing, SendNotification, SendWebhook
+from .automations import Automation, NewAutomation
 from .events import (
     ArtifactEvent,
     EventType,
+    MetricChangeFilter,
+    MetricThresholdFilter,
     OnAddArtifactAlias,
     OnCreateArtifact,
     OnLinkArtifact,
@@ -26,33 +27,23 @@ if not IS_PYDANTIC_V2:
     # - Drop support for Pydantic v1
     # - Are able to implement (limited) Pydantic v1 support
     raise ImportError(
-        "The W&B Automations API is not supported in Pydantic v1 at this time. "
-        "If at all possible, we currently recommend upgrading to Pydantic v2 to use this feature.",
+        "The W&B Automations API requires Pydantic v2. "
+        "We recommend upgrading `pydantic` to use this feature."
     )
 
 else:
     # If Pydantic v2 is available, we can use the full Automations API
     # but communicate to users that the API is still experimental and
     # may change rapidly.
-    import warnings
-
-    warnings.warn(
-        "The W&B Automations API is currently experimental. Although we'll communicate "
-        "breaking changes in release notes and attempt to minimize them in general, "
-        "please know that such changes may occur between release versions without notice. "
-        "We strongly recommend pinning your `wandb` version when using the Automations API "
-        "to avoid unexpected breakages.",
-        FutureWarning,
-        stacklevel=1,
+    wandb.termwarn(
+        "The W&B Automations API is experimental and the implementation is subject to change."
+        "Review the release notes before upgrading. We recommend pinning your "
+        f"package version to `{wandb.__package__}=={wandb.__version__}` to reduce the risk of disruption.",
+        repeat=False,
     )
 # ----------------------------------------------------------------------------
 
 __all__ = [
-    "filters",
-    "scopes",
-    "events",
-    "actions",
-    "automations",
     # Scopes
     "ScopeType",
     "ArtifactCollectionScope",
@@ -65,15 +56,16 @@ __all__ = [
     "OnRunMetric",
     "ArtifactEvent",
     "RunEvent",
+    "MetricThresholdFilter",
+    "MetricChangeFilter",
     # Actions
     "ActionType",
-    "DoNotification",
-    "DoWebhook",
+    "SendNotification",
+    "SendWebhook",
     "DoNothing",
     # Automations
     "Automation",
     "NewAutomation",
-    "PreparedAutomation",
     # Integrations
     "Integration",
     "SlackIntegration",

wandb/automations/_filters/expressions.py

@@ -6,7 +6,7 @@ from collections.abc import Iterable
 from typing import Any, Union
 
 from pydantic import ConfigDict, model_serializer
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self, TypeAlias, get_args
 
 from wandb._pydantic import CompatBaseModel, model_validator
 
@@ -98,22 +98,22 @@ class FilterableField:
     # Override the default behavior of comparison operators: <, >=, ==, etc
     def __lt__(self, other: Any) -> FilterExpr:
         if isinstance(other, ScalarTypes):
-            return self.lt(other)
+            return self.lt(other)  # type: ignore[arg-type]
         raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
 
     def __gt__(self, other: Any) -> FilterExpr:
         if isinstance(other, ScalarTypes):
-            return self.gt(other)
+            return self.gt(other)  # type: ignore[arg-type]
         raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
 
     def __le__(self, other: Any) -> FilterExpr:
         if isinstance(other, ScalarTypes):
-            return self.lte(other)
+            return self.lte(other)  # type: ignore[arg-type]
         raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
 
     def __ge__(self, other: Any) -> FilterExpr:
         if isinstance(other, ScalarTypes):
-            return self.gte(other)
+            return self.gte(other)  # type: ignore[arg-type]
         raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
 
     # Operator behavior is intentionally overridden to allow defining
@@ -124,12 +124,12 @@ class FilterableField:
     # https://github.com/sqlalchemy/sqlalchemy/blob/f21ae633486380a26dc0b67b70ae1c0efc6b4dc4/lib/sqlalchemy/orm/descriptor_props.py#L808-L812
     def __eq__(self, other: Any) -> FilterExpr:
         if isinstance(other, ScalarTypes):
-            return self.eq(other)
+            return self.eq(other)  # type: ignore[arg-type]
         raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
 
     def __ne__(self, other: Any) -> FilterExpr:
         if isinstance(other, ScalarTypes):
-            return self.ne(other)
+            return self.ne(other)  # type: ignore[arg-type]
         raise TypeError(f"Invalid operand type in filter expression: {type(other)!r}")
 
 
@@ -145,7 +145,7 @@ class FilterExpr(CompatBaseModel, SupportsLogicalOpSyntax):
     op: Op
 
     def __repr__(self) -> str:
-        return f"{type(self).__name__}({self.field!s}={self.op!r})"
+        return f"{type(self).__name__}({self.field!s}: {self.op!r})"
 
     def __rich_repr__(self) -> RichReprResult:  # type: ignore[override]
         # https://rich.readthedocs.io/en/stable/pretty.html
@@ -172,8 +172,10 @@ class FilterExpr(CompatBaseModel, SupportsLogicalOpSyntax):
         """Return a MongoDB dict representation of the expression."""
         from pydantic_core import to_jsonable_python  # Only valid in pydantic v2
 
-        op_dict = to_jsonable_python(self.op, by_alias=True, round_trip=True)
-        return {self.field: op_dict}
+        return {self.field: to_jsonable_python(self.op, by_alias=True, round_trip=True)}
 
 
+# for type annotations
 MongoLikeFilter: TypeAlias = Union[Op, FilterExpr]
+# for runtime type checks
+MongoLikeFilterTypes: tuple[type, ...] = get_args(MongoLikeFilter)

wandb/automations/_filters/operators.py

@@ -2,22 +2,17 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Dict, Iterable, Tuple, TypeVar, Union, overload
+from typing import Any, Dict, Iterable, Tuple, TypeVar, Union
 
 from pydantic import ConfigDict, Field, StrictBool, StrictFloat, StrictInt, StrictStr
 from typing_extensions import TypeAlias, get_args
 
-from wandb._pydantic import Base
-
-if TYPE_CHECKING:
-    from wandb.automations._filters.run_metrics import MetricThresholdFilter
-    from wandb.automations.events import RunMetricFilter
-
+from wandb._pydantic import GQLBase
 
 # for type annotations
 Scalar = Union[StrictStr, StrictInt, StrictFloat, StrictBool]
 # for runtime type checks
-ScalarTypes = get_args(Scalar)
+ScalarTypes: tuple[type, ...] = tuple(t.__origin__ for t in get_args(Scalar))
 
 # See: https://rich.readthedocs.io/en/stable/pretty.html#rich-repr-protocol
 RichReprResult: TypeAlias = Iterable[
@@ -44,18 +39,13 @@ class SupportsLogicalOpSyntax:
         """Syntactic sugar for: `a | b` -> `Or(a, b)`."""
         return Or(or_=[self, other])
 
-    @overload
-    def __and__(self, other: MetricThresholdFilter) -> RunMetricFilter: ...
-    @overload
-    def __and__(self, other: Any) -> And: ...
-    def __and__(self, other: Any) -> Any:
+    def __and__(self, other: Any) -> And:
         """Syntactic sugar for: `a & b` -> `And(a, b)`."""
-        from wandb.automations._filters.run_metrics import MetricThresholdFilter
+        from .expressions import FilterExpr
 
-        # Special handling `run_filter & metric_filter`
-        if isinstance(other, MetricThresholdFilter):
-            return other.__and__(self)
-        return And(and_=[self, other])
+        if isinstance(other, (BaseOp, FilterExpr)):
+            return And(and_=[self, other])
+        return NotImplemented
 
     def __invert__(self) -> Not:
         """Syntactic sugar for: `~a` -> `Not(a)`."""
@@ -63,8 +53,9 @@ class SupportsLogicalOpSyntax:
 
 
 # Base class for parsed MongoDB filter/query operators, e.g. `{"$and": [...]}`.
-class BaseOp(Base, SupportsLogicalOpSyntax):
+class BaseOp(GQLBase, SupportsLogicalOpSyntax):
     model_config = ConfigDict(
+        extra="forbid",
         frozen=True,  # Make pseudo-immutable for easier comparison and hashing
     )
 

wandb/automations/_filters/run_metrics.py

@@ -2,13 +2,21 @@
 
 from __future__ import annotations
 
-from enum import Enum
+from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any, Final, Literal, Optional, Union, overload
 
-from pydantic import Field, PositiveInt, StrictFloat, StrictInt, field_validator
-from typing_extensions import Self, override
+from pydantic import (
+    Field,
+    PositiveFloat,
+    PositiveInt,
+    StrictFloat,
+    StrictInt,
+    field_validator,
+)
+from typing_extensions import Annotated, TypeAlias, override
 
-from wandb._pydantic.base import Base, GQLBase
+from wandb._pydantic import GQLBase
+from wandb.automations._validators import LenientStrEnum
 
 from .expressions import FilterExpr
 from .operators import BaseOp, RichReprResult
@@ -28,83 +36,101 @@ MONGO2PY_OPS: Final[dict[str, str]] = {
 # Reverse mapping from Python literal (str) -> MongoDB operator key
 PY2MONGO_OPS: Final[dict[str, str]] = {v: k for k, v in MONGO2PY_OPS.items()}
 
+# Type hint for positive numbers (int or float)
+PosNum: TypeAlias = Union[PositiveInt, PositiveFloat]
 
-class Agg(str, Enum):  # from `Aggregation`
+
+class Agg(LenientStrEnum):  # from: Aggregation
     """Supported run metric aggregation operations."""
 
     MAX = "MAX"
     MIN = "MIN"
     AVERAGE = "AVERAGE"
 
+    # Shorter aliases for convenience
+    AVG = AVERAGE
+
 
-class ChangeType(str, Enum):  # from `RunMetricChangeType`
+class ChangeType(LenientStrEnum):  # from: RunMetricChangeType
     """Describes the metric change as absolute (arithmetic difference) or relative (decimal percentage)."""
 
     ABSOLUTE = "ABSOLUTE"
     RELATIVE = "RELATIVE"
 
+    # Shorter aliases for convenience
+    ABS = ABSOLUTE
+    REL = RELATIVE
+
 
-class ChangeDirection(str, Enum):  # from `RunMetricChangeDirection`
+class ChangeDir(LenientStrEnum):  # from: RunMetricChangeDirection
     """Describes the direction of the metric change."""
 
     INCREASE = "INCREASE"
     DECREASE = "DECREASE"
     ANY = "ANY"
 
+    # Shorter aliases for convenience
+    INC = INCREASE
+    DEC = DECREASE
 
-class _BaseMetricFilter(GQLBase):
+
+class BaseMetricFilter(GQLBase, ABC, extra="forbid"):
     name: str
     """Name of the observed metric."""
 
     agg: Optional[Agg]
-    """Aggregation operation, if any, to apply over the window size."""
+    """Aggregate operation, if any, to apply over the window size."""
 
     window: PositiveInt
-    """Size of the window over which the metric is aggregated."""
+    """Size of the window over which the metric is aggregated (ignored if `agg is None`)."""
 
     # ------------------------------------------------------------------------------
+    cmp: Optional[str]
+    """Comparison between the metric expression (left) vs. the threshold or target value (right)."""
 
+    # ------------------------------------------------------------------------------
     threshold: Union[StrictInt, StrictFloat]
     """Threshold value to compare against."""
 
-    @field_validator("agg", mode="before")
-    @classmethod
-    def _validate_agg(cls, v: Any) -> Any:
-        # Be helpful: e.g. "min" -> "MIN"
-        return v.strip().upper() if isinstance(v, str) else v
-
-    @overload
-    def __and__(self, other: BaseOp | FilterExpr) -> RunMetricFilter: ...
-    @overload
-    def __and__(self, other: Any) -> Any: ...
-    def __and__(self, other: BaseOp | FilterExpr | Any) -> RunMetricFilter | Any:
-        """Supports syntactic sugar for defining a triggering RunMetricEvent from `run_metric_filter & run_filter`."""
-        from wandb.automations.events import RunMetricFilter, _InnerRunMetricFilter
+    def __and__(self, other: Any) -> RunMetricFilter:
+        """Implements `(metric_filter & run_filter) -> RunMetricFilter`."""
+        from wandb.automations.events import RunMetricFilter
 
         if isinstance(run_filter := other, (BaseOp, FilterExpr)):
             # Assume `other` is a run filter, and we are building a RunMetricEvent.
             # For the metric filter, delegate to the inner validator(s) to further wrap/nest as appropriate.
-            metric_filter = _InnerRunMetricFilter.model_validate(self)
-            return RunMetricFilter(
-                run_metric_filter=metric_filter, run_filter=run_filter
-            )
-        return other.__and__(self)  # Try switching the order of operands
+            return RunMetricFilter(run=run_filter, metric=self)
+        return NotImplemented
 
+    def __rand__(self, other: BaseOp | FilterExpr) -> RunMetricFilter:
+        """Ensures `&` is commutative: `(run_filter & metric_filter) == (metric_filter & run_filter)`."""
+        return self.__and__(other)
 
-class MetricThresholdFilter(_BaseMetricFilter):  # from `RunMetricThresholdFilter`
-    """For run events, defines a metric filter comparing a metric against a user-defined threshold value."""
+    @abstractmethod
+    def __repr__(self) -> str:
+        """The text representation of the metric filter."""
+        raise NotImplementedError
+
+    @override
+    def __rich_repr__(self) -> RichReprResult:  # type: ignore[override]
+        """The representation of the metric filter when using `rich` for pretty-printing."""
+        # See: https://rich.readthedocs.io/en/stable/pretty.html#rich-repr-protocol
+        yield None, repr(self)
+
+
+class MetricThresholdFilter(BaseMetricFilter):  # from: RunMetricThresholdFilter
+    """Defines a filter that compares a run metric against a user-defined threshold value."""
 
     name: str
-    agg: Optional[Agg] = Field(default=None, alias="agg_op")
-    window: PositiveInt = Field(default=1, alias="window_size")
+    agg: Annotated[Optional[Agg], Field(alias="agg_op")] = None
+    window: Annotated[PositiveInt, Field(alias="window_size")] = 1
 
-    cmp: Literal["$gte", "$gt", "$lt", "$lte"] = Field(alias="cmp_op")
+    cmp: Annotated[Literal["$gte", "$gt", "$lt", "$lte"], Field(alias="cmp_op")]
     """Comparison operator used to compare the metric value (left) vs. the threshold value (right)."""
 
     threshold: Union[StrictInt, StrictFloat]
 
     @field_validator("cmp", mode="before")
-    @classmethod
     def _validate_cmp(cls, v: Any) -> Any:
         # Be helpful: e.g. ">" -> "$gt"
         return PY2MONGO_OPS.get(v.strip(), v) if isinstance(v, str) else v
@@ -112,72 +138,195 @@ class MetricThresholdFilter(_BaseMetricFilter):  # from `RunMetricThresholdFilte
     def __repr__(self) -> str:
         metric = f"{self.agg.value}({self.name})" if self.agg else self.name
         op = MONGO2PY_OPS.get(self.cmp, self.cmp)
-        expr = rf"{metric} {op} {self.threshold}"
-        return repr(expr)
+        return repr(rf"{metric} {op} {self.threshold}")
 
-    @override
-    def __rich_repr__(self) -> RichReprResult:  # type: ignore[override]
-        yield None, repr(self)
 
+class MetricChangeFilter(BaseMetricFilter):  # from: RunMetricChangeFilter
+    """Defines a filter that compares a change in a run metric against a user-defined threshold.
 
-class MetricChangeFilter(_BaseMetricFilter):  # from `RunMetricChangeFilter`
-    # FIXME:
-    # - `prior_window` should be optional and default to `window` if not provided.
-    # - implement declarative syntax for `MetricChangeFilter` similar to `MetricThresholdFilter`.
-    # - split this into tagged union of relative/absolute change filters.
+    The change is calculated over "tumbling" windows, i.e. the difference
+    between the current window and the non-overlapping prior window.
+    """
 
     name: str
-    agg: Optional[Agg] = Field(default=None, alias="agg_op")
+    agg: Annotated[Optional[Agg], Field(alias="agg_op")] = None
+    window: Annotated[PositiveInt, Field(alias="current_window_size")] = 1
 
-    # FIXME: Set the `prior_window` to `window` if it's not provided, for convenience.
-    window: PositiveInt = Field(alias="current_window_size")
-    prior_window: PositiveInt = Field(alias="prior_window_size")
-    """Size of the preceding window over which the metric is aggregated."""
+    # `prior_window` is only for `RUN_METRIC_CHANGE` events
+    prior_window: Annotated[
+        PositiveInt,
+        # By default, set `window -> prior_window` if the latter wasn't provided.
+        Field(alias="prior_window_size", default_factory=lambda data: data["window"]),
+    ]
+    """Size of the prior window over which the metric is aggregated (ignored if `agg is None`).
 
-    # NOTE: `cmp_op` isn't a field here.  In the backend, it's effectively `cmp_op` = "$gte"
+    If omitted, defaults to the size of the current window.
+    """
 
-    change_type: ChangeType = Field(alias="change_type")
-    change_direction: ChangeDirection = Field(alias="change_dir")
+    # ------------------------------------------------------------------------------
+    # NOTE:
+    # - The "comparison" operator isn't actually part of the backend schema,
+    #   but it's defined here for consistency -- and ignored otherwise.
+    # - In the backend, it's effectively "$gte" or "$lte", depending on the sign
+    #   (change_dir), though again, this is not explicit in the schema.
+    cmp: Annotated[None, Field(frozen=True, exclude=True, repr=False)] = None
+    """Ignored."""
 
-    threshold: Union[StrictInt, StrictFloat] = Field(alias="change_amount")
+    # ------------------------------------------------------------------------------
+    change_type: Annotated[ChangeType, Field(alias="change_type")]
+    change_dir: Annotated[ChangeDir, Field(alias="change_dir")]
+    threshold: Annotated[PosNum, Field(alias="change_amount")]
 
+    def __repr__(self) -> str:
+        metric = f"{self.agg.value}({self.name})" if self.agg else self.name
+        verb = (
+            "changes"
+            if (self.change_dir is ChangeDir.ANY)
+            else f"{self.change_dir.value.lower()}s"
+        )
+
+        fmt_spec = ".2%" if (self.change_type is ChangeType.REL) else ""
+        amt = f"{self.threshold:{fmt_spec}}"
+        return repr(rf"{metric} {verb} {amt}")
+
+
+class BaseMetricOperand(GQLBase, extra="forbid"):
+    def gt(self, value: int | float, /) -> MetricThresholdFilter:
+        """Defines a `MetricThresholdFilter` that observes for `metric_expr > threshold`."""
+        return self > value
+
+    def lt(self, value: int | float, /) -> MetricThresholdFilter:
+        """Defines a `MetricThresholdFilter` that observes for `metric_expr < threshold`."""
+        return self < value
+
+    def gte(self, value: int | float, /) -> MetricThresholdFilter:
+        """Defines a `MetricThresholdFilter` that observes for `metric_expr >= threshold`."""
+        return self >= value
+
+    def lte(self, value: int | float, /) -> MetricThresholdFilter:
+        """Defines a `MetricThresholdFilter` that observes for `metric_expr <= threshold`."""
+        return self <= value
+
+    # Overloads to implement:
+    # - `(metric_operand > threshold) -> MetricThresholdFilter`
+    # - `(metric_operand < threshold) -> MetricThresholdFilter`
+    # - `(metric_operand >= threshold) -> MetricThresholdFilter`
+    # - `(metric_operand <= threshold) -> MetricThresholdFilter`
+    def __gt__(self, other: Any) -> MetricThresholdFilter:
+        if isinstance(other, (int, float)):
+            return MetricThresholdFilter(**dict(self), cmp="$gt", threshold=other)
+        return NotImplemented
+
+    def __lt__(self, other: Any) -> MetricThresholdFilter:
+        if isinstance(other, (int, float)):
+            return MetricThresholdFilter(**dict(self), cmp="$lt", threshold=other)
+        return NotImplemented
+
+    def __ge__(self, other: Any) -> MetricThresholdFilter:
+        if isinstance(other, (int, float)):
+            return MetricThresholdFilter(**dict(self), cmp="$gte", threshold=other)
+        return NotImplemented
+
+    def __le__(self, other: Any) -> MetricThresholdFilter:
+        if isinstance(other, (int, float)):
+            return MetricThresholdFilter(**dict(self), cmp="$lte", threshold=other)
+        return NotImplemented
 
-class MetricOperand(Base):
-    name: str
-    agg: Optional[Agg] = Field(default=None, alias="agg_op")
-    window: PositiveInt = Field(default=1, alias="window_size")
+    @overload
+    def changes_by(self, *, diff: PosNum, frac: None) -> MetricChangeFilter: ...
+    @overload
+    def changes_by(self, *, diff: None, frac: PosNum) -> MetricChangeFilter: ...
+    @overload  # NOTE: This overload is for internal use only.
+    def changes_by(
+        self, *, diff: PosNum | None, frac: PosNum | None, _dir: ChangeDir
+    ) -> MetricChangeFilter: ...
+    def changes_by(
+        self,
+        *,
+        diff: PosNum | None = None,
+        frac: PosNum | None = None,
+        _dir: ChangeDir = ChangeDir.ANY,
+    ) -> MetricChangeFilter:
+        """Defines a filter that observes for any change (increase OR decrease) in a run metric.
+
+        Exactly one of the keyword arguments `frac` or `diff` must be provided.
+
+        Args:
+            diff:
+                If given, the arithmetic difference that must be observed
+                in the metric.  Must be a positive number.
+            frac:
+                If given, the fractional (relative) change that must be observed
+                in the metric.  Must be a positive number.  E.g. `frac=0.1`
+                denotes a 10% relative increase OR decrease.
+        """
+        # Enforce mutually exclusive keyword args
+        if (frac is None) is (diff is None):
+            raise ValueError("Must provide exactly one of `frac` or `diff`")
+
+        # Enforce positive values
+        if (frac is not None) and (frac <= 0):
+            raise ValueError(f"Expected positive quantity, got: {frac=}")
+        if (diff is not None) and (diff <= 0):
+            raise ValueError(f"Expected positive quantity, got: {diff=}")
+
+        if diff is None:
+            change_kws = dict(change_type=ChangeType.REL, threshold=frac)
+            return MetricChangeFilter(**dict(self), change_dir=_dir, **change_kws)
+        else:
+            change_kws = dict(change_type=ChangeType.ABS, threshold=diff)
+            return MetricChangeFilter(**dict(self), change_dir=_dir, **change_kws)
+
+    @overload
+    def increases_by(self, *, diff: PosNum, frac: None) -> MetricChangeFilter: ...
+    @overload
+    def increases_by(self, *, diff: None, frac: PosNum) -> MetricChangeFilter: ...
+    def increases_by(
+        self, *, diff: PosNum | None = None, frac: PosNum | None = None
+    ) -> MetricChangeFilter:
+        """Defines a filter that observes for an increase in the numerical value of a run metric.
 
-    def _agg(self, op: Agg, window: int) -> Self:
-        if self.agg is None:  # Prevent overwriting an existing aggregation operator
-            return self.model_copy(update={"agg": op, "window": window})
-        raise ValueError(f"Aggregation operator already set as: {self.agg!r}")
+        Arguments are the same as for `.changes_by()`.
+        """
+        return self.changes_by(diff=diff, frac=frac, _dir=ChangeDir.INC)
 
-    def max(self, window: int) -> Self:
-        return self._agg(Agg.MAX, window)
+    @overload
+    def decreases_by(self, *, diff: PosNum, frac: None) -> MetricChangeFilter: ...
+    @overload
+    def decreases_by(self, *, diff: None, frac: PosNum) -> MetricChangeFilter: ...
+    def decreases_by(
+        self, *, diff: PosNum | None = None, frac: PosNum | None = None
+    ) -> MetricChangeFilter:
+        """Defines a filter that observes for a decrease in the numerical value of a run metric.
 
-    def min(self, window: int) -> Self:
-        return self._agg(Agg.MIN, window)
+        Arguments are the same as for `.changes_by()`.
+        """
+        return self.changes_by(diff=diff, frac=frac, _dir=ChangeDir.DEC)
 
-    def average(self, window: int) -> Self:
-        return self._agg(Agg.AVERAGE, window)
 
-    # Aliased method for users familiar with e.g. torch/tf/numpy/pandas/polars/etc.
-    def mean(self, window: int) -> Self:
-        return self.average(window=window)
+class MetricVal(BaseMetricOperand):
+    """Represents a single, unaggregated metric value when defining a metric filter."""
 
-    def gt(self, other: int | float) -> MetricThresholdFilter:
-        return MetricThresholdFilter(**dict(self), cmp="$gt", threshold=other)
+    name: str
 
-    def lt(self, other: int | float) -> MetricThresholdFilter:
-        return MetricThresholdFilter(**dict(self), cmp="$lt", threshold=other)
+    # Allow users to convert this single-value metric into an aggregated metric expression.
+    def max(self, window: int) -> MetricAgg:
+        return MetricAgg(name=self.name, agg=Agg.MAX, window=window)
 
-    def gte(self, other: int | float) -> MetricThresholdFilter:
-        return MetricThresholdFilter(**dict(self), cmp="$gte", threshold=other)
+    def min(self, window: int) -> MetricAgg:
+        return MetricAgg(name=self.name, agg=Agg.MIN, window=window)
 
-    def lte(self, other: int | float) -> MetricThresholdFilter:
-        return MetricThresholdFilter(**dict(self), cmp="$lte", threshold=other)
+    def avg(self, window: int) -> MetricAgg:
+        return MetricAgg(name=self.name, agg=Agg.AVG, window=window)
 
-    __gt__ = gt
-    __lt__ = lt
-    __ge__ = gte
-    __le__ = lte
+    # Aliased method for users familiar with e.g. torch/tf/numpy/pandas/polars/etc.
+    def mean(self, window: int) -> MetricAgg:
+        return self.avg(window=window)
+
+
+class MetricAgg(BaseMetricOperand):
+    """Represents an aggregated metric value when defining a metric filter."""
+
+    name: str
+    agg: Annotated[Agg, Field(alias="agg_op")]
+    window: Annotated[PositiveInt, Field(alias="window_size")]