docs: add colab notebook for automations

colabs/automations/automations-tutorial.ipynb

@@ -0,0 +1,229 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<a href=\"https://colab.research.google.com/github/wandb/examples/blob/master/colabs/automations/automations-tutorial.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>\n",
+    "<!--- @wandbcode{automations-tutorial} -->"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# W&B Automations tutorial (API)\n",
+    "\n",
+    "This notebook walks through **W&B Automations** with the Python API. Run the notebook to configure your team, list automations, and create a project automation that will send a message to a Slack channel when a run in the project fails. Simulate a failure to test the automation, optionally update the automation for further testing, and delete it when testing is complete.\n",
+    "\n",
+    "For full documentation, including instructions for managing automations in the W&B App, see the [project automation tutorial](https://docs.wandb.ai/models/automations/project-automation-tutorial) and [registry automation tutorial](https://docs.wandb.ai/models/automations/registry-automation-tutorial)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Prerequisites\n",
+    "\n",
+    "- Install the W&B Python SDK and log in (next cells).\n",
+    "- A W&B **team** (entity) with a **project**.\n",
+    "- **Team Settings**: a [Slack integration](https://docs.wandb.ai/models/automations/create-automations/slack) and a [webhook](https://docs.wandb.ai/models/automations/create-automations/webhook).\n",
+    "- Edit **Configuration** with your `ENTITY` and `PROJECT` details."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install wandb -qU"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import wandb\n",
+    "\n",
+    "# Log in to your W&B account (same pattern as the intro Colab notebooks)\n",
+    "wandb.login()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Configuration\n",
+    "\n",
+    "Edit these values to match your team, project, and registry collection."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Team or user entity (visible in your W&B URL)\n",
+    "ENTITY = \"my-team\"\n",
+    "\n",
+    "# Project used for the run-failure example and for logging a test artifact\n",
+    "PROJECT = \"my-project\"\n",
+    "\n",
+    "api = wandb.Api()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## List automations\n",
+    "\n",
+    "Lists automations for your entity. The list may be empty if you have not created any yet."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for automation in api.automations(entity=ENTITY):\n",
+    "    print(automation.name, \"|\", getattr(automation, \"scope\", \"\"), \"|\", getattr(automation, \"enabled\", True))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Create: Project automation (run failure to Slack)\n",
+    "\n",
+    "Aligns with the [project automation tutorial](https://docs.wandb.ai/models/automations/project-automation-tutorial) in the W&B documentation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from wandb.automations import OnRunState, RunEvent, SendNotification\n",
+    "\n",
+    "project = api.project(PROJECT, entity=ENTITY)\n",
+    "slack_integration = next(api.slack_integrations(entity=ENTITY))\n",
+    "\n",
+    "event = OnRunState(\n",
+    "    scope=project,\n",
+    "    filter=RunEvent.state.in_([\"failed\"]),\n",
+    ")\n",
+    "action = SendNotification.from_integration(slack_integration)\n",
+    "\n",
+    "project_automation = api.create_automation(\n",
+    "    event >> action,\n",
+    "    name=\"run-failure-alert\",\n",
+    "    description=\"Notify the team when a run fails.\",\n",
+    ")\n",
+    "print(\"Created:\", project_automation.name)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Optional: Test the project automation\n",
+    "\n",
+    "Run this cell to log a failed run in the same project you used above. Within a short time you should see a Slack message with the run link and status."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "with wandb.init(project=PROJECT, entity=ENTITY) as run:\n",
+    "    run.log({\"loss\": 1.23})\n",
+    "    run.finish(exit_code=1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Get one automation by name\n",
+    "\n",
+    "Use this after you have created an automation. If the name does not exist or is ambiguous, the API raises `ValueError`. See also [Manage automations with the API](https://docs.wandb.ai/models/automations/api#get-one-automation)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fetched = api.automation(name=\"run-failure-alert\", entity=ENTITY)\n",
+    "print(fetched.name, fetched.description, fetched.enabled)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Update an automation\n",
+    "\n",
+    "Run the **optional** test cells above before this section if you want Slack or webhook delivery while the automations are still enabled.\n",
+    "\n",
+    "This section fetches the project automation by name, then disables it and updates the description."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "to_update = api.automation(name=\"run-failure-alert\", entity=ENTITY)\n",
+    "updated = api.update_automation(\n",
+    "    to_update,\n",
+    "    enabled=False,\n",
+    "    description=\"Temporarily disabled.\",\n",
+    ")\n",
+    "print(\"Updated:\", updated.name, updated.enabled, updated.description)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Delete an automation\n",
+    "\n",
+    "Optionally, run this cell to delete the automation when you are finished testing."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "api.delete_automation(api.automation(name=\"run-failure-alert\", entity=ENTITY))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}