examples/egocentric: fail loudly, not with a raw traceback, when hf is missing

examples/README.md

@@ -53,9 +53,11 @@ Code: [`openai_vision/pipeline.py`](./openai_vision/pipeline.py)
 download, declared fault injection, local processing, Airflow scheduling,
 inspection with Foxglove and DuckDB, and SQL curation.
 
-**Prerequisites:** accepted Hugging Face dataset terms, `hf` authentication,
-network access, and about 2.5 GB of disk (a ~1 GB pinned download plus the
-generated corpus). Docker is needed only for the Airflow path.
+**Prerequisites:** accepted Hugging Face dataset terms, the `hf` CLI
+authenticated (`uv tool install -U huggingface_hub`, then
+`hf auth login`), network access, and about 2.5 GB of disk (a ~1 GB pinned
+download plus the generated corpus). Docker is needed only for the Airflow
+path.
 
 ```bash
 uv run python examples/egocentric/prepare.py

examples/egocentric/README.md

@@ -27,8 +27,9 @@ declared data you can edit (see [inject your own faults](#inject-your-own-faults
 
 ## Prerequisites
 
-- A Hugging Face account that has accepted the dataset's access terms, and an
-  authenticated `hf` CLI (`hf auth login`).
+- A Hugging Face account that has accepted the dataset's access terms, and the
+  `hf` CLI, authenticated: `uv tool install -U huggingface_hub` then
+  `hf auth login`.
 - Network access and disk: a ~1 GB download, about 2.5 GB total once the
   sources are extracted and the 96 episodes (~640 MB) are written.
 - Docker with Compose v2 (only for the [Airflow path](#run-it-under-airflow)).

examples/egocentric/prepare.py

@@ -307,6 +307,12 @@ def _ensure_source_archive(manifest: CorpusManifest, data_root: Path) -> Path:
     download_root = data_root / "huggingface"
     archive_path = download_root / manifest.archive.path
     if not archive_path.is_file():
+        if shutil.which("hf") is None:
+            raise RuntimeError(
+                "the `hf` CLI is required to download this dataset but is not on PATH. "
+                "Install it with `uv tool install -U huggingface_hub`, then "
+                "`hf auth login`."
+            )
         command = [
             "hf",
             "download",