Python SDK: Docs release v0.23.1

docs.json

@@ -579,12 +579,15 @@
                           "models/ref/python/automations/automation",
                           "models/ref/python/automations/donothing",
                           "models/ref/python/automations/metricchangefilter",
+                          "models/ref/python/automations/metriczscorefilter",
                           "models/ref/python/automations/metricthresholdfilter",
                           "models/ref/python/automations/newautomation",
                           "models/ref/python/automations/onaddartifactalias",
                           "models/ref/python/automations/oncreateartifact",
                           "models/ref/python/automations/onlinkartifact",
                           "models/ref/python/automations/onrunmetric",
+                          "models/ref/python/automations/onrunstate",
+                          "models/ref/python/automations/runstatefilter",
                           "models/ref/python/automations/sendnotification",
                           "models/ref/python/automations/sendwebhook"
                         ]

models/ref/python/automations/metricthresholdfilter.mdx

@@ -10,7 +10,10 @@ import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx';
 
 
 ## <kbd>class</kbd> `MetricThresholdFilter`
-Filter that compares a metric value against a user-defined threshold.
+Filter that compares an **absolute** metric value against a user-defined threshold.
+
+The value may be a single value or an aggregated result over a window of
+multiple values.
 
 
 ### <kbd>method</kbd> `MetricThresholdFilter.__init__`

models/ref/python/automations/metriczscorefilter.mdx

@@ -0,0 +1,63 @@
+---
+title: MetricZScoreFilter
+namespace: automations_namespace
+python_object_type: class
+---
+import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx';
+
+<GitHubLink url="https://github.com/wandb/wandb/blob/main/wandb/automations/_filters/run_metrics.py" />
+
+
+
+## <kbd>class</kbd> `MetricZScoreFilter`
+Usage docs: https://docs.pydantic.dev/2.10/concepts/models/
+
+A base class for creating Pydantic models.
+
+Attributes:
+    __class_vars__: The names of the class variables defined on the model.
+    __private_attributes__: Metadata about the private attributes of the model.
+    __signature__: The synthesized `__init__` [`Signature`][inspect.Signature] of the model.
+
+    __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
+    __pydantic_core_schema__: The core schema of the model.
+    __pydantic_custom_init__: Whether the model has a custom `__init__` function.
+    __pydantic_decorators__: Metadata containing the decorators defined on the model.
+        This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1.
+    __pydantic_generic_metadata__: Metadata for generic models; contains data used for a similar purpose to
+        __args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these.
+    __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
+    __pydantic_post_init__: The name of the post-init method for the model, if defined.
+    __pydantic_root_model__: Whether the model is a [`RootModel`][pydantic.root_model.RootModel].
+    __pydantic_serializer__: The `pydantic-core` `SchemaSerializer` used to dump instances of the model.
+    __pydantic_validator__: The `pydantic-core` `SchemaValidator` used to validate instances of the model.
+
+    __pydantic_fields__: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects.
+    __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects.
+
+    __pydantic_extra__: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra]
+        is set to `'allow'`.
+    __pydantic_fields_set__: The names of fields explicitly set during instantiation.
+    __pydantic_private__: Values of private attributes set on the model instance.
+
+
+### <kbd>method</kbd> `MetricZScoreFilter.__init__`
+
+```python
+__init__(
+    name: 'str',
+    window: 'int' = 30,
+    threshold: 'Annotated | Annotated' = 3.0,
+    change_dir: 'ChangeDir' = ANY
+) → None
+```
+
+**Args:**
+
+ - `name` (str): Name of the observed metric.
+ - `window` (int): Size of the window to calculate the metric mean and standard deviation over.
+ - `threshold` (Union[Annotated, Annotated]): Threshold for the z-score.
+ - `change_dir` (ChangeDir): Direction of the z-score change to watch for.
+
+**Returns:**
+ An `MetricZScoreFilter` object.

models/ref/python/automations/onaddartifactalias.mdx

@@ -12,22 +12,39 @@ import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx';
 ## <kbd>class</kbd> `OnAddArtifactAlias`
 A new alias is assigned to an artifact.
 
