diffusers-workflow 0.4.0__py3-none-any.whl

dw/docs/WORKSPACES.md

@@ -0,0 +1,316 @@
+# Workspaces
+
+A workspace is the directory your own content lives in: the workflows you
+write, the prompt library they reference, the assets they read, and the files
+they generate.
+
+```
+<workspace>/
+  workflows/    your workflows
+  prompts/      the stored prompt library ('prompt:' references)
+  assets/       input media
+  outputs/      generated files
+```
+
+This exists so that day-to-day work does not have to live inside a checkout of
+this repository. The examples under the repo's `workflows/` are still examples
+— a corpus to read, copy and run — but they are not where your own workflows
+belong, and generated media does not belong in a source tree at all.
+
+## Which directory is used
+
+First match wins:
+
+1. `--workspace <dir>` on `dw.run`, `dw.serve` (`config set workspace=` in the REPL)
+2. the `DW_WORKSPACE` environment variable
+3. `"workspace"` in `~/.diffusers_helper/settings.json`
+4. the working directory, when it holds any of `workflows/`, `prompts/` or `outputs/`
+5. `~/diffusers-workspace`
+
+Rule 4 is why nothing changes when you work from a checkout: the repository
+root holds all three, so it resolves to itself and every default lands exactly
+where it always has. Only a working directory with none of those folders falls
+through to the home workspace.
+
+Nothing is created just by resolving. A command that is about to write creates
+what it needs — `dw.run` creates its output directory, `dw.serve` creates the
+workspace's `workflows/` so the UI has somewhere to save.
+
+## Overriding one folder
+
+The existing per-directory flags still work and each overrides exactly one
+folder of the workspace:
+
+```bash
+python -m dw.run workflows/templates/text-to-image.json -o /mnt/big-disk/renders
+python -m dw.serve --workspace ~/studio --output-dir /mnt/big-disk/renders
+python -m dw.run some.json --prompt-dir ~/shared-prompts
+```
+
+`--output-dir` is the one people reach for most: video work fills disks, and
+the outputs folder is the one worth putting on another volume.
+
+## Working in a workspace
+
+```bash
+mkdir -p ~/studio/{workflows,prompts,assets,outputs}
+export DW_WORKSPACE=~/studio
+
+# or, standing, in ~/.diffusers_helper/settings.json
+#   { "workspace": "/home/you/studio" }
+
+python -m dw.serve                       # serves ~/studio
+python -m dw.run ~/studio/workflows/x.json
+```
+
+An example from a checkout still runs by path, and writes into the workspace's
+outputs:
+
+```bash
+DW_WORKSPACE=~/studio python -m dw.run ~/src/diffusers-workflow/workflows/templates/text-to-image.json
+```
+
+The server reports what it resolved at `GET /api/server`, under
+`directories.workspace` alongside the three folder paths.
+
+## The prompt library
+
+`prompt:` references resolve to the workspace's `prompts/` when a workspace was
+named explicitly (rules 1–3 above, or `DW_PROMPT_DIR`, which still wins over
+everything). A workspace that was merely inferred from the working directory
+does not preempt the older discovery — `./prompts`, then the nearest `prompts/`
+above the workflow file — so a repository workflow keeps reaching the library
+it lives beside. When the workspace is explicit, its `prompts/` becomes the library
+even if it does not exist yet, so a checkout's `./prompts` is no longer found once
+a standing workspace setting (like `DW_WORKSPACE` or `"workspace"` in settings.json)
+is in place; `--prompt-dir` and `DW_PROMPT_DIR` still override it. This follows
+the "explicit wins" rule. See [Prompt References](WORKFLOW_GUIDE.md#prompt-references).
+
+## Assets
+
+`assets/` is the input-media library. A workflow argument written as
+`asset:name.ext` (or `asset:folder/name.ext`) resolves to that file's path,
+rooted at the library rather than at the workflow file — so a workflow and the
+media it reads no longer have to sit in the same folder. `--asset-dir` and
+`DW_ASSET_DIR` override the folder, and browser uploads land in
+`assets/uploads/`, coming back as `asset:uploads/<name>` (and served for
+preview under `/inputs/`, since the SPA's own bundles own `/assets/`).
+
+A generated file becomes an input the same way: **Keep as asset** in the
+gallery (`POST /api/assets/keep`, `keep_output` over MCP) links or copies it
+out of `outputs/` into `assets/` under a name you choose, so a later workflow
+carries `asset:<name>` rather than a run id that pruning would break. The copy
+stays inside the workspace — a hard link where the filesystem allows one, so
+keeping one frame of a large render costs no second copy of it. See
+[Asset References](WORKFLOW_GUIDE.md#asset-references).
+
+## Where workflows are read from, and written to
+
+The server reads workflows from a search path and writes them to exactly one
+place — the front:
+
+```
+<workspace>/workflows/    yours, writable — every save lands here
+<--examples-dir>          read-only, repeatable
+```
+
+A name found in an earlier root shadows the same name in a later one, so a
+workspace copy of an example is the one that runs. Reads — listing, opening,
+downloading, validating, running — span the whole path. Saves and deletes do
+not: `PUT` always writes into the writable root, and deleting something from a
+read-only root is refused with a 403 that says where it came from.
+
+That makes "open an example, change it, save" do the obvious thing: the copy
+lands in your library and shadows the example from then on, and the example
+itself is never touched. It is also what stops an agent's saves landing in a
+checkout — point `--workflow-dir` (or `--workspace`) at your own directory and
+the repository's workflows at `--examples-dir`:
+
+```bash
+python -m dw.serve --workspace ~/studio --examples-dir ~/src/diffusers-workflow/workflows
+```
+
+`GET /api/workflows` reports the path as `sources` and tags every entry with
+its `origin` and `writable`, which is how the UI knows to hide delete and how
+an MCP client can tell what it may change.
+
+### The prompts and assets an examples tree brings with it
+
+An example workflow references the prompts and media that live beside its
+tree, not the ones in your workspace, so each `--examples-dir` puts those on
+the back of the two libraries as well: the `prompts/` and `assets/` folders
+beside the directory (or inside it, if that is where they are). Both libraries
+work exactly like the workflow path — your workspace's own is searched first
+and a name there shadows the example's, reads span everything, and writes only
+ever reach your own:
+
+```
+<workspace>/prompts/      yours, writable — every save lands here
+<--examples-dir>/../prompts   read-only
+
+<workspace>/assets/       yours, writable — uploads and "keep as asset" land here
+<--examples-dir>/../assets    read-only
+```
+
+So the command above makes `workflows/models/flux-dev.json`'s
+`"prompt:flux/biomechanical_daffodil"` resolve out of the checkout, without
+copying the prompt library into the workspace. `GET /api/prompts` and
+`GET /api/assets` report the roots as `prompt_dirs` / `asset_dirs` and tag
+each entry with its `origin`; deleting a prompt that came from a read-only
+library is refused with a 403, and saving one writes a copy into your
+workspace the way saving an example workflow does.
+
+The packaged workflows in `dw/workflows/` are deliberately *not* on the path.
+They are the pieces a `builtin:` sub-workflow step names, resolved by the
+engine where that step is read — not workflows to browse or run on their own.
+
+## Runs
+
+Each execution writes its own directory under the output folder, named by the
+workflow and the run:
+
+```
+outputs/
+  ltx2/Gyre/
+    20260905-181530-a1b2c3d4/
+      Gyre-still.0-0.0.png
+      Gyre-video.1-0.0.mp4
+      manifest.json
+      workflow.json
+```
+
+The folder is the workflow's identity — its path under a `workflows/` tree
+when it has one, its file name otherwise, its `id` for an inline definition.
+The run id is a timestamp plus a short digest of what actually ran, so two
+runs of the same workflow sort by time and a rerun of an edited workflow is
+visibly different; a second run of the same spec in the same second takes a
+counter rather than sharing a directory.
+
+`workflow.json` is the realized workflow — the definition with this run's
+arguments, seed and stored prompts pinned into it, so the directory reproduces
+itself. `manifest.json` points at it and lists which prompts were inlined.
+
+`manifest.json` records the run beside what it made — status, seed, arguments,
+device, dw version, and each step's files, named relative to the directory so
+it keeps describing itself if you move or copy it. It is written even when a
+run fails part way, since the files it did write are on disk either way. A
+sub-workflow is part of its parent's run: it writes into the same directory and
+rolls up into the same manifest.
+
+An unchanged rerun still reuses the step cache: it writes no new files and its
+manifest reports the earlier run's, marked `"reused": true`. The cache is
+validated against the output *root* a run writes into, which is the pinned
+workspace's own `outputs/` - so it is per workspace, not per workflow alone.
+A run in one workspace does not make `validate_workflow`'s
+`plan.cached_steps` come back nonzero for a matching run sitting in another
+workspace, and deleting a workspace drops its cache entries along with its
+`outputs/` directory. The cache itself is also per *process*: entries are
+held in memory by the running server, not read back from `outputs/`, so a
+`dw.serve` restart empties it even though every run directory is still on
+disk - a `plan.cached_steps` of 0 right after a restart is expected, not a
+lost run.
+
+A later workflow names what an earlier run made with an `output:` reference —
+`output:ltx2/Gyre/latest/Gyre-still.0-0.0.png` — so a multi-stage pipeline no
+longer needs files copied back by hand. See
+[Output References](WORKFLOW_GUIDE.md#output-references).
+
+To keep the previous layout — everything at the output root, with only a
+`workflows/`-mirroring subfolder — use `--output-layout flat`, `DW_OUTPUT_LAYOUT=flat`,
+or `"output_layout": "flat"` in settings. Scripts that glob the output directory
+are the reason to.
+
+## Several workspaces on one server
+
+Everything above describes one workspace, which is all `dw.run` and the REPL
+ever see. `dw.serve` goes one step further: the workspace root can hold
+several, and a client picks which one it is working in.
+
+```
+<workspace root>/
+  workflows/  assets/  outputs/    <- the 'default' workspace
+  prompts/                         <- shared by all of them
+  common/assets/                   <- shared by all of them
+  studio/
+    workflows/  assets/  outputs/  <- the 'studio' workspace
+  scratch/
+    workflows/  assets/  outputs/  <- the 'scratch' workspace
+```
+
+The root's own three folders are the workspace named `default`, so a server
+that has never heard of named workspaces behaves exactly as it did. A named
+workspace is a sibling directory holding the same three folders — and *not* a
+`prompts/`, because there is one prompt library: `prompt:` is shared by
+reference, and a prompt duplicated per workspace would resolve to different
+text depending on where a workflow happened to be saved. `workflows`,
+`prompts`, `assets` and `outputs` are reserved names for that reason.
+
+Two more names are reserved beside `workflows`, `prompts`, `assets` and
+`outputs`: `exports` and `common`. `POST /api/jobs/{id}/export` gathers one
+finished job into `<root>/exports/<job id>/`, and that folder is never mistaken
+for a workspace.
+
+**The shared asset library.** `common/assets/` is the one place an asset can
+live that belongs to no single workspace. Assets are otherwise per workspace,
+which is right for the inputs of one piece of work and wrong for a recurring
+cast: a character's portrait and voice clip uploaded while making episode one
+were invisible from the workspace episode four was made in, and the only way
+through was to copy the files in. It sits on every workspace's asset search
+path behind that workspace's own library, so:
+
+- `asset:cast/priya.png` resolves in the workspace first, then in the shared
+  library, then in any read-only examples library — a workspace's own name
+  still shadows a shared one
+- `GET /api/assets` spans all of them and tags each entry's `origin`:
+  `workspace`, `common`, or `examples`
+- writes still land in the workspace unless they say otherwise:
+  `POST /api/uploads?shared=true`, `POST /api/assets/keep` with
+  `"shared": true`, and over MCP `upload_asset(..., shared=True)` /
+  `keep_output(..., shared=True)`
+
+It holds assets only. A prompt is already shared, and workflows and outputs
+belong to the work that made them.
+
+This is what lets two agents share one GPU without sharing a namespace: each
+takes a workspace, and neither can save over the other's workflows or delete
+the other's renders.
+
+**How a client picks one.** Every scoped route takes an optional
+`?workspace=<name>`; omitting it means `default`, which is why every
+pre-workspace call still means what it meant.
+
+| Client | How |
+| --- | --- |
+| Web UI | The sidebar lists every workspace; the selected one is named in the hash (`#/ws/<name>/...`), so a link and a reload both land where they say. The choice is remembered in `localStorage` as a fallback for a route that names none (Shared, Server), and Server → Status adds a filter over the all-workspaces queue — job history spans every workspace there and says which one each job ran in |
+| MCP | `list_workspaces`, then `use_workspace(name)`. It is a session default rather than an argument on each call, so switching is one visible step in the transcript instead of a flag that can be forgotten on the call where it mattered |
+| HTTP | `?workspace=` on the route, or `"workspace"` in a `POST /api/jobs` body |
+| Web UI (create/delete) | The sidebar's `+ new` creates one; a workspace's own Overview page deletes it (disabled for `default`) |
+
+A job carries its own workflow, asset and output directories, so it stays in
+the workspace it was submitted from however many others the server serves
+while it runs — including through a rerun, and when its files are served back
+from history.
+
+**Creating and deleting.** `POST /api/workspaces` (`create_workspace` over
+MCP) makes one; creating does not switch to it. Deleting removes everything in
+it, so it refuses until acknowledged and answers first with what it would
+remove — file counts and bytes per folder. The default workspace cannot be
+deleted (it holds the shared prompt library, and there has to be somewhere to
+work), nor can one with jobs still queued.
+
+A workspace is a **namespace, not a security boundary**. The API token is
+all-or-nothing: anything that can reach the server can name any workspace on
+it. Use them to keep work apart, not to keep it private.
+
+## Where this is going
+
+The resolver, the workflow search path with writes confined to the writable
+root, run directories with an on-disk manifest, `asset:` and `output:`
+references, and server-side named workspaces are all implemented. A further
+stage was designed but deliberately not built: a client-side workspace (a
+laptop directory, under version control) that mirrors into a read-only
+server workspace, so an agent could author offline and only push at submit
+time. It stayed on the drawing board because source control of creative work
+is not this project's job — that is already handled on the client, by the
+user, with the tools they already use — which is what makes a mirroring
+layer unnecessary rather than merely speculative.

dw/download_watch.py

@@ -0,0 +1,335 @@
+"""Makes a `from_pretrained` download visible on the run's event stream (#343).
+
+`from_pretrained` downloads with no hook of its own, and a pull that runs
+long looks identical to a hang: the phase-stall watchdog (dw/events.py) has
+nothing but silence to report. This does not intercept or pre-fetch
+anything - `from_pretrained` fetches exactly what it would have - it only
+listens to the byte counts the download already reports while a `loading`
+phase is in progress.
+
+Two signals, and the larger is reported:
+
+- The hub's own xet progress report (`XetDownloadProgressReporter`), which
+  carries the bytes *received from the network* as well as the bytes written
+  to disk. The network count is the one that matters: hf_xet buffers and
+  writes a file in order, and on lem held a 2.8 GB file at 67 MB on disk
+  while 700 MB had arrived, then wrote the rest at the very end. No location
+  on disk tells that apart from a hang; the transfer count does. Hooked
+  whether or not the hub's progress bars are displayed.
+- The repo's cache directory, for a plain HTTP download (no hf_xet), which
+  writes its `.incomplete` file as bytes arrive. A published blob is a
+  symlink into the hub's shared store (`<cache>/blobs/xx/<sha>`), so the
+  size is taken through the link - measured beside it, the total fell by the
+  size of every file that finished (#343, a negative rate).
+
+Both only ever count up, so `downloaded_bytes` never goes backwards.
+
+A `download_progress` event fires about every EMIT_INTERVAL_SECONDS while a
+download is underway. One reporting growth is progress. One reporting none
+is not: it still fires, so `phase_detail` says `no bytes for 45s` instead of
+repeating the last healthy rate, but the stall watchdog counts it as silence
+and says `phase_stall` once bytes have been flat for its threshold - a
+download and a hang no longer read the same.
+
+A cancel during a download aborts it: the xet session is aborted (the hub's
+own KeyboardInterrupt path, `abort_xet_session`) and a plain HTTP download is
+stopped at its next chunk, and the load surfaces as `WorkflowCancelled`
+rather than running to the end of a multi-gigabyte file first.
+"""
+
+import logging
+import os
+import threading
+import time
+
+from huggingface_hub.constants import HF_HUB_CACHE
+from huggingface_hub.file_download import repo_folder_name
+from huggingface_hub.utils import HFValidationError, validate_repo_id
+
+from .events import WorkflowCancelled, get_context
+
+logger = logging.getLogger("dw")
+
+# How often the watcher re-measures, and the gap between emitted events -
+# well under the phase-stall threshold (30s) so a real, ongoing download
+# never trips it, but not so tight that a run emits an event per chunk.
+CHECK_INTERVAL_SECONDS = 1.0
+EMIT_INTERVAL_SECONDS = 5.0
+
+
+def is_watchable_repo_id(name):
+    """Whether name is shaped like a Hugging Face repo id - a local path or
+    checkout is not something a cache directory watch means anything for."""
+    try:
+        validate_repo_id(name)
+        return True
+    except HFValidationError:
+        return False
+
+
+def _blob_dir_size(blob_dir):
+    """Bytes under a repo's blobs/ directory, counting a published blob
+    through its symlink into the shared store."""
+    total = 0
+    try:
+        with os.scandir(blob_dir) as entries:
+            for entry in entries:
+                try:
+                    if entry.is_file():
+                        total += entry.stat().st_size
+                except OSError:
+                    # A blob renamed or published mid-scan is not a fault
+                    continue
+    except FileNotFoundError:
+        return 0
+    return total
+
+
+# The watches currently open and the hub hooks they share. One job runs at a
+# time in the worker, but a hook is process-wide, so it is installed on the
+# first open watch and removed with the last.
+_lock = threading.Lock()
+_active = []
+_originals = {}
+
+
+def _note_hub_bytes(transferred, written):
+    with _lock:
+        watches = list(_active)
+    for watch_ in watches:
+        watch_._add_hub_bytes(transferred, written)
+
+
+def _any_cancelled():
+    with _lock:
+        return any(w._context.cancelled for w in _active)
+
+
+def _install_hooks():
+    try:
+        from huggingface_hub.utils import _xet_progress_reporting as xet_reporting
+
+        reporter = xet_reporting.XetDownloadProgressReporter
+        original = reporter.update_progress
+        last_seen = {}
+
+        def update_progress(self, group_report, *args, **kwargs):
+            # Runs on hf_xet's callback thread, which prints and swallows
+            # anything raised here - so nothing may be raised, and the
+            # hub's own bar update is guarded along with the counting
+            try:
+                key = id(self)
+                previous = last_seen.get(key, (0, 0))
+                transferred = group_report.total_transfer_bytes_completed
+                written = group_report.total_bytes_completed
+                last_seen[key] = (
+                    max(previous[0], transferred),
+                    max(previous[1], written),
+                )
+                _note_hub_bytes(
+                    max(0, transferred - previous[0]), max(0, written - previous[1])
+                )
+            except Exception as e:
+                logger.debug(f"Download watch could not read xet progress: {e}")
+            try:
+                return original(self, group_report, *args, **kwargs)
+            except Exception as e:
+                logger.debug(f"xet progress update raised: {e}")
+
+        _patch(reporter, "update_progress", update_progress)
+    except (ImportError, AttributeError) as e:
+        logger.debug(f"No xet progress reporter to hook: {e}")
+
+    try:
+        from importlib import import_module
+
+        hub_tqdm = import_module("huggingface_hub.utils.tqdm").tqdm
+        original_update = hub_tqdm.update
+
+        def update(self, n=1):
+            # A plain HTTP download calls this once per chunk on the thread
+            # running from_pretrained - the one place that can stop it
+            if _any_cancelled():
+                raise WorkflowCancelled("Workflow run was cancelled")
+            return original_update(self, n)
+
+        _patch(hub_tqdm, "update", update)
+    except (ImportError, AttributeError) as e:
+        logger.debug(f"No hub progress bar to hook: {e}")
+
+
+def _patch(owner, name, replacement):
+    # Remembers whether the class defined the method itself or inherited it,
+    # so removing the hook restores exactly what was there
+    _originals[(owner, name)] = vars(owner).get(name)
+    setattr(owner, name, replacement)
+
+
+def _remove_hooks():
+    for (owner, name), original in _originals.items():
+        if original is None:
+            delattr(owner, name)
+        else:
+            setattr(owner, name, original)
+    _originals.clear()
+
+
+def _abort_xet_downloads():
+    try:
+        from huggingface_hub.utils._xet import abort_xet_session
+
+        abort_xet_session()
+    except Exception as e:
+        logger.debug(f"Could not abort the xet session: {e}")
+
+
+class DownloadWatch:
+    """Context manager that reports one repo's download on the active run
+    context for as long as it is open.
+
+    Not a download itself - `from_pretrained` runs unmodified inside the
+    `with` block. A load that downloads nothing (every file cached) emits
+    nothing, same as no watch at all.
+    """
+
+    def __init__(self, repo_id, context, cache_dir=None, repo_type="model"):
+        self._repo_id = repo_id
+        self._context = context
+        resolved_cache_dir = cache_dir or HF_HUB_CACHE
+        self._blob_dir = os.path.join(
+            resolved_cache_dir,
+            repo_folder_name(repo_id=repo_id, repo_type=repo_type),
+            "blobs",
+        )
+        self._stop = threading.Event()
+        self._thread = None
+        self._counts_lock = threading.Lock()
+        self._transferred = 0
+        self._written = 0
+        self._aborted = False
+
+    def _add_hub_bytes(self, transferred, written):
+        with self._counts_lock:
+            self._transferred += transferred
+            self._written += written
+
+    def _hub_bytes(self):
+        with self._counts_lock:
+            return max(self._transferred, self._written)
+
+    def __enter__(self):
+        with _lock:
+            if not _active:
+                _install_hooks()
+            _active.append(self)
+        self._thread = threading.Thread(
+            target=self._run, daemon=True, name="dw-download-watch"
+        )
+        self._thread.start()
+        return self
+
+    def __exit__(self, exc_type, exc, traceback):
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=CHECK_INTERVAL_SECONDS * 2)
+        with _lock:
+            if self in _active:
+                _active.remove(self)
+            if not _active:
+                _remove_hooks()
+        if (
+            exc is not None
+            and not isinstance(exc, WorkflowCancelled)
+            and self._context.cancelled
+        ):
+            # The abort surfaces as whatever the download library raises
+            # (hf_xet: "RuntimeError: Operation cancelled") - it is the
+            # cancel, not a load failure, and must read as one
+            raise WorkflowCancelled("Workflow run was cancelled") from exc
+        return False
+
+    def _run(self):
+        baseline = _blob_dir_size(self._blob_dir)
+        disk_high_water = 0
+        downloaded = 0
+        emitted = 0
+        last_emit_at = time.monotonic()
+        last_change_at = last_emit_at
+        while not self._stop.wait(CHECK_INTERVAL_SECONDS):
+            try:
+                if self._context.cancelled and not self._aborted:
+                    self._aborted = True
+                    _abort_xet_downloads()
+                disk_high_water = max(
+                    disk_high_water, _blob_dir_size(self._blob_dir) - baseline
+                )
+                now = time.monotonic()
+                current = max(downloaded, disk_high_water, self._hub_bytes())
+                if current > downloaded:
+                    downloaded = current
+                    last_change_at = now
+                elapsed = now - last_emit_at
+                if downloaded == 0 or elapsed < EMIT_INTERVAL_SECONDS:
+                    continue
+                growth = downloaded - emitted
+                emitted = downloaded
+                last_emit_at = now
+                # Flat bytes still report, so phase_detail stops showing the
+                # last healthy rate - but do not count as progress, so the
+                # stall watchdog sees the silence a hang is
+                self._context.emit(
+                    "download_progress",
+                    counts_as_progress=growth > 0,
+                    repo_id=self._repo_id,
+                    downloaded_bytes=downloaded,
+                    bytes_per_second=growth / elapsed,
+                    seconds_since_bytes_changed=round(now - last_change_at, 1),
+                )
+            except Exception as e:
+                # A watch that breaks must not take the download down with it
+                logger.debug(f"Download watch for '{self._repo_id}' failed: {e}")
+                return
+
+
+def _format_bytes(n):
+    # Decimal units, as the labels say and as the hub itself reports sizes -
+    # 1,879,623,333 bytes is 1.9 GB (it is 1.75 GiB)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if n < 1000 or unit == "TB":
+            return f"{n:.1f} {unit}" if unit != "B" else f"{n:.0f} {unit}"
+        n /= 1000
+
+
+def format_progress(
+    repo_id, downloaded_bytes, bytes_per_second, seconds_since_bytes_changed=None
+):
+    """The `phase_detail` text a job's progress reports while this repo is
+    downloading - `downloading <repo>: 12.3 GB, 38.0 MB/s` per #343, or
+    `downloading <repo>: 12.3 GB, no bytes for 45s` once bytes stop."""
+    text = f"downloading {repo_id}: {_format_bytes(downloaded_bytes or 0)}"
+    if bytes_per_second:
+        text += f", {_format_bytes(bytes_per_second)}/s"
+    elif seconds_since_bytes_changed:
+        text += f", no bytes for {seconds_since_bytes_changed:.0f}s"
+    return text
+
+
+def watch(repo_id, cache_dir=None, repo_type="model"):
+    """A DownloadWatch on the active run context, or a no-op context manager
+    when repo_id is not shaped like a hub repo (a local path, for instance)."""
+    if not is_watchable_repo_id(repo_id):
+        return _NULL_WATCH
+    return DownloadWatch(
+        repo_id, get_context(), cache_dir=cache_dir, repo_type=repo_type
+    )
+
+
+class _NullWatch:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_info):
+        return False
+
+
+_NULL_WATCH = _NullWatch()