Hebbian-Robotics/hflow

Current behavior The libx264 parameters that produce conforming canonical video are typed out by hand in four places: site variable src/hflow/video.py:199-201 x264_params, inside encode_images_to_h264 (the transform's encoder) src/hflow/importers/video.py:217 inline, in the direct-H.264 import added by #594 examples/egocentric/convert.py:132-135 x264_parameters, added by #592 examples/egocentric/prepare.py:503-506 x264_parameters Every copy is the same string: keyint={N}:min-keyint={N}:scenecut=0:bframes=0:repeat-headers=1:aud=1 Why it matters These are not tuning knobs. Each flag is one of the normative constraints in docs/FORMAT.md: aud=1 is item 2, repeat-headers=1 is item 3, bframes=0 is item 4, and keyint=min-keyint with scenecut=0 is item 5. Four copies of the format contract means that when one constraint changes, the copies that were missed keep producing episodes that hflow doctor rejects, and nothing fails at the point of the edit. The canonical one is a loca

Version or commit d0ea4ac (0.2.13) Environment Ubuntu, Python 3.12, x86_64. Synthetic MCAP only. Minimal reproduction Write one MCAP with two episode/v1 metadata records: the first says task=first, success=false; the second says task=second, success=true. Also write a minimal provenance/v1 so doctor has a stamp to read. Run hflow.doctor.diagnose on that file. Run write_canonical_episode and read Episode.metadata_records["episode/v1"]. Expected behavior A file with two metadata records of the same name is not a clean canonical episode. Doctor reports the duplicate, and the transform does not publish a canonical whose task / success are whichever record happened to be last. MCAP allows repeated names; HFlow's keyed view does not, and that disagreement should be visible. Actual behavior Doctor prints no findings at all. EpisodeReader.metadata() keeps the later record and logs a warning. After the library logging boundary (#590) that warning does not reach an unconfigured host. The trans

Cache-root policy is duplicated in src/hflow/_pinned_asset.py:26 and src/hflow/storage.py:165. Both honor XDG_CACHE_HOME, then hard-code ~/.cache/hflow. macOS is supported, but this bypasses its native cache location and lets the two implementations drift. Adopt platformdirs.user_cache_path("hflow") behind one HFlow helper. Preserve the existing HFLOW_MIRROR_DIR override. Reuse or safely migrate the legacy ~/.cache/hflow contents so upgrades do not redownload large FFmpeg binaries, models, or bucket mirrors. Definition of done: Declare platformdirs as a direct core dependency. Route pinned assets and object-store mirrors through one cache-root helper. Preserve HFLOW_MIRROR_DIR precedence. Cover default Linux/macOS paths, XDG_CACHE_HOME, the mirror override, and legacy-cache reuse with behavior-focused tests. Update cache-path documentation affected by the platform-specific location. Run uv run ruff check --fix, uv run ruff format, uv run ty check, and uv run pytest -q.

The Airflow client builds HTTP requests and translates urllib/network failures by hand in src/hflow/runtime/_client.py:202. Its module docstring cites keeping dependencies light, but httpx2 is already a core dependency. Migrate this transport to synchronous httpx2, keeping the existing public Airflow client API and typed response models. Scope this PR to the Airflow client and its tests; the Hugging Face importer and asset downloads are separate work. Acceptance criteria: Replace urllib request execution with httpx2 and close responses/clients reliably. Keep constructor arguments and existing call sites compatible. Preserve password authentication, one refresh after an expired token, and pre-issued bearer tokens that fail without attempting refresh. Preserve request payloads, URL escaping, caller-supplied run IDs, conflict handling, pagination, and health-body interpretation. Keep current retry policy; transport migration must not introduce retries of POST requests. Preserve configure

examples/egosuite_evaluation/evaluate.py:1654 defines labels, run, and compare with argparse, then converts Namespace attributes into evaluation configuration. Migrate this CLI to typed Typer commands so argument types are checked through to configuration construction. Scope: examples/egosuite_evaluation/evaluate.py, its CLI coverage, and its workspace dependencies. Keep the existing evaluation/configuration functions as the business-logic boundary. Add Typer directly to examples/egosuite_evaluation/pyproject.toml and update the shared uv.lock; this can land independently of the main CLI migration. Acceptance criteria: Replace argparse and Namespace-based CLI adapters with typed Typer command functions for labels, run, and compare. Keep existing invocation syntax, flags, defaults, output locations, and failure exit codes. Preserve camera/response-format choices, environment defaults, numeric bounds, multiple input paths, and mutual exclusion between --limit-per-episode and --samples-p