Merge pull request #739 from superannotateai/FRIDAY-3464

Friday 3464

Author: VaghinakDev

docs/source/api_reference/api_team.rst

@@ -7,3 +7,4 @@ Team
 .. automethod:: superannotate.SAClient.get_integrations
 .. automethod:: superannotate.SAClient.invite_contributors_to_team
 .. automethod:: superannotate.SAClient.search_team_contributors
+.. automethod:: superannotate.SAClient.get_user_metadata

src/superannotate/lib/app/interface/sdk_interface.py

@@ -55,6 +55,7 @@
 from lib.core.entities.integrations import IntegrationEntity
 from lib.core.entities.integrations import IntegrationTypeEnum
 from lib.core.enums import ImageQuality
+from lib.core.enums import CustomFieldEntityEnum
 from lib.core.enums import ProjectType
 from lib.core.enums import ClassTypeEnum
 from lib.core.exceptions import AppException
@@ -279,6 +280,79 @@ def get_team_metadata(self):
         response = self.controller.get_team()
         return TeamSerializer(response.data).serialize()
 
+    def get_user_metadata(
+        self, pk: Union[int, str], include: List[Literal["custom_fields"]] = None
+    ):
+        """
+        Returns user metadata
+
+        :param pk: The email address or ID of the team contributor.
+        :type pk: str or int
+
+        :param include: Specifies additional fields to include in the response.
+
+                Possible values are
+
+                    - "custom_fields": whether to include custom fields that have been created for the team user.
+
+        :type include: list of str, optional
+
+        :return: metadata of team contributor
+        :rtype: dict
+        """
+        user = self.controller.work_management.get_user_metadata(pk=pk, include=include)
+        return BaseSerializer(user).serialize(by_alias=False)
+
+    def set_user_custom_field(
+        self, pk: Union[int, str], custom_field_name: str, value: Any
+    ):
+        """
+        Set the custom field for team contributors.
+
+        :param pk: The email address or ID of the team contributor.
+        :type pk: str or int
+
+        :param custom_field_name: the name of the custom field created for the team contributor,
+                                    used to set or update its value.
+
+        :type custom_field_name: str
+
+        :param value: The value
+        :type value: Any
+
+         Request Example:
+        ::
+            from superannotate import SAClient
+
+
+            sa = SAClient()
+
+            client.set_user_custom_field(
+                "example@email.com",
+                custom_field_name="Due date",
+                value="Dec 20, 2024"
+            )
+        """
+        user_id = self.controller.work_management.get_user_metadata(pk=pk).id
+        self.controller.work_management.set_custom_field_value(
+            entity_id=user_id,
+            field_name=custom_field_name,
+            value=value,
+            entity=CustomFieldEntityEnum.CONTRIBUTOR,
+            parent_entity=CustomFieldEntityEnum.TEAM,
+        )
+
+    def list_users(self, *, include: List[Literal["custom_fields"]] = None, **filters):
+        """
+
+        @param include:
+        @param filters:
+        @return:
+        """
+        return BaseSerializer.serialize_iterable(
+            self.controller.work_management.list_users(include=include, **filters)
+        )
+
     def get_component_config(self, project: Union[NotEmptyStr, int], component_id: str):
         """
         Retrieves the configuration for a given project and component ID.
@@ -2903,7 +2977,7 @@ def list_items(
         project: Union[NotEmptyStr, int],
         folder: Optional[Union[NotEmptyStr, int]] = None,
         *,
-        include: List[Literal["custom_metadata", "category"]] = None,
+        include: List[Literal["custom_metadata", "categories"]] = None,
         **filters,
     ):
         """
@@ -2923,6 +2997,7 @@ def list_items(
                 Possible values are
 
                 - "custom_metadata": Includes custom metadata attached to the item.
+                - "categories": Includes categories attached to the item.
         :type include: list of str, optional
 
         :param filters: Specifies filtering criteria (e.g., name, ID, annotation status),
@@ -2993,6 +3068,40 @@ def list_items(
                 }
             ]
 
+        Request Example with include categories:
+        ::
+
+            client.list_items(
+                project="My Multimodal",
+                folder="folder1",
+                include=["categories"]
+            )
+
+        Response Example:
+        ::
+
+            [
+                {
+                    "id": 48909383,
+                    "name": "scan_123.jpeg",
+                    "path": "Medical Annotations/folder1",
+                    "url": "https://sa-public-files.s3.../scan_123.jpeg",
+                    "annotation_status": "InProgress",
+                    "createdAt": "2022-02-10T14:32:21.000Z",
+                    "updatedAt": "2022-02-15T20:46:44.000Z",
+                    "entropy_value": None,
+                    "assignments": [],
+                    "categories": [
+                        {
+                            "createdAt": "2025-01-29T13:51:39.000Z",
+                            "updatedAt": "2025-01-29T13:51:39.000Z",
+                            "id": 328577,
+                            "name": "my_category",
+                        },
+                    ],
+                }
+            ]
+
         Additional Filter Examples:
         ::
 
