feat: FIT-710: Enable FSM state fields in serializers and models

[bmartel]

This pull request adds robust support for annotating and exposing finite state machine (FSM) state information for core entities (Task, Project, Annotation) in the Data Manager and API responses, while ensuring zero performance impact when FSM-related feature flags are disabled. The main improvements include new reusable mixins and serializer fields for efficient state annotation, integration of FSM state into querysets and serializers, and feature flag-based conditional exposure.

FSM State Annotation & API Exposure

• Introduced FSMStateQuerySetMixin in fsm/queryset_mixins.py, providing an efficient annotate_fsm_state() method for Django querysets to annotate entities with their current FSM state using optimized subqueries, avoiding N+1 queries. Annotation is strictly controlled by two feature flags for performance and rollout safety.
• Added FSMStateField in fsm/serializer_fields.py, a DRF serializer field that exposes the FSM state in API responses, using annotated values when available or falling back to the state manager. The field is read-only and respects feature flags for conditional exposure.

Integration with Data Manager and Serializers

• Updated TaskQuerySet, ProjectQuerySet, and AnnotationQuerySet to inherit from FSMStateQuerySetMixin, allowing FSM state annotation in their respective managers (TaskManager, ProjectManager, AnnotationManager). Added .with_state() helper methods for convenient access to annotated querysets. [1] [2] [3]
• Added the state field (using FSMStateField) to the DataManagerTaskSerializer, and ensured its conditional removal from API output based on feature flags. [1] [2]
• Implemented the annotate_state function and registered it in DATA_MANAGER_ANNOTATIONS_MAP, enabling FSM state annotation as a Data Manager column. [1] [2]

Manager and QuerySet Enhancements

• Refactored model managers (TaskManager, ProjectManager, AnnotationManager) to return FSM-enabled querysets and support .with_state() for annotated queries, ensuring seamless integration and consistent usage patterns. [1] [2] [3]
• Improved documentation and code comments throughout to clarify usage, feature flag controls, and performance considerations. [1] [2] [3]

These changes collectively provide a scalable, performant, and feature-flagged approach to FSM state management and exposure in both backend queries and API responses.

References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

[netlify]

✅ Deploy Preview for label-studio-docs-new-theme canceled.

Name	Link
🔨 Latest commit	629512c
🔍 Latest deploy log	https://app.netlify.com/projects/label-studio-docs-new-theme/deploys/6912055fce15320008a2f8f6

[netlify]

✅ Deploy Preview for label-studio-storybook canceled.

Name	Link
🔨 Latest commit	629512c
🔍 Latest deploy log	https://app.netlify.com/projects/label-studio-storybook/deploys/6912055f6b84090008f959bd

[netlify]

✅ Deploy Preview for heartex-docs canceled.

Name	Link
🔨 Latest commit	629512c
🔍 Latest deploy log	https://app.netlify.com/projects/heartex-docs/deploys/6912055fd73c550008b3f85b

[netlify]

✅ Deploy Preview for label-studio-playground canceled.

Name	Link
🔨 Latest commit	629512c
🔍 Latest deploy log	https://app.netlify.com/projects/label-studio-playground/deploys/6912055f77d95d0008afb8c9

[codecov]

Codecov Report

❌ Patch coverage is 77.41935% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.67%. Comparing base (c1b6cb6) to head (629512c).
⚠️ Report is 1 commits behind head on develop.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
label_studio/fsm/serializer_fields.py	54.16%	11 Missing ⚠️
label_studio/fsm/queryset_mixins.py	57.14%	9 Missing ⚠️
label_studio/tasks/models.py	86.66%	4 Missing ⚠️
label_studio/data_manager/managers.py	78.57%	3 Missing ⚠️
label_studio/projects/models.py	90.90%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           develop    #8775       +/-   ##
============================================
+ Coverage    67.28%   80.67%   +13.39%     
============================================
  Files          804      253      -551     
  Lines        62347    23107    -39240     
  Branches     10419        0    -10419     
============================================
- Hits         41951    18642    -23309     
+ Misses       20393     4465    -15928     
+ Partials         3        0        -3     

Flag	Coverage Δ
lsf-e2e	?
lsf-integration	?
lsf-unit	?
pytests	80.67% <77.41%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.