clarifai 11.8.1__py3-none-any.whl → 11.8.3__py3-none-any.whl

clarifai/client/module.py

@@ -1,4 +1,4 @@
-from typing import Dict, Generator
+from typing import Dict, Generator, Optional
 
 from clarifai_grpc.grpc.api import resources_pb2, service_pb2
 
@@ -15,25 +15,26 @@ class Module(Lister, BaseClient):
 
     def __init__(
         self,
-        url: str = None,
-        module_id: str = None,
-        module_version: Dict = {'id': ""},
+        url: Optional[str] = None,
+        module_id: Optional[str] = None,
+        module_version: Dict[str, str] = {'id': ""},
         base_url: str = DEFAULT_BASE,
-        pat: str = None,
-        token: str = None,
-        root_certificates_path: str = None,
+        pat: Optional[str] = None,
+        token: Optional[str] = None,
+        root_certificates_path: Optional[str] = None,
         **kwargs,
     ):
         """Initializes a Module object.
 
         Args:
-            url (str): The URL to initialize the module object.
-            module_id (str): The Module ID to interact with.
-            module_version (dict): The Module Version to interact with.
+            url (Optional[str]): The URL to initialize the module object.
+            module_id (Optional[str]): The Module ID to interact with.
+            module_version (Dict[str, str]): The Module Version to interact with.
+                                           Defaults to {'id': ""} for latest version.
             base_url (str): Base API url. Default "https://api.clarifai.com"
-            pat (str): A personal access token for authentication. Can be set as env var CLARIFAI_PAT.
-            token (str): A session token for authentication. Accepts either a session token or a pat. Can be set as env var CLARIFAI_SESSION_TOKEN.
-            root_certificates_path (str): Path to the SSL root certificates file, used to establish secure gRPC connections.
+            pat (Optional[str]): A personal access token for authentication. Can be set as env var CLARIFAI_PAT.
+            token (Optional[str]): A session token for authentication. Accepts either a session token or a pat. Can be set as env var CLARIFAI_SESSION_TOKEN.
+            root_certificates_path (Optional[str]): Path to the SSL root certificates file, used to establish secure gRPC connections.
             **kwargs: Additional keyword arguments to be passed to the Module.
         """
         if url and module_id:

clarifai/client/nodepool.py

@@ -334,7 +334,9 @@ class Nodepool(Lister, BaseClient):
             f"Runner with ID '{response.runners[0].id}' is created:\n{response.status}"
         )
 
-        dict_response = MessageToDict(response.runners[0], preserving_proto_field_name=True)
+        dict_response = MessageToDict(
+            response.runners[0], preserving_proto_field_name=True, use_integers_for_enums=True
+        )
         kwargs = self.process_response_keys(dict_response, 'runner')
         return Runner.from_auth_helper(auth=self.auth_helper, **kwargs)
 

clarifai/client/pipeline.py

@@ -1,6 +1,6 @@
 import time
 import uuid
-from typing import Dict, List
+from typing import Dict, List, Optional
 
 from clarifai_grpc.grpc.api import resources_pb2, service_pb2
 from clarifai_grpc.grpc.api.status import status_code_pb2