@@ -3014,6 +3123,14 @@ def list_items(
             if isinstance(project, int)
             else self.controller.get_project(project)
         )
+        if (
+            include
+            and "categories" in include
+            and project.type != ProjectType.MULTIMODAL.value
+        ):
+            raise AppException(
+                "The 'categories' option in the 'include' field is only supported for Multimodal projects."
+            )
         if folder is None:
             folder = self.controller.get_folder(project, "root")
         else:
@@ -3088,6 +3205,7 @@ def list_projects(
                 - status__in: List[Literal[“NotStarted”, “InProgress”, “Completed”, “OnHold”]]
                 - status__notin: List[Literal[“NotStarted”, “InProgress”, “Completed”, “OnHold”]]
                 - custom_field: Optional[dict] – Specifies custom fields attributes to filter projects by.
+
                   Custom fields can be accessed using the `custom_field__` prefix followed by the attribute name.
 
         :type filters: ProjectFilters

src/superannotate/lib/core/entities/__init__.py

@@ -14,6 +14,7 @@
 from lib.core.entities.project import AttachmentEntity
 from lib.core.entities.project import CategoryEntity
 from lib.core.entities.project import ContributorEntity
+from lib.core.entities.project import CustomFieldEntity
 from lib.core.entities.project import ProjectEntity
 from lib.core.entities.project import SettingEntity
 from lib.core.entities.project import StepEntity
@@ -28,6 +29,7 @@
     "ConfigEntity",
     "SettingEntity",
     "SubSetEntity",
+    "CustomFieldEntity",
     # items
     "BaseEntity",
     "ImageEntity",

src/superannotate/lib/core/entities/filters.py

@@ -37,3 +37,19 @@ class ProjectFilters(BaseFilters):
     status__ne: Literal["NotStarted", "InProgress", "Completed", "OnHold"]
     status__in: List[Literal["NotStarted", "InProgress", "Completed", "OnHold"]]
     status__notin: List[Literal["NotStarted", "InProgress", "Completed", "OnHold"]]
+    custom_field: Optional[str]  # dummy field to pass first level validation
+
+
+class UserFilters(TypedDict, total=False):
+    id: Optional[int]
+    id__in: Optional[List[int]]
+    email: Optional[str]
+    email__in: Optional[List[str]]
+    email__contains: Optional[str]
+    email__starts: Optional[str]
+    email__ends: Optional[str]
+    state: Optional[str]
+    state__in: Optional[List[str]]
+    role: Optional[str]
+    role__in: Optional[List[str]]
+    custom_field: Optional[str]  # dummy field to pass first level validation

src/superannotate/lib/core/entities/items.py

@@ -1,6 +1,7 @@
 from typing import Optional
 
 from lib.core.entities.base import BaseItemEntity
+from lib.core.entities.base import TimedBaseModel
 from lib.core.enums import ApprovalStatus
 from lib.core.enums import ProjectType
 from lib.core.pydantic_v1 import Extra
@@ -16,6 +17,21 @@ class Config:
         extra = Extra.ignore
 
 
+class MultiModalItemCategoryEntity(TimedBaseModel):
+    id: int = Field(None, alias="category_id")
+    name: str = Field(None, alias="category_name")
+
+    class Config:
+        extra = Extra.ignore
+
+
+class MultiModalItemEntity(BaseItemEntity):
+    categories: Optional[list[MultiModalItemCategoryEntity]]
+
+    class Config:
+        extra = Extra.ignore
+
+
 class VideoEntity(BaseItemEntity):
     approval_status: Optional[ApprovalStatus] = Field(None)
 
@@ -51,4 +67,5 @@ class Config:
     ProjectType.TILED: ImageEntity,
     ProjectType.VIDEO: VideoEntity,
     ProjectType.DOCUMENT: DocumentEntity,
+    ProjectType.MULTIMODAL: MultiModalItemEntity,
 }

src/superannotate/lib/core/entities/project.py

@@ -170,6 +170,13 @@ class Config:
         extra = Extra.ignore
 
 