+Examples:
+    Define an event that triggers whenever the alias "prod" is assigned to
+    any artifact in the collection "my-collection":
+
+    ```python
+    from wandb import Api
+    from wandb.automations import OnAddArtifactAlias, ArtifactEvent
+
+    api = Api()
+    collection = api.artifact_collection(name="my-collection", type_name="model")
+
+    event = OnAddArtifactAlias(
+        scope=collection,
+        filter=ArtifactEvent.alias.eq("prod"),
+    )
+    ```
+
 
 ### <kbd>method</kbd> `OnAddArtifactAlias.__init__`
 
 ```python
 __init__(
     event_type: 'Literal[ADD_ARTIFACT_ALIAS]' = ADD_ARTIFACT_ALIAS,
     scope: '_ArtifactSequenceScope | _ArtifactPortfolioScope | ProjectScope',
-    filter: 'And | Or | Nor | Not | Lt | Gt | Lte | Gte | Eq | Ne | In | NotIn | Exists | Regex | Contains | dict[str, Any] | FilterExpr' = And([])
+    filter: 'And | Or | Nor | Not | Lt | Gt | Lte | Gte | Eq | Ne | In | NotIn | Exists | Regex | Contains | FilterExpr | dict[str, Any]' = And(())
 ) → None
 ```
 
 **Args:**
 
  - `event_type` (Literal[ADD_ARTIFACT_ALIAS]): 
  - `scope` (Union[_ArtifactSequenceScope, _ArtifactPortfolioScope, ProjectScope]): The scope of the event.
- - `filter` (Union[And, Or, Nor, Not, Lt, Gt, Lte, Gte, Eq, Ne, In, NotIn, Exists, Regex, Contains, Dict[str, Any], FilterExpr]): Additional conditions(s), if any, that are required for this event to trigger.
+ - `filter` (Union[And, Or, Nor, Not, Lt, Gt, Lte, Gte, Eq, Ne, In, NotIn, Exists, Regex, Contains, FilterExpr, Dict[str, Any]]): Additional conditions(s), if any, that are required for this event to trigger.
 
 **Returns:**
  An `OnAddArtifactAlias` object.

models/ref/python/automations/oncreateartifact.mdx

@@ -12,22 +12,36 @@ import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx';
 ## <kbd>class</kbd> `OnCreateArtifact`
 A new artifact is created.
 
+Examples:
+    Define an event that triggers when a new artifact is created in the
+    collection "my-collection":
+
+    ```python
+    from wandb import Api
+    from wandb.automations import OnCreateArtifact
+
+    api = Api()
+    collection = api.artifact_collection(name="my-collection", type_name="model")
+
+    event = OnCreateArtifact(scope=collection)
+    ```
+
 
 ### <kbd>method</kbd> `OnCreateArtifact.__init__`
 
 ```python
 __init__(
     event_type: 'Literal[CREATE_ARTIFACT]' = CREATE_ARTIFACT,
     scope: '_ArtifactSequenceScope | _ArtifactPortfolioScope',
-    filter: 'And | Or | Nor | Not | Lt | Gt | Lte | Gte | Eq | Ne | In | NotIn | Exists | Regex | Contains | dict[str, Any] | FilterExpr' = And([])
+    filter: 'And | Or | Nor | Not | Lt | Gt | Lte | Gte | Eq | Ne | In | NotIn | Exists | Regex | Contains | FilterExpr | dict[str, Any]' = And(())
 ) → None
 ```
 
 **Args:**
 
  - `event_type` (Literal[CREATE_ARTIFACT]): 
  - `scope` (Union[_ArtifactSequenceScope, _ArtifactPortfolioScope]): The scope of the event: must be an artifact collection.
- - `filter` (Union[And, Or, Nor, Not, Lt, Gt, Lte, Gte, Eq, Ne, In, NotIn, Exists, Regex, Contains, Dict[str, Any], FilterExpr]): Additional conditions(s), if any, that are required for this event to trigger.
+ - `filter` (Union[And, Or, Nor, Not, Lt, Gt, Lte, Gte, Eq, Ne, In, NotIn, Exists, Regex, Contains, FilterExpr, Dict[str, Any]]): Additional conditions(s), if any, that are required for this event to trigger.
 
 **Returns:**
  An `OnCreateArtifact` object.

models/ref/python/automations/onlinkartifact.mdx

@@ -12,22 +12,39 @@ import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx';
 ## <kbd>class</kbd> `OnLinkArtifact`
 A new artifact is linked to a collection.
 
