clarifai 9.8.1__py3-none-any.whl → 9.9.0__py3-none-any.whl

clarifai_utils/client/dataset.py

@@ -29,13 +29,18 @@ ClarifaiDatasetType = TypeVar('ClarifaiDatasetType', VisualClassificationDataset
 class Dataset(Lister, BaseClient):
   """Dataset is a class that provides access to Clarifai API endpoints related to Dataset information."""
 
-  def __init__(self, url_init: str = "", dataset_id: str = "", **kwargs):
+  def __init__(self,
+               url_init: str = "",
+               dataset_id: str = "",
+               base_url: str = "https://api.clarifai.com",
+               **kwargs):
     """Initializes a Dataset object.
 
     Args:
         url_init (str): The URL to initialize the dataset object.
         dataset_id (str): The Dataset ID within the App to interact with.
-        **kwargs: Additional keyword arguments to be passed to the ClarifaiAuthHelper.
+        base_url (str): Base API url. Default "https://api.clarifai.com"
+        **kwargs: Additional keyword arguments to be passed to the Dataset.
     """
     if url_init != "" and dataset_id != "":
       raise UserError("You can only specify one of url_init or dataset_id.")
@@ -51,7 +56,7 @@ class Dataset(Lister, BaseClient):
     self.chunk_size = 128  # limit max protos in a req
     self.task = None  # Upload dataset type
     self.input_object = Inputs(user_id=self.user_id, app_id=self.app_id)
-    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id)
+    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id, base=base_url)
     Lister.__init__(self)
 
   def _concurrent_annot_upload(self, annots: List[List[resources_pb2.Annotation]]

clarifai_utils/client/input.py

@@ -23,12 +23,18 @@ from clarifai.utils.misc import BackoffIterator, Chunker
 class Inputs(Lister, BaseClient):
   """Inputs is a class that provides access to Clarifai API endpoints related to Input information."""
 
-  def __init__(self, user_id: str = "", app_id: str = "", logger_level: str = "INFO", **kwargs):
+  def __init__(self,
+               user_id: str = "",
+               app_id: str = "",
+               logger_level: str = "INFO",
+               base_url: str = "https://api.clarifai.com",
+               **kwargs):
     """Initializes an Input object.
 
     Args:
         user_id (str): A user ID for authentication.
         app_id (str): An app ID for the application to interact with.
+        base_url (str): Base API url. Default "https://api.clarifai.com"
         **kwargs: Additional keyword arguments to be passed to the Input
     """
     self.user_id = user_id
@@ -36,7 +42,7 @@ class Inputs(Lister, BaseClient):
     self.kwargs = {**kwargs}
     self.input_info = resources_pb2.Input(**self.kwargs)
     self.logger = get_logger(logger_level=logger_level, name=__name__)
-    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id)
+    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id, base=base_url)
     Lister.__init__(self)
 
   def _get_proto(self,
@@ -121,8 +127,8 @@ class Inputs(Lister, BaseClient):
         Input: An Input object for the specified input ID.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> input_proto = input_obj.get_input_from_url(input_id = 'demo', image_url='https://samples.clarifai.com/metro-north.jpg')
     """
     if not any((image_url, video_url, audio_url, text_url)):
@@ -163,8 +169,8 @@ class Inputs(Lister, BaseClient):
         Input: An Input object for the specified input ID.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> input_proto = input_obj.get_input_from_file(input_id = 'demo', video_file='file_path')
     """
     if not any((image_file, video_file, audio_file, text_file)):
@@ -205,8 +211,8 @@ class Inputs(Lister, BaseClient):
         Input: An Input object for the specified input ID.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> image = open('demo.jpg', 'rb').read()
         >>> video = open('demo.mp4', 'rb').read()
         >>> input_proto = input_obj.get_input_from_bytes(input_id = 'demo',image_bytes =image, video_bytes=video)
@@ -240,8 +246,8 @@ class Inputs(Lister, BaseClient):
         list of Input: A list of Input objects for the specified folder.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> input_protos = input_obj.get_image_inputs_from_folder(folder_path='demo_folder')
     """
     input_protos = []
@@ -270,8 +276,8 @@ class Inputs(Lister, BaseClient):
         Text: An Input object for the specified input ID.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> input_protos = input_obj.get_text_input(input_id = 'demo', raw_text = 'This is a test')
     """
     text_pb = resources_pb2.Text(raw=raw_text)
@@ -296,8 +302,8 @@ class Inputs(Lister, BaseClient):
         inputs: List of inputs
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> input_protos = input_obj.get_inputs_from_csv(csv_path='filepath', input_type='text', csv_type='raw')
     """
     input_protos = []
@@ -357,8 +363,8 @@ class Inputs(Lister, BaseClient):
         list of Input: A list of Input objects for the specified folder.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> input_protos = input_obj.get_text_inputs_from_folder(folder_path='demo_folder')
     """
     input_protos = []
@@ -385,8 +391,8 @@ class Inputs(Lister, BaseClient):
         An annotation object for the specified input ID.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> input_obj.get_annotation_proto(input_id='demo', label='demo', annotations=[x_min, y_min, x_max, y_max])
     """
     if not isinstance(annotations, list):
@@ -424,8 +430,8 @@ class Inputs(Lister, BaseClient):
         An annotation object for the specified input ID.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input()
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs()
         >>> input_obj.get_mask_proto(input_id='demo', label='demo', polygons=[[[x,y],...,[x,y]],...])
     """
     if not isinstance(polygons, list):
@@ -471,8 +477,8 @@ class Inputs(Lister, BaseClient):
         input_job_id: job id for the upload request.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input(user_id = 'user_id', app_id = 'demo_app')
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs(user_id = 'user_id', app_id = 'demo_app')
         >>> input_obj.upload_from_url(input_id='demo', image_url='https://samples.clarifai.com/metro-north.jpg')
     """
     input_pb = self.get_input_from_url(input_id, image_url, video_url, audio_url, text_url,
@@ -501,8 +507,8 @@ class Inputs(Lister, BaseClient):
         input_job_id: job id for the upload request.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input(user_id = 'user_id', app_id = 'demo_app')
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs(user_id = 'user_id', app_id = 'demo_app')
         >>> input_obj.upload_from_file(input_id='demo', audio_file='demo.mp3')
     """
     input_pb = self.get_input_from_file(input_id, image_file, video_file, audio_file, text_file,
@@ -531,8 +537,8 @@ class Inputs(Lister, BaseClient):
         input_job_id: job id for the upload request.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input(user_id = 'user_id', app_id = 'demo_app')
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs(user_id = 'user_id', app_id = 'demo_app')
         >>> image = open('demo.jpg', 'rb').read()
         >>> input_obj.upload_from_bytes(input_id='demo', image_bytes=image)
     """
@@ -553,8 +559,8 @@ class Inputs(Lister, BaseClient):
         input_job_id (str): job id for the upload request.
 
     Example:
-        >>> from clarifai.client.input import Input
-        >>> input_obj = Input(user_id = 'user_id', app_id = 'demo_app')
+        >>> from clarifai.client.input import Inputs
+        >>> input_obj = Inputs(user_id = 'user_id', app_id = 'demo_app')
         >>> input_obj.upload_text(input_id = 'demo', raw_text = 'This is a test')
     """
     input_pb = self._get_proto(

clarifai_utils/client/model.py

@@ -5,6 +5,7 @@ from typing import Dict, List
 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 clarifai.client.base import BaseClient
 from clarifai.client.lister import Lister
@@ -22,6 +23,7 @@ class Model(Lister, BaseClient):
                model_id: str = "",
                model_version: Dict = {'id': ""},
                output_config: Dict = {'min_value': 0},
+               base_url: str = "https://api.clarifai.com",
                **kwargs):
     """Initializes a Model object.
 
@@ -34,7 +36,8 @@ class Model(Lister, BaseClient):
           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.
-        **kwargs: Additional keyword arguments to be passed to the ClarifaiAuthHelper.
+        base_url (str): Base API url. Default "https://api.clarifai.com"
+        **kwargs: Additional keyword arguments to be passed to the Model.
     """
     if url_init != "" and model_id != "":
       raise UserError("You can only specify one of url_init or model_id.")
@@ -49,9 +52,75 @@ class Model(Lister, BaseClient):
                    'output_info': {'output_config': output_config}}
     self.model_info = resources_pb2.Model(**self.kwargs)
     self.logger = get_logger(logger_level="INFO")
-    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id)
+    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id, base=base_url)
     Lister.__init__(self)
 
