Add metadata support to SuggestionFrame for preserving group information

[talmo]

Summary

This PR adds a metadata dictionary to SuggestionFrame (similar to Video.backend_metadata) to store arbitrary metadata that isn't explicitly represented in the data model. The primary use case is preserving the group key when reading/writing SLP files, which was previously being discarded.

Key Changes

1. Added metadata attribute to SuggestionFrame (sleap_io/model/suggestions.py)

• New metadata: dict[str, any] attribute with factory default (empty dict)
• Follows the same pattern as Video.backend_metadata for consistency
• Serves as a catch-all for metadata not explicitly represented in the data model

2. Updated read_suggestions (sleap_io/io/slp.py)

• Extracts the group key from JSON data if present
• Passes it to SuggestionFrame via the new metadata parameter
• Preserves metadata when reading SLP files

3. Updated write_suggestions (sleap_io/io/slp.py)

• Checks if suggestion.metadata contains a "group" key
• Uses that value if present, otherwise defaults to 0 for backward compatibility
• Removed TODO comment since metadata is now properly handled

4. Added comprehensive tests (tests/io/test_slp.py)

• Tests round-trip preservation of group metadata with different values (0, 1, 2)
• Tests backward compatibility when metadata is not provided (defaults to group 0)

Example Usage

from sleap_io import Video, SuggestionFrame

video = Video.from_filename("video.mp4")

# Create suggestion with group metadata
suggestion = SuggestionFrame(
    video=video,
    frame_idx=42,
    metadata={"group": 1}
)

# Metadata is preserved when saving/loading
print(suggestion.metadata["group"])  # 1

Testing

All tests pass:

• ✅ New test test_suggestions_metadata validates round-trip preservation
• ✅ Existing test test_suggestions validates backward compatibility
• ✅ All 83 tests in tests/io/test_slp.py pass

Backward Compatibility

This change is fully backward compatible:

• SLP files without group metadata will default to group=0
• Existing code that doesn't use metadata will continue to work unchanged
• The metadata attribute has a factory default (empty dict)

Benefits

• 🎯 Preserves the group metadata that was previously being lost
• 🔧 Uses a flexible catch-all pattern that can handle future metadata additions
• ↔️ Maintains backward compatibility with existing SLP files
• 📏 Follows existing codebase patterns (Video.backend_metadata)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.89%. Comparing base (f8b681d) to head (c25af5c).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #251      +/-   ##
==========================================
+ Coverage   93.82%   93.89%   +0.07%     
==========================================
  Files          28       28              
  Lines        5763     5765       +2     
  Branches     1528     1528              
==========================================
+ Hits         5407     5413       +6     
+ Misses        136      134       -2     
+ Partials      220      218       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.