Metadata-Version: 2.4
Name: datamint
Version: 2.18.1
Summary: A library for interacting with the Datamint API, designed for efficient data management, processing and Deep Learning workflows.
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: detection
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: examples
Provides-Extra: nnunet
Requires-Dist: Deprecated (>=1.2.0)
Requires-Dist: Flask (<4)
Requires-Dist: Flask-Cors (<7)
Requires-Dist: aiohttp (>=3.0.0,<4.0.0)
Requires-Dist: aioresponses (>=0.7.8,<0.8.0) ; extra == "dev"
Requires-Dist: albumentations (>=2.0.0)
Requires-Dist: backports-strenum ; python_version < "3.11"
Requires-Dist: cachetools (>=6.0.0)
Requires-Dist: certifi (>=2025.0.0)
Requires-Dist: filelock (>=3.0) ; extra == "nnunet"
Requires-Dist: h5py (>=3.0) ; extra == "examples"
Requires-Dist: httpx
Requires-Dist: humanize (>=4.0.0,<5.0.0)
Requires-Dist: lazy-loader (>=0.3.0)
Requires-Dist: lightning[extra] (>=2.5.6)
Requires-Dist: matplotlib
Requires-Dist: medimgkit (>=0.17.0)
Requires-Dist: mlflow-skinny (==3.8.1)
Requires-Dist: nest-asyncio (>=1.0.0,<2.0.0)
Requires-Dist: nibabel (>=4.0.0)
Requires-Dist: nnunetv2 (>=2.4,<3.0) ; extra == "nnunet"
Requires-Dist: numpy
Requires-Dist: opencv-python (>=4.0.0)
Requires-Dist: pandas (>=2.0.0)
Requires-Dist: platformdirs (>=4.0.0,<5.0.0)
Requires-Dist: pydantic (>=2.6.4)
Requires-Dist: pydicom (>=3.0.0,<4.0.0)
Requires-Dist: pylibjpeg (>=2.0.0,<3.0.0)
Requires-Dist: pylibjpeg-libjpeg (>=2.0.0,<3.0.0)
Requires-Dist: pytest (>=9.0.3,<10.0.0) ; extra == "dev"
Requires-Dist: pytest-cov (>=7.1.0,<8.0.0) ; extra == "dev"
Requires-Dist: pyyaml (>=5.0.0)
Requires-Dist: requests (>=2.0.0,<3.0.0)
Requires-Dist: responses (>=0.20.0,<0.21.0) ; extra == "dev"
Requires-Dist: respx (>=0.22.0) ; extra == "dev"
Requires-Dist: rich (>=10.0.0)
Requires-Dist: segmentation-models-pytorch (>=0.5.0)
Requires-Dist: setuptools (>=57.0) ; extra == "docs"
Requires-Dist: sphinx (>=5.0) ; extra == "docs"
Requires-Dist: sphinx-rtd-dark-mode (>=1.3.0) ; extra == "docs"
Requires-Dist: sphinx-tabs (>=3.0.0) ; extra == "docs"
Requires-Dist: sphinx_rtd_theme (>=2.0.0) ; extra == "docs"
Requires-Dist: torch (>=1.2.0,!=2.3.0)
Requires-Dist: torchvision (>=0.18.0)
Requires-Dist: tqdm (>=4.0.0,<5.0.0)
Requires-Dist: typing_extensions (>=4.0.0)
Requires-Dist: yolox-datamint (>=0.3.1) ; extra == "detection"
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/logo.png" alt="Datamint logo" width="120">
</p>

# Datamint Python API