+  def create_model_version(self, **kwargs) -> 'Model':
+    """Creates a model version for the Model.
+
+    Args:
+        **kwargs: Additional keyword arguments to be passed to Model Version.
+          - description (str): The description of the model version.
+          - concepts (list[Concept]): The concepts to associate with the model version.
+          - output_info (resources_pb2.OutputInfo(): The output info to associate with the model version.
+
+    Returns:
+        Model: A Model object for the specified model ID.
+
+    Example:
+        >>> from clarifai.client.model import Model
+        >>> model = Model("model_url")
+                    or
+        >>> model = Model(model_id='model_id', user_id='user_id', app_id='app_id')
+        >>> model_version = model.create_model_version(description='model_version_description')
+    """
+    request = service_pb2.PostModelVersionsRequest(
+        user_app_id=self.user_app_id,
+        model_id=self.id,
+        model_versions=[resources_pb2.ModelVersion(**kwargs)])
+
+    response = self._grpc_request(self.STUB.PostModelVersions, request)
+    if response.status.code != status_code_pb2.SUCCESS:
+      raise Exception(response.status)
+    self.logger.info("\nModel Version created\n%s", response.status)
+
+    kwargs.update({'app_id': self.app_id, 'user_id': self.user_id})
+    dict_response = MessageToDict(response, preserving_proto_field_name=True)
+    kwargs = self.process_response_keys(dict_response['model'], 'model')
+
+    return Model(**kwargs)
+
+  def list_versions(self) -> List['Model']:
+    """Lists all the versions for the model.
+
+    Returns:
+        List[Model]: A list of Model objects for the versions of the model.
+
+    Example:
+        >>> from clarifai.client.model import Model
+        >>> model = Model("model_url") # Example URL: https://clarifai.com/clarifai/main/models/general-image-recognition
+                    or
+        >>> model = Model(model_id='model_id', user_id='user_id', app_id='app_id')
+        >>> all_model_versions = model.list_versions()
+    """
+    request_data = dict(
+        user_app_id=self.user_app_id,
+        model_id=self.id,
+        per_page=self.default_page_size,
+    )
+    all_model_versions_info = list(
+        self.list_all_pages_generator(self.STUB.ListModelVersions,
+                                      service_pb2.ListModelVersionsRequest, request_data))
+
+    for model_version_info in all_model_versions_info:
+      model_version_info['id'] = model_version_info['model_version_id']
+      del model_version_info['model_version_id']
+
+    return [
+        Model(model_id=self.id, **dict(self.kwargs, model_version=model_version_info))
+        for model_version_info in all_model_versions_info
+    ]
+
   def predict(self, inputs: List[Input]):
     """Predicts the model based on the given inputs.
 

clarifai_utils/client/module.py

@@ -16,6 +16,7 @@ class Module(Lister, BaseClient):
                url_init: str = "",
                module_id: str = "",
                module_version: Dict = {'id': ""},
+               base_url: str = "https://api.clarifai.com",
                **kwargs):
     """Initializes a Module object.
 