@@ -19,35 +19,35 @@ class Pipeline(Lister, BaseClient):
 
     def __init__(
         self,
-        url: str = None,
-        pipeline_id: str = None,
-        pipeline_version_id: str = None,
-        pipeline_version_run_id: str = None,
-        user_id: str = None,
-        app_id: str = None,
-        nodepool_id: str = None,
-        compute_cluster_id: str = None,
-        log_file: str = None,
+        url: Optional[str] = None,
+        pipeline_id: Optional[str] = None,
+        pipeline_version_id: Optional[str] = None,
+        pipeline_version_run_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        app_id: Optional[str] = None,
+        nodepool_id: Optional[str] = None,
+        compute_cluster_id: Optional[str] = None,
+        log_file: Optional[str] = None,
         base_url: str = DEFAULT_BASE,
-        pat: str = None,
-        token: str = None,
-        root_certificates_path: str = None,
+        pat: Optional[str] = None,
+        token: Optional[str] = None,
+        root_certificates_path: Optional[str] = None,
         **kwargs,
     ):
         """Initializes a Pipeline object.
 
         Args:
-            url (str): The URL to initialize the pipeline object.
-            pipeline_id (str): The Pipeline ID to interact with.
-            pipeline_version_id (str): The Pipeline Version ID to interact with.
-            pipeline_version_run_id (str): The Pipeline Version Run ID. If not provided, a UUID will be generated.
-            user_id (str): The User ID that owns the pipeline.
-            app_id (str): The App ID that contains the pipeline.
-            nodepool_id (str): The Nodepool ID to run the pipeline on.
-            compute_cluster_id (str): The Compute Cluster ID to run the pipeline on.
-            log_file (str): Path to file where logs should be written. If not provided, logs are displayed on console.
+            url (Optional[str]): The URL to initialize the pipeline object.
+            pipeline_id (Optional[str]): The Pipeline ID to interact with.
+            pipeline_version_id (Optional[str]): The Pipeline Version ID to interact with.
+            pipeline_version_run_id (Optional[str]): The Pipeline Version Run ID. If not provided, a UUID will be generated.
+            user_id (Optional[str]): The User ID that owns the pipeline.
+            app_id (Optional[str]): The App ID that contains the pipeline.
+            nodepool_id (Optional[str]): The Nodepool ID to run the pipeline on.
+            compute_cluster_id (Optional[str]): The Compute Cluster ID to run the pipeline on.
+            log_file (Optional[str]): Path to file where logs should be written. If not provided, logs are displayed on console.
             base_url (str): Base API url. Default "https://api.clarifai.com"
-            pat (str): A personal access token for authentication. Can be set as env var CLARIFAI_PAT
+            pat (Optional[str]): A personal access token for authentication. Can be set as env var CLARIFAI_PAT
             token (str): A session token for authentication. Accepts either a session token or a pat. Can be set as env var CLARIFAI_SESSION_TOKEN
             root_certificates_path (str): Path to the SSL root certificates file, used to establish secure gRPC connections.
             **kwargs: Additional keyword arguments to be passed to the Pipeline.

clarifai/client/pipeline_step.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from clarifai.client.base import BaseClient
 from clarifai.client.lister import Lister
 from clarifai.urls.helper import ClarifaiUrlHelper
@@ -9,31 +11,31 @@ class PipelineStep(Lister, BaseClient):
 
     def __init__(
         self,
-        url: str = None,
-        pipeline_step_id: str = None,
-        pipeline_step_version_id: str = None,
-        user_id: str = None,
-        app_id: str = None,
-        pipeline_id: str = None,
+        url: Optional[str] = None,
+        pipeline_step_id: Optional[str] = None,
+        pipeline_step_version_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        app_id: Optional[str] = None,
+        pipeline_id: Optional[str] = None,
         base_url: str = DEFAULT_BASE,
-        pat: str = None,
-        token: str = None,
-        root_certificates_path: str = None,
+        pat: Optional[str] = None,
+        token: Optional[str] = None,
+        root_certificates_path: Optional[str] = None,
         **kwargs,
     ):
         """Initializes a PipelineStep object.
 
         Args:
-            url (str): The URL to initialize the pipeline step object.
-            pipeline_step_id (str): The PipelineStep ID for the PipelineStep to interact with.
-            pipeline_step_version_id (str): The PipelineStep version ID for the PipelineStep to interact with.
-            user_id (str): The User ID for the PipelineStep to interact with.
-            app_id (str): The App ID for the PipelineStep to interact with.
-            pipeline_id (str): The Pipeline ID for the PipelineStep to interact with.
+            url (Optional[str]): The URL to initialize the pipeline step object.
+            pipeline_step_id (Optional[str]): The PipelineStep ID for the PipelineStep to interact with.
+            pipeline_step_version_id (Optional[str]): The PipelineStep version ID for the PipelineStep to interact with.
+            user_id (Optional[str]): The User ID for the PipelineStep to interact with.
+            app_id (Optional[str]): The App ID for the PipelineStep to interact with.
+            pipeline_id (Optional[str]): The Pipeline ID for the PipelineStep to interact with.
             base_url (str): Base API url. Default "https://api.clarifai.com"
-            pat (str): A personal access token for authentication.
-            token (str): A session token for authentication.
-            root_certificates_path (str): Path to the SSL root certificates file.
+            pat (Optional[str]): A personal access token for authentication.
+            token (Optional[str]): A session token for authentication.
+            root_certificates_path (Optional[str]): Path to the SSL root certificates file.
             **kwargs: Additional keyword arguments to be passed to the BaseClient.
         """
         if url:

clarifai/client/search.py

@@ -91,14 +91,21 @@ class Search(Lister, BaseClient):
         )
         Lister.__init__(self, page_size=1000)
 
-    def _get_annot_proto(self, **kwargs):
+    def _get_annot_proto(self, **kwargs) -> resources_pb2.Annotation:
         """Get an Annotation proto message based on keyword arguments.
 
         Args:
