Project Level SDK Functions

v 1.3.20

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.
- ProjectRoles
  - {Manager, Labeler, Reviewer, Lead}
- Example: ProjectRoles.Labeler
- (Note: you must import the enum containing the roles using from imerit_ango.models.enums import ProjectRoles)

Returns:

output: dict

Example:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.models.enums import ProjectRoles

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

ango_sdk.add_members_to_project(project_id=project_id,
                                members=["user1@example.com", "user2@example.com"],
                                role=ProjectRoles.Labeler)

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:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

asset_ids = ['<YOUR ASSET ID 1>', '<YOUR ASSET ID 2>']
batch_ids = ['<YOUR BATCH ID 1>', '<YOUR BATCH ID 2>']

ango_sdk.assign_batches(project_id, asset_ids, batch_ids)

Outputs:

{
  "status": "success",
  "data": {
    "assets": 2
  }
}

Where "assets" is the number of assets successfully assigned to the batch(es).

See also

create_batch, get_batches

assign_task(project_id, task_ids, stage_filter, email)

Assign a task to a specific user with email.

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'
task_ids: 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:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

task_id = '<YOUR TASK ID>'
email = '<example@example.com>'
ango_sdk.assign_task(project_id=project_id, task_ids=[task_id], stage_filter='Label', email=email)

See also

get_tasks

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 = [
    {"externalId": "sample_image_1.png",
     "attachments": [
         {"type": "IMAGE", "value": "https://sample-attachment-image.jpg"},
         {"type": "TEXT", "value": "Some sample text."}
     ]
     },
    {"externalId": "sample_image_2.png",
     "attachments": [
         {"type": "VIDEO", "value": "https://sample-attachment-video.jpg"}
     ]
     }
]

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:

https://bucket-name.s3.eu-central-1.amazonaws.com/filename.JPG?storageId=111bb111389ff80015f2b914

Returns:

output: dict

Example:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

attachments = [{"externalId": "sample_image_1.png",
                "attachments": [{"type": "IMAGE",
                                 "value": "https://sample-attachment-image.jpg"},
                                {"type": "TEXT",
                                 "value": "Some sample text."}]
               },
               {"externalId": "sample_image_2.png",
                "attachments": [{"type": "VIDEO",
                                 "value": "https://sample-attachment-video.jpg"}]
               }]

ango_sdk.create_attachment(project_id, attachments)

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:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

ango_sdk.create_batch(project_id, "My Batch Name")

Prevent creating duplicate batches:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

batch_name = "My Batch"

# Get available batch names from project
batch_response = ango_sdk.get_batches(project_id)

project_batch_name_list = []
for index in range(len(batch_response)):
    project_batch_name = batch_response[index]['name']
    project_batch_name_list.append(project_batch_name)

# Create batch if it is not available on the project
if batch_name not in project_batch_name_list:
    ango_sdk.create_batch(project_id=project_id, batch_name=batch_name)

See also

assign_batches, get_batches

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:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

task_id = '<YOUR TASK ID>'
content = 'Hey! Check this annotation.'
position = [25, 15]

ango_sdk.create_issue(task_id, content, position)

See also

get_tasks

create_label_set(project_id, tools, classifications, relations, raw_category_schema)

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 the 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:

# Get existing project information
existing_project = sdk.get_project(project_id="<EXISTING_PROJECT_ID>")

# Extract category schema info from the existing project
cat_schema = existing_project.get("data").get("project").get("categorySchema")

# Create a new project
new_project = sdk.create_project("New Project Title", "New Project Description") 

# Retrieve id of the newly created project
new_project_id = new_project.get("data").get("project").get("_id")

# Add new category schema to newly created project
sdk.create_label_set(project_id=new_project_id, raw_category_schema=cat_schema)

As an example, a raw_category_schema obtained from a project could be this:

{
  "tools": [
    {
      "title": "Vehicle",
      "tool": "bounding-box",
      "required": false,
      "schemaId": "c053da596995f93c2c71520",
      "ocrEnabled": false,
      "classifications": [],
      "multiple": false,
      "color": "#f44336",
      "shortcutKey": "1"
    }
  ],
  "classifications": [
    {
      "title": "Color",
      "tool": "radio",
      "required": false,
      "schemaId": "75c02176796c17e7c657955",
      "frameSpecific": false,
      "classifications": [],
      "multiple": false,
      "options": [
        {
          "value": "Red",
          "schemaId": "95df97dc43d2e1dcc77d536"
        },
        {
          "value": "Yellow",
          "schemaId": "f477d05947e30259cc53538"
        },
        {
          "value": "Blue",
          "schemaId": "18a8212c7c48c2ee3464602"
        }
      ],
      "shortcutKey": "2"
    }
  ],
  "relations": []
}

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":

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.models.label_category import LabelOption, ClassificationCategory, Classification

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

category = ClassificationCategory(Classification.Single_dropdown,
                                  title = "Choice",
                                  options = [LabelOption("First"),
                                             LabelOption("Second")])

label_set = [category]

