Added item context interface

Author: VaghinakDev

docs/source/api_reference/api_item.rst

@@ -8,6 +8,7 @@ Items
 .. automethod:: superannotate.SAClient.list_items
 .. automethod:: superannotate.SAClient.search_items
 .. automethod:: superannotate.SAClient.attach_items
+.. automethod:: superannotate.SAClient.item_context
 .. automethod:: superannotate.SAClient.copy_items
 .. automethod:: superannotate.SAClient.move_items
 .. automethod:: superannotate.SAClient.delete_items

src/superannotate/__init__.py

@@ -15,6 +15,7 @@
 from lib.core import PACKAGE_VERSION_INFO_MESSAGE
 from lib.core import PACKAGE_VERSION_MAJOR_UPGRADE
 from lib.core.exceptions import AppException
+from lib.core.exceptions import FileChangedError
 from superannotate.lib.app.input_converters import convert_project_type
 from superannotate.lib.app.input_converters import export_annotation
 from superannotate.lib.app.input_converters import import_annotation
@@ -30,6 +31,7 @@
     # Utils
     "enums",
     "AppException",
+    "FileChangedError",
     "import_annotation",
     "export_annotation",
     "convert_project_type",

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

@@ -28,11 +28,13 @@
 from tqdm import tqdm
 
 import lib.core as constants
+from lib.infrastructure.controller import Controller
 from lib.app.helpers import get_annotation_paths
 from lib.app.helpers import get_name_url_duplicated_from_csv
 from lib.app.helpers import wrap_error as wrap_validation_errors
 from lib.app.interface.base_interface import BaseInterfaceFacade
 from lib.app.interface.base_interface import TrackableMeta
+
 from lib.app.interface.types import EmailStr
 from lib.app.serializers import BaseSerializer
 from lib.app.serializers import FolderSerializer
@@ -45,7 +47,7 @@
 from lib.core.conditions import Condition
 from lib.core.jsx_conditions import Filter, OperatorEnum
 from lib.core.conditions import EmptyCondition
-from lib.core.entities import AttachmentEntity
+from lib.core.entities import AttachmentEntity, FolderEntity, BaseItemEntity
 from lib.core.entities import SettingEntity
 from lib.core.entities.classes import AnnotationClassEntity
 from lib.core.entities.classes import AttributeGroup
@@ -61,6 +63,9 @@
 from lib.core.pydantic_v1 import constr
 from lib.core.pydantic_v1 import conlist
 from lib.core.pydantic_v1 import parse_obj_as
+from lib.infrastructure.annotation_adapter import BaseMultimodalAnnotationAdapter
+from lib.infrastructure.annotation_adapter import MultimodalSmallAnnotationAdapter
+from lib.infrastructure.annotation_adapter import MultimodalLargeAnnotationAdapter
 from lib.infrastructure.utils import extract_project_folder
 from lib.infrastructure.validators import wrap_error
 
@@ -69,7 +74,6 @@
 # NotEmptyStr = TypeVar("NotEmptyStr", bound=constr(strict=True, min_length=1))
 NotEmptyStr = constr(strict=True, min_length=1)
 
-
 PROJECT_STATUS = Literal["NotStarted", "InProgress", "Completed", "OnHold"]
 
 PROJECT_TYPE = Literal[
@@ -82,7 +86,6 @@
     "Multimodal",
 ]
 
-
 APPROVAL_STATUS = Literal["Approved", "Disapproved", None]
 
 IMAGE_QUALITY = Literal["compressed", "original"]
@@ -110,6 +113,87 @@ class Attachment(TypedDict, total=False):
     integration: NotRequired[str]  # noqa
 
 