+Examples:
+    Define an event that triggers when an artifact is linked to the
+    collection "my-collection" with the alias "prod":
+
+    ```python
+    from wandb import Api
+    from wandb.automations import OnLinkArtifact, ArtifactEvent
+
+    api = Api()
+    collection = api.artifact_collection(name="my-collection", type_name="model")
+
+    event = OnLinkArtifact(
+        scope=collection,
+        filter=ArtifactEvent.alias.eq("prod"),
+    )
+    ```
+
 
 ### <kbd>method</kbd> `OnLinkArtifact.__init__`
 
 ```python
 __init__(
     event_type: 'Literal[LINK_ARTIFACT]' = LINK_ARTIFACT,
     scope: '_ArtifactSequenceScope | _ArtifactPortfolioScope | ProjectScope',
-    filter: 'And | Or | Nor | Not | Lt | Gt | Lte | Gte | Eq | Ne | In | NotIn | Exists | Regex | Contains | dict[str, Any] | FilterExpr' = And([])
+    filter: 'And | Or | Nor | Not | Lt | Gt | Lte | Gte | Eq | Ne | In | NotIn | Exists | Regex | Contains | FilterExpr | dict[str, Any]' = And(())
 ) → None
 ```
 
 **Args:**
 
  - `event_type` (Literal[LINK_ARTIFACT]): 
  - `scope` (Union[_ArtifactSequenceScope, _ArtifactPortfolioScope, ProjectScope]): The scope of the event.
- - `filter` (Union[And, Or, Nor, Not, Lt, Gt, Lte, Gte, Eq, Ne, In, NotIn, Exists, Regex, Contains, Dict[str, Any], FilterExpr]): Additional conditions(s), if any, that are required for this event to trigger.
+ - `filter` (Union[And, Or, Nor, Not, Lt, Gt, Lte, Gte, Eq, Ne, In, NotIn, Exists, Regex, Contains, FilterExpr, Dict[str, Any]]): Additional conditions(s), if any, that are required for this event to trigger.
 
 **Returns:**
  An `OnLinkArtifact` object.

models/ref/python/automations/onrunmetric.mdx

@@ -12,20 +12,37 @@ import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx';
 ## <kbd>class</kbd> `OnRunMetric`
 A run metric satisfies a user-defined condition.
 
+Examples:
+    Define an event that triggers for any run in project "my-project" when
+    the average of the last 5 values of metric "my-metric" exceeds 123.45:
+
+    ```python
+    from wandb import Api
+    from wandb.automations import OnRunMetric, RunEvent
+
+    api = Api()
+    project = api.project(name="my-project")
+
+    event = OnRunMetric(
+        scope=project,
+        filter=RunEvent.metric("my-metric").avg(5).gt(123.45),
+    )
+    ```
+
 
 ### <kbd>method</kbd> `OnRunMetric.__init__`
 
 ```python
 __init__(
-    event_type: 'Literal[RUN_METRIC_THRESHOLD, RUN_METRIC_CHANGE]',
+    event_type: 'Literal[RUN_METRIC_THRESHOLD, RUN_METRIC_CHANGE, RUN_METRIC_ZSCORE]',
     scope: 'ProjectScope',
     filter: 'RunMetricFilter'
 ) → None
 ```
 
 **Args:**
 
- - `event_type` (Literal[RUN_METRIC_THRESHOLD, RUN_METRIC_CHANGE]): 
+ - `event_type` (Literal[RUN_METRIC_THRESHOLD, RUN_METRIC_CHANGE, RUN_METRIC_ZSCORE]): 
  - `scope` (ProjectScope): The scope of the event: must be a project.
  - `filter` (RunMetricFilter): Run and/or metric condition(s) that must be satisfied for this event to trigger.
 

models/ref/python/automations/onrunstate.mdx

@@ -0,0 +1,50 @@
+---
+title: OnRunState
+namespace: automations_namespace
+python_object_type: class
+---
+import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx';
+
+<GitHubLink url="https://github.com/wandb/wandb/blob/main/wandb/automations/events.py" />
+
+
+
+## <kbd>class</kbd> `OnRunState`
+A run state changes.
+
+Examples:
+    Define an event that triggers for any run in project "my-project" when
+    its state changes to "finished" (i.e. succeeded) or "failed":
+
+    ```python
+    from wandb import Api
+    from wandb.automations import OnRunState
+
+    api = Api()
+    project = api.project(name="my-project")
+
+    event = OnRunState(
+        scope=project,
+        filter=RunEvent.state.in_(["finished", "failed"]),
+    )
+    ```
+
+
+### <kbd>method</kbd> `OnRunState.__init__`
+
+```python
+__init__(
+    event_type: 'Literal[RUN_STATE]' = RUN_STATE,
+    scope: 'ProjectScope',
+    filter: 'RunStateFilter'
+) → None
+```
+
+**Args:**
+
+ - `event_type` (Literal[RUN_STATE]): 
+ - `scope` (ProjectScope): The scope of the event: must be a project.
+ - `filter` (RunStateFilter): Run state condition(s) that must be satisfied for this event to trigger.
+
+**Returns:**
+ An `OnRunState` object.