response = ango_sdk.create_label_set(project_id=project_id,
                                     classifications=label_set)

Creating an ontology with:

A Single Dropdown classification with the classifications "First" and "Second"
A Segmentation tool called "SegmentationTool"
A Single Relation called "SingleRelationTool"

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.models.label_category import ClassificationCategory, Classification, LabelOption, Tool, ToolCategory, RelationCategory, Relation

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

dropdown = ClassificationCategory(Classification.Single_dropdown,
                                  title = "SingleDropdown",
                                  options = [LabelOption('First'), 
                                             LabelOption('Second')])
classifications = [dropdown]

segmentation = ToolCategory(Tool.Segmentation, title="SegmentationTool")
tools = [segmentation]

relation = RelationCategory(Relation.Single, title="SingleRelationTool")
relations = [relation]

ango_sdk.create_label_set(project_id=project_id,
                          tools=tools,
                          classifications=classifications,
                          relations=relations)

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".

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.models.label_category import ClassificationCategory, LabelOption, Classification

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

nested_class_in_dropdown = ClassificationCategory(Classification.Single_dropdown,
                                                  title="Position",
                                                  options=[LabelOption('On Road'),
                                                           LabelOption('Off Road')])

dropdown = ClassificationCategory(Classification.Single_dropdown,
                                  title="Entity Type",
                                  options=[LabelOption('Vehicle'),
                                           LabelOption('Person')],
                                  classifications=[nested_class_in_dropdown],
                                  required=True)

classifications = [dropdown]

ango_sdk.create_label_set(project_id=project_id, classifications=classifications)

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

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.models.label_category import ClassificationCategory, Classification, TreeOption

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

subtree0 = TreeOption(title="subtree0")
subtree1 = TreeOption(title="subtree1")
tree0 = TreeOption(title="tree0", children=[subtree0, subtree1])
tree1 = TreeOption(title="tree1")

tree_tool = ClassificationCategory(classification=Classification.Tree_dropdown,
                                  title="Tree One",
                                  treeOptions=[tree0, tree1])

ango_sdk.create_label_set(project_id=project_id, classifications=[tree_tool])

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, parentOptionId links the text tool to the option which reveals it)

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.models.label_category import ClassificationCategory, LabelOption, Classification

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

radio1 = LabelOption(value="Radio Option 1", schemaId="radioOption1SchemaId")
radio2 = LabelOption(value="Radio Option 2")

conditional_text = ClassificationCategory(classification=Classification.Text,
                                          title="Text Tool",
                                          parentOptionId="radioOption1SchemaId",
                                          color="#333333",
                                          richText=True)

radio = ClassificationCategory(classification=Classification.Radio,
                               title="Radio Classification",
                               options=[radio1, radio2],
                               classifications=[conditional_text])

ango_sdk.create_label_set(project_id=project_id, classifications=[radio])

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"

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.models.label_category import ClassificationCategory, LabelOption, Classification

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

leaf1 = TreeOption(title="Leaf 1")
leaf2 = TreeOption(title="Leaf 2")
leaf3 = TreeOption(title="Leaf 3")

branch1 = TreeOption(title="Branch 1",
                     children=[leaf1, leaf2])

tree_tool = ClassificationCategory(classification=Classification.Tree_dropdown,
                                  title='tree',
                                  treeOptions=[branch1, leaf3],
                                  parentOptionId="radioOptionSchemaId")

radio1 = LabelOption(value="Radio Answer 1")
radio2 = LabelOption(value="Radio Answer 2")

radio = ClassificationCategory(classification=Classification.Radio,
                               title='radio',
                               classifications=[tree_tool],
                               options=[radio1, radio2])

ango_sdk.create_label_set(project_id=project_id, classifications=[radio])

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:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

response = ango_sdk.create_project(name="Created from SDK",
                                   description="I created this from the SDK.")

Returns:

{
  "status": "success",
  "data": {
    "project": {
      "aiAssistance": {
        "cocoRelations": []
      },
      "description": "I created this from the SDK.",
      "categorySchema": {
        "tools": [],
        "classifications": [],
        "relations": []
      },
      "consensusCount": 1,
      "benchmark": false,
      "deleted": false,
      "reviewConf": {
        "filters": []
      },
      "batches": [],
      "_id": "PROJECT ID",
      "name": "Created from SDK",
      "user": "USER ID OF PROJECT CREATOR",
      "organization": "ORGANIZATION ID",
      "createdAt": "2022-12-13T13:28:34.479Z",
      "assignedTo": [],
      "tags": [],
      "__v": 0
    }
  }
}

See also

list_projects, get_project

delete_issue(project_id, issue_id)

Delete the issue specified with issue_id

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'
issue_id: string
- ID of the issue to be deleted

Returns:

output: dict

Example

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

issue_id = "<YOUR ISSUE ID>"
sdk_response = ango_sdk.delete_issue(project_id=project_id, issue_id=issue_id)

