supervisely 6.73.399__py3-none-any.whl → 6.73.400__py3-none-any.whl

supervisely/__init__.py

@@ -127,6 +127,7 @@ from supervisely.api.workspace_api import WorkspaceInfo
 from supervisely.api.team_api import TeamInfo
 from supervisely.api.entity_annotation.figure_api import FigureInfo
 from supervisely.api.app_api import WorkflowSettings, WorkflowMeta
+from supervisely.api.entities_collection_api import EntitiesCollectionInfo
 
 from supervisely.cli import _handle_creds_error_to_console
 

supervisely/api/api.py

@@ -38,6 +38,7 @@ import supervisely.api.agent_api as agent_api
 import supervisely.api.annotation_api as annotation_api
 import supervisely.api.app_api as app_api
 import supervisely.api.dataset_api as dataset_api
+import supervisely.api.entities_collection_api as entities_collection_api
 import supervisely.api.file_api as file_api
 import supervisely.api.github_api as github_api
 import supervisely.api.image_annotation_tool_api as image_annotation_tool_api
@@ -45,9 +46,8 @@ import supervisely.api.image_api as image_api
 import supervisely.api.import_storage_api as import_stoarge_api
 import supervisely.api.issues_api as issues_api
 import supervisely.api.labeling_job_api as labeling_job_api
-import supervisely.api.nn.neural_network_api as neural_network_api
 import supervisely.api.labeling_queue_api as labeling_queue_api
-import supervisely.api.entities_collection_api as entities_collection_api
+import supervisely.api.nn.neural_network_api as neural_network_api
 import supervisely.api.object_class_api as object_class_api
 import supervisely.api.plugin_api as plugin_api
 import supervisely.api.pointcloud.pointcloud_api as pointcloud_api
@@ -297,19 +297,20 @@ class Api:
 
     def __init__(
         self,
-        server_address: str = None,
-        token: str = None,
+        server_address: Optional[str] = None,
+        token: Optional[str] = None,
         retry_count: Optional[int] = 10,
         retry_sleep_sec: Optional[int] = None,
         external_logger: Optional[Logger] = None,
-        ignore_task_id: Optional[bool] = False,
-        api_server_address: str = None,
+        ignore_task_id: bool = False,
+        api_server_address: Optional[str] = None,
         check_instance_version: Union[bool, str] = False,
     ):
         self.logger = external_logger or logger
 
-        if server_address is None and token is None:
+        if server_address is None:
             server_address = os.environ.get(SERVER_ADDRESS, None)
+        if token is None:
             token = os.environ.get(API_TOKEN, None)
 
         if server_address is None:

supervisely/api/app_api.py

@@ -1723,7 +1723,7 @@ class AppApi(TaskApi):
             users_ids = [users_id]
 
         new_params = {}
-        if "state" not in params:
+        if params is not None and "state" not in params:
             new_params["state"] = params
         else:
             new_params = params
@@ -1833,6 +1833,23 @@ class AppApi(TaskApi):
             raise ValueError(f"Multiple serving apps found for app name {app_name}")
         return modules[0]["id"]
 
+    def get_session_token(self, slug: str) -> str:
+        """
+        Get session token for the app with specified slug.
+
+        :param slug: Slug of the app, e.g. "supervisely-ecosystem/hello-world-app".
+        :type slug: str
+
+        :return: Session token for the app.
+        :rtype: str
+        """
+        data = {ApiField.SLUG: slug}
+        response = self._api.post(
+            "instance.get-render-previews-session-token",
+            data,
+        )
+        return response.text
+
 
 # info about app in team
 # {

supervisely/api/entities_collection_api.py

@@ -4,7 +4,10 @@
 # docs
 from __future__ import annotations
 
