wandb 0.19.9__py3-none-macosx_11_0_arm64.whl → 0.19.10__py3-none-macosx_11_0_arm64.whl

wandb/automations/_generated/update_filter_trigger.py

@@ -0,0 +1,21 @@
+# Generated by ariadne-codegen
+# Source: tools/graphql_codegen/automations/
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import Field
+
+from wandb._pydantic import GQLBase
+
+from .fragments import UpdateFilterTriggerResult
+
+
+class UpdateFilterTrigger(GQLBase):
+    update_filter_trigger: Optional[UpdateFilterTriggerResult] = Field(
+        alias="updateFilterTrigger"
+    )
+
+
+UpdateFilterTrigger.model_rebuild()

wandb/automations/_utils.py

@@ -0,0 +1,123 @@
+# ruff: noqa: UP007  # Avoid using `X | Y` for union fields, as this can cause issues with pydantic < 2.6
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional, Protocol, TypedDict
+
+from wandb._pydantic import to_json
+from wandb.automations.events import InputEvent
+from wandb.automations.scopes import InputScope
+
+from ._generated import (
+    CreateFilterTriggerInput,
+    TriggeredActionConfig,
+    UpdateFilterTriggerInput,
+)
+from .actions import (
+    ActionType,
+    DoNothing,
+    DoNotification,
+    DoWebhook,
+    InputAction,
+    SavedAction,
+)
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+    from .automations import Automation, NewAutomation
+
+
+class HasId(Protocol):
+    id: str
+
+
+def extract_id(obj: HasId | str) -> str:
+    return obj.id if hasattr(obj, "id") else obj
+
+
+# NOTE: `QueueJobActionInput` for defining a Launch job is deprecated,
+# so we deliberately don't currently expose it in the API for *creating* automations.
+_ACTION_CONFIG_KEYS: dict[ActionType, str] = {
+    ActionType.NOTIFICATION: "notification_action_input",
+    ActionType.GENERIC_WEBHOOK: "generic_webhook_action_input",
+    ActionType.NO_OP: "no_op_action_input",
+}
+
+
+class InputActionConfig(TriggeredActionConfig):
+    """A `TriggeredActionConfig` that prepares the action config for saving an automation."""
+
+    notification_action_input: Optional[DoNotification] = None
+    generic_webhook_action_input: Optional[DoWebhook] = None
+    no_op_action_input: Optional[DoNothing] = None
+
+
+def prepare_action_input(obj: InputAction | SavedAction) -> InputActionConfig:
+    """Return a `TriggeredActionConfig` as required in the input schema of CreateFilterTriggerInput."""
+    key = _ACTION_CONFIG_KEYS[obj.action_type]
+    # Delegate the validators for each ActionInput type to handle custom logic
+    # for converting from saved action types to an input action type.
+    return InputActionConfig.model_validate({key: obj})
+
+
+class AutomationParams(TypedDict, total=False):
+    """Keyword arguments that can be passed to create or update an automation."""
+
+    name: str
+    description: str
+    enabled: bool
+
+    scope: InputScope
+    event: InputEvent
+    action: InputAction
+
+
+def prepare_create_input(
+    obj: NewAutomation, **updates: Unpack[AutomationParams]
+) -> CreateFilterTriggerInput:
+    """Prepares the payload to create an automation in a GraphQL request."""
+    from .automations import PreparedAutomation
+
+    # Apply any updates to the properties of the automation
+    updated = obj.model_copy(update=updates)
+    prepared = PreparedAutomation.model_validate(updated)
+
+    # Prepare the input as required for the GraphQL request
+    return CreateFilterTriggerInput(
+        name=prepared.name,
+        description=prepared.description,
+        enabled=prepared.enabled,
+        scope_type=prepared.scope.scope_type,
+        scope_id=prepared.scope.id,
+        triggering_event_type=prepared.event.event_type,
+        event_filter=to_json(prepared.event.filter),
+        triggered_action_type=prepared.action.action_type,
+        triggered_action_config=prepare_action_input(prepared.action).model_dump(),
+    )
+
+
+def prepare_update_input(
+    obj: Automation, **updates: Unpack[AutomationParams]
+) -> UpdateFilterTriggerInput:
+    """Prepares the payload to update an automation in a GraphQL request."""
+    from .events import SavedEventFilter
+
+    updated = obj.model_copy(update=updates)
+
+    return UpdateFilterTriggerInput(
+        id=updated.id,
+        name=updated.name,
+        description=updated.description,
+        enabled=updated.enabled,
+        scope_type=updated.scope.scope_type,
+        scope_id=updated.scope.id,
+        triggering_event_type=updated.event.event_type,
+        event_filter=to_json(
+            updated.event.filter.filter
+            if isinstance(updated.event.filter, SavedEventFilter)
+            else updated.event.filter
+        ),
+        triggered_action_type=updated.action.action_type,
+        triggered_action_config=prepare_action_input(updated.action).model_dump(),
+    )