models/ref/python/automations/runstatefilter.mdx

@@ -0,0 +1,59 @@
+---
+title: RunStateFilter
+namespace: automations_namespace
+python_object_type: class
+---
+import { GitHubLink } from '/snippets/en/_includes/github-source-link.mdx';
+
+<GitHubLink url="https://github.com/wandb/wandb/blob/main/wandb/automations/events.py" />
+
+
+
+## <kbd>class</kbd> `RunStateFilter`
+Usage docs: https://docs.pydantic.dev/2.10/concepts/models/
+
+A base class for creating Pydantic models.
+
+Attributes:
+    __class_vars__: The names of the class variables defined on the model.
+    __private_attributes__: Metadata about the private attributes of the model.
+    __signature__: The synthesized `__init__` [`Signature`][inspect.Signature] of the model.
+
+    __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
+    __pydantic_core_schema__: The core schema of the model.
+    __pydantic_custom_init__: Whether the model has a custom `__init__` function.
+    __pydantic_decorators__: Metadata containing the decorators defined on the model.
+        This replaces `Model.__validators__` and `Model.__root_validators__` from Pydantic V1.
+    __pydantic_generic_metadata__: Metadata for generic models; contains data used for a similar purpose to
+        __args__, __origin__, __parameters__ in typing-module generics. May eventually be replaced by these.
+    __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
+    __pydantic_post_init__: The name of the post-init method for the model, if defined.
+    __pydantic_root_model__: Whether the model is a [`RootModel`][pydantic.root_model.RootModel].
+    __pydantic_serializer__: The `pydantic-core` `SchemaSerializer` used to dump instances of the model.
+    __pydantic_validator__: The `pydantic-core` `SchemaValidator` used to validate instances of the model.
+
+    __pydantic_fields__: A dictionary of field names and their corresponding [`FieldInfo`][pydantic.fields.FieldInfo] objects.
+    __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [`ComputedFieldInfo`][pydantic.fields.ComputedFieldInfo] objects.
+
+    __pydantic_extra__: A dictionary containing extra values, if [`extra`][pydantic.config.ConfigDict.extra]
+        is set to `'allow'`.
+    __pydantic_fields_set__: The names of fields explicitly set during instantiation.
+    __pydantic_private__: Values of private attributes set on the model instance.
+
+
+### <kbd>method</kbd> `RunStateFilter.__init__`
+
+```python
+__init__(
+    run: 'And | Or | Nor | Not | Lt | Gt | Lte | Gte | Eq | Ne | In | NotIn | Exists | Regex | Contains | FilterExpr | dict[str, Any]' = And(()),
+    state: 'StateFilter'
+) → None
+```
+
+**Args:**
+
+ - `run` (Union[And, Or, Nor, Not, Lt, Gt, Lte, Gte, Eq, Ne, In, NotIn, Exists, Regex, Contains, FilterExpr, Dict[str, Any]]): Filters that must match any runs that will trigger this event.
+ - `state` (StateFilter): Run state condition(s) that must be satisfied for this event to trigger.
+
+**Returns:**
+ An `RunStateFilter` object.

models/ref/python/automations/sendwebhook.mdx

@@ -37,7 +37,7 @@ __init__(
 ```python
 from_integration(
     integration: 'WebhookIntegration',
-    payload: 'Optional[SerializedToJson[dict[str, Any]]]' = None
+    payload: 'Optional[JsonEncoded[dict[str, Any]]]' = None
 ) → Self
 ```
 

models/ref/python/experiments/run.mdx

@@ -767,8 +767,8 @@ Declare an artifact as an output of a run.
 log_code(
     root: 'str | None' = '.',
     name: 'str | None' = None,
-    include_fn: 'Callable[[str, str], bool] | Callable[[str], bool]' = <function _is_py_requirements_or_dockerfile at 0x1065727a0>,
-    exclude_fn: 'Callable[[str, str], bool] | Callable[[str], bool]' = <function exclude_wandb_fn at 0x107249360>
+    include_fn: 'Callable[[str, str], bool] | Callable[[str], bool]' = <function _is_py_requirements_or_dockerfile at 0x1071c9090>,
+    exclude_fn: 'Callable[[str, str], bool] | Callable[[str], bool]' = <function exclude_wandb_fn at 0x111258ee0>
 ) → Artifact | None
 ```