![Build Status](https://github.com/SonanceAI/datamint-python-api/actions/workflows/run_test.yaml/badge.svg)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

Datamint turns medical imaging ML work. Dataset management, annotation, training, and deployment into a few lines of Python, with built-in support for DICOM/NIfTI/PNG, PyTorch Lightning trainers, and MLflow tracking.

**Common use cases:** 🩻 Segmentation · 🏷️ Classification · 📦 Detection

Datamint handles the full journey from **raw files** to a **deployed model**:

```mermaid
flowchart LR
    Files(["📁 Your Files"])

    subgraph s1 [1 · Ingest]
        Resource(["📦 Resource"])
    end

    subgraph s2 [2 · Organize & Annotate]
        direction TB
        Project(["🗂️ Project"])
        Annotations(["🏷️ Annotations"])
        Project -.->|annotate| Annotations
    end

    subgraph s3 [3 · Train]
        direction LR
        Dataset(["🧮 Dataset"])
        Trainer(["🧠 Trainer"])
        Model(["📈 Model"])
        Dataset -->|train| Trainer -->|register| Model
    end

    subgraph s4 [4 · Deploy & Predict]
        direction LR
        DeployJob(["🚀 Deploy Job"])
        Inference(["🔮 Inference"])
        DeployJob -->|predict| Inference
    end

    Files -->|upload| Resource
    Resource -->|organize| Project
    Project -->|load| Dataset
    Model -->|deploy| DeployJob

    classDef ingestNode fill:#ffffff,stroke:#1f6feb,stroke-width:2px,color:#0b2b4c
    classDef organizeNode fill:#ffffff,stroke:#1a7f37,stroke-width:2px,color:#0b3a1c
    classDef mlNode fill:#ffffff,stroke:#8250df,stroke-width:2px,color:#2c1a4d
    classDef deployNode fill:#ffffff,stroke:#d1720f,stroke-width:2px,color:#4d2b00
    classDef fileNode fill:#f6f8fa,stroke:#57606a,stroke-width:2px,color:#24292f

    class Files fileNode
    class Resource ingestNode
    class Project,Annotations organizeNode
    class Dataset,Trainer,Model mlNode
    class DeployJob,Inference deployNode

    style s1 fill:#dceeff,stroke:#1f6feb,stroke-width:2px,color:#0b2b4c
    style s2 fill:#dbf5df,stroke:#1a7f37,stroke-width:2px,color:#0b3a1c
    style s3 fill:#ecdcff,stroke:#8250df,stroke-width:2px,color:#2c1a4d
    style s4 fill:#ffe8c7,stroke:#d1720f,stroke-width:2px,color:#4d2b00
```

## 📋 Table of Contents

- [See it in action](#-see-it-in-action)
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Documentation](#-documentation)
- [Support](#-support)

## 🎬 See it in action

**Create** a project, **split** the data, **train**, and **deploy**, all through the API:

![Datamint pipeline demo](assets/pipeline-demo.gif)

## 🚀 Features

- **Dataset Management**: Download, upload, and manage medical imaging datasets using intuitive object-based APIs or CLI tools
- **Annotation Tools**: Create, upload, and manage annotations (segmentations, labels, measurements) with ease
- **Experiment Tracking**: Seamless support for experiment management via MLflow integration
- **One-line Trainers**: Train segmentation, classification, and detection models with built-in PyTorch Lightning trainers, skipping the dataset class, training loop, and logging setup
- **DICOM Support**: Native handling of DICOM files, including powerful anonymization capabilities during upload to protect patient privacy
- **Multi-format Support**: Robust support for a wide range of medical imaging formats: PNG, JPEG, NIfTI (NIfTI/NRRD), DICOMs and more

## ⚡ Quick Start

**1. Install**

`pip install -U datamint`

<details>
<summary>Using a virtual environment (recommended)</summary>

We recommend that you install Datamint in a dedicated virtual environment, to avoid conflicting with your system packages.
For instance, create the enviroment once with `python3 -m venv datamint-env` and then activate it whenever you need it with:

1. **Create the environment** (one-time setup):
   ```bash
   python3 -m venv datamint-env
   ```

2. **Activate the environment** (run whenever you need it):

   | Platform | Command |
   |----------|---------|
   | Linux/macOS | `source datamint-env/bin/activate` |
   | Windows CMD | `datamint-env\Scripts\activate.bat` |
   | Windows PowerShell | `datamint-env\Scripts\Activate.ps1` |

3. **Install the package**:
   ```bash
   pip install datamint
   ```

</details>

**2. Configure your API key**

```bash
datamint config
```

Follow the prompts (ask your administrator if you don't have a key yet). Environment variable and programmatic options are in the [Setup API Key guide](https://sonanceai.github.io/datamint-python-api/getting_started.html#setup-api-key).

**3. Scaffold a project — the fastest way to start**

```bash
datamint init
```

This is the recommended on-ramp: it asks for a project name and task type (**segmentation**, **classification**, or **detection**), then generates a ready-to-run, numbered set of scripts (`01_upload_data.py` → `06_deploy.py`) — upload data, train, and deploy by running them in order.

**4. ...or write it yourself**

```python
from datamint import Api
from datamint.lightning import UNetPPTrainer

api = Api()
api.projects.create(name="my-project", exists_ok=True)

trainer = UNetPPTrainer(project="my-project")
results = trainer.fit()
```

## 📚 Documentation

**Difficulty levels:**

- ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) no ML knowledge needed 
- ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow)assumes SDK familiarity, introduces ML/dataset concepts
- ![Advanced](https://img.shields.io/badge/level-advanced-red) full training pipelines, custom models, 3D data, multi-step workflows.

| Resource | Level | Description |
|----------|-------|-------------|
| [🚀 Getting Started](https://sonanceai.github.io/datamint-python-api/getting_started.html) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Step-by-step setup and basic usage |
| [📖 API Reference](https://sonanceai.github.io/datamint-python-api/client_api.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Complete API documentation |
| [🔥 PyTorch Integration](https://sonanceai.github.io/datamint-python-api/pytorch_integration.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | ML workflow integration |
| [🧠 Trainer Guide](https://sonanceai.github.io/datamint-python-api/trainer_api.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Built-in trainers, trainer lifecycle, and custom model integration |
| [🛠️ Command Line Tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Full reference for `datamint upload`, `datamint init`, and `datamint config` |
| [🔒 SSL Troubleshooting](https://sonanceai.github.io/datamint-python-api/ssl_troubleshooting.html) | — | Fixing `SSLCertVerificationError` |
| [📓 Notebooks](notebooks/) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) ![Advanced](https://img.shields.io/badge/level-advanced-red) | Numbered, runnable tutorials. Start at `01_getting_started` and work through annotations, datasets, experiment tracking, deployment, and a full end-to-end example |

## 🆘 Support

[Full Documentation](https://sonanceai.github.io/datamint-python-api)  
[GitHub Issues](https://github.com/SonanceAI/datamint-python-api/issues)