wandb/automations/_validators.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from functools import singledispatch
+from itertools import chain
+from typing import Any, TypeVar
+
+from ._filters import And, FilterExpr, In, Nor, Not, NotIn, Op, Or
+
+T = TypeVar("T")
+
+
+def validate_scope(v: Any) -> Any:
+    """Convert a familiar wandb `Project` or `ArtifactCollection` object to an automation scope."""
+    from wandb.apis.public import ArtifactCollection, Project
+
+    from .scopes import ProjectScope, _ArtifactPortfolioScope, _ArtifactSequenceScope
+
+    if isinstance(v, Project):
+        return ProjectScope(id=v.id, name=v.name)
+    if isinstance(v, ArtifactCollection):
+        cls = _ArtifactSequenceScope if v.is_sequence() else _ArtifactPortfolioScope
+        return cls(id=v.id, name=v.name)
+    return v
+
+
+@singledispatch
+def simplify_op(op: Op | FilterExpr) -> Op | FilterExpr:
+    """Simplify a MongoDB filter by removing and unnesting redundant operators."""
+    return op
+
+
+@simplify_op.register
+def _(op: And) -> Op:
+    # {"$and": []} -> {"$and": []}
+    if not (args := op.and_):
+        return op
+
+    # {"$and": [op]} -> op
+    if len(args) == 1:
+        return simplify_op(args[0])
+
+    # {"$and": [op, {"$and": [op2, ...]}]} -> {"$and": [op, op2, ...]}
+    flattened = chain.from_iterable(x.and_ if isinstance(x, And) else [x] for x in args)
+    return And(and_=map(simplify_op, flattened))
+
+
+@simplify_op.register
+def _(op: Or) -> Op:
+    # {"$or": []} -> {"$or": []}
+    if not (args := op.or_):
+        return op
+
+    # {"$or": [op]} -> op
+    if len(args) == 1:
+        return simplify_op(args[0])
+
+    # {"$or": [op, {"$or": [op2, ...]}]} -> {"$or": [op, op2, ...]}
+    flattened = chain.from_iterable(x.or_ if isinstance(x, Or) else [x] for x in args)
+    return Or(or_=map(simplify_op, flattened))
+
+
+@simplify_op.register
+def _(op: Not) -> Op:
+    inner = op.not_
+
+    # {"$not": {"$not": op}} -> op
+    # {"$not": {"$or": [op, ...]}} -> {"$nor": [op, ...]}
+    # {"$not": {"$nor": [op, ...]}} -> {"$or": [op, ...]}
+    # {"$not": {"$in": [op, ...]}} -> {"$nin": [op, ...]}
+    # {"$not": {"$nin": [op, ...]}} -> {"$in": [op, ...]}
+    if isinstance(inner, (Not, Or, Nor, In, NotIn)):
+        return simplify_op(~inner)
+    return Not(not_=simplify_op(inner))

wandb/automations/actions.py

