clarifai 10.3.0__tar.gz → 10.3.1__tar.gz

{clarifai-10.3.0/clarifai.egg-info → clarifai-10.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: clarifai
-Version: 10.3.0
+Version: 10.3.1
 Summary: Clarifai Python SDK
 Home-page: https://github.com/Clarifai/clarifai-python
 Author: Clarifai
@@ -83,6 +83,7 @@ Give the repo a star ⭐
   * [Smart Image Search](#smart-image-search)
   * [Smart Text Search](#smart-text-search)
   * [Filters](#filters)
+  * [Pagination](#pagination)
 * **[Retrieval Augmented Generation (RAG)](#retrieval-augmented-generation-rag)**
 * **[More Examples](#pushpin-more-examples)**
 
@@ -478,6 +479,22 @@ Input filters allows to filter by input_type, status of inputs and by inputs_dat
 results = search.query(filters=[{'input_types': ['image', 'text']}])
 ```
 
+#### Pagination
+
+Below is an example of using Search with Pagination.
+
+```python
+# Note: CLARIFAI_PAT must be set as env variable.
+from clarifai.client.search import Search
+search = Search(user_id="user_id", app_id="app_id", metric="cosine", pagination=True)
+
+# Search by image url
+results = search.query(ranks=[{"image_url": "https://samples.clarifai.com/metro-north.jpg"}],page_no=2,per_page=5)
+
+for data in results:
+  print(data.hits[0].input.data.image.url)
+```
+
 ## Retrieval Augmented Generation (RAG)
 
 You can setup and start your RAG pipeline in 4 lines of code. The setup method automatically creates a new app and the necessary components under the hood. By default it uses the [mistral-7B-Instruct](https://clarifai.com/mistralai/completion/models/mistral-7B-Instruct) model.

{clarifai-10.3.0 → clarifai-10.3.1}/README.md

@@ -48,6 +48,7 @@ Give the repo a star ⭐
   * [Smart Image Search](#smart-image-search)
   * [Smart Text Search](#smart-text-search)
   * [Filters](#filters)
+  * [Pagination](#pagination)
 * **[Retrieval Augmented Generation (RAG)](#retrieval-augmented-generation-rag)**
 * **[More Examples](#pushpin-more-examples)**
 
@@ -443,6 +444,22 @@ Input filters allows to filter by input_type, status of inputs and by inputs_dat
 results = search.query(filters=[{'input_types': ['image', 'text']}])
 ```
 
+#### Pagination
+
+Below is an example of using Search with Pagination.
+
+```python
+# Note: CLARIFAI_PAT must be set as env variable.
+from clarifai.client.search import Search
+search = Search(user_id="user_id", app_id="app_id", metric="cosine", pagination=True)
+
+# Search by image url
+results = search.query(ranks=[{"image_url": "https://samples.clarifai.com/metro-north.jpg"}],page_no=2,per_page=5)
+
+for data in results:
+  print(data.hits[0].input.data.image.url)
+```
+
 ## Retrieval Augmented Generation (RAG)
 
 You can setup and start your RAG pipeline in 4 lines of code. The setup method automatically creates a new app and the necessary components under the hood. By default it uses the [mistral-7B-Instruct](https://clarifai.com/mistralai/completion/models/mistral-7B-Instruct) model.

clarifai-10.3.1/VERSION

@@ -0,0 +1 @@
+10.3.1

{clarifai-10.3.0 → clarifai-10.3.1}/clarifai/client/model.py

@@ -1,3 +1,4 @@
+import json
 import os
 import time
 from typing import Any, Dict, Generator, List, Tuple, Union
@@ -9,7 +10,7 @@ from clarifai_grpc.grpc.api import resources_pb2, service_pb2
 from clarifai_grpc.grpc.api.resources_pb2 import Input
 from clarifai_grpc.grpc.api.status import status_code_pb2
 from google.protobuf.json_format import MessageToDict
-from google.protobuf.struct_pb2 import Struct
+from google.protobuf.struct_pb2 import Struct, Value
 from tqdm import tqdm
 
 from clarifai.client.base import BaseClient
@@ -25,6 +26,10 @@ from clarifai.utils.model_train import (find_and_replace_key, params_parser,
                                         response_to_model_params, response_to_param_info,
                                         response_to_templates)
 
+MAX_SIZE_PER_STREAM = int(89_128_960)  # 85GiB
+MIN_CHUNK_FOR_UPLOAD_FILE = int(5_242_880)  # 5MiB
+MAX_CHUNK_FOR_UPLOAD_FILE = int(5_242_880_000)  # 5GiB
+
 
 class Model(Lister, BaseClient):
   """Model is a class that provides access to Clarifai API endpoints related to Model information."""
@@ -58,7 +63,7 @@ class Model(Lister, BaseClient):
       user_id, app_id, _, model_id, model_version_id = ClarifaiUrlHelper.split_clarifai_url(url)
       model_version = {'id': model_version_id}
       kwargs = {'user_id': user_id, 'app_id': app_id}
-    self.kwargs = {**kwargs, 'id': model_id, 'model_version': model_version,}
+    self.kwargs = {**kwargs, 'id': model_id, 'model_version': model_version, }
     self.model_info = resources_pb2.Model(**self.kwargs)
     self.logger = get_logger(logger_level="INFO", name=__name__)
     self.training_params = {}
@@ -132,11 +137,11 @@ class Model(Lister, BaseClient):
       raise Exception(response.status)
     params = response_to_model_params(
         response=response, model_type_id=self.model_info.model_type_id, template=template)
-    #yaml file
+    # yaml file
     assert save_to.endswith('.yaml'), "File extension should be .yaml"
     with open(save_to, 'w') as f:
       yaml.dump(params, f, default_flow_style=False, sort_keys=False)
-    #updating the global model params
+    # updating the global model params
     self.training_params.update(params)
 
     return params
@@ -159,14 +164,14 @@ class Model(Lister, BaseClient):
       raise UserError(
           f"Run 'model.get_params' to get the params for the {self.model_info.model_type_id} model type"
       )
-    #getting all the keys in nested dictionary
+    # getting all the keys in nested dictionary
     all_keys = [key for key in self.training_params.keys()] + [
         key for key in self.training_params.values() if isinstance(key, dict) for key in key
     ]
-    #checking if the given params are valid
+    # checking if the given params are valid
     if not set(kwargs.keys()).issubset(all_keys):
       raise UserError("Invalid params")
-    #updating the global model params
+    # updating the global model params
     for key, value in kwargs.items():
       find_and_replace_key(self.training_params, key, value)
 
@@ -238,7 +243,7 @@ class Model(Lister, BaseClient):
         params_dict = yaml.safe_load(file)
     else:
       params_dict = self.training_params
-    #getting all the concepts for the model type
+    # getting all the concepts for the model type
     if self.model_info.model_type_id not in ["clusterer", "text-to-text"]:
       concepts = self._list_concepts()
     train_dict = params_parser(params_dict, concepts)
@@ -423,7 +428,7 @@ class Model(Lister, BaseClient):
       response = self._grpc_request(self.STUB.PostModelOutputs, request)
 
       if response.status.code == status_code_pb2.MODEL_DEPLOYING and \
-        time.time() - start_time < 60 * 10: # 10 minutes
+              time.time() - start_time < 60 * 10:  # 10 minutes
         self.logger.info(f"{self.id} model is still deploying, please wait...")
         time.sleep(next(backoff_iterator))
         continue
@@ -1013,7 +1018,7 @@ class Model(Lister, BaseClient):
       while True:
         get_export_response = _get_export_response()
         if get_export_response.export.status.code == status_code_pb2.MODEL_EXPORTING and \
-          time.time() - start_time < 60 * 30: # 30 minutes
+                time.time() - start_time < 60 * 30:  # 30 minutes
           self.logger.info(
               f"Model ID {self.id} with version {self.model_info.model_version.id} is still exporting, please wait..."
           )
@@ -1027,3 +1032,302 @@ class Model(Lister, BaseClient):
               Req ID: {get_export_response.status.req_id}""")
     elif get_export_response.export.status.code == status_code_pb2.MODEL_EXPORTED:
       _download_exported_model(get_export_response, os.path.join(export_dir, "model.tar"))
+
+  @staticmethod
+  def _make_pretrained_config_proto(input_field_maps: dict,
+                                    output_field_maps: dict,
+                                    url: str = None):
+    """Make PretrainedModelConfig for uploading new version
+
+    Args:
+        input_field_maps (dict): dict
+        output_field_maps (dict): dict
+        url (str, optional): direct download url. Defaults to None.
+    """
+
+    def _parse_fields_map(x):
+      """parse input, outputs to Struct"""
+      _fields_map = Struct()
+      _fields_map.update(x)
+      return _fields_map
+
+    input_fields_map = _parse_fields_map(input_field_maps)
+    output_fields_map = _parse_fields_map(output_field_maps)
+
+    return resources_pb2.PretrainedModelConfig(
+        input_fields_map=input_fields_map, output_fields_map=output_fields_map, model_zip_url=url)
+
+  @staticmethod
+  def _make_inference_params_proto(
+      inference_parameters: List[Dict]) -> List[resources_pb2.ModelTypeField]:
+    """Convert list of Clarifai inference parameters to proto for uploading new version
+
+    Args:
+        inference_parameters (List[Dict]): Each dict has keys {field_type, path, default_value, description}
+
+    Returns:
+        List[resources_pb2.ModelTypeField]
+    """
+
+    def _make_default_value_proto(dtype, value):
+      if dtype == 1:
+        return Value(bool_value=value)
+      elif dtype == 2 or dtype == 21:
+        return Value(string_value=value)
+      elif dtype == 3:
+        return Value(number_value=value)
+
+    iterative_proto_params = []
+    for param in inference_parameters:
+      dtype = param.get("field_type")
+      proto_param = resources_pb2.ModelTypeField(
+          path=param.get("path"),
+          field_type=dtype,
+          default_value=_make_default_value_proto(dtype=dtype, value=param.get("default_value")),
+          description=param.get("description"),
+      )
+      iterative_proto_params.append(proto_param)
+    return iterative_proto_params
+
+  def create_version_by_file(self,
+                             file_path: str,
+                             input_field_maps: dict,
+                             output_field_maps: dict,
+                             inference_parameter_configs: dict = None,
+                             model_version: str = None,
+                             part_id: int = 1,
+                             range_start: int = 0,
+                             no_cache: bool = False,
+                             no_resume: bool = False,
+                             description: str = "") -> 'Model':
+    """Create model version by uploading local file
+
+    Args:
+        file_path (str): path to built file.
+        input_field_maps (dict): a dict where the key is clarifai input field and the value is triton model input,
+          {clarifai_input_field: triton_input_filed}.
+        output_field_maps (dict): a dict where the keys are clarifai output fields and the values are triton model outputs,
+          {clarifai_output_field1: triton_output_filed1, clarifai_output_field2: triton_output_filed2,...}.
+        inference_parameter_configs (List[dict]): list of dicts - keys are path, field_type, default_value, description. Default is None
+        model_version (str, optional): Custom model version. Defaults to None.
+        part_id (int, optional): part id of file. Defaults to 1.
+        range_start (int, optional): range of uploaded size. Defaults to 0.
+        no_cache (bool, optional): not saving uploading cache that is used to resume uploading. Defaults to False.
+        no_resume (bool, optional): disable auto resume upload. Defaults to False.
+        description (str): Model description.
+
+    Return:
+      Model: instance of Model with new created version
+
+    """
+    file_size = os.path.getsize(file_path)
+    assert MIN_CHUNK_FOR_UPLOAD_FILE <= file_size <= MAX_CHUNK_FOR_UPLOAD_FILE, "The file size exceeds the allowable limit, which ranges from 5MiB to 5GiB."
+
+    pretrained_proto = Model._make_pretrained_config_proto(
+        input_field_maps=input_field_maps, output_field_maps=output_field_maps)
+    inference_param_proto = Model._make_inference_params_proto(
+        inference_parameter_configs) if inference_parameter_configs else None
+
+    if file_size >= 1e9:
+      chunk_size = 1024 * 50_000  # 50MB
+    else:
+      chunk_size = 1024 * 10_000  # 10MB
+
+    #self.logger.info(f"Chunk {chunk_size/1e6}MB, {file_size/chunk_size} steps")
+    #self.logger.info(f" Max bytes per stream {MAX_SIZE_PER_STREAM}")
+
+    cache_dir = os.path.join(file_path, '..', '.cache')
+    cache_upload_file = os.path.join(cache_dir, "upload.json")
+    last_percent = 0
+    if os.path.exists(cache_upload_file) and not no_resume:
+      with open(cache_upload_file, "r") as fp:
+        try:
+          cache_info = json.load(fp)
+          if isinstance(cache_info, dict):
+            part_id = cache_info.get("part_id", part_id)
+            chunk_size = cache_info.get("chunk_size", chunk_size)
+            range_start = cache_info.get("range_start", range_start)
+            model_version = cache_info.get("model_version", model_version)
+            last_percent = cache_info.get("last_percent", last_percent)
+        except Exception as e:
+          self.logger.error(f"Skipping loading the upload cache due to error {e}.")
+
+    def init_model_version_upload(model_version):
+      return service_pb2.PostModelVersionsUploadRequest(
+          upload_config=service_pb2.PostModelVersionsUploadConfig(
+              user_app_id=self.user_app_id,
+              model_id=self.id,
+              total_size=file_size,
+              model_version=resources_pb2.ModelVersion(
+                  id=model_version,
+                  pretrained_model_config=pretrained_proto,
+                  description=description,
+                  output_info=resources_pb2.OutputInfo(params_specs=inference_param_proto)),
+          ))
+
+    def _uploading(chunk, part_id, range_start, model_version):
+      return service_pb2.PostModelVersionsUploadRequest(
+          content_part=resources_pb2.UploadContentPart(
+              data=chunk, part_number=part_id, range_start=range_start))
+
+    finished_status = [status_code_pb2.SUCCESS, status_code_pb2.UPLOAD_DONE]
+    uploading_in_progress_status = [
+        status_code_pb2.UPLOAD_IN_PROGRESS, status_code_pb2.MODEL_UPLOADING
+    ]
+
+    def _save_cache(cache: dict):
+      if not no_cache:
+        os.makedirs(cache_dir, exist_ok=True)
+        with open(cache_upload_file, "w") as fp:
+          json.dump(cache, fp, indent=2)
+
+    def stream_request(fp, part_id, end_part_id, chunk_size, version):
+      yield init_model_version_upload(version)
+      for iter_part_id in range(part_id, end_part_id):
+        chunk = fp.read(chunk_size)
+        if not chunk:
+          return
+        yield _uploading(
+            chunk=chunk,
+            part_id=iter_part_id,
+            range_start=chunk_size * (iter_part_id - 1),
+            model_version=version)
+
+    tqdm_loader = tqdm(total=100)
+    if model_version:
+      desc = f"Uploading model `{self.id}` version `{model_version}` ..."
+    else:
+      desc = f"Uploading model `{self.id}` ..."
+    tqdm_loader.set_description(desc)
+
+    cache_uploading_info = {}
+    cache_uploading_info["part_id"] = part_id
+    cache_uploading_info["model_version"] = model_version
+    cache_uploading_info["range_start"] = range_start
+    cache_uploading_info["chunk_size"] = chunk_size
+    cache_uploading_info["last_percent"] = last_percent
+    tqdm_loader.update(last_percent)
+    last_part_id = part_id
+    n_chunks = file_size // chunk_size
+    n_chunk_per_stream = MAX_SIZE_PER_STREAM // chunk_size or 1
+
+    def stream_and_logging(request, tqdm_loader, cache_uploading_info, expected_steps: int = None):
+      for st_step, st_response in enumerate(self.auth_helper.get_stub().PostModelVersionsUpload(
+          request, metadata=self.auth_helper.metadata)):
+        if st_response.status.code in uploading_in_progress_status:
+          if cache_uploading_info["model_version"]:
+            assert st_response.model_version_id == cache_uploading_info[
+                "model_version"], RuntimeError
+          else:
+            cache_uploading_info["model_version"] = st_response.model_version_id
+          if st_step > 0:
+            cache_uploading_info["part_id"] += 1
+            cache_uploading_info["range_start"] += chunk_size
+            _save_cache(cache_uploading_info)
+
+            if st_response.status.percent_completed:
+              step_percent = st_response.status.percent_completed - cache_uploading_info["last_percent"]
+              cache_uploading_info["last_percent"] += step_percent
+              tqdm_loader.set_description(
+                  f"{st_response.status.description}, {st_response.status.details}, version id  {cache_uploading_info.get('model_version')}"
+              )
+              tqdm_loader.update(step_percent)
+        elif st_response.status.code not in finished_status + uploading_in_progress_status:
+          # TODO: Find better way to handle error
+          if expected_steps and st_step < expected_steps:
+            raise Exception(f"Failed to upload model, error: {st_response.status}")
+
+    with open(file_path, 'rb') as fp:
+      # seeking
+      for _ in range(1, last_part_id):
+        fp.read(chunk_size)
+      # Stream even part
+      end_part_id = n_chunks or 1
+      for iter_part_id in range(int(last_part_id), int(n_chunks), int(n_chunk_per_stream)):
+        end_part_id = iter_part_id + n_chunk_per_stream
+        if end_part_id >= n_chunks:
+          end_part_id = n_chunks
+        expected_steps = end_part_id - iter_part_id + 1  # init step
+        st_reqs = stream_request(
+            fp,
+            iter_part_id,
+            end_part_id=end_part_id,
+            chunk_size=chunk_size,
+            version=cache_uploading_info["model_version"])
+        stream_and_logging(st_reqs, tqdm_loader, cache_uploading_info, expected_steps)
+      # Stream last part
+      accum_size = (end_part_id - 1) * chunk_size
+      remained_size = file_size - accum_size if accum_size >= 0 else file_size
+      st_reqs = stream_request(
+          fp,
+          end_part_id,
+          end_part_id=end_part_id + 1,
+          chunk_size=remained_size,
+          version=cache_uploading_info["model_version"])
+      stream_and_logging(st_reqs, tqdm_loader, cache_uploading_info, 2)
+
+    # clean up cache
+    if not no_cache:
+      try:
+        os.remove(cache_upload_file)
+      except Exception:
+        _save_cache({})
+
+    if cache_uploading_info["last_percent"] <= 100:
+      tqdm_loader.update(100 - cache_uploading_info["last_percent"])
+      tqdm_loader.set_description("Upload done")
+
+    tqdm_loader.set_description(
+        f"Success uploading model {self.id}, new version {cache_uploading_info.get('model_version')}"
+    )
+
+    return Model.from_auth_helper(
+        auth=self.auth_helper,
+        model_id=self.id,
+        model_version=dict(id=cache_uploading_info.get('model_version')))
+
+  def create_version_by_url(self,
+                            url: str,
+                            input_field_maps: dict,
+                            output_field_maps: dict,
+                            inference_parameter_configs: List[dict] = None,
+                            description: str = "") -> 'Model':
+    """Upload a new version of an existing model in the Clarifai platform using direct download url.
+
+    Args:
+      url (str]): url of zip of model
+      input_field_maps (dict): a dict where the key is clarifai input field and the value is triton model input,
+          {clarifai_input_field: triton_input_filed}.
+      output_field_maps (dict): a dict where the keys are clarifai output fields and the values are triton model outputs,
+          {clarifai_output_field1: triton_output_filed1, clarifai_output_field2: triton_output_filed2,...}.
+      inference_parameter_configs (List[dict]): list of dicts - keys are path, field_type, default_value, description. Default is None
+      description (str): Model description.
+
+    Return:
+      Model: instance of Model with new created version
+    """
+
+    pretrained_proto = Model._make_pretrained_config_proto(
+        input_field_maps=input_field_maps, output_field_maps=output_field_maps, url=url)
+    inference_param_proto = Model._make_inference_params_proto(
+        inference_parameter_configs) if inference_parameter_configs else None
+    request = service_pb2.PostModelVersionsRequest(
+        user_app_id=self.user_app_id,
+        model_id=self.id,
+        model_versions=[
+            resources_pb2.ModelVersion(
+                pretrained_model_config=pretrained_proto,
+                description=description,
+                output_info=resources_pb2.OutputInfo(params_specs=inference_param_proto))
+        ])
+    response = self._grpc_request(self.STUB.PostModelVersions, request)
+
+    if response.status.code != status_code_pb2.SUCCESS:
+      raise Exception(f"Failed to upload model, error: {response.status}")
+    self.logger.info(
+        f"Success uploading model {self.id}, new version {response.model.model_version.id}")
+
+    return Model.from_auth_helper(
+        auth=self.auth_helper,
+        model_id=self.id,
+        model_version=dict(id=response.model.model_version.id))

{clarifai-10.3.0 → clarifai-10.3.1}/clarifai/client/search.py

@@ -10,7 +10,8 @@ from schema import SchemaError
 from clarifai.client.base import BaseClient
 from clarifai.client.input import Inputs
 from clarifai.client.lister import Lister
-from clarifai.constants.search import DEFAULT_SEARCH_METRIC, DEFAULT_TOP_K
+from clarifai.constants.search import (DEFAULT_SEARCH_ALGORITHM, DEFAULT_SEARCH_METRIC,
+                                       DEFAULT_TOP_K)
 from clarifai.errors import UserError
 from clarifai.schema.search import get_schema
 
@@ -20,8 +21,10 @@ class Search(Lister, BaseClient):
   def __init__(self,
                user_id: str,
                app_id: str,
-               top_k: int = DEFAULT_TOP_K,
+               top_k: int = None,
                metric: str = DEFAULT_SEARCH_METRIC,
+               algorithm: str = DEFAULT_SEARCH_ALGORITHM,
+               pagination: bool = False,
                base_url: str = "https://api.clarifai.com",
                pat: str = None,
                token: str = None,
@@ -33,6 +36,8 @@ class Search(Lister, BaseClient):
         app_id (str): App ID.
         top_k (int, optional): Top K results to retrieve. Defaults to 10.
         metric (str, optional): Similarity metric (either 'cosine' or 'euclidean'). Defaults to 'cosine'.
+        alogrithm (str, optional): Search algorithm (either 'nearest_neighbor' or 'brute_force'). Defaults to 'nearest_neighbor'.
+        pagination (bool, optional): Enable pagination. Defaults to False.
         base_url (str, optional): Base API url. Defaults to "https://api.clarifai.com".
         pat (str, optional): 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
@@ -40,16 +45,27 @@ class Search(Lister, BaseClient):
 
     Raises:
         UserError: If the metric is not 'cosine' or 'euclidean'.
+        UserError: If the algorithm is not 'nearest_neighbor' or 'brute_force'.
     """
     if metric not in ["cosine", "euclidean"]:
       raise UserError("Metric should be either cosine or euclidean")
+    if algorithm not in ["nearest_neighbor", "brute_force"]:
+      raise UserError("Algorithm should be either nearest_neighbor or brute_force")
+    if metric == "cosine" and algorithm == "nearest_neighbor":
+      raise UserError("Cosine distance metric is not supported with nearest neighbor algorithm")
+    if top_k and pagination:
+      raise UserError(
+          "top_k and pagination cannot be used together. Please set pagination to False.")
+    if not top_k and not pagination:
+      top_k = DEFAULT_TOP_K
 
     self.user_id = user_id
     self.app_id = app_id
     self.metric_distance = dict(cosine="COSINE_DISTANCE", euclidean="EUCLIDEAN_DISTANCE")[metric]
+    self.algorithm = algorithm
     self.data_proto = resources_pb2.Data()
     self.top_k = top_k
-
+    self.pagination = pagination
     self.inputs = Inputs(
         user_id=self.user_id, app_id=self.app_id, pat=pat, token=token, base_url=base_url)
     self.rank_filter_schema = get_schema()
@@ -159,9 +175,8 @@ class Search(Lister, BaseClient):
         geo_point=resources_pb2.GeoPoint(longitude=longitude, latitude=latitude),
         geo_limit=resources_pb2.GeoLimit(type="withinKilometers", value=geo_limit))
 
-  def list_all_pages_generator(
-      self, endpoint: Callable[..., Any], proto_message: Any,
-      request_data: Dict[str, Any]) -> Generator[Dict[str, Any], None, None]:
+  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.
 
         Args:
@@ -199,12 +214,61 @@ class Search(Lister, BaseClient):
       total_hits += per_page
       yield response
 
-  def query(self, ranks=[{}], filters=[{}]):
+  def _list_all_pages_generator(self,
+                                endpoint: Callable,
+                                proto_message: Any,
+                                request_data: Dict[str, Any],
+                                page_no: int = None,
+                                per_page: int = None) -> Generator[Dict[str, Any], None, None]:
+    """Lists pages of a resource.
+
+    Args:
+        endpoint (Callable): The endpoint to call.
+        proto_message (Any): The proto message to use.
+        request_data (dict): The request data to use.
+        page_no (int): The page number to list.
+        per_page (int): The number of items per page.
+
+    Yields:
+        response_dict: The next item in the listing.
+    """
+    page = 1 if not page_no else page_no
+    if page_no and not per_page:
+      per_page = self.default_page_size
+    while True:
+      request_data['pagination'] = service_pb2.Pagination(page=page, per_page=per_page)
+      response = self._grpc_request(endpoint, proto_message(**request_data))
+      dict_response = MessageToDict(response, preserving_proto_field_name=True)
+      if response.status.code != status_code_pb2.SUCCESS:
+        if "page * perPage cannot exceed" in str(response.status.details):
+          msg = (f"Your pagination is set to {page_no*per_page}. "
+                 f"The current pagination settings exceed the limit. Please reach out to "
+                 f"support@clarifai.com to request an increase for your use case.\n"
+                 f"req_id: {response.status.req_id}")
+          raise UserError(msg)
+        else:
+          raise Exception(f"Listing failed with response {response!r}")
+      if 'hits' not in list(dict_response.keys()):
+        break
+      yield response
+      if page_no is not None or per_page is not None:
+        break
+      page += 1
+
+  def query(
+      self,
+      ranks=[{}],
+      filters=[{}],
+      page_no: int = None,
+      per_page: int = None,
+  ):
     """Perform a query with rank and filters.
 
     Args:
         ranks (List[Dict], optional): List of rank parameters. Defaults to [{}].
         filters (List[Dict], optional): List of filter parameters. Defaults to [{}].
+        page_no (int): The page number to list.
+        per_page (int): The number of items per page.
 
     Returns:
         Generator[Dict[str, Any], None, None]: A generator of query results.
@@ -217,13 +281,16 @@ class Search(Lister, BaseClient):
 
         Vector search over inputs
         >>> from clarifai.client.search import Search
-        >>> search = Search(user_id='user_id', app_id='app_id', top_k=1, metric='cosine')
-        >>> res = search.query(ranks=[{'image_url': 'https://samples.clarifai.com/dog.tiff'}])
+        >>> search = Search(user_id='user_id', app_id='app_id' , metric='cosine', pagination=True)
+        >>> res = search.query(ranks=[{'image_url': 'https://samples.clarifai.com/dog.tiff'}],page_no=2, per_page=5)
 
     Note:
         For schema of rank and filter, please refer to [schema](https://github.com/Clarifai/clarifai-python/tree/master/clarifai/schema/search.py).
         For more detailed search examples, please refer to [examples](https://github.com/Clarifai/examples/tree/main/search).
     """
+    if not self.pagination and (per_page or page_no):
+      raise UserError("Pagination settings are only available when pagination is enabled."
+                      "Please set Search(pagination=True) while initializing Search().")
     try:
       self.rank_filter_schema.validate(ranks)
       self.rank_filter_schema.validate(filters)
@@ -249,11 +316,15 @@ class Search(Lister, BaseClient):
           searches=[
               resources_pb2.Search(
                   query=resources_pb2.Query(ranks=all_ranks, filters=all_filters),
+                  algorithm=self.algorithm,
                   metric=self.metric_distance)
           ])
-
-      return self.list_all_pages_generator(self.STUB.PostInputsSearches,
-                                           service_pb2.PostInputsSearchesRequest, request_data)
+      if self.pagination:
+        return self._list_all_pages_generator(self.STUB.PostInputsSearches,
+                                              service_pb2.PostInputsSearchesRequest, request_data,
+                                              page_no, per_page)
+      return self._list_topk_generator(self.STUB.PostInputsSearches,
+                                       service_pb2.PostInputsSearchesRequest, request_data)
 
     # Calls PostAnnotationsSearches for annotation ranks, filters
     filters_annot_proto = []
@@ -269,8 +340,12 @@ class Search(Lister, BaseClient):
         searches=[
             resources_pb2.Search(
                 query=resources_pb2.Query(ranks=all_ranks, filters=all_filters),
+                algorithm=self.algorithm,
                 metric=self.metric_distance)
         ])
-
-    return self.list_all_pages_generator(self.STUB.PostAnnotationsSearches,
-                                         service_pb2.PostAnnotationsSearchesRequest, request_data)
+    if self.pagination:
+      return self._list_all_pages_generator(self.STUB.PostAnnotationsSearches,
+                                            service_pb2.PostAnnotationsSearchesRequest,
+                                            request_data, page_no, per_page)
+    return self._list_topk_generator(self.STUB.PostAnnotationsSearches,
+                                     service_pb2.PostAnnotationsSearchesRequest, request_data)

clarifai-10.3.1/clarifai/constants/search.py

@@ -0,0 +1,3 @@
+DEFAULT_TOP_K = 10
+DEFAULT_SEARCH_METRIC = "euclidean"
+DEFAULT_SEARCH_ALGORITHM = "nearest_neighbor"

{clarifai-10.3.0 → clarifai-10.3.1}/clarifai/models/model_serving/README.md

@@ -141,6 +141,9 @@ Get your PAT from https://clarifai.com/settings/security and pass it here: <inse
 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>
 ```