clarifai 10.0.0__py3-none-any.whl → 10.1.0__py3-none-any.whl

clarifai/models/model_serving/cli/login.py

@@ -0,0 +1,26 @@
+import argparse
+
+from ..constants import CLARIFAI_PAT_PATH
+from ..utils import _persist_pat
+from .base import BaseClarifaiCli
+
+
+class LoginCli(BaseClarifaiCli):
+
+  @staticmethod
+  def register(parser: argparse._SubParsersAction):
+    upload_parser = parser.add_parser("login", help="Login to Clarifai and save PAT locally")
+    upload_parser.set_defaults(func=LoginCli)
+
+  def __init__(self, args: argparse.Namespace) -> None:
+    pass
+
+  def _parse_config(self):
+    # do something with self.config_path
+    raise NotImplementedError()
+
+  def run(self):
+    msg = "Get your PAT from https://clarifai.com/settings/security and pass it here: "
+    _pat = input(msg)
+    _persist_pat(_pat)
+    print(f"Your PAT is saved at {CLARIFAI_PAT_PATH}")

clarifai/models/model_serving/cli/upload.py

@@ -0,0 +1,182 @@
+# 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 typing import Union
+
+from clarifai.client.auth.helper import ClarifaiAuthHelper
+from clarifai.models.api import Models
+from clarifai.models.model_serving.model_config import (MODEL_TYPES, get_model_config,
+                                                        load_user_config)
+from clarifai.models.model_serving.model_config.inference_parameter import InferParamManager
+
+from ..utils import login
+from .base import BaseClarifaiCli
+
+
+class UploadCli(BaseClarifaiCli):
+
+  @staticmethod
+  def register(parser: argparse._SubParsersAction):
+    creator_parser = parser.add_parser("upload", help="Upload component to Clarifai platform")
+    sub_creator_parser = creator_parser.add_subparsers()
+
+    UploadModelSubCli.register(sub_creator_parser)
+
+    creator_parser.set_defaults(func=UploadCli)
+
+
+class UploadModelSubCli(BaseClarifaiCli):
+
+  @staticmethod
+  def register(parser: argparse._SubParsersAction):
+    upload_parser = parser.add_parser("model", help="Upload Clarifai model")
+    upload_parser.add_argument(
+        "path",
+        type=str,
+        nargs='?',
+        help=
+        "Path to working dir to get clarifai_config.yaml or path to yaml. Default is current directory",
+        default=".")
+    upload_parser.add_argument(
+        "--url", type=str, required=True, help="Direct download url of zip file")
+    upload_parser.add_argument("--id", type=str, required=False, help="Model ID")
+    upload_parser.add_argument(
+        "--user-app",
+        type=str,
+        required=False,
+        help="User ID and App ID separated by '/', e.g., <user_id>/<app_id>")
+    upload_parser.add_argument(
+        "--no-test",
+        action="store_true",
+        help="Trigger this flag to skip testing before uploading")
+
+    upload_parser.add_argument(
+        "--update-version",
+        action="store_true",
+        required=False,
+        help="Update exist model with new version")
+
+    upload_parser.set_defaults(func=UploadModelSubCli)
+
+  def __init__(self, args: argparse.Namespace) -> None:
+    self.no_test = args.no_test
+
+    working_dir_or_config = args.path
+    # if input a config file, then not running test
+    if working_dir_or_config.endswith(".yaml"):
+      config_yaml_path = working_dir_or_config
+      self.test_path = None
+      self.no_test = True
+    # if it is a directory - working dir then it must contain config and test
+    else:
+      config_yaml_path = os.path.join(working_dir_or_config, "clarifai_config.yaml")
+      self.test_path = os.path.join(working_dir_or_config, "test.py")
+
+    assert os.path.exists(config_yaml_path), FileNotFoundError(
+        f"`{config_yaml_path}` does not exist")
+    self.config = load_user_config(cfg_path=config_yaml_path)
+
+    self.user_id, self.app_id = "", ""
+    user_app = args.user_app
+    self.url: str = args.url
+    self.update_version = args.update_version
+    assert self.url.startswith("http") or self.url.startswith(
+        "s3"), f"Invalid url supported http or s3 url. Got {self.url}"
+
+    clarifai_cfg = self.config.clarifai_model
+    self.url: str = args.url
+    self.id = args.id or clarifai_cfg.clarifai_model_id
+    self.type = clarifai_cfg.type
+    self.desc = clarifai_cfg.description
+    self.infer_param = clarifai_cfg.inference_parameters
+    user_app = user_app or clarifai_cfg.clarifai_user_app_id
+
+    if user_app:
+      user_app = user_app.split('/')
+      assert len(
+          user_app
+      ) == 2, f"id must be combination of user_id and app_id separated by `/`, e.g. <user_id>/<app_id>. Got {args.id}"
+      self.user_id, self.app_id = user_app
+
+    if self.user_id:
+      os.environ["CLARIFAI_USER_ID"] = self.user_id
+    if self.app_id:
+      os.environ["CLARIFAI_APP_ID"] = self.app_id
+
+    _user_id = os.environ.get("CLARIFAI_USER_ID", None)
+    _app_id = os.environ.get("CLARIFAI_APP_ID", None)
+    assert _user_id or _app_id, f"Missing user-id or app-id, got user-id {_user_id} and app-id {_app_id}"
+    login()
+
+  def run(self):
+
+    # Run test before uploading
+    if not self.no_test:
+      assert os.path.exists(self.test_path), FileNotFoundError(f"Not found {self.test_path}")
+      result = subprocess.run(f"pytest -s --log-level=INFO {self.test_path}")
+      assert result.returncode == 0, "Test has failed. Please make sure no error exists in your code."
+
+    deploy(
+        model_url=self.url,
+        model_id=self.id,
+        desc=self.desc,
+        model_type=self.type,
+        update_version=self.update_version,
+        inference_parameters=self.infer_param)
+
+
+def deploy(model_url,
+           model_id: str = None,
+           model_type: str = None,
+           desc: str = "",
+           update_version: bool = False,
+           inference_parameters: Union[dict, str] = None):
+  # init Auth from env vars
+  auth = ClarifaiAuthHelper.from_env()
+  # init api
+  model_api = Models(auth)
+  # key map
+  assert model_type in MODEL_TYPES, f"model_type should be one of {MODEL_TYPES}"
+  clarifai_key_map = get_model_config(model_type=model_type).clarifai_model.field_maps
+  # inference parameters
+  if isinstance(inference_parameters, str) and os.path.isfile(inference_parameters):
+    inference_parameters = InferParamManager(json_path=inference_parameters).get_list_params()
+  # if updating new version of existing model
+  if update_version:
+    resp = model_api.post_model_version(
+        model_id=model_id,
+        model_zip_url=model_url,
+        input=clarifai_key_map.input_fields_map,
+        outputs=clarifai_key_map.output_fields_map,
+        param_specs=inference_parameters)
+  # creating new model
+  else:
+    # post model
+    resp = model_api.upload_model(
+        model_id=model_id,
+        model_zip_url=model_url,
+        model_type=model_type,
+        input=clarifai_key_map.input_fields_map,
+        outputs=clarifai_key_map.output_fields_map,
+        description=desc,
+        param_specs=inference_parameters)
+  # response
+  if resp["status"]["code"] != "SUCCESS":
+    raise Exception("Post models failed, details: {}, {}".format(resp["status"]["description"],
+                                                                 resp["status"]["details"]))
+  else:
+    print("Success!")
+    print(f'Model version: {resp["model"]["model_version"]["id"]}')