-from typing import Dict, List, NamedTuple, Optional
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Dict, List, NamedTuple, Optional, Union
+
+import requests
 
 from supervisely.api.module_api import (
     ApiField,
@@ -14,16 +17,152 @@ from supervisely.api.module_api import (
 )
 from supervisely.sly_logger import logger
 
+if TYPE_CHECKING:
+    from supervisely.api.api import Api
+    from supervisely.api.image_api import ImageInfo
+
+
+class CollectionType:
+    DEFAULT = "default"
+    AI_SEARCH = "aiSearch"
+    ALL = "all"
+
+
+class CollectionTypeFilter:
+    AI_SEARCH = "entities_ai_search_collection"
+    DEFAULT = "entities_collection"
+
+
+class AiSearchThresholdDirection:
+    ABOVE = "above"
+    BELOW = "below"
+
+
+@dataclass
+class CollectionItem:
+    """
+    Collection item with meta information.
+
+    :param entity_id: Supervisely ID of the item.
+    :type entity_id: int
+    :param meta: Meta information about the item. Optional, defaults to None.
+    :type meta: :class:`CollectionItem.Meta`, optional
+    """
+
+    @dataclass
+    class Meta:
+        """
+        Meta information about the item.
+
+        :param score: Score value of the item that indicates search relevance.
+        :type score: float
+        """
+
+        score: Optional[float] = 0.0
+
+        def to_json(self) -> dict:
+            """
+            Convert meta information to a JSON-compatible dictionary.
+
+            :return: Dictionary with meta information.
+            :rtype: dict
+            """
+            return {ApiField.SCORE: self.score}
+
+        @classmethod
+        def from_json(cls, data: dict) -> "CollectionItem.Meta":
+            """
+            Create Meta from a JSON-compatible dictionary.
+
+            :param data: Dictionary with meta information.
+            :type data: dict
+            :return: Meta object.
+            :rtype: CollectionItem.Meta
+            """
+            return cls(score=data.get(ApiField.SCORE, 0.0))
+
+    entity_id: int
+    meta: Optional[Meta] = None
+
+    def to_json(self) -> dict:
+        """
+        Convert collection item to a JSON-compatible dictionary.
+
+        :return: Dictionary with collection item data.
+        :rtype: dict
+        """
+        result = {ApiField.ENTITY_ID: self.entity_id}
+        if self.meta is not None:
+            result[ApiField.META] = self.meta.to_json()
+        return result
+
+    @classmethod
+    def from_json(cls, data: dict) -> "CollectionItem":
+        """
+        Create CollectionItem from a JSON-compatible dictionary.
+
+        :param data: Dictionary with collection item data.
+        :type data: dict
+        :return: CollectionItem object.
+        :rtype: CollectionItem
+        """
+        meta_data = data.get(ApiField.META)
+        meta = cls.Meta.from_json(meta_data) if meta_data is not None else None
+        return cls(entity_id=data[ApiField.ENTITY_ID], meta=meta)
+
 
 class EntitiesCollectionInfo(NamedTuple):
+    """
+    Object with entitites collection parameters from Supervisely.
+
+    :Example:
+
+     .. code-block:: python
+
+        EntitiesCollectionInfo(
+            id=1,
+            team_id=2,
+            project_id=3,
+            name="collection_name",
+            created_at="2023-01-01T00:00:00Z",
+            updated_at="2023-01-02T00:00:00Z",
+            description="This is a collection",
+            options={"key": "value"},
+            type="default",
+            ai_search_key="search_key"
+        )
+    """
+
+    #: ID of the collection.
     id: int
+
+    #: Name of the collection.
     name: str
+
+    #: ID of the team.
     team_id: int
+
+    #: ID of the project.
     project_id: int
-    description: str
+
+    #: Date and time when the collection was created.
     created_at: str
+
+    #: Date and time when the collection was last updated.
     updated_at: str
 
+    #: Description of the collection.
+    description: Optional[str] = None
+
+    #: Additional options for the collection.
+    options: Dict[str, Union[str, int, bool]] = None
+
+    #: Type of the collection.
+    type: str = CollectionType.DEFAULT
+
+    #: AI search key for the collection.
+    ai_search_key: Optional[str] = None
+
 
 class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
     """
@@ -76,23 +215,72 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
             ApiField.NAME,
             ApiField.TEAM_ID,
             ApiField.PROJECT_ID,
-            ApiField.DESCRIPTION,
             ApiField.CREATED_AT,
             ApiField.UPDATED_AT,
+            ApiField.DESCRIPTION,
+            ApiField.OPTIONS,
+            ApiField.TYPE,
+            ApiField.AI_SEARCH_KEY,
         ]
 
     @staticmethod
     def info_tuple_name():
         """
-        NamedTuple name - **EntitiesCollectionInfo**.
+        Get string name of :class:`EntitiesCollectionInfo` NamedTuple.
+
+        :return: NamedTuple name.
+        :rtype: :class:`str`
         """
         return "EntitiesCollectionInfo"
 
-    def __init__(self, api):
+    def __init__(self, api: Api):
         ModuleApi.__init__(self, api)
+        self._api = api
+
+    def _convert_json_info(self, info: dict, skip_missing=True) -> EntitiesCollectionInfo:
+        """
+        Differs from the original method by using skip_missing equal to True by default.
+        Also unpacks 'meta' field to top level for fields in info_sequence.
+        """
+
+        def _get_value(dict, field_name, skip_missing):
+            if skip_missing is True:
+                return dict.get(field_name, None)
+            else:
+                return dict[field_name]
+
+        if info is None:
+            return None
+        else:
+            field_values = []
+            meta = info.get("meta", {})
+
+            for field_name in self.info_sequence():
+                if type(field_name) is str:
+                    # Try to get from meta first if the field exists there
+                    if field_name in meta:
+                        field_values.append(meta.get(field_name))
+                    else:
+                        field_values.append(_get_value(info, field_name, skip_missing))
+                elif type(field_name) is tuple:
+                    value = None
+                    for sub_name in field_name[0]:
+                        if value is None:
+                            value = _get_value(info, sub_name, skip_missing)
+                        else:
+                            value = _get_value(value, sub_name, skip_missing)
+                    field_values.append(value)
+                else:
+                    raise RuntimeError("Can not parse field {!r}".format(field_name))
+            return self.InfoType(*field_values)
 
     def create(
-        self, project_id: int, name: str, description: Optional[str] = None
+        self,
+        project_id: int,
+        name: str,
+        description: Optional[str] = None,
+        type: str = CollectionType.DEFAULT,
+        ai_search_key: Optional[str] = None,
     ) -> EntitiesCollectionInfo:
         """
         Creates Entities Collections.
@@ -103,6 +291,10 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
         :type name: str
         :param description: Entities Collection description.
         :type description: str
+        :param type: Type of the collection. Defaults to "default".
+        :type type: str
+        :param ai_search_key: AI search key for the collection. Defaults to None.
+        :type ai_search_key: Optional[str]
         :return: Information about new Entities Collection
         :rtype: :class:`EntitiesCollectionInfo`
         :Usage example:
@@ -115,28 +307,77 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
             os.environ['API_TOKEN'] = 'Your Supervisely API Token'
             api = sly.Api.from_env()
 
-            user_name = 'Collection #1'
-            project_id = 602
-            new_collection = api.entities_collection.create(name, project_id)
+            project_id = 123
+            name = "Chihuahuas"
+            description = "Collection of Chihuahuas"
+            type = CollectionType.AI_SEARCH
+            ai_search_key = "0ed6a5256433bbe32822949d563d476a"
+
+            new_collection = api.entities_collection.create(project_id, name, description, type, ai_search_key)
             print(new_collection)
         """
-
-        data = {ApiField.NAME: name, ApiField.PROJECT_ID: project_id}
+        method = "entities-collections.add"
+        data = {
+            ApiField.PROJECT_ID: project_id,
+            ApiField.NAME: name,
+            ApiField.TYPE: type,
+        }
         if description is not None:
             data[ApiField.DESCRIPTION] = description
-        response = self._api.post("entities-collections.add", data)
+        if ai_search_key is not None:
+            if type != CollectionType.AI_SEARCH:
+                raise ValueError(
+                    "ai_search_key is only available for creation AI Search collection type."
+                )
+            if ApiField.META not in data:
+                data[ApiField.META] = {}
+            data[ApiField.META][ApiField.AI_SEARCH_KEY] = ai_search_key
+        elif type == CollectionType.AI_SEARCH:
+            raise ValueError("ai_search_key is required for AI Search collection type.")
+        response = self._api.post(method, data)
         return self._convert_json_info(response.json())
 
+    def remove(self, id: int, force: bool = False):
+        """
+        Remove Entites Collection with the specified ID from the Supervisely server.
+
+        If `force` is set to True, the collection will be removed permanently.
+        If `force` is set to False, the collection will be disabled instead of removed.
+
+        :param id: Entites Collection ID in Supervisely
+        :type id: int
+        :param force: If True, the collection will be removed permanently. Defaults to False.
+        :type force: bool
+        :return: None
+        """
+        self._api.post(
+            self._remove_api_method_name(), {ApiField.ID: id, ApiField.HARD_DELETE: force}
+        )
+
     def get_list(
         self,
         project_id: int,
         filters: Optional[List[Dict[str, str]]] = None,
+        with_meta: bool = False,
+        collection_type: CollectionType = CollectionType.DEFAULT,
     ) -> List[EntitiesCollectionInfo]:
         """
         Get list of information about Entities Collection for the given project.
 
         :param project_id: Project ID in Supervisely.
         :type project_id: int, optional
+        :param filters: List of filters to apply to the request. Optional, defaults to None.
+        :type filters: List[Dict[str, str]], optional
+        :param with_meta: If True, includes meta information in the response. Defaults to False.
+        :type with_meta: bool, optional
+        :param collection_type: Type of the collection.
+                    Defaults to CollectionType.DEFAULT.
+
+                    Available types are:
+                     - CollectionType.DEFAULT
+                     - CollectionType.AI_SEARCH
+                     - CollectionType.ALL
+        :type collection_type: CollectionType
         :return: List of information about Entities Collections.
         :rtype: :class:`List[EntitiesCollectionInfo]`
         :Usage example:
@@ -151,19 +392,25 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
 
             collections = api.entities_collection.get_list(4)
         """
-        if filters is None:
-            filters = []
-        return self.get_list_all_pages(
-            "entities-collections.list",
-            {ApiField.PROJECT_ID: project_id, ApiField.FILTER: filters},
-        )
-
-    def get_info_by_id(self, id: int) -> EntitiesCollectionInfo:
+        method = "entities-collections.list"
+
+        data = {
+            ApiField.PROJECT_ID: project_id,
+            ApiField.FILTER: filters or [],
+            ApiField.TYPE: collection_type,
+        }
+        if with_meta:
+            data.update({ApiField.EXTRA_FIELDS: [ApiField.META]})
+        return self.get_list_all_pages(method, data)
+
+    def get_info_by_id(self, id: int, with_meta: bool = False) -> EntitiesCollectionInfo:
         """
         Get information about Entities Collection with given ID.
 
         :param id: Entities Collection ID in Supervisely.
         :type id: int
+        :param with_meta: If True, includes meta information in the response. Defaults to False.
+        :type with_meta: bool, optional
         :return: Information about Entities Collection.
         :rtype: :class:`EntitiesCollectionInfo`
         :Usage example:
@@ -189,7 +436,66 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
             #     "updatedAt": "2018-08-21T14:25:56.140Z"
             # }
         """
-        return self._get_info_by_id(id, "entities-collections.info")
+        method = "entities-collections.info"
+        if with_meta:
+            extra_fields = [ApiField.META]
+        else:
+            extra_fields = None
+        return self._get_info_by_id(id, method, extra_fields)
+
+    def get_info_by_ai_search_key(
+        self, project_id: int, ai_search_key: str
+    ) -> Optional[EntitiesCollectionInfo]:
+        """
+        Get information about Entities Collection of type `CollectionType.AI_SEARCH` with given AI search key.
+
+        :param project_id: Project ID in Supervisely.
+        :type project_id: int
+        :param ai_search_key: AI search key for the collection.
+        :type  ai_search_key: str
+        :return: Information about Entities Collection.
+        :rtype: :class:`EntitiesCollectionInfo`
+        :Usage example:
+         .. code-block:: python
+            import supervisely as sly
+            os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
+            os.environ['API_TOKEN'] = 'Your Supervisely API Token'
+            api = sly.Api.from_env()
+            project_id = 123
+            ai_search_key = "0ed6a5256433bbe32822949d563d476a"
+
+            # Get collection by AI search key
+            collection = api.entities_collection.get_info_by_ai_search_key(project_id, ai_search_key)
+        """
+        collections = self.get_list(
+            project_id=project_id,
+            with_meta=True,
+            collection_type=CollectionType.AI_SEARCH,
+        )
+        return next(
+            (collection for collection in collections if collection.ai_search_key == ai_search_key),
+            None,
+        )
+
+    def _get_response_by_id(self, id, method, id_field, extra_fields=None):
+        """Differs from the original method by using extra_fields."""
+        try:
+            data = {id_field: id}
+            if extra_fields is not None:
+                data.update({ApiField.EXTRA_FIELDS: extra_fields})
+            return self._api.post(method, data)
+        except requests.exceptions.HTTPError as error:
+            if error.response.status_code == 404:
+                return None
+            else:
+                raise error
+
+    def _get_info_by_id(self, id, method, extra_fields=None):
+        """_get_info_by_id"""
+        response = self._get_response_by_id(
+            id, method, id_field=ApiField.ID, extra_fields=extra_fields
+        )
+        return self._convert_json_info(response.json()) if (response is not None) else None
 
     def _get_update_method(self):
         """ """
@@ -199,23 +505,22 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
         """ """
         return "entities-collections.remove"
 
-    def _get_update_method(self):
-        """ """
-        return "entities-collections.editInfo"
-
-    def add_items(self, id: int, items: List[int]) -> List[Dict[str, int]]:
+    def add_items(self, id: int, items: List[Union[int, CollectionItem]]) -> List[Dict[str, int]]:
         """
         Add items to Entities Collection.
 
         :param id: Entities Collection ID in Supervisely.
         :type id: int
-        :param items: List of item IDs in Supervisely.
-        :type items: List[int]
+        :param items: List of items to add to the collection. Could be a list of entity IDs (int) or CollectionItem objects.
+        :type items: List[Union[int, CollectionItem]]
+        :return: List of added items with their IDs and creation timestamps.
+        :rtype: List[Dict[str, int]]
         :Usage example:
 
          .. code-block:: python
 
             import supervisely as sly
+            from supervisely.api.entities_collection_api import CollectionItem
 
             os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
             os.environ['API_TOKEN'] = 'Your Supervisely API Token'
@@ -223,14 +528,24 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
 
             collection_id = 2
             item_ids = [525, 526]
-            new_items = api.entities_collection.add_items(collection_id, item_ids)
+            items = [CollectionItem(entity_id=item_id) for item_id in item_ids]
+            new_items = api.entities_collection.add_items(collection_id, items)
             print(new_items)
             # Output: [
             #   {"id": 1, "entityId": 525, 'createdAt': '2025-04-10T08:49:41.852Z'},
             #   {"id": 2, "entityId": 526, 'createdAt': '2025-04-10T08:49:41.852Z'}
             ]
         """
-        data = {ApiField.COLLECTION_ID: id, ApiField.ENTITY_IDS: items}
+        if all(isinstance(item, int) for item in items):
+            data = {ApiField.COLLECTION_ID: id, ApiField.ENTITY_IDS: items}
+        elif all(isinstance(item, CollectionItem) for item in items):
+            items = [item.to_json() for item in items]
+            data = {ApiField.COLLECTION_ID: id, ApiField.ENTITY_ITEMS: items}
+        else:
+            raise ValueError(
+                "Items list must contain only integers or only CollectionItem instances, not a mix."
+            )
+
         response = self._api.post("entities-collections.items.bulk.add", data)
         response = response.json()
         if len(response["missing"]) > 0:
@@ -239,16 +554,29 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
             )
         return response["items"]
 
-    def get_items(self, id: int, project_id: Optional[int] = None) -> List[int]:
+    def get_items(
+        self,
+        collection_id: int,
+        collection_type: CollectionTypeFilter,
+        project_id: Optional[int] = None,
+        ai_search_threshold: Optional[float] = None,
+        ai_search_threshold_direction: AiSearchThresholdDirection = AiSearchThresholdDirection.ABOVE,
+    ) -> List[ImageInfo]:
         """
         Get items from Entities Collection.
 
