Ango Hub Python SDK

A comprehensive Python SDK to interface programmatically with Ango Hub, iMerit's data annotation and AI training platform.

Overview

The iMerit-Ango SDK provides a powerful Python interface for interacting with Ango Hub, enabling you to:

Manage Projects: Create, configure, and manage annotation projects
Upload Data: Import assets from local storage, cloud storage (AWS S3, GCP, Azure), or URLs
Handle Annotations: Import and export annotations in various formats (COCO, YOLO, KITTI, Ango native format)
Workflow Management: Manage labeling workflows, batches, and task assignments
Team Collaboration: Add team members, manage roles, and track performance
Integration: Connect with your existing ML pipelines and data infrastructure

Installation

Install the latest version from PyPI:

pip install imerit-ango

To upgrade to the latest version:

pip install -U imerit-ango

Quick Start

1. Get Your API Key

First, obtain your API key from your Ango Hub account page:

Navigate to your Account page in Ango Hub
Go to the API tab
Create a new API key or copy your existing key

2. Basic Usage

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

# Load environment variables
load_dotenv()

# Initialize SDK
sdk = SDK(api_key=os.getenv('API_KEY'))

# List your projects
projects = sdk.list_projects()
print(f"Found {len(projects)} projects")

# Get project details
project = sdk.get_project(project_id=os.getenv('PROJECT_ID'))
print(f"Project: {project['name']}")

SDK Functions Overview

Project-Level Functions

Project Management: create_project(), get_project(), list_projects(), clone_project(), delete_project(), purge_project()
Data Upload: upload_files(), upload_files_cloud(), upload_chat_assets()
Batch Management: create_batch(), assign_batches(), get_batches()
Task Management: get_tasks(), assign_task(), requeue_tasks()
Annotations: import_labels(), export(), exportV3()
Team: add_members_to_project()
Performance: get_metrics(), get_project_performance()

Organization-Level Functions

Storage: create_storage(), get_storages(), delete_storage()
LLM: create_llm(), get_llms(), delete_llm()
Members: invite_members_to_org(), get_organization_members()
Permissions: update_organization_members_role()
Notifications: send_notification()

Deleting a project

delete_project(project_id) soft-deletes the project and its assets, tasks, issues, and histories. It does not purge storage.

purge_project(project_id, confirm_name) does that soft delete and also deletes the {project_id}/ prefix in the default bucket. confirm_name must match the project name. Files in customer-connected external storage are not deleted.

Supported Asset Types

The SDK supports a wide variety of data types:

Images: PNG, JPEG, TIFF, BMP, WebP
Videos: MP4, AVI, MOV, WebM
Medical: DICOM, NRRD files
Documents: PDF, Markdown, HTML
Text: Plain text, NER datasets
3D Data: Point clouds, multi-sensor fusion
Audio: WAV, MP3, FLAC
LLM: Chat conversations and responses

Documentation

Comprehensive Documentation

Full SDK documentation is available at: https://docs.imerit.net/sdk/sdk-documentation

Key Resources

Examples

Upload and Create a Labeling Project

# Create a new project
project = sdk.create_project(
    organization_id=org_id,
    name="My Annotation Project",
    description="Object detection for autonomous vehicles"
)

# Upload images from local directory
sdk.upload_files(
    project_id=project['_id'],
    file_paths=['/path/to/images/*.jpg']
)

# Create batches for organized labeling
batch = sdk.create_batch(
    project_id=project['_id'],
    batch_name="Training Set Batch 1"
)

Clone a Project

Clone copies project settings into a new project named {name} copy in the same organization. Assets, tasks, labels, and annotations are not cloned.

# Copy all settings (schema, assignees, batches, workflow, plugin presets, general settings)
cloned = sdk.clone_project(project_id)

# Exclude some sections from the copy
cloned = sdk.clone_project(
    project_id,
    batches=False,
    plugin_presets=False,
)

Send a Notification

Notifications are delivered to members of your organization and appear in their Notifications panel. The API key's user must be an organization admin.

# Plain notification
sdk.send_notification(
    receivers=['labeler@example.com'],
    message='The new task batch is ready for labeling.',
    title='New Batch'
)

# Notification with a link attached
sdk.send_notification(
    receivers=['labeler@example.com'],
    message='The new task batch is ready for labeling.',
    clickable_link=f'https://imerit.ango.ai/projects/{project_id}'
)

Limits enforced by the server:

receivers: 1 to 100 emails. Every receiver must be a member of your organization, otherwise the whole request is rejected.
message: at most 1000 characters.
title: at most 200 characters.
clickable_link: an absolute http/https URL, at most 2048 characters.

Export Annotations

# Export annotations in COCO format
export_result = sdk.export(
    project_id=project_id,
    export_format='COCO'
)

# Download the export
import requests
response = requests.get(export_result['downloadUrl'])
with open('annotations.json', 'wb') as f:
    f.write(response.content)

Release Process

Releases are created from master only and are triggered by pushing a vX.Y.Z tag. Using an annotated tag is the recommended release command.

Update the shared package version in imerit_ango/version.py.
Merge that version change into master.
Create an annotated release tag:

