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

wandb/automations/events.py

@@ -7,11 +7,12 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 
 from pydantic import Field
-from typing_extensions import Self, TypeAlias, get_args
+from typing_extensions import Annotated, Self, get_args
 
 from wandb._pydantic import (
     GQLBase,
     SerializedToJson,
+    ensure_json,
     field_validator,
     model_validator,
     pydantic_isinstance,
@@ -19,26 +20,34 @@ from wandb._pydantic import (
 
 from ._filters import And, MongoLikeFilter, Or
 from ._filters.expressions import FilterableField
-from ._filters.run_metrics import (
-    Agg,
-    MetricChangeFilter,
-    MetricOperand,
-    MetricThresholdFilter,
-)
-from ._generated import EventTriggeringConditionType, FilterEventFields
-from ._validators import simplify_op
-from .actions import InputAction, InputActionTypes
-from .scopes import ArtifactCollectionScope, InputScope, ProjectScope
+from ._filters.run_metrics import MetricChangeFilter, MetricThresholdFilter, MetricVal
+from ._generated import FilterEventFields
+from ._validators import LenientStrEnum, simplify_op
+from .actions import InputAction, InputActionTypes, SavedActionTypes
+from .scopes import ArtifactCollectionScope, AutomationScope, ProjectScope
 
 if TYPE_CHECKING:
     from .automations import NewAutomation
 
 
 # NOTE: Re-defined publicly with a more readable name for easier access
-EventType = EventTriggeringConditionType
-"""The type of event that triggers an automation."""
+class EventType(LenientStrEnum):
+    """The type of event that triggers an automation."""
+
+    # ---------------------------------------------------------------------------
+    # Events triggered by GraphQL mutations
+    UPDATE_ARTIFACT_ALIAS = "UPDATE_ARTIFACT_ALIAS"  # NOTE: Avoid in new automations
 
-Agg = Agg
+    CREATE_ARTIFACT = "CREATE_ARTIFACT"
+    ADD_ARTIFACT_ALIAS = "ADD_ARTIFACT_ALIAS"
+    LINK_ARTIFACT = "LINK_MODEL"
+    # Note: "LINK_MODEL" is the (legacy) value expected by the backend, but we
+    # name it "LINK_ARTIFACT" here in the public API for clarity and consistency.
+
+    # ---------------------------------------------------------------------------
+    # Events triggered by Run conditions
+    RUN_METRIC_THRESHOLD = "RUN_METRIC"
+    RUN_METRIC_CHANGE = "RUN_METRIC_CHANGE"
 
 
 # ------------------------------------------------------------------------------
@@ -46,11 +55,11 @@ Agg = Agg
 
 
 # Note: In GQL responses containing saved automation data, the filter is wrapped in an extra `filter` key.
-class SavedEventFilter(GQLBase):
-    filter: SerializedToJson[MongoLikeFilter] = Field(default_factory=And)
+class _WrappedSavedEventFilter(GQLBase):  # from: TriggeringFilterEvent
+    filter: SerializedToJson[MongoLikeFilter] = And()
 
 
-class _InnerRunMetricFilter(GQLBase):  # from `RunMetricFilter`
+class _WrappedMetricFilter(GQLBase):  # from: RunMetricFilter
     threshold_filter: Optional[MetricThresholdFilter] = None
     change_filter: Optional[MetricChangeFilter] = None
 
@@ -65,58 +74,67 @@ class _InnerRunMetricFilter(GQLBase):  # from `RunMetricFilter`
 
     @model_validator(mode="after")
     def _ensure_exactly_one_set(self) -> Self:
-        set_field_names = [name for name, val in self if (val is not None)]
-        if not set_field_names:
-            raise ValueError("Must specify a run metric filter")
-        if len(set_field_names) > 1:
-            names = ", ".join(map(repr, set_field_names))
-            raise ValueError(f"Must specify a single run metric filter, got: {names}")
+        set_fields = [name for name, val in self if (val is not None)]
+
+        if not set_fields:
+            all_names = ", ".join(map(repr, type(self).model_fields))
+            raise ValueError(f"Expected one of: {all_names}")
+
+        if len(set_fields) > 1:
+            set_names = ", ".join(map(repr, set_fields))
+            raise ValueError(f"Expected exactly one metric filter, got: {set_names}")
+
         return self
 
+    @property
+    def event_type(self) -> EventType:
+        if self.threshold_filter is not None:
+            return EventType.RUN_METRIC_THRESHOLD
+        if self.change_filter is not None:
+            return EventType.RUN_METRIC_CHANGE
+        raise RuntimeError("Expected one of: `threshold_filter` or `change_filter`")
+
+
+class RunMetricFilter(GQLBase):  # from: TriggeringRunMetricEvent
+    run: Annotated[SerializedToJson[MongoLikeFilter], Field(alias="run_filter")] = And()
+    metric: Annotated[_WrappedMetricFilter, Field(alias="run_metric_filter")]
 
-class RunMetricFilter(GQLBase):  # from `RunMetricEvent`
-    run_filter: SerializedToJson[MongoLikeFilter] = Field(default_factory=And)
-    run_metric_filter: _InnerRunMetricFilter
+    # ------------------------------------------------------------------------------
+    legacy_metric_filter: Annotated[
+        Optional[SerializedToJson[MetricThresholdFilter]],
+        Field(alias="metric_filter", deprecated=True),
+    ] = None
+    """Deprecated legacy field that was previously used to define run metric threshold events.
 
-    #: Legacy field to define triggers on run metrics from absolute thresholds.  Use `run_metric_filter` instead.
-    metric_filter: Optional[SerializedToJson[MetricThresholdFilter]] = Field(
-        default=None,
-        deprecated="The `metric_filter` field is deprecated: use `run_metric_filter` instead.",
-    )
+    For new automations, use the `metric` field (`run_metric_filter` JSON alias) instead.
+    """
 
     @model_validator(mode="before")
     @classmethod
     def _wrap_metric_filter(cls, v: Any) -> Any:
         if pydantic_isinstance(v, (MetricThresholdFilter, MetricChangeFilter)):
-            # If we're only given an (unwrapped) metric filter, automatically wrap it
-            # in the appropriate nested structure, and use the default run filter.
-
-            # Delegate to the inner validator to further wrap the filter as appropriate.
-            return cls(run_metric_filter=_InnerRunMetricFilter.model_validate(v))
+            # If only an (unnested) metric filter is given, nest it under the
+            # `metric` field, delegating to inner validator(s) for further
+            # wrapping/nesting, if needed.
+            # This is necessary to conform to the expected backend schema.
+            return cls(metric=v)
         return v
 
-    @field_validator("run_filter", mode="after")
-    @classmethod
+    @field_validator("run", mode="after")
     def _wrap_run_filter(cls, v: MongoLikeFilter) -> Any:
         v_new = simplify_op(v)
-        return (
-            And.model_validate(v_new)
-            if pydantic_isinstance(v_new, And)
-            else And(and_=[v_new])
-        )
+        return v_new if pydantic_isinstance(v_new, And) else And(and_=[v_new])
 
 
-# type alias defined for naming consistency/clarity
-SavedRunMetricFilter: TypeAlias = RunMetricFilter
+class SavedEvent(FilterEventFields):  # from: FilterEventTriggeringCondition
+    """A triggering event from a saved automation."""
 
+    event_type: Annotated[EventType, Field(frozen=True)]  # type: ignore[assignment]
 
-class SavedEvent(FilterEventFields):  # from `FilterEventTriggeringCondition`
-    """A more introspection-friendly representation of a triggering event from a saved automation."""
-
-    # We override the type of the `filter` field since the original GraphQL
-    # schema (and generated class) defines it as a JSONString (str), but we
-    # have more specific expectations for the structure of the JSON data.
-    filter: SerializedToJson[Union[SavedEventFilter, SavedRunMetricFilter]]
+    # We override the type of the `filter` field in order to enforce the expected
+    # structure for the JSON data when validating and serializing.
+    filter: SerializedToJson[Union[_WrappedSavedEventFilter, RunMetricFilter]]
+    """The condition(s) under which this event triggers an automation."""
 
 
 # ------------------------------------------------------------------------------
@@ -127,98 +145,123 @@ class SavedEvent(FilterEventFields):  # from `FilterEventTriggeringCondition`
 # eventFilter returned in responses for saved automations.
 class _BaseEventInput(GQLBase):
     event_type: EventType
-    scope: InputScope
+
+    scope: AutomationScope
+    """The scope of the event."""
+
     filter: SerializedToJson[Any]
 
-    def add_action(self, action: InputAction) -> NewAutomation:
-        """Define an executed action to be triggered by this event."""
+    def then(self, action: InputAction) -> NewAutomation:
+        """Define a new Automation in which this event triggers the given action."""
         from .automations import NewAutomation
 
-        if isinstance(action, InputActionTypes):
-            return NewAutomation(scope=self.scope, event=self, action=action)
+        if isinstance(action, (InputActionTypes, SavedActionTypes)):
+            return NewAutomation(event=self, action=action)
 
         raise TypeError(f"Expected a valid action, got: {type(action).__qualname__!r}")
 
     def __rshift__(self, other: InputAction) -> NewAutomation:
-        """Supports `event >> action` as syntactic sugar to combine an event and action."""
-        return self.add_action(other)
+        """Implements `event >> action` to define an Automation with this event and action."""
+        return self.then(other)
 
 
+# ------------------------------------------------------------------------------
+# Events that trigger on specific mutations in the backend
 class _BaseMutationEventInput(_BaseEventInput):
-    event_type: EventType
-    scope: InputScope
-    filter: SerializedToJson[MongoLikeFilter] = Field(default_factory=And)
+    filter: SerializedToJson[MongoLikeFilter] = And()
+    """Additional condition(s), if any, that must be met for this event to trigger an automation."""
 
     @field_validator("filter", mode="after")
-    @classmethod
     def _wrap_filter(cls, v: Any) -> Any:
         """Ensure the given filter is wrapped like: `{"$or": [{"$and": [<original_filter>]}]}`.
 
         This is awkward but necessary, because the frontend expects this format.
         """
         v_new = simplify_op(v)
-        v_new = (
-            And.model_validate(v_new)
-            if pydantic_isinstance(v_new, And)
-            else And(and_=[v_new])
-        )
-        v_new = Or(or_=[v_new])
-        return v_new
+        v_new = v_new if pydantic_isinstance(v_new, And) else And(and_=[v_new])
+        return Or(or_=[v_new])
 
 
 class OnLinkArtifact(_BaseMutationEventInput):
     """A new artifact is linked to a collection."""
 
-    event_type: Literal[EventType.LINK_MODEL] = EventType.LINK_MODEL
-    scope: InputScope
+    event_type: Literal[EventType.LINK_ARTIFACT] = EventType.LINK_ARTIFACT
 
 
 class OnAddArtifactAlias(_BaseMutationEventInput):
     """A new alias is assigned to an artifact."""
 
     event_type: Literal[EventType.ADD_ARTIFACT_ALIAS] = EventType.ADD_ARTIFACT_ALIAS
-    scope: InputScope
 
 
 class OnCreateArtifact(_BaseMutationEventInput):
     """A new artifact is created."""
 
     event_type: Literal[EventType.CREATE_ARTIFACT] = EventType.CREATE_ARTIFACT
-    scope: ArtifactCollectionScope
 
+    scope: ArtifactCollectionScope
+    """The scope of the event: only artifact collections are valid scopes for this event."""
 
-class OnRunMetric(_BaseEventInput):
-    """A run metric satisfies a user-defined absolute threshold."""
 
-    event_type: Literal[EventType.RUN_METRIC] = EventType.RUN_METRIC
+# ------------------------------------------------------------------------------
+# Events that trigger on run conditions
+class _BaseRunEventInput(_BaseEventInput):
     scope: ProjectScope
+    """The scope of the event: only projects are valid scopes for this event."""
+
+
+class OnRunMetric(_BaseRunEventInput):
+    """A run metric satisfies a user-defined condition."""
+
+    event_type: Literal[EventType.RUN_METRIC_THRESHOLD, EventType.RUN_METRIC_CHANGE]
+
     filter: SerializedToJson[RunMetricFilter]
+    """Run and/or metric condition(s) that must be satisfied for this event to trigger an automation."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _infer_event_type(cls, data: Any) -> Any:
+        """Infer the event type at validation time from the inner filter.
+
+        This allows this class to accommodate both "threshold" and "change" metric
+        filter types, which are can only be determined after parsing and validating
+        the inner JSON data.
+        """
+        if isinstance(data, dict) and (raw_filter := data.get("filter")):
+            # At this point, `raw_filter` may or may not be JSON-serialized
+            parsed_filter = RunMetricFilter.model_validate_json(ensure_json(raw_filter))
+            return {**data, "event_type": parsed_filter.metric.event_type}
+
+        return data
 
 
 # for type annotations
-InputEvent = Union[
-    OnLinkArtifact,
-    OnAddArtifactAlias,
-    OnCreateArtifact,
-    OnRunMetric,
+InputEvent = Annotated[
+    Union[
+        OnLinkArtifact,
+        OnAddArtifactAlias,
+        OnCreateArtifact,
+        OnRunMetric,
+    ],
+    Field(discriminator="event_type"),
 ]
 # for runtime type checks
-InputEventTypes: tuple[type, ...] = get_args(InputEvent)
+InputEventTypes: tuple[type, ...] = get_args(InputEvent.__origin__)  # type: ignore[attr-defined]
 
 
 # ----------------------------------------------------------------------------
 
 
 class RunEvent:
-    name = FilterableField("display_name")
+    name = FilterableField(server_name="display_name")
     # `Run.name` is actually filtered on `Run.display_name` in the backend.
     # We can't reasonably expect users to know this a priori, so
     # automatically fix it here.
 
     @staticmethod
-    def metric(name: str) -> MetricOperand:
+    def metric(name: str) -> MetricVal:
         """Define a metric filter condition."""
-        return MetricOperand(name=name)
+        return MetricVal(name=name)
 
 
 class ArtifactEvent:
@@ -227,9 +270,18 @@ class ArtifactEvent:
 
 MetricThresholdFilter.model_rebuild()
 RunMetricFilter.model_rebuild()
-SavedEventFilter.model_rebuild()
+_WrappedSavedEventFilter.model_rebuild()
 
 OnLinkArtifact.model_rebuild()
 OnAddArtifactAlias.model_rebuild()
 OnCreateArtifact.model_rebuild()
 OnRunMetric.model_rebuild()
+
+__all__ = [
+    "EventType",
+    *(cls.__name__ for cls in InputEventTypes),
+    "RunEvent",
+    "ArtifactEvent",
+    "MetricThresholdFilter",
+    "MetricChangeFilter",
+]

wandb/automations/integrations.py

@@ -1,6 +1,7 @@
 from typing import Union
 
 from pydantic import Field
+from typing_extensions import Annotated
 
 from wandb._pydantic import GQLBase
 from wandb.automations._generated import (
@@ -10,17 +11,35 @@ from wandb.automations._generated import (
 
 
 class SlackIntegration(SlackIntegrationFields):
-    pass
+    team_name: str
+    """The name of the Slack workspace (not the W&B team) that this integration is associated with."""
+
+    channel_name: str
+    """The name of the Slack channel that this integration will post messages to."""
 
 
 class WebhookIntegration(GenericWebhookIntegrationFields):
-    pass
+    name: str
+    """The name of this webhook integration."""
+
+    url_endpoint: str
+    """The URL that this webhook will POST events to."""
 
 
-Integration = Union[SlackIntegration, WebhookIntegration]
+Integration = Annotated[
+    Union[SlackIntegration, WebhookIntegration],
+    Field(discriminator="typename__"),
+]
 
 
 # For parsing integration instances from paginated responses
 class _IntegrationEdge(GQLBase):
     cursor: str
-    node: Integration = Field(discriminator="typename__")
+    node: Integration
+
+
+__all__ = [
+    "Integration",
+    "SlackIntegration",
+    "WebhookIntegration",
+]

wandb/automations/scopes.py

@@ -14,26 +14,29 @@ from wandb.automations._generated import (
     ProjectScopeFields,
 )
 
-from ._generated import TriggerScopeType
-from ._validators import validate_scope
+from ._validators import LenientStrEnum, to_scope
+
 
 # NOTE: Re-defined publicly with a more readable name for easier access
-ScopeType = TriggerScopeType
-"""The type of scope that triggers an automation."""
+class ScopeType(LenientStrEnum):
+    """The kind of scope that triggers an automation."""
+
+    PROJECT = "PROJECT"
+    ARTIFACT_COLLECTION = "ARTIFACT_COLLECTION"
 
 
 class _BaseScope(GQLBase):
-    scope_type: ScopeType
+    scope_type: Annotated[ScopeType, Field(frozen=True)]
 
 
 class _ArtifactSequenceScope(_BaseScope, ArtifactSequenceScopeFields):
-    """The ID and name of a "sequence"-type ArtifactCollection scope of an automation."""
+    """An automation scope defined by a specific `ArtifactSequence`."""
 
     scope_type: Literal[ScopeType.ARTIFACT_COLLECTION] = ScopeType.ARTIFACT_COLLECTION
 
 
 class _ArtifactPortfolioScope(_BaseScope, ArtifactPortfolioScopeFields):
-    """The ID and name of a "portfolio"-type ArtifactCollection scope of an automation."""
+    """An automation scope defined by a specific `ArtifactPortfolio` (e.g. a registry collection)."""
 
     scope_type: Literal[ScopeType.ARTIFACT_COLLECTION] = ScopeType.ARTIFACT_COLLECTION
 
@@ -41,20 +44,19 @@ class _ArtifactPortfolioScope(_BaseScope, ArtifactPortfolioScopeFields):
 # for type annotations
 ArtifactCollectionScope = Annotated[
     Union[_ArtifactSequenceScope, _ArtifactPortfolioScope],
-    BeforeValidator(validate_scope),
+    BeforeValidator(to_scope),
     Field(discriminator="typename__"),
 ]
-"""The ID and name of the ArtifactCollection scope of an automation."""
+"""An automation scope defined by a specific `ArtifactCollection`."""
 
 # for runtime type checks
-ArtifactCollectionScopeTypes: tuple[type, ...] = (
-    _ArtifactSequenceScope,
-    _ArtifactPortfolioScope,
+ArtifactCollectionScopeTypes: tuple[type, ...] = get_args(
+    ArtifactCollectionScope.__origin__  # type: ignore[attr-defined]
 )
 
 
 class ProjectScope(_BaseScope, ProjectScopeFields):
-    """The ID and name of the Project scope of an automation."""
+    """An automation scope defined by a specific `Project`."""
 
     scope_type: Literal[ScopeType.PROJECT] = ScopeType.PROJECT
 
@@ -62,15 +64,15 @@ class ProjectScope(_BaseScope, ProjectScopeFields):
 # for type annotations
 AutomationScope: TypeAlias = Annotated[
     Union[_ArtifactSequenceScope, _ArtifactPortfolioScope, ProjectScope],
-    BeforeValidator(validate_scope),
+    BeforeValidator(to_scope),
     Field(discriminator="typename__"),
 ]
 # for runtime type checks
-AutomationScopeTypes: tuple[type, ...] = get_args(AutomationScope)
+AutomationScopeTypes: tuple[type, ...] = get_args(AutomationScope.__origin__)  # type: ignore[attr-defined]
 
-# Aliases for naming clarity/consistency
-SavedScope: TypeAlias = AutomationScope
-InputScope: TypeAlias = AutomationScope
 
-SavedScopeTypes: tuple[type, ...] = get_args(SavedScope)
-InputScopeTypes: tuple[type, ...] = get_args(InputScope)
+__all__ = [
+    "ScopeType",
+    "ArtifactCollectionScope",
+    "ProjectScope",
+]

wandb/env.py

@@ -88,6 +88,7 @@ LAUNCH_QUEUE_NAME = "WANDB_LAUNCH_QUEUE_NAME"
 LAUNCH_QUEUE_ENTITY = "WANDB_LAUNCH_QUEUE_ENTITY"
 LAUNCH_TRACE_ID = "WANDB_LAUNCH_TRACE_ID"
 _REQUIRE_LEGACY_SERVICE = "WANDB_X_REQUIRE_LEGACY_SERVICE"
+ENABLE_DCGM_PROFILING = "WANDB_ENABLE_DCGM_PROFILING"
 
 # For testing, to be removed in future version
 USE_V1_ARTIFACTS = "_WANDB_USE_V1_ARTIFACTS"
@@ -177,6 +178,16 @@ def ssl_disabled() -> bool:
     return _env_as_bool(DISABLE_SSL, default="False")
 
 
+def dcgm_profiling_enabled() -> bool:
+    """Checks whether collecting profiling metrics for Nvidia GPUs using DCGM is requested.
+
+    Note: Enabling this feature can lead to increased resource usage
+          compared to standard monitoring.
+          Requires the `nvidia-dcgm` service to be running on the machine.
+    """
+    return _env_as_bool(ENABLE_DCGM_PROFILING, default="False")
+
+
 def get_error_reporting(
     default: bool | str = True,
     env: MutableMapping | None = None,

wandb/old/settings.py

@@ -146,6 +146,10 @@ class Settings:
         try:
             home_config_dir = os.path.join(os.path.expanduser("~"), ".config", "wandb")
 
+            if os.getenv(env.CONFIG_DIR):
+                try_create_dir(os.getenv(env.CONFIG_DIR))
+                return os.path.join(os.getenv(env.CONFIG_DIR), "settings")
+
             if not try_create_dir(home_config_dir):
                 temp_config_dir = os.path.join(
                     tempfile.gettempdir(), ".config", "wandb"
@@ -162,7 +166,6 @@ class Settings:
             else:
                 config_dir = home_config_dir
 
-            config_dir = os.environ.get(env.CONFIG_DIR, config_dir)
             return os.path.join(config_dir, "settings")
         except Exception:
             return None