uai_annotation_requests 0.4.4

Understand.ai Python Client SDK for requesting annotations.

UAI Annotation Requests

Summary

UAI Annotation Requests: The API lets a client request annotations from UAI, track the progress of the work and fetch the result annotations.

Table of Contents

• UAI Annotation Requests
  • Example Usage
  • Authentication
  • Available Resources and Operations
  • Error Handling

Example Usage

Example

Below is an example of how an annotation request with data can be submitted to UAI for annotation.

from uai_annotation_requests import UaiAnnotationRequests
from uai_annotation_requests_util import uai_oauth2, uai_upload_data

with UaiAnnotationRequests(
    uai_oauth2=uai_oauth2("<client_id>", "<client_secret>"),
) as uar_client:

    res = uar_client.annotation_request.create(project_id="<id>", clips=[
        {
            "clip_reference_id": "clip_reference_01",
            "display_name": "my first clip",
        },
    ], request_reference_id="request_reference_01", priority=0, display_name="my annotation request")

    # Handle response
    print(res)

    # Upload data directory for each defined clip
    # The upload step here is only relevant for projects
    # That are uploading archived data to UAI where no
    # bucket integration is configured.
    for clip in res.clips:
        uai_upload_data(res, clip, path_to_data)

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

Name	Type	Scheme
uai_oauth2	oauth2	uai_oauth2 helper or OAuth2 token

To authenticate with the API the uai_oauth2 parameter must be set when initializing the SDK client instance. The uai_oauth2 parameter accepts either the uai_oauth2 helper login function or an OAuth2 token. For example:

from uai_annotation_requests import UaiAnnotationRequests
from uai_annotation_requests_util import uai_oauth2

with UaiAnnotationRequests(
    uai_oauth2=uai_oauth2(client_id="<UAI_CLIENT_ID>", client_secret="<UAI_CLIENT_SECRET>"),
) as uar_client:

    res = uar_client.annotation_request.create(project_id="<id>", clips=[
        {
            "clip_reference_id": "clip_reference_01",
            "display_name": "my first clip",
        },
    ], request_reference_id="request_reference_01", priority=0, display_name="my annotation request")

    # Handle response
    print(res)

Available Resources and Operations

Available methods

annotation_request

• create - Create a new annotation request
• get - Get annotation request
• get_by_annotation_request_id - Get annotation request by the annotation request ID
• get_exported_annotations - Request the download URLs for the result annotations.

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or raise an exception.

By default, an API error will raise a models.APIError exception, which has the following properties:

Property	Type	Description
.status_code	int	The HTTP status code
.message	str	The error message
.raw_response	httpx.Response	The raw HTTP response
.body	str	The response content

When custom error responses are specified for an operation, the SDK may also raise their associated exceptions. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the get_async method may raise the following exceptions:

Error Type	Status Code	Content Type
models.AnnotationRequestNotFoundDTO	404	application/json
models.APIError	4XX, 5XX	*/*

Example

import uai_annotation_requests
from uai_annotation_requests import UaiAnnotationRequests, models

with UaiAnnotationRequests(
    uai_oauth2="<YOUR_UAI_OAUTH2_HERE>",
) as uar_client:
    res = None
    try:

        res = uar_client.annotation_request.get(project_id="<id>", field=uai_annotation_requests.FilterField.REQUEST_REFERENCE_ID, value="<value>")

        # Handle response
        print(res)

    except models.AnnotationRequestNotFoundDTO as e:
        # handle e.data: models.AnnotationRequestNotFoundDTOData
        raise(e)
    except models.APIError as e:
        # handle exception
        raise(e)