chore: FIT-1124: sync SDK (#702)

Co-authored-by: fern-api[bot] <115122769+fern-api[bot]@users.noreply.github.com>
Co-authored-by: robot-ci-heartex <robot-ci-heartex@users.noreply.github.com>

Author: robot-ci-heartex

reference.md

@@ -10147,6 +10147,20 @@ Data that you want to duplicate: settings only, with tasks, with annotations
             must include a "text" field.
             <br>
 
+            ## Async Import Behavior
+            <hr style="opacity:0.3">
+
+            **For non-Community editions, this endpoint processes imports asynchronously.**
+            
+            - The POST request **can fail** for invalid parameters, malformed request body, or other request-level validation errors.
+            - However, **data validation errors** that occur during import processing are handled asynchronously and will not cause the POST request to fail.
+            - Upon successful request validation, a response is returned: `{"import": <import_id>}`
+            - Use the returned `import_id` to poll the GET `/api/projects/{project_id}/imports/{import_id}` endpoint to check the import status and see any data validation errors.
+            - Data-level errors and import failures will only be visible in the GET request response.
+
+            For Community edition, imports are processed synchronously and return task counts immediately.
+            <br>
+
             ## POST requests
             <hr style="opacity:0.3">
 
@@ -10455,7 +10469,17 @@ client.projects.validate_label_config(
 <dl>
 <dd>
 
-Return data related to async project import operation
+
+            Poll the status of an asynchronous project import operation.
+            
+            **Usage:**
+            1. When you POST to `/api/projects/{project_id}/import`, you'll receive a response like `{"import": <import_id>}`
+            2. Use that `import_id` with this GET endpoint to check the import status
+            3. Poll this endpoint to see if the import has completed, is still processing, or has failed
+            4. **Import errors and failures will only be visible in this GET response**, not in the original POST request
+            
+            This endpoint returns detailed information about the import including task counts, status, and any error messages.
+        
 </dd>
 </dl>
 </dd>

src/label_studio_sdk/projects/client.py

@@ -1014,6 +1014,20 @@ def import_tasks(
                     must include a "text" field.
                     <br>
         
+                    ## Async Import Behavior
+                    <hr style="opacity:0.3">
+        
+                    **For non-Community editions, this endpoint processes imports asynchronously.**
+                    
+                    - The POST request **can fail** for invalid parameters, malformed request body, or other request-level validation errors.
+                    - However, **data validation errors** that occur during import processing are handled asynchronously and will not cause the POST request to fail.
+                    - Upon successful request validation, a response is returned: `{"import": <import_id>}`
+                    - Use the returned `import_id` to poll the GET `/api/projects/{project_id}/imports/{import_id}` endpoint to check the import status and see any data validation errors.
+                    - Data-level errors and import failures will only be visible in the GET request response.
+        
+                    For Community edition, imports are processed synchronously and return task counts immediately.
+                    <br>
+        
                     ## POST requests
                     <hr style="opacity:0.3">
         
@@ -1079,7 +1093,7 @@ def import_tasks(
         Returns
         -------
         ImportTasksProjectsResponse
-            Tasks successfully imported
+            Tasks successfully imported or import queued. **For non-Community editions**, the response will be `{"import": <import_id>}` which you can use to poll the import status. **For Community edition**, the response contains task counts and is processed synchronously.
         
         Examples
         --------
@@ -2291,6 +2305,20 @@ async def import_tasks(
                     must include a "text" field.
                     <br>
         
+                    ## Async Import Behavior
+                    <hr style="opacity:0.3">
+        
+                    **For non-Community editions, this endpoint processes imports asynchronously.**
+                    
+                    - The POST request **can fail** for invalid parameters, malformed request body, or other request-level validation errors.
+                    - However, **data validation errors** that occur during import processing are handled asynchronously and will not cause the POST request to fail.
+                    - Upon successful request validation, a response is returned: `{"import": <import_id>}`
+                    - Use the returned `import_id` to poll the GET `/api/projects/{project_id}/imports/{import_id}` endpoint to check the import status and see any data validation errors.
+                    - Data-level errors and import failures will only be visible in the GET request response.
+        
+                    For Community edition, imports are processed synchronously and return task counts immediately.
+                    <br>
+        
                     ## POST requests
                     <hr style="opacity:0.3">
         
@@ -2356,7 +2384,7 @@ async def import_tasks(
         Returns
         -------
         ImportTasksProjectsResponse
-            Tasks successfully imported
+            Tasks successfully imported or import queued. **For non-Community editions**, the response will be `{"import": <import_id>}` which you can use to poll the import status. **For Community edition**, the response contains task counts and is processed synchronously.
         
         Examples
         --------

src/label_studio_sdk/projects/types/import_tasks_projects_response.py

@@ -3,52 +3,61 @@
 from ...core.unchecked_base_model import UncheckedBaseModel
 import typing
 import pydantic
+import typing_extensions
+from ...core.serialization import FieldMetadata
 from ...core.pydantic_utilities import IS_PYDANTIC_V2
 
 
 class ImportTasksProjectsResponse(UncheckedBaseModel):
     """
-    Task creation response
+    Response format varies by edition. Non-Community editions return `{"import": <import_id>}` for async processing. Community edition returns the detailed response below with task counts.
     """
 
     annotation_count: typing.Optional[int] = pydantic.Field(default=None)
     """
-    Number of annotations added
+    Number of annotations added (Community edition sync import only)
     """
 
     could_be_tasks_list: typing.Optional[bool] = pydantic.Field(default=None)
     """
-    Whether uploaded files can contain lists of tasks, like CSV/TSV files
+    Whether uploaded files can contain lists of tasks, like CSV/TSV files (Community edition sync import only)
     """
 
     data_columns: typing.Optional[typing.List[str]] = pydantic.Field(default=None)
     """
-    The list of found data columns
+    The list of found data columns (Community edition sync import only)
     """
 
     duration: typing.Optional[float] = pydantic.Field(default=None)
     """
-    Time in seconds to create
+    Time in seconds to create (Community edition sync import only)
     """
 
     file_upload_ids: typing.Optional[typing.List[int]] = pydantic.Field(default=None)
     """
-    Database IDs of uploaded files
+    Database IDs of uploaded files (Community edition sync import only)
     """
 
     found_formats: typing.Optional[typing.List[str]] = pydantic.Field(default=None)
     """
-    The list of found file formats
+    The list of found file formats (Community edition sync import only)
+    """
+
+    import_: typing_extensions.Annotated[typing.Optional[int], FieldMetadata(alias="import")] = pydantic.Field(
+        default=None
+    )
+    """
+    Import ID for async operations (non-Community editions only). Use this ID to poll `/api/projects/{project_id}/imports/{import_id}` for status.
     """
 
     predictions_count: typing.Optional[int] = pydantic.Field(default=None)
     """
-    Number of predictions added
+    Number of predictions added (Community edition sync import only)
     """
 
     task_count: typing.Optional[int] = pydantic.Field(default=None)
     """
-    Number of tasks added
+    Number of tasks added (Community edition sync import only)
     """
 
     if IS_PYDANTIC_V2:

src/label_studio_sdk/tasks/client.py

@@ -34,7 +34,17 @@ def create_many_status(
         self, id: int, import_pk: int, *, request_options: typing.Optional[RequestOptions] = None
     ) -> ProjectImport:
         """
-        Return data related to async project import operation
+
+                    Poll the status of an asynchronous project import operation.
+
+                    **Usage:**
+                    1. When you POST to `/api/projects/{project_id}/import`, you'll receive a response like `{"import": <import_id>}`
+                    2. Use that `import_id` with this GET endpoint to check the import status
+                    3. Poll this endpoint to see if the import has completed, is still processing, or has failed
+                    4. **Import errors and failures will only be visible in this GET response**, not in the original POST request
+
+                    This endpoint returns detailed information about the import including task counts, status, and any error messages.
+
 
         Parameters
         ----------
@@ -856,7 +866,17 @@ async def create_many_status(
         self, id: int, import_pk: int, *, request_options: typing.Optional[RequestOptions] = None
     ) -> ProjectImport:
         """
-        Return data related to async project import operation
+
+                    Poll the status of an asynchronous project import operation.
+
+                    **Usage:**
+                    1. When you POST to `/api/projects/{project_id}/import`, you'll receive a response like `{"import": <import_id>}`
+                    2. Use that `import_id` with this GET endpoint to check the import status
+                    3. Poll this endpoint to see if the import has completed, is still processing, or has failed
+                    4. **Import errors and failures will only be visible in this GET response**, not in the original POST request
+
+                    This endpoint returns detailed information about the import including task counts, status, and any error messages.
+
 
         Parameters
         ----------