clarifai 11.7.4__py3-none-any.whl → 11.7.5rc1__py3-none-any.whl

clarifai/client/user.py

@@ -533,6 +533,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/models/model_serving/README.md

@@ -0,0 +1,158 @@
+# Clarifai Model Serving
+
+## Overview
+
+Model Serving is a part of user journey at Clarifai offers a user-friendly interface for deploying your local model into production with Clarifai, featuring:
+
+* A convenient command-line interface (CLI)
+* Easy implementation and testing in Python
+* No need for MLops expertise.
+
+## Quickstart Guide
+
+Quick example for deploying a `text-to-text` model
+
+### Initialize a Clarifai model repository
+
+Suppose your working directory name is `your_model_dir`. Then run
+
+```bash
+$ clarifai create model --type text-to-text --working-dir your_model_dir
+$ cd your_model_dir
+```
+
+In `your_model_dir` folder you will see essential files for deployment process
+
+```bash
+your_model_dir
+├── clarifai_config.yaml
+├── inference.py
+├── test.py
+└── requirements.txt
+```
+
+### Implementation
+
+Write your code in class `InferenceModel` which is an interface between your model and Clarifai server in `inference.py`, there are 2 functions you must implement:
+
+* `__init__`: load your model checkpoint once.
+* `predict`: make prediction, called everytime when you make request from API.
+
+For example, a complete implementation of a hf text-generation model
+
+```python
+import os
+from typing import Dict, Union
+from clarifai.models.model_serving.model_config import *
+
+import torch
+from transformers import AutoTokenizer
+import transformers
+
+class InferenceModel(TextToText):
+  """User model inference class."""
+
+  def __init__(self) -> None:
+    """
+    Load inference time artifacts that are called frequently .e.g. models, tokenizers, etc.
+    in this method so they are loaded only once for faster inference.
+    """
+    # current directory
+    self.base_path = os.path.dirname(__file__)
+    # where you save hf checkpoint in your working dir e.i. `your_model_dir`
+    model_path = os.path.join(self.base_path, "checkpoint")
+    self.tokenizer = AutoTokenizer.from_pretrained(model_path)
+    self.pipeline = transformers.pipeline(
+        "text-generation",
+        model=model_path,
+        torch_dtype=torch.float16,
+        device_map="auto",
+    )
+
+  def predict(self, input_data: list,
+              inference_parameters: Dict[str, Union[str, float, int]]) -> list:
+    """ Custom prediction function for `text-to-text` (also called as `text generation`) model.
+
+    Args:
+      input_data (List[str]): List of text
+      inference_parameters (Dict[str, Union[str, float, int]]): your inference parameters
+
+    Returns:
+      list of TextOutput
+
+    """
+    output_sequences = self.pipeline(
+        input_data,
+        eos_token_id=self.tokenizer.eos_token_id,
+        **inference_parameters)
+
+    # wrap outputs in Clarifai defined output
+    return [TextOutput(each[0]) for each in output_sequences]
+```
+
+Update dependencies in `requirements.txt`
+
+```
+clarifai
+torch=2.1.1
+transformers==4.36.2
+accelerate==0.26.1
+```
+
+### Test (optional)
+
+> NOTE: Running `test` is also involved in `build` and `upload` command.
+
+Test and play with your implementation by executing `test.py`.
+
+Install pytest
+
+```bash
+$ pip install pytest
+```
+
+Execute test
+
+```bash
+$ pytest test.py
+```
+
+### Build
+
+Prepare for deployment step. Run:
+
+```bash
+$ clarifai build model
+```
+
+You will obtain `*.clarifai` file, it's simply a zip having all nessecary files in it to get your model work on Clarifai platform.
+
+`NOTE`: you need to upload your built file to cloud storage to get direct download `url` for next step
+
+### Deployment
+
+Login to Clarifai
+
+```bash
+$ clarifai login
+Get your PAT from https://clarifai.com/settings/security and pass it here: <insert your pat here>
+```
+
+Upload
+
+```bash
+# upload built file directly
+$ clarifai upload model <your-working-dir> --user-app <your_user_id>/<your_app_id> --id <your_model_id>
+# or using direct download url of cloud storage
+$ clarifai upload model --url <url> --user-app <your_user_id>/<your_app_id> --id <your_model_id>
+```
+
+## Learn More
+
+* [Detail Instruction](./docs/concepts.md)
+* [Examples](https://github.com/Clarifai/examples/tree/main/model_upload)
+* [Initialize from example](./docs/cli.md)
+* [CLI usage](./docs/cli.md)
+* [Inference parameters](./docs/inference_parameters.md)
+* [Model Types](./docs/model_types.md)
+* [Dependencies](./docs/dependencies.md)

clarifai/models/model_serving/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2023 Clarifai, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from .model_config import *  # noqa
+from .repo_build import *  # noqa

clarifai/models/model_serving/cli/__init__.py

@@ -0,0 +1,12 @@
+# Copyright 2023 Clarifai, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

clarifai/models/model_serving/cli/_utils.py

@@ -0,0 +1,53 @@
+from __future__ import annotations  # isort: skip
+import os
+import shutil
+import subprocess
+from typing import Dict, Union
+
+from ..constants import (CLARIFAI_EXAMPLES_REPO, CLARIFAI_EXAMPLES_REPO_PATH,
+                         MODEL_UPLOAD_EXAMPLE_FOLDER)
+
+
+def download_examples_repo(forced_download: bool = False):
+
+  def _pull():
+    subprocess.run(f"git clone {CLARIFAI_EXAMPLES_REPO} {CLARIFAI_EXAMPLES_REPO_PATH}", shell=True)
+
+  if not os.path.isdir(CLARIFAI_EXAMPLES_REPO_PATH):
+    print(f"Download examples to {CLARIFAI_EXAMPLES_REPO_PATH}")
+    _pull()
+  else:
+    if forced_download:
+
+      def _rm_dir_readonly(func, path, _):
+        import stat
+        os.chmod(path, stat.S_IWRITE)
+        func(path)
+
+      print("Removing old examples...")
+      shutil.rmtree(CLARIFAI_EXAMPLES_REPO_PATH, onerror=_rm_dir_readonly)
+      _pull()
+
+
+def list_model_upload_examples(
+    forced_download: bool = False) -> Dict[str, tuple[str, Union[str, None]]]:
+  download_examples_repo(forced_download)
+  model_upload_folder = MODEL_UPLOAD_EXAMPLE_FOLDER
+  model_upload_path = os.path.join(CLARIFAI_EXAMPLES_REPO_PATH, model_upload_folder)
+  examples = {}
+  for model_type_ex in os.listdir(model_upload_path):
+    _folder = os.path.join(model_upload_path, model_type_ex)
+    if os.path.isdir(_folder):
+      _walk = list(os.walk(_folder))
+      if len(_walk) > 0:
+        _, model_names, _files = _walk[0]
+        readme = [item for item in _files if "readme" in item.lower()]
+        for name in model_names:
+          examples.update({
+              f"{model_type_ex}/{name}": [
+                  os.path.join(_folder, name),
+                  os.path.join(_folder, readme[0]) or None
+              ]
+          })
+
+  return examples

clarifai/models/model_serving/cli/base.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from argparse import _SubParsersAction
+
+
+class BaseClarifaiCli(ABC):
+
+  @staticmethod
+  @abstractmethod
+  def register(parser: _SubParsersAction):
+    raise NotImplementedError()
+
+  @abstractmethod
+  def run(self):
+    raise NotImplementedError()

clarifai/models/model_serving/cli/build.py

@@ -0,0 +1,79 @@
+# Copyright 2023 Clarifai, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Commandline interface for model upload utils."""
+import argparse
+import os
+import subprocess
+
+from ..repo_build import RepositoryBuilder
+from .base import BaseClarifaiCli
+
+
+class BuildCli(BaseClarifaiCli):
+
+  @staticmethod
+  def register(parser: argparse._SubParsersAction):
+    parser = parser.add_parser("build", help="Build clarifai model for uploading")
+    sub_parser = parser.add_subparsers()
+
+    BuildModelSubCli.register(sub_parser)
+
+    parser.set_defaults(func=BuildCli)
+
+
+class BuildModelSubCli(BaseClarifaiCli):
+
+  @staticmethod
+  def register(parser: argparse._SubParsersAction):
+    sub_parser = parser.add_parser("model", help="Build Clarifai model")
+    sub_parser.add_argument(
+        "path",
+        type=str,
+        nargs='?',
+        help="Path to working directory, default is current directory",
+        default=".")
+    sub_parser.add_argument(
+        "--out-path", type=str, required=False, help="Output path of built model", default=None)
+    sub_parser.add_argument(
+        "--name",
+        type=str,
+        required=False,
+        help="Name of built file, default is `clarifai_model_id` in config if set or `model`",
+        default=None)
+    sub_parser.add_argument(
+        "--no-test",
+        action="store_true",
+        help="Trigger this flag to skip testing before uploading")
+    sub_parser.set_defaults(func=BuildModelSubCli)
+
+  def __init__(self, args: argparse.Namespace) -> None:
+    self.path = args.path
+    self.no_test = args.no_test
+    self.test_path = os.path.join(self.path, "test.py")
+    self.output_path = args.out_path or self.path
+    self.serving_backend = "triton"
+    self.name = args.name
+
+  def run(self):
+
+    # Run test before uploading
+    if not self.no_test:
+      assert os.path.exists(
+          self.test_path), FileNotFoundError(f"Could not find `test.py` in {self.path}")
+      result = subprocess.run(f"pytest -s --log-level=INFO {self.test_path}", shell=True)
+      assert result.returncode == 0, "Test has failed. Please make sure no error exists in your code."
+
+    # build
+    print("Start building...")
+    RepositoryBuilder.build(
+        self.path, backend=self.serving_backend, output_dir=self.output_path, name=self.name)

clarifai/models/model_serving/cli/clarifai_clis.py

@@ -0,0 +1,33 @@
+from argparse import ArgumentParser
+
+from .build import BuildCli
+from .create import CreateCli
+from .example_cli import ExampleCli
+from .login import LoginCli
+from .upload import UploadCli
+
+
+def main():
+
+  parser = ArgumentParser("clarifai")
+  cmd_parser = parser.add_subparsers(help="Clarifai cli helpers")
+
+  UploadCli.register(cmd_parser)
+  CreateCli.register(cmd_parser)
+  LoginCli.register(cmd_parser)
+  ExampleCli.register(cmd_parser)
+  BuildCli.register(cmd_parser)
+
+  args = parser.parse_args()
+
+  if not hasattr(args, "func"):
+    parser.print_help()
+    exit(1)
+
+  # Run
+  service = args.func(args)
+  service.run()
+
+
+if __name__ == "__main__":
+  main()