[LIG-10238] Batch class counts by selected sample tags

[ikondrat]

Summary

• add a dedicated image-annotation count endpoint grouped by an ordered list of sample tags
• preserve the existing ungrouped count endpoint and response contract
• validate that every requested tag is a sample tag owned by the target collection
• intersect each comparison tag with the active image filter and annotation source/type scope
• preserve requested tag order and zero-fill missing classes on a shared class axis
• support both annotation-object and distinct-sample count modes

Why

Class-distribution comparison needs all selected sample-tag series in one request. Counting each tag independently prevents overlapping tags from collapsing into one subset and keeps the frontend query reactive without issuing one request per tag.

The diff is larger than the usual PR target because it includes resolver and route coverage for the backend acceptance matrix. The production change remains focused on this endpoint.

API

POST /api/collections/{collection_id}/images/annotations/count-by-sample-tags

The request accepts ordered sample_tag_ids, the active image filter, optional annotation type/source scoping, and count mode. The response returns one named, zero-filled class-count series per requested tag.

Testing

From lightly_studio/:

make static-checks
uv run pytest -q tests/resolvers/image_resolver/test_count_image_annotations_by_sample_tags.py tests/api/routes/api/test_image.py
uv run pytest -n auto

Validated locally:

• Ruff, mypy, and formatting checks pass
• focused resolver/API suite: 21 passed
• full DuckDB backend suite: 1,736 passed, 32 skipped

PostgreSQL-specific execution requires the Docker-backed test environment and should be exercised by CI.

Linear

LIG-10238

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: aa0a35c0-062d-4f6b-9789-0029240611ce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch kondrat-lig-10238-backend-batch-class-counts-by-selected-sample-tags

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}