-        :param id: Entities Collection ID in Supervisely.
-        :type id: int
+        :param collection_id: Entities Collection ID in Supervisely.
+        :type collection_id: int
+        :param collection_type: Type of the collection. Can be CollectionTypeFilter.AI_SEARCH or CollectionTypeFilter.DEFAULT.
+        :type collection_type: CollectionTypeFilter
         :param project_id: Project ID in Supervisely.
         :type project_id: int, optional
-        :return: List of item IDs in Supervisely.
-        :rtype: List[int]
+        :param ai_search_threshold: AI search threshold for filtering items. Optional, defaults to None.
+        :type ai_search_threshold: float, optional
+        :param ai_search_threshold_direction: Direction for the AI search threshold. Optional, defaults to 'above'.
+        :type ai_search_threshold_direction: str
+        :return: List of ImageInfo objects.
+        :rtype: List[ImageInfo]
         :raises RuntimeError: If Entities Collection with given ID not found.
         :Usage example:
 
@@ -266,12 +594,24 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
             print(item_ids)
         """
         if project_id is None:
-            info = self.get_info_by_id(id)
+            info = self.get_info_by_id(collection_id)
             if info is None:
-                raise RuntimeError(f"Entities Collection with id={id} not found.")
+                raise RuntimeError(f"Entities Collection with id={collection_id} not found.")
             project_id = info.project_id
 
-        return self._api.image.get_list(project_id=project_id, entities_collection_id=id)
+        if collection_type == CollectionTypeFilter.AI_SEARCH:
+            return self._api.image.get_list(
+                project_id=project_id,
+                ai_search_collection_id=collection_id,
+                extra_fields=[ApiField.EMBEDDINGS_UPDATED_AT],
+                ai_search_threshold=ai_search_threshold,
+                ai_search_threshold_direction=ai_search_threshold_direction,
+            )
+        else:
+            return self._api.image.get_list(
+                project_id=project_id,
+                entities_collection_id=collection_id,
+            )
 
     def remove_items(self, id: int, items: List[int]) -> List[Dict[str, int]]:
         """
@@ -279,7 +619,7 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
 
         :param id: Entities Collection ID in Supervisely.
         :type id: int
-        :param items: List of item IDs in Supervisely.
+        :param items: List of entity IDs in Supervisely, e.g. image IDs etc.
         :type items: List[int]
         :Usage example:
 
@@ -294,8 +634,10 @@ class EntitiesCollectionApi(UpdateableModule, RemoveableModuleApi):
             # print(removed_items)
             # Output: [{"id": 1, "entityId": 525}, {"id": 2, "entityId": 526}]
         """
+        method = "entities-collections.items.bulk.remove"
+
         data = {ApiField.COLLECTION_ID: id, ApiField.ENTITY_IDS: items}
-        response = self._api.post("entities-collections.items.bulk.remove", data)
+        response = self._api.post(method, data)
         response = response.json()
         if len(response["missing"]) > 0:
             logger.warning(