Cache per-video pose attributes to skip load-time pose scan (KLAUS-506)

[gbeane]

Summary

Caches the per-video pose attributes read at project load (frame count, identity count, static objects, lixit keypoints, cm-per-pixel) so subsequent loads rescan only new/changed pose files instead of opening all of them.

Measured on a 488-video project (external SSD): cold load 3.88s (488 pose scans) → cached load 0.01s (0 scans), with identical identity counts and pose version.

What changed

• New jabs/cache/pose_attribute_cache.json, keyed by video filename and gated by a cheap stat token (size:mtime_ns) of the pose file; schema-versioned.
• New module pose_attribute_cache.py (pose_token / load / save); ProjectPaths.pose_attribute_cache_file (returns None when use_cache=False).
• _run_video_scan split into _scan_jobs + _run_cached_video_scan. The opt-in enable_video_check path bypasses the cache, since video frame counts are not cached.
• Transparent to VideoManager / FeatureManager (same VideoScanResult); no consumer changes.

Behavior

• Missing / corrupt / schema-mismatched cache → full rescan (self-healing; existing projects upgrade lazily on first load, no migration).
• A changed pose file (new stat token) or a pose-version upgrade invalidates that entry; removed videos are pruned.
• clear_cache() removes the file harmlessly; use_cache=False → no persistence.

Tests

13 new tests: module unit tests plus cache-hit (no rescan), token invalidation, new-video-only scan, use_cache=False, and fresh-vs-cached parity. Full suite green.

Jira: KLAUS-506

[Copilot]

Pull request overview

Introduces a persistent, per-video cache of pose-derived metadata to avoid opening and scanning every pose HDF5 file on subsequent project loads, significantly reducing load time for large projects.

Changes:

• Added pose_attribute_cache module to load/save a schema-versioned JSON cache keyed by video filename and pose-file stat token.
• Updated Project._run_video_scan to reuse cached per-video pose attributes and rescan only new/changed pose files (while bypassing cache when enable_video_check=True).
• Added unit + integration-style tests covering cache hits, invalidation, new-video-only scans, and use_cache=False.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
tests/project/test_pose_attribute_cache.py	Adds tests validating cache persistence, cache-hit behavior, and invalidation scenarios.
src/jabs/project/project.py	Implements cached scan path and reconstructs scan results from cached pose attributes.
src/jabs/project/project_paths.py	Adds pose_attribute_cache_file path helper (returns None when caching is disabled).
src/jabs/project/pose_attribute_cache.py	New module handling token generation and resilient cache load/save.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/jabs/project/project.py:318

• future_to_video is created as a mapping to video names, but the video-name values are never used (the loop iterates over the dict keys). This adds unnecessary work and can be misleading; either use a plain list of futures or use the mapping to add context when a future raises.

            future_to_video = {
                process_pool.submit(scan_video_metadata, job): job["video"] for job in jobs
            }
            results: dict[str, VideoScanResult] = {}
            for future in as_completed(future_to_video):

[gbeane]

UnicodeError is a subclass of ValueError, so it will be caught

[gbeane]

Addressed the suppressed low-confidence note about future_to_video in _scan_jobs (in 7d2067b): the future->video mapping is now used to add context on failure. The as_completed loop wraps future.result() in a try/except that logs which video's pose scan failed (logger.error(..., exc_info=True)) before re-raising, so a failing scan is now traceable to a specific video instead of surfacing a bare exception. The success path is unchanged.