@@ -23,7 +24,8 @@ class Module(Lister, BaseClient):
             url_init (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.
-            **kwargs: Additional keyword arguments to be passed to the ClarifaiAuthHelper.
+            base_url (str): Base API url. Default "https://api.clarifai.com"
+            **kwargs: Additional keyword arguments to be passed to the Module.
         """
     if url_init != "" and module_id != "":
       raise UserError("You can only specify one of url_init or module_id.")
@@ -38,7 +40,7 @@ class Module(Lister, BaseClient):
     self.kwargs = {**kwargs, 'id': module_id, 'module_version': module_version}
     self.module_info = resources_pb2.Module(**self.kwargs)
     self.logger = get_logger(logger_level="INFO")
-    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id)
+    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id, base=base_url)
     Lister.__init__(self)
 
   def list_versions(self) -> List['Module']:

clarifai_utils/client/runner.py

@@ -0,0 +1,161 @@
+# 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.
+"""Interface to Clarifai Runners API."""
+
+import os
+
+from clarifai_grpc.grpc.api import resources_pb2, service_pb2
+from clarifai_grpc.grpc.api.status import status_code_pb2, status_pb2
+from google.protobuf import json_format
+
+from clarifai.client.base import BaseClient
+from clarifai.errors import UserError
+from clarifai.utils.logging import get_logger
+
+
+class Runner(BaseClient):
+  """Base class for remote inference runners. This should be subclassed with the run_input method
+  implemented to process each input in the request.
+
+  Then on the subclass call start() to start the run loop.
+  """
+
+  def __init__(self,
+               runner_id: str,
+               user_id: str = "",
+               check_runner_exists: bool = True,
+               base_url: str = "https://api.clarifai.com",
+               **kwargs) -> None:
+    """
+    Args:
+      runner_id (str): the id of the runner to use. Create the runner in the Clarifai API first
+      user_id (str): Clarifai User ID
+      base_url (str): Base API url. Default "https://api.clarifai.com"
+    """
+    user_id = user_id or os.environ.get("CLARIFAI_USER_ID", "")
+
+    if user_id == "":
+      raise UserError(
+          "Set CLARIFAI_USER_ID as environment variables or pass user_id as input arguments")
+
+    self.runner_id = runner_id
+    self.logger = get_logger("INFO", __name__)
+    self.kwargs = {**kwargs, 'id': runner_id, 'user_id': user_id}
+    self.runner_info = resources_pb2.Runner(**self.kwargs)
+    BaseClient.__init__(self, user_id=self.user_id, app_id="", base=base_url)
+
+    # Check that the runner exists.
+    if check_runner_exists:
+      request = service_pb2.GetRunnerRequest(user_app_id=self.user_app_id, runner_id=runner_id)
+      response = self._grpc_request(self.STUB.GetRunner, request)
+      if response.status.code != status_code_pb2.SUCCESS:
+        raise Exception(
+            f"""Error getting runner, are you use this is a valid runner id {runner_id} at the user_id
+            {self.user_app_id.user_id}.
+            Error: {response.status.description}""")
+
+  def start(self):
+    """Start the run loop. This will ask the Clarifai API for work, and when it gets work, it will run
+    the model on the inputs and post the results back to the Clarifai API. It will then ask for more
+    work again.
+    """
+    self._long_poll_loop()
+
+  def _run(self, request: service_pb2.PostModelOutputsRequest) -> service_pb2.MultiOutputResponse:
+    """Run the model on the given request. You shouldn't need to override this method, see run_input
+    for the implementation to process each input in the request.
+
+    Args:
+      request: service_pb2.PostModelOutputsRequest - the request to run the model on
+
+    Returns:
+      service_pb2.MultiOutputResponse - the response from the model's run_input implementation.
+    """
+    outputs = []
+    # TODO: parallelize this
+    for inp in request.inputs:
+      # TODO: handle errors
+      outputs.append(self.run_input(inp))
+
+    return service_pb2.MultiOutputResponse(
+        status=status_pb2.Status(
+            code=status_code_pb2.SUCCESS,
+            description="Success",
+        ),
+        outputs=outputs,
+    )
+
+  def run_input(self, input: resources_pb2.Input) -> resources_pb2.Output:
+    """Run the model on the given input in the request. This is the method you should override to
+    process each input in the request.
+
+    Args:
+      input: resources_pb2.Input - the input to run the model on
+
+    Returns:
+      resources_pb2.Output - the response from the model's run_input implementation.
+    """
+    raise NotImplementedError("run_input() not implemented")
+
+  def _long_poll_loop(self):
+    """This method will long poll for work, and when it gets work, it will run the model on the inputs
+    and post the results back to the Clarifai API. It will then long poll again for more work.
+    """
+    c = 0
+    # TODO: handle more errors within this loop so it never stops.
+    # TODO: perhaps have multiple processes running this loop to handle more work.
+    while True:
+      # Long poll waiting for work.
+      self.logger.info("Loop iteration: {}".format(c))
+      request = service_pb2.ListRunnerItemsRequest(
+          user_app_id=self.user_app_id, runner_id=self.runner_id)
+      work_response = self._grpc_request(self.STUB.ListRunnerItems, request)
+      if work_response.status.code == status_code_pb2.RUNNER_NEEDS_RETRY:
+        c += 1
+        continue  # immediate restart the long poll
+      if work_response.status.code != status_code_pb2.SUCCESS:
+        raise Exception("Error getting work: {}".format(work_response.status.description))
+      if len(work_response.items) == 0:
+        self.logger.info("No work to do. Waiting...")
+        continue
+
+      # We have work to do. Run the model on the inputs.
+      for item in work_response.items:
+        if not item.HasField('post_model_outputs_request'):
+          raise Exception("Unexpected work item type: {}".format(item))
+        self.logger.info(
+            f"Working on item: {item.id} with inputs {len(item.post_model_outputs_request.inputs)}"
+        )
+        result = self._run(item.post_model_outputs_request)
+
+        request = service_pb2.PostRunnerItemOutputsRequest(
+            user_app_id=self.user_app_id,
+            item_id=item.id,
+            runner_id=self.runner_id,
+            runner_item_outputs=[service_pb2.RunnerItemOutput(multi_output_response=result)])
+        result_response = self._grpc_request(self.STUB.PostRunnerItemOutputs, request)
+        if result_response.status.code != status_code_pb2.SUCCESS:
+          raise Exception(
+              json_format.MessageToJson(result_response, preserving_proto_field_name=True))
+          # raise Exception("Error posting result: {}".format(result_response.status.description))
+
+  def __getattr__(self, name):
+    return getattr(self.runner_info, name)
+
+  def __str__(self):
+    init_params = [param for param in self.kwargs.keys()]
+    attribute_strings = [
+        f"{param}={getattr(self.runner_info, param)}" for param in init_params
+        if hasattr(self.runner_info, param)
+    ]
+    return f"Runner Details: \n{', '.join(attribute_strings)}\n"

clarifai_utils/client/search.py

@@ -0,0 +1,173 @@
+from typing import Any, Callable, Dict, Generator
+
+from clarifai_grpc.grpc.api import resources_pb2, service_pb2
+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 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.errors import UserError
+from clarifai.schema.search import get_schema
+
+
+class Search(Lister, BaseClient):
+
+  def __init__(self,
+               user_id,
+               app_id,
+               top_k: int = DEFAULT_TOP_K,
+               metric: str = DEFAULT_SEARCH_METRIC):
+    """Initialize the Search object.
+
+        Args:
+            user_id (str): User ID.
+            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'.
+
+        Raises:
+            UserError: If the metric is not 'cosine' or 'euclidean'.
+        """
+    if metric not in ["cosine", "euclidean"]:
+      raise UserError("Metric should be either cosine or euclidean")
+
+    self.user_id = user_id
+    self.app_id = app_id
+    self.metric_distance = dict(cosine="COSINE_DISTANCE", euclidean="EUCLIDEAN_DISTANCE")[metric]
+    self.data_proto = resources_pb2.Data()
+
+    self.inputs = Inputs(user_id=self.user_id, app_id=self.app_id)
+    self.rank_filter_schema = get_schema()
+    BaseClient.__init__(self, user_id=self.user_id, app_id=self.app_id)
+    Lister.__init__(self, page_size=top_k)
+
+  def _get_annot_proto(self, **kwargs):
+    """Get an Annotation proto message based on keyword arguments.
+
+        Args:
+            **kwargs: Keyword arguments specifying the resource.
+
+        Returns:
+            resources_pb2.Annotation: An Annotation proto message.
+        """
+    if not kwargs:
+      return resources_pb2.Annotation()
+
+    self.data_proto = resources_pb2.Data()
+    for key, value in kwargs.items():
+      if key == "image_bytes":
+        image_proto = self.inputs.get_input_from_bytes("", image_bytes=value).data.image
+        self.data_proto.image.CopyFrom(image_proto)
+
+      elif key == "image_url":
+        image_proto = self.inputs.get_input_from_url("", image_url=value).data.image
+        self.data_proto.image.CopyFrom(image_proto)
+
+      elif key == "concepts":
+        for concept in value:
+          concept_proto = resources_pb2.Concept(**concept)
+          self.data_proto.concepts.add().CopyFrom(concept_proto)
+
+      elif key == "text_raw":
+        text_proto = self.inputs.get_input_from_bytes(
+            "", text_bytes=bytes(value, 'utf-8')).data.text
+        self.data_proto.text.CopyFrom(text_proto)
+
+      elif key == "metadata":
+        metadata_struct = Struct()
+        metadata_struct.update(value)
+        self.data_proto.metadata.CopyFrom(metadata_struct)
+
+      elif key == "geo_point":
+        geo_point_proto = self._get_geo_point_proto(value["longitude"], value["latitude"],
+                                                    value["geo_limit"])
+        self.data_proto.geo.CopyFrom(geo_point_proto)
+
+      else:
+        raise UserError(f"kwargs contain key that is not supported: {key}")
+    return resources_pb2.Annotation(data=self.data_proto)
+
+  def _get_geo_point_proto(self, longitude: float, latitude: float,
+                           geo_limit: float) -> resources_pb2.Geo:
+    """Get a GeoPoint proto message based on geographical data.
+
+        Args:
+            longitude (float): Longitude coordinate.
+            latitude (float): Latitude coordinate.
+            geo_limit (float): Geographical limit.
+
+        Returns:
+            resources_pb2.Geo: A Geo proto message.
+        """
+    return resources_pb2.Geo(
+        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]:
+    """Lists all 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.
+
+        Yields:
+            response_dict: The next item in the listing.
+        """
+    page = 1
+    request_data['pagination'] = service_pb2.Pagination(page=page, per_page=self.default_page_size)
+    while True:
+      request_data['pagination'].page = 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:
+        raise Exception(f"Listing failed with response {response!r}")
+
+      if 'hits' not in list(dict_response.keys()):
+        break
+      page += 1
+      yield response
+
+  def query(self, ranks=[{}], filters=[{}]):
+    """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 [{}].
+
+        Returns:
+            Generator[Dict[str, Any], None, None]: A generator of query results.
+        """
+    try:
+      self.rank_filter_schema.validate(ranks)
+      self.rank_filter_schema.validate(filters)
+    except SchemaError as err:
+      raise UserError(f"Invalid rank or filter input: {err}")
+
+    rank_annot_proto, filters_annot_proto = [], []
+    for rank_dict in ranks:
+      rank_annot_proto.append(self._get_annot_proto(**rank_dict))
+    for filter_dict in filters:
+      filters_annot_proto.append(self._get_annot_proto(**filter_dict))
+
+    all_ranks = [resources_pb2.Rank(annotation=rank_annot) for rank_annot in rank_annot_proto]
+    all_filters = [
+        resources_pb2.Filter(annotation=filter_annot) for filter_annot in filters_annot_proto
+    ]
+
+    request_data = dict(
+        user_app_id=self.user_app_id,
+        searches=[
+            resources_pb2.Search(
+                query=resources_pb2.Query(ranks=all_ranks, filters=all_filters),
+                metric=self.metric_distance)
+        ])
+
+    return self.list_all_pages_generator(self.STUB.PostAnnotationsSearches,
+                                         service_pb2.PostAnnotationsSearchesRequest, request_data)