-            **kwargs: Keyword arguments specifying the resource.
+            **kwargs: Keyword arguments specifying the annotation data.
+                     Supported keys:
+                     - image_bytes (bytes): Raw image bytes
+                     - image_url (str): URL to an image
+                     - concepts (List[Dict]): List of concept dictionaries
+                     - metadata (Dict): Metadata dictionary
+                     - geo_longitude (float): Geographic longitude
+                     - geo_latitude (float): Geographic latitude
 
         Returns:
-            resources_pb2.Annotation: An Annotation proto message.
+            resources_pb2.Annotation: An Annotation proto message with the specified data.
         """
         if not kwargs:
             return resources_pb2.Annotation()
@@ -139,14 +146,24 @@ class Search(Lister, BaseClient):
                 raise UserError(f"kwargs contain key that is not supported: {key}")
         return resources_pb2.Annotation(data=self.data_proto)
 
-    def _get_input_proto(self, **kwargs):
+    def _get_input_proto(self, **kwargs) -> resources_pb2.Input:
         """Get an Input proto message based on keyword arguments.
 
         Args:
-            **kwargs: Keyword arguments specifying the resource.
+            **kwargs: Keyword arguments specifying the input data.
+                     Supported keys:
+                     - input_types (List[str]): List of input types ('image', 'text', 'audio', 'video')
+                     - dataset_ids (List[str]): List of dataset IDs to filter by
+                     - image_bytes (bytes): Raw image bytes
+                     - image_url (str): URL to an image
+                     - text_raw (str): Raw text content
+                     - concepts (List[Dict]): List of concept dictionaries
+                     - metadata (Dict): Metadata dictionary
+                     - geo_longitude (float): Geographic longitude
+                     - geo_latitude (float): Geographic latitude
 
         Returns:
-            resources_pb2.Input: An Input proto message.
+            resources_pb2.Input: An Input proto message with the specified data.
         """
         if not kwargs:
             return resources_pb2.Input()
@@ -194,15 +211,22 @@ class Search(Lister, BaseClient):
     def _list_topk_generator(
         self, endpoint: Callable[..., Any], proto_message: Any, request_data: Dict[str, Any]
     ) -> Generator[Dict[str, Any], None, None]:
-        """Lists all pages of a resource.
+        """Lists top-k results with pagination support.
+
+        This method handles pagination for search results when top_k is specified,
+        automatically calculating the required number of pages and per-page limits.
 
         Args:
-            endpoint (Callable): The endpoint to call.
-            proto_message (Any): The proto message to use.
-            request_data (dict): The request data to use.
+            endpoint (Callable[..., Any]): The gRPC endpoint method to call for search.
+            proto_message (Any): The protobuf message class for the request.
+            request_data (Dict[str, Any]): The base request data dictionary.
 
         Yields:
-            response_dict: The next item in the listing.
+            Dict[str, Any]: Individual search result items from the API response.
+
+        Raises:
+            UserError: If pagination limits are exceeded or top_k is too large.
+            Exception: If the API request fails.
         """
         max_pages = ceil(self.top_k / self.default_page_size)
         total_hits = 0

clarifai/client/user.py

@@ -1,5 +1,5 @@
 import os
-from typing import Any, Dict, Generator, List
+from typing import Any, Dict, Generator, List, Optional
 
 import yaml
 from clarifai_grpc.grpc.api import resources_pb2, service_pb2
