(prototype) Add the View and Sample batch contract

[gabrielfruet]

Prototype. Do not merge. This is a design exploration for the LightlySSL 2.0
refactor, opened to be read and argued with, not to land on master. The whole
stack goes together or not at all, and the shape is still open.

1 of 7 in a stack. Base: master.

A transform returns list[Tensor] today, which covers two of the seven cases the library already serves, and it forked once into MultiViewTransformV2 because it could not carry a mask. Four incompatible return contracts ship right now and no caller can write one loop over them.

View carries the tensor plus what it is: a stream, a role, and an extras dict for a mask, a grid or patch ids. Sample holds the views and per-sample meta, with by_role and by_stream. One collate stacks data and every extras entry, and takes no configuration because everything it needs arrived with the data. legacy_collate yields the old (views, labels, filenames).

Nothing uses it yet. The transforms move in PR 5 of this stack.

collate is not re-exported from lightly.data: the name is taken by the deprecated lightly.data.collate module until that goes. Import it from lightly.data.sample.

One import fix rides along. lightly/data/collate.py now imports GaussianBlur and friends from their own modules, because going through the lightly.transforms package closes an import loop once transforms need View.

Testing: pytest tests/data/test_sample.py, 10 cases covering stacking, extras, ragged batches and views labelled differently across samples.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e2b3eec69a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reject mismatched metadata before batching

When a batch mixes supported item forms, such as a view-only item followed by (views, target, filename) (for example at a ConcatDataset boundary), iterating only over the first item's metadata silently discards every target and filename from later items; reversing the same batch instead raises KeyError. Validate that all metadata key sets agree, as is already done for view counts and extras, so batch contents and ordering cannot determine whether labels are lost.

Useful? React with 👍 / 👎.