export(project_id, batches, stage, export_format, export_type, include_key_frames_only, zip_file_path, filters)

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'
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']
export_format: string, default "json", {"json", "ndjson"}
- Select the format of the export output
- Example: "ndjson"
export_type: string, optional, default None, {"issue"}
- You may choose to only export issues by passing export_type="issue".
include_key_frames_only: bool, default False
- You may choose to only export key frames for video assets.
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):

filters = {
    'sendEmail': 'false',
    'includeMetadata': 'false',
    'includeHistory': 'false',
    'includeSegmentationPoints': 'true',
}

Returns:

output: dict

Example:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

ango_sdk.export(project_id)

See also

import_labels, exportV3

exportV3(project_id, batches, stage, export_format, export_type, include_key_frames_only, 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']
export_format: string, default "json", {"json", "ndjson"}
- Select the format of the export output
- Example: "ndjson"
export_type: string, optional, default None, {"issue"}
- You may choose to only export issues by passing export_type="issue".
include_key_frames_only: bool, default False
- You may choose to only export key frames for video assets.
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):

filters = {
    'sendEmail': 'false',
    'includeMetadata': 'false',
    'includeHistory': 'false',
    'includeSegmentationPoints': 'true',
}

Returns:

output: dict

get_assets(project_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'
page: integer, default 1
limit: integer, default 10
filters: dict, default {}
- 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:

{
    _id : str, # A specific Asset ID to get.
    externalId: str, # A specific externalId to get.
    isPreLabeled: bool,
    batches: ["<batch_id_1>", "<batch_id_2>"] # When including multiple batches, only the assets belonging to BOTH (all) batches will be returned. This is an "AND" operation.
    createdAt: {"gt": "<ISO_TIME_STR>"}, # gt: Greater Than (after), lt: Less Than (before), ISO_TIME_STR example: 2002-12-09T00:00:00.000Z
    createdAt: {"lt": "<ISO_TIME_STR>"}
}

Returns:

output: dict

Example:

Retrieve the first ten assets from the project:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

sdk_response = ango_sdk.get_assets(project_id)

data_url = sdk_response['data']['assets'][0]['data']
external_id = sdk_response['data']['assets'][0]['externalId']

Retrieve all assets from the project:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

items_per_page = 100
max_limit = None

assets = []
page = 1
remaining_tasks = 1
while remaining_tasks > 0:
    response =  ango_sdk.get_assets(project_id, page=page, limit=items_per_page)
    assets.extend(response['data']['assets'])
    remaining_tasks = response["data"]["total"] - len(assets)
    page += 1
    if max_limit:
        if len(assets) >= max_limit:
            assets = assets[:max_limit]
            break

print(len(assets))

Retrieve a single asset via asset ID:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

asset_id = 'YOUR_ASSET_ID'

ango_sdk = SDK(api_key)

sdk_response = ango_sdk.get_assets(project_id, filters={"_id": asset_id})

data_url = sdk_response['data']['assets'][0]['data']
external_id = sdk_response['data']['assets'][0]['externalId']

See also

get_task, get_tasks

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:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

output = ango_sdk.get_batches(project_id=project_id)

Outputs:

[
  {
    "_id": "<BATCH_ID_1>",
    "name": "Batch Name 1"
  },
  {
    "_id": "<BATCH_ID_2>",
    "name": "Batch Name 2"
  }
]

See also

assign_batches, create_batch

get_issues(project_id, asset_id, task_id, stage_id, created_by)

Retrieve issues of a project

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'
asset_id: string, default None
task_id: string, default None
stage_id: string, default None
created_by: string, default None

Returns:

output: dict

Example:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

# Get all issues of the project
sdk_response = ango_sdk.get_issues(project_id=project_id)

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.Metrics
    LabelStageGroups
    TimePerTask
    AnnotationStatus
    AnswerDistribution
    ConsensusRanges
    AssetSize

Returns:

output: dict

Example:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK
from imerit_ango.sdk import Metrics

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

output = ango_sdk.get_metrics(project_id=project_id, metric=Metrics.TimePerTask)

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:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')
project_id = os.getenv('PROJECT_ID')

ango_sdk = SDK(api_key)

sdk_response = ango_sdk.get_project(project_id)

project_name = sdk_response['data']['project']['name']
project_description = sdk_response['data']['project']['description']
project_creation_time = sdk_response['data']['project']['createdAt']
project_ontology = sdk_response['data']['project']['categorySchema']

print(project_name)
print(project_description)
print(project_creation_time)
print(project_ontology)

Outputs:

<Project Name>
<Project Description>
2000-01-01T00:00:00.000Z
{'tools': [...], 'classifications': [...], 'relations': [...]}

See also

create_project, list_projects

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:

import os
from dotenv import load_dotenv
from imerit_ango.sdk import SDK

load_dotenv('variables.env')
api_key = os.getenv('API_KEY')

ango_sdk = SDK(api_key)

sdk_response = ango_sdk.get_task('<YOUR TASK ID>')

data_url = sdk_response['data']['task']['asset']['data']
external_id = sdk_response['data']['task']['asset']['externalId']

See also

get_assets, get_tasks

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: