SDK Client
- class groundlight.Groundlight(endpoint: str | None = None, api_token: str | None = None, disable_tls_verification: bool | None = None)
Client for accessing the Groundlight cloud service.
The API token (auth) is specified through the GROUNDLIGHT_API_TOKEN environment variable by default.
Example usage:
gl = Groundlight() detector = gl.get_or_create_detector( name="door", query="Is the door locked?", confidence_threshold=0.9 ) image_query = gl.submit_image_query( detector=detector, image="path/to/image.jpeg", wait=0.0, human_review="ALWAYS" ) print(f"Image query confidence = {image_query.result.confidence}") # Poll the backend service for a confident answer image_query = gl.wait_for_confident_result( image_query=image_query, confidence_threshold=0.9, timeout_sec=60.0 ) # Examine new confidence after a continuously trained ML model has re-evaluated the image query print(f"Image query confidence = {image_query.result.confidence}")
- Parameters:
endpoint (str | None) –
api_token (str | None) –
disable_tls_verification (bool | None) –
- __init__(endpoint: str | None = None, api_token: str | None = None, disable_tls_verification: bool | None = None) None
Constructs a Groundlight client.
- Parameters:
endpoint (str | None) – optionally specify a different endpoint
api_token (str | None) – use this API token for your API calls. If unset, fallback to the environment variable “GROUNDLIGHT_API_TOKEN”.
disable_tls_verification (Optional[bool]) –
Set this to True to skip verifying SSL/TLS certificates when calling API from https server. If unset, the fallback will check the environment variable “DISABLE_TLS_VERIFY” for 1 or 0. By default, certificates are verified.
Disable verification if using a self-signed TLS certificate with a Groundlight Edge Endpoint. It is unadvised to disable verification if connecting directly to the Groundlight cloud service.
- Returns:
Groundlight client
- Return type:
None
- add_label(image_query: ImageQuery | str, label: Label | str)
Add a new label to an image query. This answers the detector’s question.
- Parameters:
image_query (ImageQuery | str) – Either an ImageQuery object (returned from submit_image_query) or an image_query id as a string.
label (Label | str) – The string “YES” or the string “NO” in answer to the query.
- Returns:
None
- ask_async(detector: Detector | str, image: str | bytes | Image | BytesIO | BufferedReader | UnavailableModule, patience_time: float | None = None, confidence_threshold: float | None = None, human_review: str | None = None, metadata: dict | str | None = None, inspection_id: str | None = None) ImageQuery
Convenience method for submitting an ImageQuery asynchronously. This is equivalent to calling submit_image_query with want_async=True and wait=0. Use get_image_query to retrieve the result of the ImageQuery.
- Parameters:
detector (Detector | str) – the Detector object, or string id of a detector like det_12345
image (str | bytes | Image | BytesIO | BufferedReader | UnavailableModule) –
The image, in several possible formats:
filename (string) of a jpeg file
byte array or BytesIO or BufferedReader with jpeg bytes
numpy array with values 0-255 and dimensions (H,W,3) in BGR order (Note OpenCV uses BGR not RGB. img[:, :, ::-1] will reverse the channels)
PIL Image: Any binary format must be JPEG-encoded already. Any pixel format will get converted to JPEG at high quality before sending to service.
patience_time (float | None) – How long to wait (in seconds) for a confident answer for this image query. The longer the patience_time, the more likely Groundlight will arrive at a confident answer. Within patience_time, Groundlight will update ML predictions based on stronger findings, and, additionally, Groundlight will prioritize human review of the image query if necessary. This is a soft server-side timeout. If not set, use the detector’s patience_time.
confidence_threshold (float | None) – The confidence threshold to wait for. If not set, use the detector’s confidence threshold.
human_review (str | None) – If None or DEFAULT, send the image query for human review only if the ML prediction is not confident. If set to ALWAYS, always send the image query for human review. If set to NEVER, never send the image query for human review.
inspection_id (str | None) – Most users will omit this. For accounts with Inspection Reports enabled, this is the ID of the inspection to associate with the image query.
metadata (dict | str | None) – 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().
- Returns:
ImageQuery
- Return type:
Example usage:
gl = Groundlight() detector = gl.get_or_create_detector( name="door", query="Is the door locked?", confidence_threshold=0.9 ) image_query = gl.ask_async( detector=detector, image="path/to/image.jpeg") # the image_query will have an id for later retrieval assert image_query.id is not None # Do not attempt to access the result of this query as the result for all async queries # will be None. Your result is being computed asynchronously and will be available later assert image_query.result is None # retrieve the result later or on another machine by calling gl.wait_for_confident_result() # with the id of the image_query above. This will block until the result is available. image_query = gl.wait_for_confident_result(image_query.id) # now the result will be available for your use assert image_query.result is not None # alternatively, you can check if the result is available (without blocking) by calling # gl.get_image_query() with the id of the image_query above. image_query = gl.get_image_query(image_query.id)
- ask_confident(detector: Detector | str, image: str | bytes | Image | BytesIO | BufferedReader | UnavailableModule, confidence_threshold: float | None = None, wait: float | None = None, metadata: dict | str | None = None, inspection_id: str | None = None) ImageQuery
Evaluates an image with Groundlight waiting until an answer above the confidence threshold of the detector is reached or the wait period has passed.
- Parameters:
detector (Detector | str) – the Detector object, or string id of a detector like det_12345
image (str | bytes | Image | BytesIO | BufferedReader | UnavailableModule) –
The image, in several possible formats: - filename (string) of a jpeg file - byte array or BytesIO or BufferedReader with jpeg bytes - numpy array with values 0-255 and dimensions (H,W,3) in BGR order
(Note OpenCV uses BGR not RGB. img[:, :, ::-1] will reverse the channels)
PIL Image
Any binary format must be JPEG-encoded already. Any pixel format will get converted to JPEG at high quality before sending to service.
confidence_threshold (float | None) – The confidence threshold to wait for. If not set, use the detector’s confidence threshold.
wait (float | None) – How long to wait (in seconds) for a confident answer.
metadata (dict | str | None) – 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().
inspection_id (str | None) –
- Returns:
ImageQuery
- Return type:
- ask_ml(detector: Detector | str, image: str | bytes | Image | BytesIO | BufferedReader | UnavailableModule, wait: float | None = None, metadata: dict | str | None = None, inspection_id: str | None = None) ImageQuery
Evaluates an image with Groundlight, getting the first answer Groundlight can provide.
- Parameters:
detector (Detector | str) – the Detector object, or string id of a detector like det_12345
image (str | bytes | Image | BytesIO | BufferedReader | UnavailableModule) –
The image, in several possible formats: - filename (string) of a jpeg file - byte array or BytesIO or BufferedReader with jpeg bytes - numpy array with values 0-255 and dimensions (H,W,3) in BGR order
(Note OpenCV uses BGR not RGB. img[:, :, ::-1] will reverse the channels)
PIL Image
Any binary format must be JPEG-encoded already. Any pixel format will get converted to JPEG at high quality before sending to service.
wait (float | None) – How long to wait (in seconds) for any answer.
metadata (dict | str | None) – 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().
inspection_id (str | None) –
- Returns:
ImageQuery
- Return type:
- create_detector(name: str, query: str, *, confidence_threshold: float | None = None, pipeline_config: str | None = None, metadata: dict | str | None = None) Detector
Create a new detector with a given name and query
- Parameters:
name (str) – the detector name
query (str) – the detector query
confidence_threshold (float | None) – the confidence threshold
pipeline_config (str | None) – the pipeline config
metadata (dict | str | None) – A dictionary or JSON string of custom key/value metadata to associate with the detector (limited to 1KB). You can retrieve this metadata later by calling get_detector().
- Returns:
Detector
- Return type:
- get_detector_by_name(name: str) Detector
Get a detector by name
- Parameters:
name (str) – the detector name
- Returns:
Detector
- Return type:
- get_image_query(id: str) ImageQuery
Get an image query by id
- Parameters:
id (str) – the image query id
- Returns:
ImageQuery
- Return type:
- get_or_create_detector(name: str, query: str, *, confidence_threshold: float | None = None, pipeline_config: str | None = None, metadata: dict | str | None = None) Detector
Tries to look up the detector by name. If a detector with that name, query, and confidence exists, return it. Otherwise, create a detector with the specified query and config.
- Parameters:
name (str) – the detector name
query (str) – the detector query
confidence_threshold (float | None) – the confidence threshold
pipeline_config (str | None) – the pipeline config
metadata (dict | str | None) – A dictionary or JSON string of custom key/value metadata to associate with the detector (limited to 1KB). You can retrieve this metadata later by calling get_detector().
- Returns:
Detector
- Return type:
- list_detectors(page: int = 1, page_size: int = 10) PaginatedDetectorList
List out detectors you own
- Parameters:
page (int) – the page number
page_size (int) – the page size
- Returns:
PaginatedDetectorList
- Return type:
- list_image_queries(page: int = 1, page_size: int = 10) PaginatedImageQueryList
List out image queries you own
- Parameters:
page (int) – the page number
page_size (int) – the page size
- Returns:
PaginatedImageQueryList
- Return type:
- start_inspection() str
NOTE: For users with Inspection Reports enabled only. Starts an inspection report and returns the id of the inspection.
- Returns:
The unique identifier of the inspection.
- Return type:
str
- stop_inspection(inspection_id: str) str
NOTE: For users with Inspection Reports enabled only. Stops an inspection and raises an exception if the response from the server indicates that the inspection was not successfully stopped.
- Parameters:
inspection_id (str) – The unique identifier of the inspection.
- Returns:
“PASS” or “FAIL” depending on the result of the inspection.
- Return type:
str
- submit_image_query(detector: Detector | str, image: str | bytes | Image | BytesIO | BufferedReader | UnavailableModule, wait: float | None = None, patience_time: float | None = None, confidence_threshold: float | None = None, human_review: str | None = None, want_async: bool = False, inspection_id: str | None = None, metadata: dict | str | None = None) ImageQuery
Evaluates an image with Groundlight.
- Parameters:
detector (Detector | str) – the Detector object, or string id of a detector like det_12345
image (str | bytes | Image | BytesIO | BufferedReader | UnavailableModule) –
The image, in several possible formats: - filename (string) of a jpeg file - byte array or BytesIO or BufferedReader with jpeg bytes - numpy array with values 0-255 and dimensions (H,W,3) in BGR order
(Note OpenCV uses BGR not RGB. img[:, :, ::-1] will reverse the channels)
PIL Image: Any binary format must be JPEG-encoded already. Any pixel format will get converted to JPEG at high quality before sending to service.
wait (float | None) – How long to poll (in seconds) for a confident answer. This is a client-side timeout.
patience_time (float | None) – How long to wait (in seconds) for a confident answer for this image query. The longer the patience_time, the more likely Groundlight will arrive at a confident answer. Within patience_time, Groundlight will update ML predictions based on stronger findings, and, additionally, Groundlight will prioritize human review of the image query if necessary. This is a soft server-side timeout. If not set, use the detector’s patience_time.
confidence_threshold (float | None) – The confidence threshold to wait for. If not set, use the detector’s confidence threshold.
human_review (str | None) – If None or DEFAULT, send the image query for human review only if the ML prediction is not confident. If set to ALWAYS, always send the image query for human review. If set to NEVER, never send the image query for human review.
want_async (bool) – If True, the client will return as soon as the image query is submitted and will not wait for an ML/human prediction. The returned ImageQuery will have a result of None. Must set wait to 0 to use want_async.
inspection_id (str | None) – Most users will omit this. For accounts with Inspection Reports enabled, this is the ID of the inspection to associate with the image query.
metadata (dict | str | None) – 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().
- Returns:
ImageQuery
- Return type:
- update_detector_confidence_threshold(detector_id: str, confidence_threshold: float) None
Updates the confidence threshold of a detector given a detector_id.
- Parameters:
detector_id (str) – The id of the detector to update.
confidence_threshold (float) – The new confidence threshold for the detector.
- Return type:
None
:return None :rtype None
- update_inspection_metadata(inspection_id: str, user_provided_key: str, user_provided_value: str) None
NOTE: For users with Inspection Reports enabled only. Add/update inspection metadata with the user_provided_key and user_provided_value.
- Parameters:
inspection_id (str) – The unique identifier of the inspection.
user_provided_key (str) – the key in the key/value pair for the inspection metadata.
user_provided_value (str) – the value in the key/value pair for the inspection metadata.
- Returns:
None
- Return type:
None
- wait_for_confident_result(image_query: ImageQuery | str, confidence_threshold: float | None = None, timeout_sec: float = 30.0) ImageQuery
Waits for an image query result’s confidence level to reach the specified value. Currently this is done by polling with an exponential back-off.
- Parameters:
image_query (ImageQuery | str) – An ImageQuery object to poll
confidence_threshold (float | None) – The confidence threshold to wait for. If not set, use the detector’s confidence threshold.
timeout_sec (float) – The maximum number of seconds to wait.
- Returns:
ImageQuery
- Return type:
- wait_for_ml_result(image_query: ImageQuery | str, timeout_sec: float = 30.0) ImageQuery
Waits for the first ml result to be returned. Currently this is done by polling with an exponential back-off.
- Parameters:
image_query (ImageQuery | str) – An ImageQuery object to poll
timeout_sec (float) – The maximum number of seconds to wait.
- Returns:
ImageQuery
- Return type:
- whoami() str
Return the username associated with the API token.
- Returns:
str
- Return type:
str
API Response Objects
- pydantic model model.Detector
Show JSON schema
{ "title": "Detector", "type": "object", "properties": { "id": { "description": "A unique ID for this object.", "title": "Id", "type": "string" }, "type": { "allOf": [ { "$ref": "#/$defs/DetectorTypeEnum" } ], "description": "The type of this object." }, "created_at": { "description": "When this detector was created.", "format": "date-time", "title": "Created At", "type": "string" }, "name": { "description": "A short, descriptive name for the detector.", "maxLength": 200, "title": "Name", "type": "string" }, "query": { "description": "A question about the image.", "title": "Query", "type": "string" }, "group_name": { "description": "Which group should this detector be part of?", "title": "Group Name", "type": "string" }, "confidence_threshold": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": 0.9, "description": "If the detector's prediction is below this confidence threshold, send the image query for human review.", "title": "Confidence Threshold" }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "default": null, "description": "A dictionary of custom key/value metadata to associate with the detector (limited to 1KB). This is encoded as a URL-safe, base64-encoded JSON string.", "title": "Metadata" } }, "$defs": { "DetectorTypeEnum": { "const": "detector", "title": "DetectorTypeEnum" } }, "required": [ "id", "type", "created_at", "name", "query", "group_name" ] }
- Fields:
- field confidence_threshold: Optional[confloat(ge=0.0, le=1.0)] = 0.9
If the detector’s prediction is below this confidence threshold, send the image query for human review.
- field created_at: datetime [Required]
When this detector was created.
- field group_name: str [Required]
Which group should this detector be part of?
- field id: str [Required]
A unique ID for this object.
- field metadata: Dict[str, Any] | None = None
A dictionary of custom key/value metadata to associate with the detector (limited to 1KB). This is encoded as a URL-safe, base64-encoded JSON string.
- field name: constr(max_length=200) [Required]
A short, descriptive name for the detector.
- Constraints:
max_length = 200
- field query: str [Required]
A question about the image.
- field type: DetectorTypeEnum [Required]
The type of this object.
- pydantic model model.ImageQuery
Show JSON schema
{ "title": "ImageQuery", "type": "object", "properties": { "id": { "description": "A unique ID for this object.", "title": "Id", "type": "string" }, "type": { "allOf": [ { "$ref": "#/$defs/ImageQueryTypeEnum" } ], "description": "The type of this object." }, "created_at": { "description": "When was this detector created?", "format": "date-time", "title": "Created At", "type": "string" }, "query": { "description": "A question about the image.", "title": "Query", "type": "string" }, "detector_id": { "description": "Which detector was used on this image query?", "title": "Detector Id", "type": "string" }, "result_type": { "allOf": [ { "$ref": "#/$defs/ResultTypeEnum" } ], "description": "What type of result are we returning?" }, "result": { "anyOf": [ { "$ref": "#/$defs/ClassificationResult" }, { "type": "null" } ], "default": null }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "default": null, "description": "A dictionary of custom key/value metadata to associate with the image query (limited to 1KB).", "title": "Metadata" } }, "$defs": { "ClassificationResult": { "properties": { "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "On a scale of 0 to 1, how confident are we in the predicted label?", "title": "Confidence" }, "label": { "description": "What is the predicted label?", "title": "Label", "type": "string" } }, "required": [ "label" ], "title": "ClassificationResult", "type": "object" }, "ImageQueryTypeEnum": { "const": "image_query", "title": "ImageQueryTypeEnum" }, "ResultTypeEnum": { "const": "binary_classification", "title": "ResultTypeEnum" } }, "required": [ "id", "type", "created_at", "query", "detector_id", "result_type" ] }
- Fields:
- field created_at: datetime [Required]
When was this detector created?
- field detector_id: str [Required]
Which detector was used on this image query?
- field id: str [Required]
A unique ID for this object.
- field metadata: Dict[str, Any] | None = None
A dictionary of custom key/value metadata to associate with the image query (limited to 1KB).
- field query: str [Required]
A question about the image.
- field result: ClassificationResult | None = None
- field result_type: ResultTypeEnum [Required]
What type of result are we returning?
- field type: ImageQueryTypeEnum [Required]
The type of this object.
- pydantic model model.PaginatedDetectorList
Show JSON schema
{ "title": "PaginatedDetectorList", "type": "object", "properties": { "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "example": 123, "title": "Count" }, "next": { "anyOf": [ { "format": "uri", "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "example": "http://api.example.org/accounts/?page=4", "title": "Next" }, "previous": { "anyOf": [ { "format": "uri", "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "example": "http://api.example.org/accounts/?page=2", "title": "Previous" }, "results": { "anyOf": [ { "items": { "$ref": "#/$defs/Detector" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Results" } }, "$defs": { "Detector": { "properties": { "id": { "description": "A unique ID for this object.", "title": "Id", "type": "string" }, "type": { "allOf": [ { "$ref": "#/$defs/DetectorTypeEnum" } ], "description": "The type of this object." }, "created_at": { "description": "When this detector was created.", "format": "date-time", "title": "Created At", "type": "string" }, "name": { "description": "A short, descriptive name for the detector.", "maxLength": 200, "title": "Name", "type": "string" }, "query": { "description": "A question about the image.", "title": "Query", "type": "string" }, "group_name": { "description": "Which group should this detector be part of?", "title": "Group Name", "type": "string" }, "confidence_threshold": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": 0.9, "description": "If the detector's prediction is below this confidence threshold, send the image query for human review.", "title": "Confidence Threshold" }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "default": null, "description": "A dictionary of custom key/value metadata to associate with the detector (limited to 1KB). This is encoded as a URL-safe, base64-encoded JSON string.", "title": "Metadata" } }, "required": [ "id", "type", "created_at", "name", "query", "group_name" ], "title": "Detector", "type": "object" }, "DetectorTypeEnum": { "const": "detector", "title": "DetectorTypeEnum" } } }
- Fields:
- field count: int | None = None
- field next: AnyUrl | None = None
- field previous: AnyUrl | None = None
- pydantic model model.PaginatedImageQueryList
Show JSON schema
{ "title": "PaginatedImageQueryList", "type": "object", "properties": { "count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "example": 123, "title": "Count" }, "next": { "anyOf": [ { "format": "uri", "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "example": "http://api.example.org/accounts/?page=4", "title": "Next" }, "previous": { "anyOf": [ { "format": "uri", "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "example": "http://api.example.org/accounts/?page=2", "title": "Previous" }, "results": { "anyOf": [ { "items": { "$ref": "#/$defs/ImageQuery" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Results" } }, "$defs": { "ClassificationResult": { "properties": { "confidence": { "anyOf": [ { "maximum": 1.0, "minimum": 0.0, "type": "number" }, { "type": "null" } ], "default": null, "description": "On a scale of 0 to 1, how confident are we in the predicted label?", "title": "Confidence" }, "label": { "description": "What is the predicted label?", "title": "Label", "type": "string" } }, "required": [ "label" ], "title": "ClassificationResult", "type": "object" }, "ImageQuery": { "properties": { "id": { "description": "A unique ID for this object.", "title": "Id", "type": "string" }, "type": { "allOf": [ { "$ref": "#/$defs/ImageQueryTypeEnum" } ], "description": "The type of this object." }, "created_at": { "description": "When was this detector created?", "format": "date-time", "title": "Created At", "type": "string" }, "query": { "description": "A question about the image.", "title": "Query", "type": "string" }, "detector_id": { "description": "Which detector was used on this image query?", "title": "Detector Id", "type": "string" }, "result_type": { "allOf": [ { "$ref": "#/$defs/ResultTypeEnum" } ], "description": "What type of result are we returning?" }, "result": { "anyOf": [ { "$ref": "#/$defs/ClassificationResult" }, { "type": "null" } ], "default": null }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "default": null, "description": "A dictionary of custom key/value metadata to associate with the image query (limited to 1KB).", "title": "Metadata" } }, "required": [ "id", "type", "created_at", "query", "detector_id", "result_type" ], "title": "ImageQuery", "type": "object" }, "ImageQueryTypeEnum": { "const": "image_query", "title": "ImageQueryTypeEnum" }, "ResultTypeEnum": { "const": "binary_classification", "title": "ResultTypeEnum" } } }
- Fields:
- field count: int | None = None
- field next: AnyUrl | None = None
- field previous: AnyUrl | None = None
- field results: List[ImageQuery] | None = None