feat(gui): drive inference via sleap predict (sleap-nn 0.3.0 unified pipeline)

[talmo]

Draft — the code change is complete and unit-tested, but the inference path needs end-to-end validation with real trained models before merge (checklist below).

Stacked on #2796 (base = talmo/1.7.0-deps-upgrade-tier0; retarget to develop after it merges).

Summary

Switches the GUI's inference subprocess from the legacy sleap track subcommand to the new unified sleap predict pipeline (sleap-nn 0.3.0, #530), in InferenceTask.make_predict_cli_call.

Why this is safe (verified against sleap-nn 0.3.0)

predict's option surface is a strict superset of track's — {track.params} − {predict.params} is empty (68 vs 105 params, confirmed by introspecting the live click commands). Every one of the 26 options the GUI emits — data/model/output/batch_size/peak_threshold/max_instances, the entire tracking arg set (--tracking, --track_matching_method, --tracking_window_size, --candidates_method, --max_tracks, --use_flow, --post_connect_single_breaks, --tracking_target_instance_count, --scoring_reduction, --robust_best_instance, --features, --scoring_method), and --filter_overlapping* — is accepted by predict under identical primary names. Nothing is renamed, dropped, or missing.

Changes (2 lines + 1 defensive flag)

1. "track" → "predict" — the subcommand.
2. Add --no-restore_source_videos. Legacy track saved with restore_original_videos=False; predict defaults restore_source_videos=True, which rewrites the output's video reference to the original source media. For non-embedded projects this is a no-op, but for an embedded .pkg.slp input it would make the post-inference sio.load_slp + Labels.merge create a duplicate video instead of merging. The negative flag preserves exact legacy save semantics.

--gui progress parsing is unchanged — predict --gui emits byte-identical JSON ({n_processed, n_total, rate, eta}) to track --gui, so neither predict_subprocess nor the threaded-worker parser needs edits.

Tests

• tests/gui/learning/test_cli_construction.py updated to assert predict + --no-restore_source_videos.
• Full tests/gui/learning/ suite: 345 passed. ruff clean.

⚠️ Validation required before un-drafting (needs real trained models)

• Embedded .pkg.slp input → run inference, confirm load_slp + merge folds into the existing video (no duplicate). The one genuine behavioral delta; should be neutralized by the flag — confirm.
• Live --gui progress end-to-end — bar advances, "Predicted: n/n FPS ETA" renders (emitter confirmed by code reading only).
• Multi-class / ID models with --tracking. Genuine divergence: legacy track silently skipped tracking for BottomUp/TopDown-MultiClass even with --tracking; predict has no such guard and will run the flow tracker. Confirm whether the GUI exposes tracking for ID configs; decide whether predict's behavior is desired (likely a fix) or needs a narrow guard.
• Centroid-only model — track hard-errors (feat(gui): centroid-only models - training pipeline UX (2/2) #2724); predict should now work. Smoke-test.
• --frames with explicit/negative indices (GUI emits e.g. 0,-2559).

Scope decision

The parity analysis recommends a clean, ungated full switch (predict is a strict superset; progress is byte-identical) rather than a feature flag or per-model-type gate — a gate would institutionalize the legacy path we're retiring. The only thing that would justify a narrow guard is if ID-model tracking (item 3) turns out unwanted.

🤖 Generated with Claude Code

https://claude.ai/code/session_019w47Wyu6LYBGZdEEegteDV

[github-actions]

Docs Preview

Preview URL	https://docs.sleap.ai/pr/2800/
Commit	dfdbcfd425ee64eaed5809f9df811e86af3cd725

API changes detected - View API Reference

This preview will be removed when the PR is closed.