update spec and add image_query_id param

spec/public-api.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Groundlight API
-  version: 0.18.1
+  version: 0.18.2
   description: Groundlight makes it simple to understand images. You can easily create
     computer vision detectors just by describing what you want to know using natural
     language.
@@ -336,18 +336,16 @@ paths:
           description: ''
     post:
       operationId: Submit image query
-      description: |2+
+      description: |2
 
         Submit an image query against a detector.
 
-        You must use `"Content-Type: image/jpeg"` for the image data. For example:
-
+        You must use `"Content-Type: image/jpeg"` or similar (image/png, image/webp, etc) for the image data. For example:
         ```Bash
         $ curl https://api.groundlight.ai/device-api/v1/image-queries?detector_id=det_abc123 \
             --header "Content-Type: image/jpeg" \
             --data-binary @path/to/filename.jpeg
         ```
-
       parameters:
       - in: query
         name: detector_id
@@ -363,6 +361,11 @@ paths:
           If set to `DEFAULT`, use the regular escalation logic (i.e., send the image query for human review if the ML model is not confident).
           If set to `ALWAYS`, always send the image query for human review even if the ML model is confident.
           If set to `NEVER`, never send the image query for human review even if the ML model is not confident.
+      - in: query
+        name: image_query_id
+        schema:
+          type: string
+        description: The ID to assign to the created image query.
       - in: query
         name: inspection_id
         schema:
@@ -995,6 +998,7 @@ components:
       - confidence
       - created_at
       - detector_id
+      - source
       - text
     LabelValueRequest:
       type: object
@@ -1330,7 +1334,6 @@ components:
           minimum: 0.0
           maximum: 1.0
         source:
-          description: Source is optional to support edge v0.2
           type: string
           enum:
           - STILL_PROCESSING
@@ -1355,7 +1358,6 @@ components:
           minimum: 0.0
           maximum: 1.0
         source:
-          description: Source is optional to support edge v0.2
           type: string
           enum:
           - STILL_PROCESSING
@@ -1380,7 +1382,6 @@ components:
           minimum: 0.0
           maximum: 1.0
         source:
-          description: Source is optional to support edge v0.2
           type: string
           enum:
           - STILL_PROCESSING

src/groundlight/client.py

@@ -441,6 +441,7 @@ def submit_image_query(  # noqa: PLR0913 # pylint: disable=too-many-arguments, t
         want_async: bool = False,
         inspection_id: Optional[str] = None,
         metadata: Union[dict, str, None] = None,
+        image_query_id: Optional[str] = None,
     ) -> ImageQuery:
         """
         Evaluates an image with Groundlight.
@@ -482,6 +483,9 @@ def submit_image_query(  # noqa: PLR0913 # pylint: disable=too-many-arguments, t
             the image query (limited to 1KB). You can retrieve this metadata later by calling
             `get_image_query()`.
 
+        :param image_query_id: The ID for the image query. This is to enable specific functionality and is not intended
+            for general external use. If not set, a random ID will be generated.
+
         :return: ImageQuery
         """
         if wait is None:
@@ -516,6 +520,9 @@ def submit_image_query(  # noqa: PLR0913 # pylint: disable=too-many-arguments, t
             # which means we need to put the metadata in the query string. To do that safely, we
             # url- and base64-encode the metadata.
             params["metadata"] = url_encode_dict(metadata, name="metadata", size_limit_bytes=1024)
+
+        if image_query_id is not None:
+            params["image_query_id"] = image_query_id
 
         raw_image_query = self.image_queries_api.submit_image_query(**params)
         image_query = ImageQuery.parse_obj(raw_image_query.to_dict())
@@ -536,6 +543,7 @@ def ask_confident(  # noqa: PLR0913 # pylint: disable=too-many-arguments
         confidence_threshold: Optional[float] = None,
         wait: Optional[float] = None,
         metadata: Union[dict, str, None] = None,
+        image_query_id: Optional[str] = None,
         inspection_id: Optional[str] = None,
     ) -> ImageQuery:
         """
@@ -561,6 +569,9 @@ def ask_confident(  # noqa: PLR0913 # pylint: disable=too-many-arguments
         :param metadata: A dictionary or JSON string of custom key/value metadata to associate with
             the image query (limited to 1KB). You can retrieve this metadata later by calling
             `get_image_query()`.
+        
+        :param image_query_id: The ID for the image query. This is to enable specific functionality and is not intended
+            for general external use. If not set, a random ID will be generated.
 
         :return: ImageQuery
         """
@@ -572,6 +583,7 @@ def ask_confident(  # noqa: PLR0913 # pylint: disable=too-many-arguments
             patience_time=wait,
             human_review=None,
             metadata=metadata,
+            image_query_id=image_query_id,
             inspection_id=inspection_id,
         )
 
@@ -581,6 +593,7 @@ def ask_ml(  # noqa: PLR0913 # pylint: disable=too-many-arguments, too-many-loca
         image: Union[str, bytes, Image.Image, BytesIO, BufferedReader, np.ndarray],
         wait: Optional[float] = None,
         metadata: Union[dict, str, None] = None,
+        image_query_id: Optional[str] = None,
         inspection_id: Optional[str] = None,
     ) -> ImageQuery:
         """
@@ -602,6 +615,9 @@ def ask_ml(  # noqa: PLR0913 # pylint: disable=too-many-arguments, too-many-loca
         :param metadata: A dictionary or JSON string of custom key/value metadata to associate with
             the image query (limited to 1KB). You can retrieve this metadata later by calling
             `get_image_query()`.
+        
+        :param image_query_id: The ID for the image query. This is to enable specific functionality and is not intended
+            for general external use. If not set, a random ID will be generated.
 
         :return: ImageQuery
         """
@@ -610,6 +626,7 @@ def ask_ml(  # noqa: PLR0913 # pylint: disable=too-many-arguments, too-many-loca
             image,
             wait=0,
             metadata=metadata,
+            image_query_id=image_query_id,
             inspection_id=inspection_id,
         )
         if iq_is_answered(iq):
@@ -625,6 +642,7 @@ def ask_async(  # noqa: PLR0913 # pylint: disable=too-many-arguments
         confidence_threshold: Optional[float] = None,
         human_review: Optional[str] = None,
         metadata: Union[dict, str, None] = None,
+        image_query_id: Optional[str] = None,
         inspection_id: Optional[str] = None,
     ) -> ImageQuery:
         """
@@ -664,6 +682,9 @@ def ask_async(  # noqa: PLR0913 # pylint: disable=too-many-arguments
         :param metadata: A dictionary or JSON string of custom key/value metadata to associate with
             the image query (limited to 1KB). You can retrieve this metadata later by calling
             `get_image_query()`.
+        
+        :param image_query_id: The ID for the image query. This is to enable specific functionality and is not intended
+            for general external use. If not set, a random ID will be generated.
 
         :return: ImageQuery
 
@@ -708,6 +729,7 @@ def ask_async(  # noqa: PLR0913 # pylint: disable=too-many-arguments
             human_review=human_review,
             want_async=True,
             metadata=metadata,
+            image_query_id=image_query_id,
             inspection_id=inspection_id,
         )