Metadata-Version: 2.4
Name: datamint
Version: 2.17.2
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: dev
Provides-Extra: docs
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: 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: 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-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)
Description-Content-Type: text/markdown

# 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/)

A comprehensive Python SDK for interacting with the Datamint platform, providing seamless integration for medical imaging workflows, dataset management, and machine learning experiments.

## 📋 Table of Contents

- [Features](#-features)
- [Installation](#-installation)
- [Quick Setup](#-setup-api-key)
- [Documentation](#-documentation)
- [Command Line Tools](#️-command-line-tools)
- [Support](#-support)

## 🚀 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
- **PyTorch Lightning Integration**: Streamlined machine learning workflows featuring specialized `LightningDataModules`, built-in trainers (`SegmentationTrainer`), and automated MLflow checkpoint logging
- **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

See the full documentation at https://sonanceai.github.io/datamint-python-api/

## 📦 Installation

> [!NOTE]
> We recommend using a virtual environment to avoid package conflicts.

### From PyPI

`pip install -U datamint`

### Virtual Environment Setup

<details>
<summary>Click to expand virtual environment setup instructions</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>

## ⚙ Setup API key

To use the Datamint API, you need to setup your API key (ask your administrator if you don't have one). Use one of the following methods to setup your API key:

### Method 1: Command-line tool (recommended)

Run ``datamint-config`` (or ``python -m datamint config`` if that doesn't work) in the terminal and follow the instructions. See [command_line_tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html#configuring-the-datamint-settings) for more details.

### Method 2: Environment variable

Specify the API key as an environment variable.

**Bash:**
```bash
export DATAMINT_API_KEY="my_api_key"
# run your commands (e.g., `datamint-upload`, `python script.py`)
```

**Python:**
```python
import os
os.environ["DATAMINT_API_KEY"] = "my_api_key"
```

## 📚 Documentation

| Resource | Description |
|----------|-------------|
| [🚀 Getting Started](https://sonanceai.github.io/datamint-python-api/getting_started.html) | Step-by-step setup and basic usage |
| [📖 API Reference](https://sonanceai.github.io/datamint-python-api/client_api.html) | Complete API documentation |
| [🔥 PyTorch Integration](https://sonanceai.github.io/datamint-python-api/pytorch_integration.html) | ML workflow integration |
| [🧠 Trainer Guide](https://sonanceai.github.io/datamint-python-api/trainer_api.html) | Built-in trainers, trainer lifecycle, and custom model integration |
| [💡 Examples](examples/) | Practical usage examples |

## 🛠️ Command Line Tools

Full documentation at [command_line_tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html).

### Upload Resources

**Upload DICOM files with anonymization:**
```bash
datamint-upload /path/to/dicoms --recursive --channel "training-data" --publish --tag "my_data_tag"
```
It anonymizes by default.

**Upload resources with segmentations and associate them with a deployed model:**
```bash
datamint-upload /path/to/dicoms \
   --recursive \
   --segmentation_path /path/to/segmentations \
   --segmentation_names /path/to/segmentation_names.yaml \
   --ai-model "knee-segmentation-v2" \
   --publish
```
Use `--ai-model` when uploaded segmentation files should be linked to an existing deployed model by name. `--segmentation_names` accepts YAML mappings and ITK-SNAP label export CSV/TXT files.

### Configuration Management

```bash
# Interactive setup
datamint-config

# Set API key
datamint-config --api-key "your-key"
```

## 🔒 SSL Certificate Troubleshooting

If you encounter SSL certificate verification errors like:
```
SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
```

### Quick Fix

**1. Upgrade certifi:**
```bash
pip install --upgrade certifi
```

**2. Set environment variables:**
```bash
export SSL_CERT_FILE=$(python -m certifi)
export REQUESTS_CA_BUNDLE=$(python -m certifi)
```

**3. Run your script:**
```bash
python your_script.py
```

### Alternative Solutions

**Option 1: Use Custom CA Bundle**
```python
from datamint import Api

api = Api(verify_ssl="/path/to/your/ca-bundle.crt")
```

**Option 2: Disable SSL Verification (Development Only)**
```python
from datamint import Api

# ⚠️ WARNING: Only use in development with self-signed certificates
api = Api(verify_ssl=False)
```

## 🆘 Support

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


