feat(LAB-4125): handle both workflow in the export

Author: FannyGaudin

src/kili/domain_api/exports.py

@@ -8,6 +8,7 @@
 from kili.domain.asset.asset import AssetStatus, StatusInStep
 from kili.domain.issue import IssueStatus, IssueType
 from kili.domain.label import LabelType
+from kili.domain.project import ProjectId
 from kili.domain.types import ListOrTuple
 from kili.domain_api.base import DomainNamespace
 from kili.domain_api.namespace_utils import get_available_methods
@@ -63,6 +64,70 @@ def __init__(self, client, gateway):
         super().__init__(client, gateway, "exports")
         self.raw = self.kili
 
+    def _get_workflow_version(self, project_id: str) -> Optional[str]:
+        """Get the workflow version for a project.
+
+        Args:
+            project_id: The project identifier
+
+        Returns:
+            The workflow version ("V1" or "V2") or None if project not found
+        """
+        project = self._gateway.get_project(
+            project_id=ProjectId(project_id), fields=["workflowVersion"]
+        )
+
+        if not project:
+            return None
+
+        return project.get("workflowVersion")
+
+    def _get_optimal_export_type(self, workflow_version: Optional[str]) -> ExportType:
+        """Determine the optimal export type based on project workflow configuration.
+
+        For non-multi-review projects (Workflow V1), uses "latest"
+        which queries the singular latestLabel field for better performance.
+
+        For multi-review projects (Workflow V2), uses "latest_from_last_step"
+        which queries the plural latestLabels field to support multiple annotators.
+
+        Args:
+            workflow_version: The workflow version ("V1", "V2", or None)
+
+        Returns:
+            The optimal export type for this project
+        """
+        if workflow_version == "V2":
+            return "latest_from_last_step"
+        return "latest"
+
+    def _validate_export_type_compatibility(
+        self, workflow_version: Optional[str], export_type: ExportType
+    ) -> None:
+        """Validate that the export type is compatible with the project workflow.
+
+        Workflow V1 projects cannot use export types that rely on multi-step workflows:
+        - latest_from_last_step: Uses latestLabels field (V2 multi-review feature)
+        - latest_from_all_steps: Uses labels with isLastForStep (V2 multi-step feature)
+
+        Args:
+            workflow_version: The workflow version ("V1", "V2", or None)
+            export_type: The requested export type
+
+        Raises:
+            ValueError: If the export type is incompatible with the project workflow version
+        """
+        if export_type not in ("latest_from_last_step", "latest_from_all_steps"):
+            return
+
+        if workflow_version == "V1":
+            raise ValueError(
+                f"Export type '{export_type}' is not compatible with Workflow V1 projects. "
+                f"Workflow V1 projects should use export_type='latest' or 'normal'. "
+                f"The '{export_type}' export type is designed for Workflow V2 projects "
+                f"with multi-step workflows."
+            )
+
     @deprecated(
         "'exports' is a namespace, not a callable method. "
         "Use kili.exports.kili() or other available methods instead."
@@ -93,7 +158,7 @@ def kili(
         include_sent_back_labels: Optional[bool] = None,
         label_type_in: Optional[list[LabelType]] = None,
         single_file: Optional[bool] = False,
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ):
         """Export project labels in Kili native format.
 
@@ -114,14 +179,17 @@ def kili(
                 whose type belongs to that list.
                 By default, only `DEFAULT` and `REVIEW` labels are exported.
             single_file: If True, all labels are exported in a single JSON file.
-            export_type: Type of export. Options are:
+            export_type: Type of export. If not specified, automatically selects the optimal type:
+                - For Workflow V1 projects: uses `"latest"` (single label per asset)
+                - For Workflow V2 projects: uses `"latest_from_last_step"` (supports multiple annotators)
+
+                Available options:
                 - `"latest_from_last_step"`: exports the latest labels from the last workflow step
                   (uses `latestLabels` field, supports multiple annotators).
                 - `"latest_from_all_steps"`: exports latest labels from all workflow steps
                 - `"latest"`: exports the latest label for each asset
                   (deprecated, use `"latest_from_last_step"` instead).
                 - `"normal"`: exports all labels for each asset.
-                Defaults to `"latest_from_last_step"`.
 
         Returns:
             Export information or None if export failed.
@@ -151,7 +219,7 @@ def coco(
         include_sent_back_labels: Optional[bool] = None,
         label_type_in: Optional[list[LabelType]] = None,
         layout: SplitOption = "split",
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ):
         """Export project labels in COCO format.
 
@@ -175,14 +243,17 @@ def coco(
                 By default, only `DEFAULT` and `REVIEW` labels are exported.
             layout: Layout of the exported files. "split" means there is one folder
                 per job, "merged" that there is one folder with every labels.
-            export_type: Type of export. Options are:
+            export_type: Type of export. If not specified, automatically selects the optimal type:
+                - For Workflow V1 projects: uses `"latest"` (single label per asset)
+                - For Workflow V2 projects: uses `"latest_from_last_step"` (supports multiple annotators)
+
+                Available options:
                 - `"latest_from_last_step"`: exports the latest labels from the last workflow step
                   (uses `latestLabels` field, supports multiple annotators).
                 - `"latest_from_all_steps"`: exports latest labels from all workflow steps
                 - `"latest"`: exports the latest label for each asset
                   (deprecated, use `"latest_from_last_step"` instead).
                 - `"normal"`: exports all labels for each asset.
-                Defaults to `"latest_from_last_step"`.
 
         Returns:
             Export information or None if export failed.
@@ -211,7 +282,7 @@ def yolo_v4(
         filter: Optional[ExportAssetFilter] = None,
         include_sent_back_labels: Optional[bool] = None,
         label_type_in: Optional[list[LabelType]] = None,
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ):
         """Export project labels in YOLO v4 format.
 
@@ -234,14 +305,17 @@ def yolo_v4(
                 By default, only `DEFAULT` and `REVIEW` labels are exported.
             include_sent_back_labels: If True, the export will include the labels that
                 have been sent back.
-            export_type: Type of export. Options are:
+            export_type: Type of export. If not specified, automatically selects the optimal type:
+                - For Workflow V1 projects: uses `"latest"` (single label per asset)
+                - For Workflow V2 projects: uses `"latest_from_last_step"` (supports multiple annotators)
+
+                Available options:
                 - `"latest_from_last_step"`: exports the latest labels from the last workflow step
                   (uses `latestLabels` field, supports multiple annotators).
                 - `"latest_from_all_steps"`: exports latest labels from all workflow steps
                 - `"latest"`: exports the latest label for each asset
                   (deprecated, use `"latest_from_last_step"` instead).
                 - `"normal"`: exports all labels for each asset.
-                Defaults to `"latest_from_last_step"`.
 
         Returns:
             Export information or None if export failed.
@@ -269,7 +343,7 @@ def yolo_v5(
         filter: Optional[ExportAssetFilter] = None,
         include_sent_back_labels: Optional[bool] = None,
         label_type_in: Optional[list[LabelType]] = None,
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ):
         """Export project labels in YOLO v5 format.
 
@@ -292,14 +366,17 @@ def yolo_v5(
                 By default, only `DEFAULT` and `REVIEW` labels are exported.
             include_sent_back_labels: If True, the export will include the labels that
                 have been sent back.
-            export_type: Type of export. Options are:
+            export_type: Type of export. If not specified, automatically selects the optimal type:
+                - For Workflow V1 projects: uses `"latest"` (single label per asset)
+                - For Workflow V2 projects: uses `"latest_from_last_step"` (supports multiple annotators)
+
+                Available options:
                 - `"latest_from_last_step"`: exports the latest labels from the last workflow step
                   (uses `latestLabels` field, supports multiple annotators).
                 - `"latest_from_all_steps"`: exports latest labels from all workflow steps
                 - `"latest"`: exports the latest label for each asset
                   (deprecated, use `"latest_from_last_step"` instead).
                 - `"normal"`: exports all labels for each asset.
-                Defaults to `"latest_from_last_step"`.
 
         Returns:
             Export information or None if export failed.
@@ -327,7 +404,7 @@ def yolo_v7(
         filter: Optional[ExportAssetFilter] = None,
         include_sent_back_labels: Optional[bool] = None,
         label_type_in: Optional[list[LabelType]] = None,
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ):
         """Export project labels in YOLO v7 format.
 
@@ -350,14 +427,17 @@ def yolo_v7(
                 By default, only `DEFAULT` and `REVIEW` labels are exported.
             include_sent_back_labels: If True, the export will include the labels that
                 have been sent back.
-            export_type: Type of export. Options are:
+            export_type: Type of export. If not specified, automatically selects the optimal type:
+                - For Workflow V1 projects: uses `"latest"` (single label per asset)
+                - For Workflow V2 projects: uses `"latest_from_last_step"` (supports multiple annotators)
+
+                Available options:
                 - `"latest_from_last_step"`: exports the latest labels from the last workflow step
                   (uses `latestLabels` field, supports multiple annotators).
                 - `"latest_from_all_steps"`: exports latest labels from all workflow steps
                 - `"latest"`: exports the latest label for each asset
                   (deprecated, use `"latest_from_last_step"` instead).
                 - `"normal"`: exports all labels for each asset.
-                Defaults to `"latest_from_last_step"`.
 
         Returns:
             Export information or None if export failed.
@@ -385,7 +465,7 @@ def yolo_v8(
         filter: Optional[ExportAssetFilter] = None,
         include_sent_back_labels: Optional[bool] = None,
         label_type_in: Optional[list[LabelType]] = None,
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ):
         """Export project labels in YOLO v8 format.
 
@@ -408,14 +488,17 @@ def yolo_v8(
                 By default, only `DEFAULT` and `REVIEW` labels are exported.
             include_sent_back_labels: If True, the export will include the labels that
                 have been sent back.
-            export_type: Type of export. Options are:
+            export_type: Type of export. If not specified, automatically selects the optimal type:
+                - For Workflow V1 projects: uses `"latest"` (single label per asset)
+                - For Workflow V2 projects: uses `"latest_from_last_step"` (supports multiple annotators)
+
+                Available options:
                 - `"latest_from_last_step"`: exports the latest labels from the last workflow step
                   (uses `latestLabels` field, supports multiple annotators).
                 - `"latest_from_all_steps"`: exports latest labels from all workflow steps
                 - `"latest"`: exports the latest label for each asset
                   (deprecated, use `"latest_from_last_step"` instead).
                 - `"normal"`: exports all labels for each asset.
-                Defaults to `"latest_from_last_step"`.
 
         Returns:
             Export information or None if export failed.
@@ -442,7 +525,7 @@ def pascal_voc(
         filter: Optional[ExportAssetFilter] = None,
         include_sent_back_labels: Optional[bool] = None,
         label_type_in: Optional[list[LabelType]] = None,
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ):
         """Export project labels in Pascal VOC format.
 
@@ -463,14 +546,17 @@ def pascal_voc(
                 By default, only `DEFAULT` and `REVIEW` labels are exported.
             include_sent_back_labels: If True, the export will include the labels that
                 have been sent back.
-            export_type: Type of export. Options are:
+            export_type: Type of export. If not specified, automatically selects the optimal type:
+                - For Workflow V1 projects: uses `"latest"` (single label per asset)
+                - For Workflow V2 projects: uses `"latest_from_last_step"` (supports multiple annotators)
+
+                Available options:
                 - `"latest_from_last_step"`: exports the latest labels from the last workflow step
                   (uses `latestLabels` field, supports multiple annotators).
                 - `"latest_from_all_steps"`: exports latest labels from all workflow steps
                 - `"latest"`: exports the latest label for each asset
                   (deprecated, use `"latest_from_last_step"` instead).
                 - `"normal"`: exports all labels for each asset.
-                Defaults to `"latest_from_last_step"`.
 
         Returns:
             Export information or None if export failed.
@@ -497,7 +583,7 @@ def geojson(
         filter: Optional[ExportAssetFilter] = None,
         include_sent_back_labels: Optional[bool] = None,
         label_type_in: Optional[list[LabelType]] = None,
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ):
         """Export project labels in GeoJSON format.
 
@@ -518,14 +604,17 @@ def geojson(
                 By default, only `DEFAULT` and `REVIEW` labels are exported.
             include_sent_back_labels: If True, the export will include the labels that
                 have been sent back.
-            export_type: Type of export. Options are:
+            export_type: Type of export. If not specified, automatically selects the optimal type:
+                - For Workflow V1 projects: uses `"latest"` (single label per asset)
+                - For Workflow V2 projects: uses `"latest_from_last_step"` (supports multiple annotators)
+
+                Available options:
                 - `"latest_from_last_step"`: exports the latest labels from the last workflow step
                   (uses `latestLabels` field, supports multiple annotators).
                 - `"latest_from_all_steps"`: exports latest labels from all workflow steps
                 - `"latest"`: exports the latest label for each asset
                   (deprecated, use `"latest_from_last_step"` instead).
                 - `"normal"`: exports all labels for each asset.
-                Defaults to `"latest_from_last_step"`.
 
         Returns:
             Export information or None if export failed.
@@ -610,7 +699,7 @@ def _export(
         project_id: str,
         single_file: bool = False,
         with_assets: Optional[bool] = True,
-        export_type: ExportType = "latest_from_last_step",
+        export_type: Optional[ExportType] = None,
     ) -> Optional[list[dict[str, Union[list[str], str]]]]:
         """Export the project labels with the requested format into the requested output path.
 
@@ -657,6 +746,13 @@ def _export(
             ...     filter={"external_id_contains": ["batch_1"]}
             ... )
         """
+        workflow_version = self._get_workflow_version(project_id)
+
+        if export_type is None:
+            export_type = self._get_optimal_export_type(workflow_version)
+        else:
+            self._validate_export_type_compatibility(workflow_version, export_type)
+
         asset_filter_kwargs = dict(filter) if filter else {}
         return self._client.export_labels(
             project_id=project_id,