clarifai/models/model_serving/constants.py

@@ -1 +1,21 @@
+import os
+
 MAX_HW_DIM = 1024
+IMAGE_TENSOR_NAME = "image"
+TEXT_TENSOR_NAME = "text"
+
+BUILT_MODEL_EXT = ".clarifai"
+
+default_home = os.path.join(os.path.expanduser("~"), ".cache")
+CLARIFAI_HOME = os.path.expanduser(
+    os.getenv(
+        "CLARIFAI_HOME",
+        os.path.join(os.getenv("XDG_CACHE_HOME", default_home), "clarifai"),
+    ))
+os.makedirs(CLARIFAI_HOME, exist_ok=True)
+CLARIFAI_PAT_PATH = os.path.join(CLARIFAI_HOME, "pat")
+
+CLARIFAI_EXAMPLES_REPO = "https://github.com/Clarifai/examples.git"
+repo_name = CLARIFAI_EXAMPLES_REPO.split("/")[-1].replace(".git", "")
+CLARIFAI_EXAMPLES_REPO_PATH = os.path.join(CLARIFAI_HOME, repo_name)
+MODEL_UPLOAD_EXAMPLE_FOLDER = "model_upload"

clarifai/models/model_serving/docs/cli.md

@@ -0,0 +1,150 @@
+# CLI helpers
+
+Supported cli:
+
+```bash
+$ clarifai -h
+upload              Upload component to Clarifai platform
+create              Create component of Clarifai platform
+login               Login to Clarifai and save PAT locally
+example             Download/List examples of model upload
+build               Build clarifai model for uploading
+```
+
+1. Login
+
+```bash
+$ clarifai login
+Get your PAT from https://clarifai.com/settings/security and pass it here: <your pat>
+```
+
+2. Create model repository
+
+Initialize template for specify model type in provided directory
+
+* `From scratch`:
+
+```bash
+$ clarifai create model --type <model-type> --working-dir <your_working_dir>
+```
+
+* `From example`:
+
+```bash
+$ clarifai create model --from-example --working-dir <your_working_dir>
+? Select an example:
+❯ multimodal_embedder/clip
+  text_classifier/xlm-roberta
+  text_embedder/instructor-xl
+  ...
+```
+
+Then will see below output
+
+```bash
+---------------------------------------------------------------------------
+* Created repository at: ./<your_working_dir>
+<your_working_dir>
+├── clarifai_config.yaml
+├── inference.py
+├── requirements.txt
+└── test.py
+
+0 directories, 4 files
+
+* Please make sure your code is tested using `test.py` before uploading
+---------------------------------------------------------------------------
+```
+
+> NOTE: if working-dir exists, need to set --overwrite flag otherwise an error arises
+
+Full arguments
+
+```bash
+$ clarifai create model -h
+--working-dir         Path to your working dir. Create new dir if it does not exist
+--from-example        Create repository from example
+--example-id          Example id, run `clarifai example list` to list of examples
+--type                Clarifai supported model types.
+--image-shape         list of H W dims for models with an image input type. H and W each have a max value of 1024
+--max-bs              Max batch size
+--overwrite           Overwrite working-dir if exists
+```
+
+3. See available examples
+
+```bash
+$ clarifai example list
+Found 11 examples
+ * multimodal_embedder/clip
+ * text_classifier/xlm-roberta
+ * text_embedder/instructor-xl
+  ....
+```
+
+4. Build
+
+This step will run `test.py` in provided working dir as default before building
+
+```
+$ clarifai build model <your_working_dir> --name model-name
+$ tree <your_working_dir> -a
+<your_working_dir>
+├── .cache # (*)
+│   ├── 1
+│   │   ├── clarifai_config.yaml
+│   │   ├── inference.py
+│   │   ├── model.py
+│   │   ├── test.py
+│   │   └── ...
+│   ├── config.pbtxt
+│   └── requirements.txt
+├── clarifai_config.yaml
+├── inference.py
+├── model-name.clarifai # (**)
+├── requirements.txt
+├── test.py
+└── ...
+```
+
+**NOTE:**
+
+(*): Build cache, user can simply ignore it.
+
+(**): zipped of .cache
+
+Full arguments
+
+```bash
+$ clarifai build model -h
+positional arguments:
+  path               Path to working directory, default is current directory
+optional arguments:
+--out-path           Output path of built model
+--name               Name of built file, default is `clarifai_model_id` in config if set or`model`
+--no-test            Trigger this flag to skip testing before uploading
+```
+
+5. Upload
+
+This step will run `test.py` in provided working dir as default before building
+
+```bash
+$ clarifai upload model <your_working_dir> --url <your url>
+```
+
+Full arguments
+
+```bash
+$ clarifai upload model -h
+positional arguments:
+  path                  Path to working dir to get clarifai_config.yaml or path to yaml. Default is current directory
+
+optional arguments:
+  --url                 Direct download url of zip file
+  --id                  Model ID
+  --user-app            User ID and App ID separated by '/', e.g., <user_id>/<app_id>
+  --update-version      Update exist model with new version
+  --no-test             Trigger this flag to skip testing before uploading
+
+```

