feat: add support for sidecar ball-tracking files in JSON to Parquet conversion

[SilvioGiancola]

Summary

• Adds support for sidecar ball-tracking files when converting JSON to Parquet
• Updates hf_transfer.py, osl_json_to_parquet.py, and parquet_to_osl_json.py accordingly

Test plan

• Verify JSON to Parquet conversion with a sidecar ball-tracking file present
• Verify existing conversions without a sidecar file still work

[Copilot]

🟡 Changes recommended

New ball_path behavior isn’t covered by existing tests and includes inaccurate error messages that should be updated to reflect the expanded supported schema.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR extends the JSON↔Parquet conversion and Hugging Face transfer tooling to recognize and carry “sidecar” ball-tracking files referenced via inputs[].ball_path, ensuring these assets can be bundled into shards, extracted back out, and included in transfer path lists.

Changes:

• Bundle sidecar ball-tracking files into WebDataset tar shards using the member naming scheme <key>.<input_idx>.ball.<ext>, and propagate them through manifest/path-rewrite logic.
• Extract sidecar ball-tracking files during Parquet→JSON media extraction, writing them to the original ball_path locations under the output media root.
• Include ball_path in HF download/upload path extraction utilities.

File summaries

File	Description
opensportslib/tools/osl_json_to_parquet.py	Adds sidecar ball_path file bundling to shard creation and supports rewriting ball_path in payloads when absolute paths are used.
opensportslib/tools/parquet_to_osl_json.py	Extracts sidecar ball-tracking tar members back to disk alongside primary inputs during extract_media.
opensportslib/tools/hf_transfer.py	Extends HF path extraction/upload entry generation to include inputs[].ball_path alongside inputs[].path.

Review details

Suppressed comments (2)

opensportslib/tools/hf_transfer.py:130

• The ValueError message is now inaccurate because this function also collects inputs[].ball_path (and legacy videos[].path). If a JSON only includes sidecar ball_path values, the message still claims there were no inputs with 'path'.

    if not repo_paths:
        raise ValueError("No file paths found in the provided JSON (no inputs with 'path').")

opensportslib/tools/hf_transfer.py:676

• The empty-result error message only mentions data[].inputs[].path, but this function now also accepts data[].inputs[].ball_path. Update the message to reflect both supported fields.

    if not entries:
        raise ValueError("No valid data[].inputs[].path entries found in the provided dataset JSON.")

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.