@@ -53,14 +53,17 @@ class User(Lister, BaseClient):
         Lister.__init__(self)
 
     def list_apps(
-        self, filter_by: Dict[str, Any] = {}, page_no: int = None, per_page: int = None
+        self,
+        filter_by: Dict[str, Any] = {},
+        page_no: Optional[int] = None,
+        per_page: Optional[int] = None,
     ) -> Generator[App, None, None]:
         """Lists all the apps for the user.
 
         Args:
-            filter_by (dict): A dictionary of filters to be applied to the list of apps.
-            page_no (int): The page number to list.
-            per_page (int): The number of items per page.
+            filter_by (Dict[str, Any]): A dictionary of filters to be applied to the list of apps.
+            page_no (Optional[int]): The page number to list. If None, lists all pages.
+            per_page (Optional[int]): The number of items per page. If None, uses default.
 
         Yields:
             App: App objects for the user.
@@ -533,6 +536,178 @@ class User(Lister, BaseClient):
         ]
         return f"Clarifai User Details: \n{', '.join(attribute_strings)}\n"
 
+    def get_secret(self, secret_id: str) -> dict:
+        """Returns a secret object if exists.
+
+        Args:
+            secret_id (str): The secret ID to interact with
+
+        Returns:
+            Dict: A dictionary containing information about the existing secret ID.
+
+        Example:
+            >>> from clarifai.client.user import User
+            >>> client = User(user_id="user_id")
+            >>> secret_info = client.get_secret(secret_id="secret_id")
+        """
+        request = service_pb2.GetSecretRequest(user_app_id=self.user_app_id, id=secret_id)
+        response = self._grpc_request(self.STUB.GetSecret, request)
+        if response.status.code != status_code_pb2.SUCCESS:
+            raise Exception(
+                f"""Error getting secret, are you sure this is a valid secret id {secret_id} at the user_id
+          {self.user_app_id.user_id}.
+          Error: {response.status.description}"""
+            )
+
+        dict_response = MessageToDict(response, preserving_proto_field_name=True)
+        kwargs = self.process_response_keys(dict_response["secret"], "secret")
+
+        return dict(auth=self.auth_helper, **kwargs)
+
+    def list_secrets(
+        self, page_no: int = None, per_page: int = None
+    ) -> Generator[dict, None, None]:
+        """List all secrets for the user
+
+        Args:
+            page_no (int): The page number to list.
+            per_page (int): The number of items per page.
+
+        Yields:
+            Dict: Dictionaries containing information about the secrets.
+
+        Example:
+            >>> from clarifai.client.user import User
+            >>> client = User(user_id="user_id")
+            >>> all_secrets = list(client.list_secrets())
+
+        Note:
+            Defaults to 16 per page if page_no is specified and per_page is not specified.
+            If both page_no and per_page are None, then lists all the resources.
+        """
+        request_data = dict(user_app_id=self.user_app_id)
+        all_secrets_info = self.list_pages_generator(
+            self.STUB.ListSecrets,
+            service_pb2.ListSecretsRequest,
+            request_data,
+            per_page=per_page,
+            page_no=page_no,
+        )
+        for secret_info in all_secrets_info:
+            yield dict(auth=self.auth_helper, **secret_info)
+
+    def create_secrets(self, secrets: List[Dict[str, Any]]) -> List[dict]:
+        """Creates secrets for the user.
+
+        Args:
+            secrets (List[Dict[str, Any]]): List of secret configurations to create.
+                Each secret dict can contain:
+                - id (str): The name/ID of the secret (required)
+                - value (str): The secret value (required)
+                - description (str): Optional description of the secret
+                - expires_at (str): Optional expiration timestamp
+
+        Returns:
+            List[Dict]: List of dictionaries containing information about the created secrets.
+
+        Example:
+            >>> from clarifai.client.user import User
+            >>> client = User(user_id="user_id")
+            >>> secrets = [{"id": "secret1", "value": "secret_value", "description": "My Secret"}]
+            >>> created_secrets = client.create_secrets(secrets)
+        """
+        assert isinstance(secrets, list), "secrets param should be a list"
+
+        # Convert dict secrets to protobuf Secret objects
+        secret_objects = []
+        for secret_config in secrets:
+            secret_objects.append(resources_pb2.Secret(**secret_config))
+
+        request = service_pb2.PostSecretsRequest(
+            user_app_id=self.user_app_id, secrets=secret_objects
+        )
+        response = self._grpc_request(self.STUB.PostSecrets, request)
+        if response.status.code != status_code_pb2.SUCCESS:
+            raise Exception(response.status)
+
+        self.logger.info(f"Secrets created successfully:\n{response.status}")
+
+        # Convert response to list of dictionaries
+        dict_response = MessageToDict(response, preserving_proto_field_name=True)
+        created_secrets = []
+        for secret in dict_response.get("secrets", []):
+            kwargs = self.process_response_keys(secret, "secret")
+            created_secrets.append(dict(auth=self.auth_helper, **kwargs))
+
+        return created_secrets
+
+    def patch_secrets(
+        self, secrets: List[Dict[str, Any]], action: str = 'overwrite'
+    ) -> List[dict]:
+        """Patches secrets for the user.
+
+        Args:
+            secrets (List[Dict[str, Any]]): List of secret configurations to patch.
+                Each secret dict should contain:
+                - id (str): The name/ID of the secret to patch (required)
+                - value (str): Optional new secret value
+                - description (str): Optional new description
+                - expires_at (str): Optional new expiration timestamp
+            action (str): The action to perform on the secrets (overwrite/remove).
+
+        Returns:
+            List[Dict]: List of dictionaries containing information about the patched secrets.
+
+        Example:
+            >>> from clarifai.client.user import User
+            >>> client = User(user_id="user_id")
+            >>> secrets = [{"id": "secret1", "description": "Updated Secret Description"}]
+            >>> patched_secrets = client.patch_secrets(secrets, action="overwrite")
+        """
+        assert isinstance(secrets, list), "secrets param should be a list"
+
+        # Convert dict secrets to protobuf Secret objects
+        secret_objects = []
+        for secret_config in secrets:
+            secret_objects.append(resources_pb2.Secret(**secret_config))
+
+        request = service_pb2.PatchSecretsRequest(
+            user_app_id=self.user_app_id, secret=secret_objects, action=action
+        )
+        response = self._grpc_request(self.STUB.PatchSecrets, request)
+        if response.status.code != status_code_pb2.SUCCESS:
+            raise Exception(response.status)
+
+        self.logger.info(f"Secrets patched successfully:\n{response.status}")
+
+        # Convert response to list of dictionaries
+        dict_response = MessageToDict(response, preserving_proto_field_name=True)
+        patched_secrets = []
+        for secret in dict_response.get("secrets", []):
+            kwargs = self.process_response_keys(secret, "secret")
+            patched_secrets.append(dict(auth=self.auth_helper, **kwargs))
+
+        return patched_secrets
+
+    def delete_secrets(self, secret_ids: List[str]) -> None:
+        """Deletes a list of secrets for the user.
+
+        Args:
+            secret_ids (List[str]): The secret IDs of the user to delete.
+
+        Example:
+            >>> from clarifai.client.user import User
+            >>> client = User(user_id="user_id")
+            >>> client.delete_secrets(secret_ids=["secret_id1", "secret_id2"])
+        """
+        assert isinstance(secret_ids, list), "secret_ids param should be a list"
+
+        request = service_pb2.DeleteSecretsRequest(user_app_id=self.user_app_id, ids=secret_ids)
+        response = self._grpc_request(self.STUB.DeleteSecrets, request)
+        if response.status.code != status_code_pb2.SUCCESS:
+            raise Exception(response.status)
+        self.logger.info("\nSecrets Deleted\n%s", response.status)
+
     def list_models(
         self,
         user_id: str = None,

clarifai/client/workflow.py

@@ -1,6 +1,6 @@
 import os
 import time
-from typing import Dict, Generator, List
+from typing import Any, Dict, Generator, List, Optional
 
 from clarifai_grpc.grpc.api import resources_pb2, service_pb2
 from clarifai_grpc.grpc.api.resources_pb2 import Input
@@ -25,29 +25,30 @@ class Workflow(Lister, BaseClient):
 
     def __init__(
         self,
-        url: str = None,
-        workflow_id: str = None,
-        workflow_version: Dict = {'id': ""},
-        output_config: Dict = {'min_value': 0},
+        url: Optional[str] = None,
+        workflow_id: Optional[str] = None,
+        workflow_version: Dict[str, str] = {'id': ""},
+        output_config: Dict[str, Any] = {'min_value': 0},
         base_url: str = DEFAULT_BASE,
-        pat: str = None,
-        token: str = None,
-        root_certificates_path: str = None,
+        pat: Optional[str] = None,
+        token: Optional[str] = None,
+        root_certificates_path: Optional[str] = None,
         **kwargs,
     ):
         """Initializes a Workflow object.
 
         Args:
