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

[chintondutta]

The gap

Following the egocentric example's README exactly from a clean environment:

uv sync --locked --all-extras
uv run python examples/egocentric/prepare.py

crashes with an uncaught FileNotFoundError: [Errno 2] No such file or directory: 'hf'.

prepare.py shells out to the hf CLI to download the pinned corpus, but that CLI is never declared as something to install: it's absent from pyproject.toml (main deps, extras, and the dev group), and neither examples/README.md nor examples/egocentric/README.md says how to get it -- both just say "authenticated hf CLI" as if it already exists on your machine.

Fix

• prepare.py: check shutil.which("hf") before shelling out and raise the same style of friendly RuntimeError the code already uses for a failed download, instead of letting a bare FileNotFoundError traceback surface.
• Both READMEs: tell you how to actually get the CLI (uv tool install -U huggingface_hub, then hf auth login).

Testing

Reproduced the original crash from a clean environment (no hf on PATH), confirmed the fix now raises a clear, actionable error instead.

Then installed and authenticated hf and ran the documented workflow against the real pinned corpus end to end:

uv run python examples/egocentric/prepare.py
uv run python examples/egocentric/pipeline.py data/egocentric/landing/*.mcap
uv run hflow curate --catalog data/egocentric/catalog --sql-file examples/egocentric/curate.sql --output data/egocentric/manifest.parquet

• Archive downloads and hashes verify against the pinned manifest.
• All 96 episodes generate, 6 with the manifest's declared faults (blackout at 14/29/44, freeze at 59/74/89).
• Pipeline: 90 ok, 6 quarantined; the three blackout episodes show black_frame_pct ≈ 15, and all six show freeze_total_s ≈ 3 -- exactly what the README describes.
• Curate: 90-row manifest, camera_health coverage 96/96 -- matches the README.

uv run ruff check --fix
uv run ruff format
uv run ty check

All pass.

[kstonekuan]

Thank you @chintondutta. This is exactly the work I was hoping you would go do: you ran the example end to end against the real pinned corpus, hit a rough edge a new user hits on their very first command, and fixed both halves of it (the crash and the missing instruction that caused it).

What I validated locally:

• Confirmed the root cause: huggingface appears nowhere in pyproject.toml, so a clean uv sync --locked --all-extras genuinely leaves you without the hf CLI that prepare.py shells out to. The dependency was real but undeclared and undocumented, which is the actual bug.
• Exercised your new guard directly, with hf forced off PATH, and got the intended message instead of a traceback: "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."
• Full quality gate is clean (ruff check, ruff format --check, ty check), 307 tests pass, and lychee reports 230 links with 0 errors.
• Checked that shutil was already imported in prepare.py, so the guard adds no new import.

Two things I appreciate. First, raising the same friendly RuntimeError shape the file already uses for a failed download, rather than inventing a new error style for this one case. Second, fixing the READMEs in the same pass: "an authenticated hf CLI" reads as a precondition you already satisfy, and uv tool install -U huggingface_hub is the missing sentence that makes it actionable.

Your end-to-end numbers are a useful record too. 96 episodes, 90 ok and 6 quarantined, black_frame_pct around 15 on the three blackout episodes, freeze_total_s around 3 on all six, and a 90-row manifest at 96/96 camera_health coverage. That matches what the README claims, which means the example's documented output is still honest.

Merging now, and thank you for keeping to one pull request at a time. Please keep going in this direction: corpus-level rough edges like this are worth more to the project than any of the starter issues.