Metadata-Version: 2.4
Name: ango
Version: 1.4.0
Summary: Ango-Hub SDK
Author: Faruk Karakaya
Author-email: <faruk@imerit.net>
Keywords: imerit_ango,angohub,Ango,Ango Hub,iMerit
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
Requires-Dist: python-socketio~=5.14.3
Requires-Dist: APScheduler~=3.9.1
Requires-Dist: websocket-client
Requires-Dist: flask-socketio~=5.3.4
Requires-Dist: requests~=2.32.4
Requires-Dist: tqdm
Requires-Dist: validators~=0.20.0
Requires-Dist: boto3==1.*
Requires-Dist: fastapi~=0.120.2
Requires-Dist: uvicorn~=0.24.0
Requires-Dist: python-dotenv~=1.0.1
Requires-Dist: mangum~=0.17.0
Requires-Dist: lxml~=6.1.1
Requires-Dist: requests-toolbelt~=1.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: requires-dist
Dynamic: summary

# Ango Hub Python SDK

<img src="https://imerit.net/wp-content/themes/imerit/images/imerit-logo.svg" alt="iMerit" height="60">

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:

```bash
pip install imerit-ango
```

To upgrade to the latest version:

```bash
pip install -U imerit-ango
```

## Quick Start

### 1. Get Your API Key

First, obtain your API key from your [Ango Hub account page](https://docs.imerit.net/sdk/sdk-documentation#obtaining-your-api-key):

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


### 2. Basic Usage

```python
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()`
- **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()`
- **Members**: `invite_members_to_org()`, `get_organization_members()`
- **Permissions**: `update_organization_members_role()`

## 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
- [Installation Guide](https://docs.imerit.net/sdk/sdk-documentation#sdk-installation)
- [API Reference](https://docs.imerit.net/sdk/sdk-documentation#project-level-sdk-functions)
- [Usage Examples](https://docs.imerit.net/sdk/sdk-useful-snippets)
- [Troubleshooting](https://docs.imerit.net/troubleshooting)

## Examples

### Upload and Create a Labeling Project

```python
# 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"
)
```

### Export Annotations

```python
# 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.

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

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

4. Push the tag to GitHub:

```bash
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`](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:

1. **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.

2. **Configure PyPI trusted publishing for `ango`.** On [pypi.org](https://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`

3. **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

1. Update `imerit_ango/version.py` with the new version number.
2. Merge the version change into `master`.
3. Create and push an annotated tag:
   ```bash
   git tag -a v1.4.1 -m "Release v1.4.1"
   git push origin v1.4.1
   ```
4. 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:
   ```bash
   git push origin :refs/tags/v1.4.1   # delete the remote tag
   git tag -d v1.4.1                    # delete the local tag
   ```
5. Once the workflow succeeds, both `ango` and `imerit-ango` will be live on PyPI and a GitHub Release will appear on the repository.

## Support

- **Documentation**: [https://docs.imerit.net](https://docs.imerit.net)
- **Status Page**: [Ango Hub Status](https://docs.imerit.net/other/ango-hub-status-page)
- **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](https://docs.imerit.net/sdk/sdk-documentation).