clarifai/models/model_serving/docs/concepts.md

@@ -0,0 +1,229 @@
+# Overview
+
+Model Serving is a straightforward interface that links user model implementations in Python with a high-performance serving framework (tritonserver). It seamlessly integrates with the Clarifai Platform, allowing users to deploy their models without any prerequisites in the serving framework.
+
+```plaintext
+
+|Model code in Python| ---> |Model Serving + Clarifai Platform| ---> |Served model|
+
+```
+
+# Understanding the concepts
+
+While functioning as an interface, it comes with certain constraints that must be adhered to throughout the process.
+
+## Model repository
+
+First of all, the model repository structure obtained by running
+
+```bash
+clarifai create model --type ... --working-dir ...
+```
+
+In your working dir:
+
+```bash
+├── inference.py
+├── clarifai_config.yaml
+├── test.py
+└── requirements.txt
+```
+Where:
+
+* [inference.py](): The crucial file where users need to implement their Python code.
+* [clarifai_config.yaml](): Contains all necessary configurations for model `test`, `build` and `upload`
+* [test.py](): Predefined test cases to evaluate `inference.py`.
+* [requirements.text]():  Equivalent to a normal Python project's requirements.txt.
+
+## inference.py
+Includes the ModelInference class, inherited from one of the Clarifai Models, providing utility wrapper functions and docstring to ensure that customized models work seamlessly within the platform server. The specific Clairfai Model is determined by the --type argument provided by users in the clarifai create model command.
+
+Sample for `text-to-text` model
+
+```python
+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: Path = os.path.dirname(__file__)
+
+  def predict(self, input_data: list,
+              inference_parameters: Dict[str, Union[str, float, int, bool]]) -> 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, bool]]): your inference parameters
+
+    Returns:
+      list of TextOutput
+
+    """
+
+    raise NotImplementedError()
+
+```
+
+Users are required to implement two functions:
+
+* `__init__`: a method to load the model, called once.
+* `predict`: a function designed to generate predictions based on the provided inputs and inference parameters. This method includes a docstring inherited from its parent, providing information on input, parameters, and output types. Refer to the docstring to confirm that the outputs of this method adhere to the correct [Clarifai Output Type](../model_config/output.py), as errors may occur otherwise.
+
+When making predictions through the Clarifai API, user inputs are transmitted to input_data as a List of strings for text input or a List of NumPy arrays for RGB image input, where each array has a shape of [W, H, 3]. Additionally, all inference parameters are conveyed through the inference_parameters argument of the predict method.
+```plaintext
+
+  list of user inputs e.g.              inference parameters e.g.
+  `text-to-text` will be                {'top_k': 5, 'temperature': 0.7, 'do_sample': False, ...}
+  ['text', 'test text',]                   |
+                    |                      |
+                    |                      |
+                    |                      |
+                    v                      v
+def predict(self, input_data:list,  inference_parameters: Dict[str, str | float | int | bool]) -> list:
+  ...
+  # Predict with input data
+  outputs = self.model(input_data, **inference_parameters)
+  # Convert to Clarifai Output Type
+  return [TextOutput(each) for each in outputs]
+                              |
+                              |
+                              |
+                              v
+          Outputs are handled by the module -> platform backend to delivery back to user
+```
+
+For testing the implementation, it's recommended to execute pytest test.py or directly call the predict method of a ModelInference instance.
+
+## clarifai_config.yaml
+
+`yaml` file for essential configs
+
+```yaml
+clarifai_model:
+  clarifai_model_id:
+  clarifai_user_app_id:
+  description:
+  inference_parameters: (*)
+  labels: (*)
+  type: (**)
+serving_backend:
+  triton: (***)
+    max_batch_size:
+    image_shape:
+```
+
+Explanation:
+
+`clarifai_model`: configs for building/testing/uploading process
+
+* `clarifai_model_id` (str, optional): Model ID on the platform.
+* `clarifai_user_app_id` (str, optional): User ID and App ID on the platform seperated by `/` for example `user_1/app_1`.
+* `description` (str, optional): Model description.
+  > These 3 attributes are used to upload model. If not provided, they can be passed in *upload* command.
+
+* (*) `inference_parameters` (List[Dict], optional): inference parameters for your model prediction method. This attribute is used to *test* and *upload* if provided. Two ways to insert it:
+
+  * Manual: Follow this [doc](./inference_parameters.md)
+  * Semi Manual: in *test.py*, init BaseTest with dict of your desired parameters. Learn more about [test.py]()
+
+* (*) `labels` (list): insert manually list of concept names ***required by*** these model types **visual-classifier**, **visual-detector**, **visual-segmenter** and **text-classifier**.
+
+* (**) `type` (str): type of your model, generated when init working dir. ***MUST NOT MODIFY IT***
+
+`serving_backend`: custom config for serving
+
+* `triton`: (optional)
+
+  * `max_batch_size` (int): Maximum number of inputs will go to `predict`. The default value is 1. Since `predict` method receives a list of inputs, if your model supports batch inference, you can set it to a value greater than 1 to leverage high-performance computation on the GPU.
+
+  * `image_shape` (list): Applicable only for image input models. It is a list of the width and height of the input image. The default is [-1, -1], which means it accepts any size.
+  > These 2 attributes can be set when initialize using **clarifai create model** command.
+
+## test.py
+The file is generated when initializing to test InfercenceModel in inference.py.
+
+This test offers two essential features to enhance the testing and validation process:
+
+**1. Implementation Validation**
+
+Prior to initiating the build or upload processes, users can leverage this feature to thoroughly validate their implementation. This ensures the correctness and readiness of the model for deployment.
+
+The test involves the validation of custom configuration in clarifai_config.yaml:
+
+* Confirming that labels are provided for concept-output models.
+* Verifying the format of inference_parameters.
+
+Additionally, it validates the InferenceModel implementation:
+
+* Ensuring the model is loaded correctly.
+* Testing predict with dummy inputs.
+
+**2. Inference Parameter Management**
+
+Users can conveniently add or update inference parameters directly in the clarifai_config.yaml file. Additionally, the system performs automatic validation during the inference, ensuring the accuracy and compatibility of these parameters with the model's requirements. The test ensures **you can only use defined inference parameters with appropriate value**
+
+### file structure
+
+```python
+class CustomTest(unittest.TestCase):
+
+  def setUp(self) -> None:
+    your_infer_parameter = dict()
+    self.model = BaseTest(your_infer_parameter)
+
+  def test_default_cases(self):
+    self.model.test_with_default_inputs()
+
+```
+
+Explanation:
+
+* `your_infer_parameter = dict()`: define your inference parameters as dict with key is parameter name and value is default value of it. For example, define params for hf text-generation model:
+
+```python
+your_infer_parameter = dict(top_p=0.95, temperature=1, return_text=False, prefix="test")
+```
+
+* `self.model = BaseTest(your_infer_parameter)` Loaded implemented model and convert inference parameters to *Clarifai inference parameters` format and save it in `clarifai_config.yaml`. See more [doc](./inference_parameters.md)
+
+* `def test_default_cases(self):` Test your model with dummy input. If these dummy input value fails your model, kindly remove or comment out this function
+
+Define new test:
+
+Create a function with 'test' prefix, see `pytest` document to understand how to make a test case.
+Call predict by `self.model.predict([list of input data], inference_paramters)`. For instance:
+
+* Text input:
+
+```python
+def test_text_input(self):
+  text: list = ["Tell me about Clarifai", "How deploy model to Clarifai"]
+  outputs = self.model.predict(text, temperature=0.9) # In term of inference parameters for the above example, it will PASSED
+  outputs = self.model.predict(text, top_k=10) # And this one will FAILED since `top_k` param is not defined when init self.model
+
+```
+
+* Image input:
+
+```python
+def test_image(self):
+  image = cv2.imread("path/to/image")
+  image = image[:, :, ::-1] # convert to RGB
+  out = self.model.predict([image])
+```
+
+* MultiModal input:
+
+```python
+def test_image_and_text(self):
+  image = cv2.imread("path/to/image")
+  image = image[:, :, ::-1]
+  text = "this is text"
+  input = dict(text=text, image=image)
+  out = self.model.predict([input])
+```

clarifai/models/model_serving/docs/dependencies.md

@@ -5,7 +5,7 @@ An execution environment is created for each model to be deployed on Clarifai an
 
 ## Supported python and torch versions
 
-Currently, models must use python 3.8 (any 3.8.x).  Supported torch versions are 1.13.1 and 2.0.1.
+Currently, models must use python 3.8 (any 3.8.x).  Supported torch versions are 1.13.1, 2.0.1 and 2.1.1.
 If your model depends on torch, torch must be listed in your requirements.txt file (even if it is
 already a dependency of another package).  An appropriate supported torch version will be selected
 based on your requirements.txt.