git tag -a v1.4.1 -m "Release v1.4.1"

Push the tag to GitHub:

git push origin v1.4.1

When a vX.Y.Z tag is pushed, GitHub Actions verifies that the tagged commit is in master history and that the tag matches the shared version in imerit_ango/version.py. It then builds both Python packages, publishes them to PyPI, and creates GitHub Release notes.

Versioning

The canonical version lives in imerit_ango/version.py as __version__. Both setup_ango.py and setup_imerit_ango.py read from this file, so updating one place is enough. The tag version (without the leading v) must match __version__ exactly or the workflow will fail.

Deployment and Releasing

One-time setup

Before the first automated release you need to configure PyPI trusted publishing and the GitHub environment:

Create a pypi environment in GitHub. Go to the repository Settings > Environments and create an environment named pypi. This is required by the publish job for OIDC token generation.
Configure PyPI trusted publishing for ango. On pypi.org, go to the ango project settings (or create the project if it does not exist yet) and add a trusted publisher with:
- PyPI project name: ango
- Owner: imerit-io
- Repository name: ango-sdk
- Workflow filename: release.yml
- Environment name: pypi
Configure PyPI trusted publishing for imerit-ango. Repeat the same steps for the imerit-ango project on PyPI:
- PyPI project name: imerit-ango
- Owner: imerit-io
- Repository name: ango-sdk
- Workflow filename: release.yml
- Environment name: pypi

After this setup, pushing a vX.Y.Z tag to master will automatically publish both packages and create a GitHub Release.

Release checklist

Update imerit_ango/version.py with the new version number.
Merge the version change into master.

Create and push an annotated tag:

git tag -a v1.4.1 -m "Release v1.4.1"
git push origin v1.4.1

Monitor the GitHub Actions run. If the workflow fails on version mismatch or master-ancestry checks, delete the tag, fix the issue, and re-tag:

git push origin :refs/tags/v1.4.1   # delete the remote tag
git tag -d v1.4.1                    # delete the local tag

Once the workflow succeeds, both ango and imerit-ango will be live on PyPI and a GitHub Release will appear on the repository.

Geofencing

If an organization has IP or country restrictions enabled, API calls from outside the allowlist fail with HTTP 451. The SDK raises that response body.

Support

Documentation: https://docs.imerit.net
Status Page: Ango Hub Status
Customer Support: Available through your Ango Hub account

License

This SDK is provided by iMerit Technology Services for use with Ango Hub platform.

For the latest updates and detailed API reference, visit our complete documentation.

Metadata

Release files for imerit-ango 1.4.10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for imerit-ango 1.4.10
File	Size	Uploaded
imerit_ango-1.4.10.tar.gz	39.9 kB	Oct 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for imerit-ango 1.4.10
File	Interpreter	ABI	Platform	Reset
imerit_ango-1.4.10-py3-none-any.whl 40.2 kB Oct 14, 2026	Python 3	none	any	Details

Total release size: 80.1 kB

Release files / imerit_ango-1.4.10.tar.gz

Download URL	imerit_ango-1.4.10.tar.gz
Size	39.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`a9503f6c53245eaa671d8e2a2332a94aa041930550ea74346f56a47250780fc4`
BLAKE2b-256 checksum How to use checksums	`2080d9c5019de014973e8dff2146a74d0d47b8feb3ea3eb7fb07552577e4162a`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/imerit-io/ango-sdk
Publishing commit: github.com/imerit-io/ango-sdk/tree/2389b75bed30f5ff71d92c9d5343824fbfe248c6

Workflow

Publishing configuration: github.com/imerit-io/ango-sdk/blob/2389b75bed30f5ff71d92c9d5343824fbfe248c6/.github/workflows/release.yml
Publishing logs: github.com/imerit-io/ango-sdk/actions/runs/38558282413/attempts/1

Artifact

Subject: imerit_ango-1.4.10.tar.gz
SHA-256 checksum: a9503f6c53245eaa671d8e2a2332a94aa041930550ea74346f56a47250780fc4 Verifying attestations

Release files / imerit_ango-1.4.10-py3-none-any.whl

Download URL	imerit_ango-1.4.10-py3-none-any.whl
Size	40.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f48484b71d22ab7d16ad102505374f3cfa2efce88ace50f10be02f54096be559`
BLAKE2b-256 checksum How to use checksums	`3b9b531f094de2961fb322668d32cabb3f85ae084f782c5caf688e3e2be21c0d`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/imerit-io/ango-sdk
Publishing commit: github.com/imerit-io/ango-sdk/tree/2389b75bed30f5ff71d92c9d5343824fbfe248c6

Workflow

Publishing configuration: github.com/imerit-io/ango-sdk/blob/2389b75bed30f5ff71d92c9d5343824fbfe248c6/.github/workflows/release.yml
Publishing logs: github.com/imerit-io/ango-sdk/actions/runs/38558282413/attempts/1

Artifact

Subject: imerit_ango-1.4.10-py3-none-any.whl
SHA-256 checksum: f48484b71d22ab7d16ad102505374f3cfa2efce88ace50f10be02f54096be559 Verifying attestations