-            url (str): The URL to initialize the workflow object.
-            workflow_id (str): The Workflow ID to interact with.
-            workflow_version (dict): The Workflow Version to interact with.
-            output_config (dict): The output config to interact with.
-              min_value (float): The minimum value of the prediction confidence to filter.
-              max_concepts (int): The maximum number of concepts to return.
-              select_concepts (list[Concept]): The concepts to select.
-              sample_ms (int): The number of milliseconds to sample.
+            url (Optional[str]): The URL to initialize the workflow object.
+            workflow_id (Optional[str]): The Workflow ID to interact with.
+            workflow_version (Dict[str, str]): The Workflow Version to interact with.
+                                              Defaults to {'id': ""} for latest version.
+            output_config (Dict[str, Any]): The output config to interact with.
+              - min_value (float): The minimum value of the prediction confidence to filter.
+              - max_concepts (int): The maximum number of concepts to return.
+              - select_concepts (List[Concept]): The concepts to select.
+              - sample_ms (int): The number of milliseconds to sample.
             base_url (str): Base API url. Default "https://api.clarifai.com"
-            pat (str): A personal access token for authentication. Can be set as env var CLARIFAI_PAT
+            pat (Optional[str]): A personal access token for authentication. Can be set as env var CLARIFAI_PAT
             token (str): A session token for authentication. Accepts either a session token or a pat. Can be set as env var CLARIFAI_SESSION_TOKEN
             root_certificates_path (str): Path to the SSL root certificates file, used to establish secure gRPC connections.
             **kwargs: Additional keyword arguments to be passed to the Workflow.