SDK Documentation
How to install and use Ango Hub's Python SDK.
We provide a Python SDK to interface programmatically with Ango Hub.
SDK Installation
How to Install the Ango SDK
To use the Ango SDK, you will need the latest imerit-ango Python package, which we publish on PyPI.
To download and add the package to your current Python environment, simply run
How to upgrade the Ango SDK
To upgrade the imerit-ango package to its latest version in your current Python environment run
Obtaining your API Key
To use the imerit-ango package, you will need an API key. To obtain your API key, from your account page, enter the API tab. From here, you can create and copy your API key. For more information, please visit the Get your API Key page.
Creating a new API key will revoke the existing one.
Obtaining Project and Task IDs
Each project and task in Ango Hub is assigned its own unique ID. You may need to use such IDs in the SDK.
Project IDs
To obtain a project's ID, open the project and look at your browser's address bar. The URL will be in the format:
https://imerit.ango.ai/projects/<project_id>
Copy the project ID from your address bar.
Task and Asset IDs
To obtain Task and Asset IDs, from the Task or the Assets tab, open the task you'd like to copy the ID of. Then, open the Task Info panel on the right and copy the ID you need.
You may use one of the Copy to Clipboard buttons to speed up the process.
Environmental Variables
Snippets in this page make the assumption that you have your API key and other variables set as environmental variables.
To set environmental variables, install the python-dotenv package from pip by running
in your Python environment.
Then, create a file called .env in your environment's root folder. The contents of this .env file will look like this:
In your Python scripts, then, import the package by using
and load the environmental variables by running load_dotenv() before using the variables in your script.
You will then be able to access your environmental variables by using os.getenv("VAR_NAME"), like so:
Project Level SDK Functions (v1.3.14)
imerit_ango.sdk.SDK.
add_members_to_project(project_id, members, role)
Add specific users to a project.
Parameters:
project_id: string
ID of the project where the attachment will be created. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
members: List[str]
A list of emails of the user(s) you wish to add to the project.
Example:
["user1@test.com", "user2@test.com"]
role: imerit_ango.models.enums.ProjectRoles
The role in which you would like to add the user(s) to the project.
Example:
ProjectRoles.labeler(Note: you must import the enum containing the roles using
from imerit_ango.models.enums import ProjectRoles)
Returns:
No return.
Example:
assign_batches(project_id, asset_ids, batches)
Assign specific asset(s) to specific batches.
Parameters:
project_id: string
ID of the project where the attachment will be created. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
asset_ids: List[str]
List of asset IDs to assign to batches. Asset IDs can be obtained from the UI, or from get_assets.
Example:
['0000000aa0a00a0000aaaa0a', '0000000aa0a00a0000aaaa0b']
batches: List[str]
List of batches to which assets will be assigned.
You can choose to pass either a list of batch names or a list of batch IDs. Batch names and batch IDs can be obtained with get_batches.
Example:
['Batch-1', 'Batch-2']or['0000000aa0a00a0000aaaa0a', '0000000aa0a00a0000aaaa0b']
Returns:
output: dict
Example:
Outputs:
Where "assets" is the number of assets successfully assigned to the batch(es).
See also
assign_task(project, tasks, stage, email)
Assign a task to a specific user with email.
Parameters:
project: string
ID of the project where the attachment will be created. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
tasks: list
A list of task IDs to be assigned. Task IDs can be obtained from the UI, and from get_tasks.
Example: [
'0000000aa0a00a0000aaaa0a', '0000000bb0b00b0000bbbb0b']
stage_filter: string
ID of the stage on which the assignee will work.
Example:
"206f2f63-ac2d-4458-92d8-b84fd7264db3"or, in the case of the default labeling stage,"Label".
email: string
Mail address with which the user is to be assigned the task to register.
Example:
'lorenzo@example.com'
Returns:
output: dict
Example:
See also
create_attachment(project_id, attachments)
Add attachments to assets in a project. More on attachments and uploading them here.
Parameters:
project_id: string
ID of the project where the attachment will be created. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
attachments: List[dict]
List of attachments to attach to existing assets. Attachments are dictionaries containing information about the asset the attachment will be attached to, the type of attachment, and the content of the attachment.
Example attachment parameter with 3 attachments being attached to 2 assets:
Attachments can have one of the types "IMAGE", "TEXT", or "VIDEO".
For IMAGE and VIDEO, you will need to provide a link to the resource. JPG, PNG, and MP4 are supported.
For text, you will need to provide the text that will be attached.
For image and video attachments, you may provide links to assets in private buckets, provided that you've connected them to Ango Hub. More information on how to do so can be found in the Attachments page.
In AWS S3, if your attachment URL does not contain region information, your attachments may not be visible. When using S3, please ensure the region information is contained in the URL right after the bucket name, like so:
Returns:
output: dict
Example:
create_batch(project_id, batch_name)
Create batches in a specific project.
Parameters:
project_id: str
ID of the project where the batch will be created. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
batch_name: str
Name of the batch to be created.
Example:
'My Batch 1'
Returns:
output: dict
Example:
See also
create_issue(task_id, content, position)
Opens an issue to the specified task, with given content on the given position.
Parameters:
task_id: string
ID of the task to be assigned. Task IDs can be obtained from the UI and from get_tasks.
Example:
'0000000aa0a00a0000aaaa0a'
content: string
Text content of the issue.
Example:
'The bounding box here should reach the edges.'
position: List[integer]
Position, in pixel, of where the issue should be placed on the image asset.
Example:
[25, 15]
Returns:
output: dict
Example:
See also
create_label_set(project_id, tools, classifications, relations)
Create and set the project's ontology.
As this method is more complex than others, we recommend also consulting the examples at the end of this section.
Parameters:
project_id: string
ID of the project where the label set will be created. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
tools: List[ToolCategory], optional
List of tools that will be added to the label set.
Example:
[ToolCategory(Tool.Segmentation, title="SegmentationTool")]
classifications: List[ClassificationCategory], optional, default None
List of classifications that will be added to the label set.
Example:
[ClassificationCategory(Classification.Single_dropdown, title = "Choice", options=[LabelOption("First"), LabelOption("Second")])]
relations: List[RelationCategory], optional, default None
List of relations that will be added to the label set.
Example:
[RelationCategory(Relation.Single, title="SingleRelationTool")]
raw_category_schema: Dict, optional, default None
Instead of creating the label set (category schema) using the previous 'tools', 'classifications', and 'relations' parameters, you may pass here a dictionary representing the entire category schema.
See section below for an example.
To get an example of what can be passed as the raw_category_schema, there are two ways:
Using the SDK itself, get the category schema from another existing project. This will also allow you to programmatically copy the category schema between two projects, like so:
As an example, a raw_category_schema obtained from a project could be this:
Label Set Classes
ToolCategory: {Segmentation, Polyline, Polygon, Rotated_bounding_box, Ner, Point, Pdf}
ToolCategory Parameters:
tool: Tool
The tool type. ex.:
Tool.Segmentation
title: string, default ""
The title of the tool.
required: bool, default None
Whether annotators are required to draw at least one instance of this tool.
schemaId: string, default None
Sets the tool's schemaId.
columnField: bool, default False
Whether this tool should be a table column.
color: string, default ""
The color assigned to this labeling tool, in the format "#FFFFFF"
shortcutKey: string, default ""
The shortcut to quickly select this tool, "0"-"9", "ctrl+0"-"ctrl+9", "a"-"k"
classifications: List[ClassificationCategory], default []
List of nested classifications, if any
options: List[LabelOption], default []
The tool's answers (options.)
ClassificationCategory: {Multi_dropdown, Single_dropdown Tree_dropdown, Radio, Checkbox, Text, Instance}
ClassificationCategory Parameters:
classification: Classification
The classification type. ex.:
Classification.Tree_dropdown
title: string, default ""
The title of the classification.
required: bool, default None
Whether annotators have to answer this classification or not.
schemaId: string, default None
Sets the classification's Schema ID.
columnField: bool, default False
Whether this classification should be a table column.
color: string, default ""
The color assigned to this labeling tool, in the format "#FFFFFF"
shortcutKey: string, default ""
The shortcut to quickly select this tool, "0"-"9", "ctrl+0"-"ctrl+9", "a"-"k"
classifications: List, default [ClassificationCategory]
List of nested classifications, if any
options: List[LabelOption], default []
The classification's answers (options.)
treeOptions: List[TreeOption], default []
For trees, the tree's leaves/branches.
parentOptionId: string, default ""
The schema ID of the parent option. That is, the option that the labeler needs to select in order for this classification to appear. Enables conditional nesting.
richText: bool, default False
Set to True to enable the Rich Text editor for the selected text classification tool.
RelationCategory: {Single, Group}
RelationCategory Parameters:
relation: Relation
The classification type. ex.:
Relation.Single
title: string, default ""
The title of the relation.
required: bool, default None
Whether annotators have to include at least one such relation in order to submit their annotation.
schemaId: string, default None
Sets the schemaId of the relation.
columnField: bool, default False
Whether this relation should be a table column.
color: string, default ""
The color assigned to this relation, in the format "#FFFFFF"
shortcutKey: string, default ""
The shortcut to quickly select this relation, "0"-"9", "ctrl+0"-"ctrl+9", "a"-"k"
classifications: List[ClassificationCategory], default []
List of nested classifications, if any
options: List[LabelOption], default []
The relation's answers (options.)
LabelOption parameters:
value: string
The text of the answer (option.)
schemaId: string, default None
The schema ID of the option. Necessary for conditional nesting.
Returns:
output: dict
Examples:
Creating an ontology with:
A Single Dropdown classification, with two choices named "First" and "Second":
Creating an ontology with:
A Single Dropdown classification with the classifications "First" and "Second"
A Segmentation tool called "SegmentationTool"
A Single Relation called "SingleRelationTool"
Creating an ontology with:
A Single Dropdown classification called "Entity Type" with the choices "Vehicle" and "Person"
Another Single Dropdown classification nested inside the first unconditionally (that is, any choice in the first dropdown will open this second) named "Position" with the choices "On Road" and "Off Road".
Creating an ontology with:
A Tree Dropdown tool with:
A root
With a "tree0" branch
With a "subtree0" leaf
With a "subtree1" leaf
With a "tree1" leaf
Creating an ontology with:
A radio classification tool with two possible answers, "Radio Option 1" and "Radio Option 2"
A conditionally nested Text classification tool using the rich text editor, which only appears if the labeler clicks on "Radio Option 1" (here,
parentOptionIdlinks the text tool to the option which reveals it)
Creating an ontology with:
A radio classification tool with the possible answers "Radio Answer 1" and "Radio Answer 2"
A Tree Dropdown classification tool which only appears if the annotator clicks on "Radio Answer 1"
The Tree Dropdown has a main root
With a branch called "Branch 1"
With leaves called "Leaf 1" and "Leaf 2"
With a leaf called "Leaf 3"
create_project(name, description)
Creates a new project.
Parameters:
name: string
The name of the project to be created. This field cannot be empty.
Example:
'Project One'
description: string, optional, default ""
Example:
'Vehicle Classification Project'
Returns:
output: dict
Example:
Returns:
See also
export(project_id, assignees, completed_at, updated_at, batches)
Export annotated assets together with labels and metadata. Use assignee, completed_at, updated_at or batch filters to export specific parts of the dataset.
Parameters:
project_id: string
ID of the project which will be exported. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
assignees: List[string], optional, default None
You may filter your export by only obtaining tasks completed by certain users. Enter your User IDs here. User IDs can be obtained with get_project.
Example:
['0000000aa0a00a0000aaaa0a', '0000000aa0a00a0000aaaa0b']
completed_at: List[datetime.datetime], optional, default None
You may obtain only tasks completed between two specific dates.
Example, to only export tasks completed from December 1st to today:
[datetime.datetime.fromisoformat("2022-12-01"), datetime.datetime.now()]
updated_at: List[datetime.datetime], optional, default None
You may obtain only tasks updated between two specific dates.
Example, to only export tasks updated from December 1st to today:
[datetime.datetime.fromisoformat("2022-12-01"), datetime.datetime.now()]
batches: List[string], optional, default None
You may choose to only export assets pertaining to one or more specific batches.
Example:
['0000000aa0a00a0000aaaa0a']
Returns:
output: dict
Example:
See also
exportV3(project_id, batches, stage, format, type, zip_file_path, filters)
Export annotated assets together with labels and metadata. Use batch or stage filters to export specific parts of the dataset.
Parameters:
project_id: string
ID of the project which will be exported. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
batches: List[string], optional, default None
You may choose to only export assets pertaining to one or more specific batches.
Example:
['0000000aa0a00a0000aaaa0a']
stage: List[string], optional, default None
You may choose to only export assets pertaining to one or more specific stages.
Example:
['Complete']
format: string, default "json", {"json", "ndjson"}
Select the format of the export output
Example: "
ndjson"
type: string, optional, default None, {"issue"}
You may choose to only export issues by passing
type="issue".
zip_file_path: string, optional, default None
If included, the export will be directly downloaded as a .zip file instead of being returned as a Python dictionary. This prevents our server from having to unzip and dict-ify the export, reducing loading times.
Example:
"/Users/lorenzo/Downloads/my_export.zip"
filters: Dict{string:string}
You may filter the export by including a filters dict here.
If you do not include it, by default, the export will not be filtered and it will contain all information.
Here is what you can include in the filters dict (picking true or false as necessary):
Returns:
output: dict
See also
get_assets(project_id, asset_id, external_id, page, limit, filters)
Get details of assets from a project.
Parameters:
project_id: string
ID of the project of which the assets will be obtained. Project IDs can be procured from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
asset_id: string, Optional, default None
List of asset IDs to assign to batches. (Asset IDs can be obtained from the UI, with get_project(project_id), and with get_tasks(project_id, page, limit, status)
Example:
['0000000aa0a00a0000aaaa0a', '0000000aa0a00a0000aaaa0b']
external_id: string, Optional, default None
page: integer, default 1
limit: integer, default 10
filters: dict
By default, all assets will be returned. By including a dict filter here, you may filter the assets you receive.
Here is a list of possible filters you may pass in the filters dict:
Returns:
output: dict
get_metrics(project_id, metric)
Get metrics from a project.
Parameters:
project_id: string
ID of the project of which the assets will be obtained. Project IDs can be procured from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
metric: imerit_ango.sdk.Metrics
The metric you wish to obtain, from:
imerit_ango.sdk.LabelStageGroupsTimePerTaskAnnotationStatusAnswerDistributionConsensusRangesAssetSize
Returns:
output: dict
Example:
get_batches(project_id)
Get details of all batches in a project.
Parameters:
project_id: string
ID of the project to download the batches of. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
Returns:
output: dict
Example:
Outputs:
See also
get_project(project_id)
Get details of a project.
Objects available within the response returned by this function:
response['data']['project']['<one of the below>']
aiAssistance, description, categorySchema, consensusCount, benchmark, deleted, reviewConf, batches, _id, name, user, organization, createdAt, assignedTo, tags, __v, role
Parameters:
project_id: string
ID of the project to download the details of. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
Returns:
output: dict
Example:
Outputs:
See also
get_storages()
Get all storages of the current organization.
Parameters:
None
Returns:
output: dict
Example:
Outputs:
See also
get_task(task_id)
Get information on a task
Parameters:
task_id: string
ID of the task the information of which will be downloaded. Task IDs can be obtained from the UI and from get_tasks.
Example:
'0000000aa0a00a0000aaaa0a'
Returns:
output: dict
Example:
See also
get_tasks(project_id, page, limit, status, stage, batches)
Get tasks of a project.
Tasks in projects are paginated. A maximum of 1000 items per page can be obtained. See the code snippets below for an example of how to download all tasks from a project by flipping through the pages.
Parameters:
project_id: string
ID of the project to download the tasks of. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
page: integer, default 1
Current page.
Example:
1
limit: integer, default 10
Page size. Default 10, maximum 1000.
Example:
100
status: string, default None, {None, "TODO", "Completed", "Reviewed"}
Filter tasks by status.
Example:
'Completed'
stages: string, default None
Pass a stage ID to filter tasks by stage. You can obtain a stage's ID by running
get_export(project_id)on the project where you'd like to get the stage IDs.Example:
'Label'or"1a1a2d88-ddad-457a-aac8-fe50a3a65272"
batches: list[str], default None
Filter tasks by batch (e.g., only get tasks belonging to the batch specified)
Example
['batch_1', 'batch_2']
Returns:
output: dict
Example:
See also
get_task_history(id, task_id)
Get the stage history of a task.
Parameters:
id: string, optional, default None
Optionally, the ID of the stage history item.
For example, if you run this function on a task without passing
id, assuming the task has been through 6 stages, you will receive a list with 6 objects. Each of these objects has its own_idvalue. If you pass this_idvalue as theidparameter, you can filter out all tak stage history items and only return the one with this specific ID.Example:
'0000000aa0a00a0000aaaa0a'
task_id: string
ID of the task to get the history of. Task IDs can be obtained from the UI, and from get_tasks.
Example:
'0000000aa0a00a0000aaaa0a'
Returns:
output: dict
Sample output:
import_labels(project_id, labels)
Import labels to the project. More details on importing existing labels to Hub here.
You can only import annotations for tasks in the Start stage.
Please ensure the assets you are trying to annotate as in the Start stage of your project before continuing.
Parameters:
project_id: string
ID of the project where to import labels. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
labels: List[dict]
List of labels to import. See more on our label format here: Ango Annotation Format and learn more about importing labels into Ango Hub here.
Example:
Returns:
output: dict
Example:
See also
list_projects(page, limit)
Lists projects from the current users' organization.
Projects are paginated. A maximum of 1000 projects can be obtained per page. See the second code example for more on how it works.
Parameters:
page: int, default 1
Current page.
Example:
1
limit: int, default 10, maximum 1000
Number of projects per page.
Example:
100
Returns:
output: dict
Example:
Outputs:
See also
update_workflow_stages(project_id, stages)
Update the workflow of your project.
Parameters:
project_id: string
ID of the project where priority will be set. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
stages: List[dict], default []
The workflow of the project, in JSON format. For example:
To get an idea of what you can pass as input in Stages, you may create a workflow in a project, then run
ango.sdk.SDK.get_project(<YOUR_PROJECT_ID>).get("data").get("project").get("stages")
As the returned JSON, you'll get the JSON representation of the project's workflow, which you can use as skeleton to create your own workflow JSONs.
Returns:
output: dict
upload_files(project_id, file_paths, storage_id, batches)
Upload files to Ango Hub. A list of local file paths should be given as an input parameter.
Optionally, a custom externalID for the files may be given from within the file_paths parameter. (See examples below)
Parameters:
project_id: string
ID of the project where priority will be set. Project IDs can be obtained from the UI and from list_projects.
Example:
'0000000aa0a00a0000aaaa0a'
file_paths: List[string]
List containing absolute paths to files and, optionally, their contextData.
Example:
storage_id: string, Optional
This parameter has no function anymore and will be deprecated in the next version of the SDK.
batches: List[string], Optional
You may assign the files you are uploading to one or more batches that exist in your project by providing their IDs here. You may create new batches with create_batch and you can get a list of batches with get_batches.
Example:
['0000000aa0a00a0000aaaa0a', '0000000aa0a00a0000aaaa0b']
Returns:
output: dict
Example:
Importing two local files:
Importing a file with a custom external ID:
See also
upload_files_cloud(project_id, assets, storage_id, batches)
Import files in cloud storage to Ango Hub. Check Importing Assets for more information.
Parameters:
project_id: string
The ID of the project where you'd like to add files.
Example:
'0000000aa0a00a0000aaaa0a'
assets: List[string]
A list of asset dictionaries in the [{"data": <URL>, "externalId": "<external_id>"}] format.
Assets uploaded with this method can also contain attachments, batches, metadata, and contextData. For example:
For image and video attachments, you may provide links to assets in private buckets, provided that you've connected them to Ango Hub. More information on how to do so can be found in the Attachments page.
For Markdown assets, you may directly include the Markdown file as plain text in the data field, like so:
Batches you specify in the assets dictionary will override the batches you specify in the batches parameter of this function.
storage_id: string, Optional, default None
If importing files from a private bucket previously integrated with Hub, this parameter is necessary. This is the ID of the bucket's integration, obtainable from get_storages().
batches: List[string], Optional
You may add the files being uploaded to one or multiple batches, by passing a list of batch IDs. You may obtain a list of batch IDs available in your project using get_batches(project_id), or create new ones using create_batch(project_id, batch_name).
Returns:
output: dict
Examples:
Importing a file from a public bucket, and assigning it to a batch:
Importing a file from a private bucket, and assigning it to multiple batches:
See also
Organization Level SDK Functions (v1.3.10)
imerit_ango.sdk.SDK.
create_storage(storage_data)
Create storage
Parameters:
storage_data: Storage
Storage
name: string
provider: StorageProvider
public_key: string
private_key: string
credentials: string
StorageProvider
{AWS, GCP, AZURE}
Returns:
output: dict
Example:
See also
delete_organization_invites(organization_id, invite_emails)
Delete organization invites
Parameters:
organization_id: string
invite_emails: List[string]
Returns:
output: dict
Example:
See also
delete_organization_members(organization_id, member_ids)
Delete organization members
Parameters:
organization_id: string
member_ids: List[string]
Returns:
output: dict
Example:
See also
delete_storage(storage_id)
Delete storage
Parameters:
storage_id: string
Returns:
output: dict
Example:
See also
get_organization_invites(organization_id)
Get organization invites
Parameters:
organization_id: string
Returns:
output: dict
Example:
get_organization_members(organization_id)
Get organization members
Parameters:
organization_id: string
Returns:
output: dict
Example:
invite_members_to_org(organization_id, invite_data)
Invite members to organization
Parameters:
organization_id: string
invite_data: Invitation
Invitation
organizationRole: OrganizationRoles
projectId: string
projectRole: ProjectRoles
OrganizationRoles
{Member, Admin}
ProjectRoles
{Manager, Labeler, Reviewer, Lead}
Returns:
output: dict
Example:
update_organization_members_role(organization_id, role_updates))
Update organization members role
Parameters:
organization_id: string
role_updates: List[RoleUpdate]
RoleUpdate
email: string
organizationRole: OrganizationRoles
OrganizationRoles
{Member, Admin}
Returns:
output: dict
Example:
See also
Last updated