@@ -0,0 +1,205 @@
+"""Actions that are triggered by W&B Automations."""
+
+# ruff: noqa: UP007  # Avoid using `X | Y` for union fields, as this can cause issues with pydantic < 2.6
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import Field
+from typing_extensions import Self, TypeAlias, get_args
+
+from wandb._pydantic import (
+    SerializedToJson,
+    field_validator,
+    model_validator,
+    pydantic_isinstance,
+)
+
+from ._generated import (
+    AlertSeverity,
+    GenericWebhookActionFields,
+    GenericWebhookActionInput,
+    NoOpActionFields,
+    NoOpTriggeredActionInput,
+    NotificationActionFields,
+    NotificationActionInput,
+    QueueJobActionFields,
+    TriggeredActionType,
+)
+from .integrations import SlackIntegration, WebhookIntegration
+
+# Note: Pydantic doesn't like `list['JsonValue']` or `dict[str, 'JsonValue']`,
+# which causes a RecursionError.
+JsonValue: TypeAlias = Union[
+    List[Any],
+    Dict[str, Any],
+    # NOTE: For now, we're not expecting any doubly-serialized strings, as this makes validation logic easier, but revisit and revise if needed.
+    # str,
+    bool,
+    int,
+    float,
+    None,
+]
+
+# NOTE: Name shortened for readability and defined publicly for easier access
+ActionType = TriggeredActionType
+"""The type of action triggered by an automation."""
+
+
+# ------------------------------------------------------------------------------
+# Saved types: for parsing response data from saved automations
+
+
+# NOTE: `QueueJobActionInput` for defining a Launch job is deprecated,
+# so while we allow parsing it from previously saved Automations, we deliberately
+# don't currently expose it in the API for creating automations.
+class SavedLaunchJobAction(QueueJobActionFields):
+    action_type: Literal[ActionType.QUEUE_JOB] = ActionType.QUEUE_JOB
+
+
+class SavedNotificationAction(NotificationActionFields):
+    action_type: Literal[ActionType.NOTIFICATION] = ActionType.NOTIFICATION
+
+
+class SavedWebhookAction(GenericWebhookActionFields):
+    action_type: Literal[ActionType.GENERIC_WEBHOOK] = ActionType.GENERIC_WEBHOOK
+
+    # We override the type of the `requestPayload` field since the original GraphQL
+    # schema (and generated class) effectively defines it as a string, when we know
+    # and need to anticipate the expected structure of the JSON-serialized data.
+    request_payload: Optional[SerializedToJson[JsonValue]] = Field(  # type: ignore[assignment]
+        default=None, alias="requestPayload"
+    )
+
+
+class SavedNoOpAction(NoOpActionFields):
+    action_type: Literal[ActionType.NO_OP] = ActionType.NO_OP
+
+
+# for type annotations
+SavedAction = Union[
+    SavedLaunchJobAction,
+    SavedNotificationAction,
+    SavedWebhookAction,
+    SavedNoOpAction,
+]
+# for runtime type checks
+SavedActionTypes: tuple[type, ...] = get_args(SavedAction)
+
+
+# ------------------------------------------------------------------------------
+# Input types: for creating or updating automations
+class DoNotification(NotificationActionInput):
+    """Schema for defining a triggered notification action."""
+
+    action_type: Literal[ActionType.NOTIFICATION] = ActionType.NOTIFICATION
+
+    # Note: Validation aliases match arg names from `wandb.alert()` to allow
+    # continuity with previous API.
+    title: str = Field(default="", validation_alias="title")
+    message: str = Field(default="", validation_alias="text")
+    severity: AlertSeverity = Field(
+        default=AlertSeverity.INFO, validation_alias="level"
+    )
+
+    @field_validator("severity", mode="before")
+    @classmethod
+    def _validate_severity(cls, v: Any) -> Any:
+        # Be helpful by accepting case-insensitive strings
+        return v.upper() if isinstance(v, str) else v
+
+    @model_validator(mode="before")
+    @classmethod
+    def _from_saved(cls, v: Any) -> Any:
+        """Convert an action on a saved automation to a new/input action."""
+        if pydantic_isinstance(v, SavedNotificationAction):
+            return cls(
+                integration_id=v.integration.id,
+                title=v.title,
+                message=v.message,
+                severity=v.severity,
+            )
+        return v
+
+    @classmethod
+    def from_integration(
+        cls,
+        integration: SlackIntegration,
+        *,
+        title: str = "",
+        text: str = "",
+        level: AlertSeverity = AlertSeverity.INFO,
+    ) -> Self:
+        """Define a notification action that sends to the given (Slack) integration."""
+        integration = SlackIntegration.model_validate(integration)
+        return cls(
+            integration_id=integration.id,
+            title=title,
+            message=text,
+            severity=level,
+        )
+
+
+class DoWebhook(GenericWebhookActionInput):
+    """Schema for defining a triggered webhook action."""
+
+    action_type: Literal[ActionType.GENERIC_WEBHOOK] = ActionType.GENERIC_WEBHOOK
+
+    # overrides the generated field type to parse/serialize JSON strings
+    request_payload: Optional[SerializedToJson[JsonValue]] = Field(  # type: ignore[assignment]
+        default=None, alias="requestPayload"
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _from_saved(cls, v: Any) -> Any:
+        """Convert an action on a saved automation to a new/input action."""
+        if pydantic_isinstance(v, SavedWebhookAction):
+            return cls(
+                integration_id=v.integration.id,
+                request_payload=v.request_payload,
+            )
+        return v
+
+    @classmethod
+    def from_integration(
+        cls,
+        integration: WebhookIntegration,
+        *,
+        request_payload: Optional[SerializedToJson[JsonValue]] = None,
+    ) -> Self:
+        """Define a webhook action that sends to the given (webhook) integration."""
+        integration = WebhookIntegration.model_validate(integration)
+        return cls(integration_id=integration.id, request_payload=request_payload)
+
+
+class DoNothing(NoOpTriggeredActionInput):
+    """Schema for defining a triggered no-op action."""
+
+    action_type: Literal[ActionType.NO_OP] = ActionType.NO_OP
+
+    no_op: bool = True  # prevent exclusion on `.model_dump(exclude_none=True)`
+
+    @field_validator("no_op", mode="before")
+    @classmethod
+    def _ensure_nonnull(cls, v: Any) -> Any:
+        # Ensuring the value isn't None complies with validation and
+        # prevents the field (and action data) from getting excluded on
+        # `.model_dump(exclude_none=True)`
+        return True if (v is None) else v
+
+
+DoNotification.model_rebuild()
+DoWebhook.model_rebuild()
+DoNothing.model_rebuild()
+
+
+# for type annotations
+InputAction = Union[
+    DoNotification,
+    DoWebhook,
+    DoNothing,
+]
+# for runtime type checks
+InputActionTypes: tuple[type, ...] = get_args(InputAction)

wandb/automations/automations.py

@@ -0,0 +1,109 @@
+# ruff: noqa: UP007  # Avoid using `X | Y` for union fields, as this can cause issues with pydantic < 2.6
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional
+
+from pydantic import Field
+
+from wandb._pydantic import Base, GQLId
+
+from ._generated import TriggerFields, UserFields
+from .actions import InputAction, SavedAction
+from .events import InputEvent, SavedEvent
+from .scopes import InputScope, SavedScope
+
+if TYPE_CHECKING:
+    pass
+
+
+# ------------------------------------------------------------------------------
+# Saved types: for parsing response data from saved automations
+class Automation(TriggerFields):
+    """A local instance of a saved W&B automation."""
+
+    id: GQLId
+
+    created_by: UserFields = Field(repr=False, frozen=True, alias="createdBy")
+    created_at: datetime = Field(repr=False, frozen=True, alias="createdAt")
+    updated_at: Optional[datetime] = Field(repr=False, frozen=True, alias="updatedAt")
+
+    name: str
+    description: Optional[str]
+
+    scope: SavedScope = Field(discriminator="typename__")
+    event: SavedEvent
+    action: SavedAction = Field(discriminator="typename__", alias="triggeredAction")
+
+    enabled: bool
+
+    # def save(
+    #     self, api: Api | None = None, **updates: Unpack[AutomationParams]
+    # ) -> Automation:
+    #     """Save this existing automation to the server, applying any local changes.
+
+    #     Args:
+    #         api: The API instance to use.  If not provided, the default API instance is used.
+    #         updates:
+    #             Any final updates to apply to the automation before
+    #             saving it.  These override previously-set values, if any.
+
+    #     Returns:
+    #         The updated automation.
+    #     """
+    #     from wandb import Api
+
+    #     return (api or Api()).update_automation(self, **updates)
+
+    # def delete(self, api: Api | None = None) -> DeleteTriggerResult:
+    #     """Delete this automation from the server.
+
+    #     Args:
+    #         api: The API instance to use.  If not provided, the default API instance is used.
+    #     """
+    #     from wandb import Api
+
+    #     return (api or Api()).delete_automation(self)
+
+
+class NewAutomation(Base):
+    """An automation which can hold any of the fields of a NewAutomation, but may not be complete yet."""
+
+    name: Optional[str] = None
+    description: Optional[str] = None
+    enabled: bool = True
+
+    scope: Optional[InputScope] = Field(discriminator="typename__", default=None)
+    event: Optional[InputEvent] = Field(discriminator="event_type", default=None)
+    action: Optional[InputAction] = Field(discriminator="action_type", default=None)
+
+    # def save(
+    #     self, api: Api | None = None, **updates: Unpack[AutomationParams]
+    # ) -> Automation:
+    #     """Create this automation by saving it to the server.
+
+    #     Args:
+    #         api: The API instance to use.  If not provided, the default API instance is used.
+    #         updates:
+    #             Any final updates to apply to the automation before
+    #             saving it.  These override previously-set values, if any.
+
+    #     Returns:
+    #         The created automation.
+    #     """
+    #     from wandb import Api
+
+    #     return (api or Api()).create_automation(self, **updates)
+
+
+class PreparedAutomation(NewAutomation):
+    """A fully defined automation, ready to be sent to the server to create or update it."""
+
+    name: str
+    description: Optional[str] = None
+    enabled: bool = True
+
+    scope: InputScope
+    event: InputEvent
+    action: InputAction