+class CustomFieldEntity(BaseModel):
+    ...
+
+    class Config:
+        extra = Extra.allow
+
+
 class WorkflowEntity(BaseModel):
     id: Optional[int]
     name: Optional[str]

src/superannotate/lib/core/entities/work_managament.py

@@ -1,4 +1,5 @@
 import datetime
+from enum import auto
 from enum import Enum
 from typing import Optional
 
@@ -9,14 +10,6 @@
 from lib.core.pydantic_v1 import validator
 
 
-class ProjectCustomFieldType(Enum):
-    Text = 1
-    MULTI_SELECT = 2
-    SINGLE_SELECT = 3
-    DATE_PICKER = 4
-    NUMERIC = 5
-
-
 class ProjectType(str, Enum):
     Vector = "VECTOR"
     Pixel = "PIXEL"
@@ -28,6 +21,25 @@ class ProjectType(str, Enum):
     Multimodal = "CUSTOM_LLM"
 
 
+class WMUserStateEnum(str, Enum):
+    Pending = "PENDING"
+    Confirmed = "CONFIRMED"
+    Video = "PUBLIC_VIDEO"
+    Document = "PUBLIC_TEXT"
+    Tiled = "TILED"
+    Other = "CLASSIFICATION"
+    PointCloud = "POINT_CLOUD"
+    Multimodal = "CUSTOM_LLM"
+
+
+class WMUserTypeEnum(int, Enum):
+    Contributor = 4
+    TeamAdmin = 7
+    TeamOwner = 12
+    OrganizationAdmin = 15
+    other = auto()
+
+
 class ProjectStatus(str, Enum):
     Undefined = "undefined"
     NotStarted = "notStarted"
@@ -87,3 +99,33 @@ def json(self, **kwargs):
         if "exclude" not in kwargs:
             kwargs["exclude"] = {"custom_fields"}
         return super().json(**kwargs)
+
+
+class WMUserEntity(TimedBaseModel):
+    id: Optional[int]
+    team_id: Optional[int]
+    role: WMUserTypeEnum
+    email: Optional[str]
+    state: Optional[WMUserStateEnum]
+    custom_fields: Optional[dict] = Field(dict(), alias="customField")
+
+    class Config:
+        extra = Extra.ignore
+        use_enum_names = True
+
+        json_encoders = {
+            Enum: lambda v: v.value,
+            datetime.date: lambda v: v.isoformat(),
+            datetime.datetime: lambda v: v.isoformat(),
+        }
+
+    @validator("custom_fields")
+    def custom_fields_transformer(cls, v):
+        if v and "custom_field_values" in v:
+            return v.get("custom_field_values", {})
+        return {}
+
+    def json(self, **kwargs):
+        if "exclude" not in kwargs:
+            kwargs["exclude"] = {"custom_fields"}
+        return super().json(**kwargs)

src/superannotate/lib/core/enums.py

@@ -185,3 +185,17 @@ class TrainingStatus(BaseTitledEnum):
     FAILED_BEFORE_EVALUATION = "FailedBeforeEvaluation", 4
     FAILED_AFTER_EVALUATION = "FailedAfterEvaluation", 5
     FAILED_AFTER_EVALUATION_WITH_SAVE_MODEL = "FailedAfterEvaluationWithSavedModel", 6
+
+
+class CustomFieldEntityEnum(str, Enum):
+    CONTRIBUTOR = "Contributor"
+    TEAM = "Team"
+    PROJECT = "Project"
+
+
+class CustomFieldType(Enum):
+    Text = 1
+    MULTI_SELECT = 2
+    SINGLE_SELECT = 3
+    DATE_PICKER = 4
+    NUMERIC = 5

src/superannotate/lib/core/service_types.py

@@ -6,6 +6,7 @@
 
 from lib.core import entities
 from lib.core.entities.work_managament import WMProjectEntity
+from lib.core.entities.work_managament import WMUserEntity
 from lib.core.enums import ProjectType
 from lib.core.exceptions import AppException
 from lib.core.pydantic_v1 import BaseModel
@@ -247,6 +248,14 @@ class WMProjectListResponse(ServiceResponse):
     res_data: List[WMProjectEntity] = None
 
 
+class WMUserListResponse(ServiceResponse):
+    res_data: List[WMUserEntity] = None
+
+
+class WMCustomFieldResponse(ServiceResponse):
+    res_data: List[entities.CustomFieldEntity] = None
+
+
 class SettingsListResponse(ServiceResponse):
     res_data: List[entities.SettingEntity] = None