+class ItemContext:
+    def __init__(
+        self,
+        controller: Controller,
+        project: Project,
+        folder: FolderEntity,
+        item: BaseItemEntity,
+        overwrite: bool = True,
+    ):
+        self.controller = controller
+        self.project = project
+        self.folder = folder
+        self.item = item
+        self._annotation_adapter: Optional[BaseMultimodalAnnotationAdapter] = None
+        self._overwrite = overwrite
+        self._annotation = None
+
+    def _set_small_annotation_adapter(self, annotation: dict = None):
+        self._annotation_adapter = MultimodalSmallAnnotationAdapter(
+            project=self.project,
+            folder=self.folder,
+            item=self.item,
+            controller=self.controller,
+            overwrite=self._overwrite,
+            annotation=annotation,
+        )
+
+    def _set_large_annotation_adapter(self, annotation: dict = None):
+        self._annotation_adapter = MultimodalLargeAnnotationAdapter(
+            project=self.project,
+            folder=self.folder,
+            item=self.item,
+            controller=self.controller,
+            annotation=annotation,
+        )
+
+    @property
+    def annotation_adapter(self) -> BaseMultimodalAnnotationAdapter:
+        if self._annotation_adapter is None:
+            res = self.controller.service_provider.annotations.get_upload_chunks(
+                project=self.project, item_ids=[self.item.id]
+            )
+            small_item = next(iter(res["small"]), None)
+            if small_item:
+                self._set_small_annotation_adapter()
+            else:
+                self._set_large_annotation_adapter()
+        return self._annotation_adapter
+
+    @property
+    def annotation(self):
+        return self.annotation_adapter.annotation
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type:
+            return False
+
+        self.save()
+        return True
+
+    def save(self):
+        if len(json.dumps(self.annotation).encode("utf-8")) > 16 * 1024 * 1024:
+            self._set_large_annotation_adapter(self.annotation)
+        else:
+            self._set_small_annotation_adapter(self.annotation)
+        self._annotation_adapter.save()
+
+    def get_metadata(self):
+        return self.annotation["metadata"]
+
+    def get_component_value(self, component_id: str):
+        return self.annotation_adapter.get_component_value(component_id)
+
+    def set_component_value(self, component_id: str, value: Any):
+        self.annotation_adapter.set_component_value(component_id, value)
+        return self
+
+
 class SAClient(BaseInterfaceFacade, metaclass=TrackableMeta):
     """Create SAClient instance to authorize SDK in a team scope.
     In case of no argument has been provided, SA_TOKEN environmental variable
@@ -3540,3 +3624,107 @@ def set_approval_statuses(
         )
         if response.errors:
             raise AppException(response.errors)
+
+    def item_context(
+        self,
+        path: Union[str, Tuple[NotEmptyStr, NotEmptyStr], Tuple[int, int]],
+        item: Union[NotEmptyStr, int],
+        overwrite: bool = True,
+    ) -> ItemContext:
+        """
+        Creates an `ItemContext` instance for managing item annotations and metadata.
+
+        The function retrieves the specified project and folder based on the given `path`
+        (can be a string path or a tuple of project and folder names/IDs) and locates the
+        item by name or ID. It then returns an `ItemContext` object to handle the annotations
+        of the specified item. Changes to annotations are automatically saved upon exiting
+        the context.
+
+        :param path: Specifies the project and folder containing the item. Can be one of:
+            - A string path, e.g., "project_name/folder_name".
+            - A tuple of strings, e.g., ("project_name", "folder_name").
+            - A tuple of integers (IDs), e.g., (project_id, folder_id).
+        :type path: Union[str, Tuple[str, str], Tuple[int, int]]
+
+        :param item: The name or ID of the item for which the context is being created.
+        :type item: Union[str, int]
+
+        :param overwrite: If `True`, annotations are overwritten during saving. Defaults to `True`.
+            If `False`, raises a `FileChangedError` if the item was modified concurrently.
+        :type overwrite: bool
+
+        :raises AppException: If the provided `path` is invalid or if the item cannot be located.
+
+        :return: An `ItemContext` object to manage the specified item's annotations and metadata.
+        :rtype: ItemContext
+
+        **Examples:**
+
+        Create an `ItemContext` using a string path and item name:
+        ```python
+        with client.item_context("project_name/folder_name", "item_name") as item_context:
+            metadata = item_context.get_metadata()
+            value = item_context.get_component_value("prompts")
+            item_context.set_component_value("prompts", value)
+        ```
+
+        Create an `ItemContext` using a tuple of strings and an item ID:
+        ```python
+        with client.item_context(("project_name", "folder_name"), 12345) as context:
+            metadata = context.get_metadata()
+            print(metadata)
+        ```
+
+        Create an `ItemContext` using a tuple of IDs and an item name:
+        ```python
+        with client.item_context((101, 202), "item_name") as context:
+            value = context.get_component_value("component_id")
+            print(value)
+        ```
+
+        Save annotations automatically after modifying component values:
+        ```python
+        with client.item_context("project_name/folder_name", "item_name", overwrite=True) as context:
+            context.set_component_value("component_id", "new_value")
+        # No need to call .save(), changes are saved automatically on context exit.
+        ```
+
+        Handle exceptions during context execution:
+        ```python
+        from superannotate import FileChangedError
+
+        try:
+            with client.item_context((101, 202), "item_name") as context:
+                context.set_component_value("component_id", "new_value")
+        except FileChangedError as e:
+            print(f"An error occurred: {e}")
+        ```
+        """
+        if isinstance(path, str):
+            project, folder = self.controller.get_project_folder_by_path(path)
+        elif len(path) == 2 and all([isinstance(i, str) for i in path]):
+            project = self.controller.get_project(path[0])
+            folder = self.controller.get_folder(project, path[1])
+        elif len(path) == 2 and all([isinstance(i, int) for i in path]):
+            project = self.controller.get_project_by_id(path[0]).data
+            folder = self.controller.get_folder_by_id(path[1], project.id).data
+        else:
+            raise AppException("Invalid path provided.")
+        if isinstance(item, int):
+            _item = self.controller.get_item_by_id(item_id=item, project=project)
+        else:
+            items = self.controller.items.list_items(project, folder, name=item)
+            if not items:
+                raise AppException("Item not found.")
+            _item = items[0]
+        if project.type != ProjectType.MULTIMODAL:
+            raise AppException(
+                f"The function is not supported for {project.type.name} projects."
+            )
+        return ItemContext(
+            controller=self.controller,
+            project=project,
+            folder=folder,
+            item=_item,
+            overwrite=overwrite,
+        )

src/superannotate/lib/core/__init__.py

@@ -178,6 +178,7 @@ def setup_logging(level=DEFAULT_LOGGING_LEVEL, file_path=LOG_FILE_LOCATION):
     "UploadFileType",
     "Tokenization",
     "ImageAutoAssignEnable",
+    "TemplateState",
 ]
 
 __alL__ = (

src/superannotate/lib/core/enums.py

@@ -174,6 +174,7 @@ class IntegrationTypeEnum(BaseTitledEnum):
     GCP = "gcp", 2
     AZURE = "azure", 3
     CUSTOM = "custom", 4
+    DATABRICKS = "databricks", 5
 
 
 class TrainingStatus(BaseTitledEnum):

src/superannotate/lib/core/exceptions.py

@@ -35,3 +35,9 @@ class PathError(AppException):
     """
     User input Error
     """
+
+
+class FileChangedError(AppException):
+    """
+    User input Error
+    """

src/superannotate/lib/core/service_types.py

@@ -114,6 +114,10 @@ def ok(self):
             return 199 < self.status < 300
         return False
 
+    def raise_for_status(self):
+        if not self.ok:
+            raise AppException(self.error)
+
     @property
     def error(self):
         if self.res_error:

src/superannotate/lib/core/serviceproviders.py

@@ -97,6 +97,18 @@ def get_by_id(self, project_id: int):
     def create(self, entity: entities.ProjectEntity) -> ProjectResponse:
         raise NotImplementedError
 
+    @abstractmethod
+    def attach_editor_template(
+        self, team: entities.TeamEntity, project: entities.ProjectEntity, template: dict
+    ) -> ServiceResponse:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_editor_template(
+        self, team: entities.TeamEntity, project: entities.ProjectEntity
+    ) -> ServiceResponse:
+        raise NotImplementedError
+
     @abstractmethod
     def list(self, condition: Condition = None) -> ProjectListResponse:
         raise NotImplementedError
@@ -346,6 +358,7 @@ async def get_big_annotation(
         project: entities.ProjectEntity,
         item: entities.BaseItemEntity,
         reporter: Reporter,
+        transform_version: str = None,
     ) -> dict:
         raise NotImplementedError
 
@@ -357,6 +370,7 @@ async def list_small_annotations(
         item_ids: List[int],
         reporter: Reporter,
         callback: Callable = None,
+        transform_version: str = None,
     ) -> List[dict]:
         raise NotImplementedError
 
@@ -396,6 +410,7 @@ async def upload_small_annotations(
         project: entities.ProjectEntity,
         folder: entities.FolderEntity,
         items_name_data_map: Dict[str, dict],
+        transform_version: str = None,
     ) -> UploadAnnotationsResponse:
         raise NotImplementedError
 
@@ -407,6 +422,7 @@ async def upload_big_annotation(
         item_id: int,
         data: io.StringIO,
         chunk_size: int,
+        transform_version: str = None,
     ) -> bool:
         raise NotImplementedError
 
@@ -429,6 +445,29 @@ def get_delete_progress(
     def get_schema(self, project_type: int, version: str) -> ServiceResponse:
         raise NotImplementedError
 
+    @abstractmethod
+    def get_item_annotations(
+        self,
+        project: entities.ProjectEntity,
+        folder: entities.FolderEntity,
+        item_id: int,
+        transform_version: str = "llmJsonV2",
+    ) -> ServiceResponse:
+        raise NotImplementedError
+
+    @abstractmethod
+    def set_item_annotations(
+        self,
+        project: entities.ProjectEntity,
+        folder: entities.FolderEntity,
+        item_id: int,
+        data: dict,
+        overwrite: bool,
+        transform_version: str = "llmJsonV2",
+        etag: str = None,
+    ) -> ServiceResponse:
+        raise NotImplementedError
+
 
 class BaseIntegrationService(SuperannotateServiceProvider):
     @abstractmethod