Metadata-Version: 2.4
Name: miracle-sdk
Version: 0.1.1
Summary: The Official Python SDK for the MIRACLE API - Cardiovascular MRI Reference Values
Project-URL: Homepage, https://github.com/drankush/MIRACLE-sdk
Project-URL: Bug Tracker, https://github.com/drankush/MIRACLE-sdk/issues
Project-URL: Documentation, https://miracleapi.readme.io
Author-email: Ankush <miracle-support@drankush.com>
License: MIT License
        
        Copyright (c) 2025 Ankush
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cardiovascular,medical-imaging,mri,pediatrics,reference-values,scmr,sdk,z-score
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.8
Requires-Dist: pandas>=1.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Description-Content-Type: text/markdown

# MIRACLE SDK 🫀

**The Official Python SDK for the MIRACLE API**

[![PyPI version](https://badge.fury.io/py/miracle-sdk.svg)](https://pypi.org/project/miracle-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

📦 **PyPI**: [pypi.org/project/miracle-sdk](https://pypi.org/project/miracle-sdk/)

---

> **MIRACLE**: **M**R **I**maging **R**eference **A**PI for **C**ardiovascular **L**imits from **E**vidence

The MIRACLE SDK provides a simple, typed, and high-performance Python interface to access standardized cardiovascular MRI reference values. Built for data scientists and medical researchers who need to process cardiac imaging data at scale.

## ✨ Features

- **34 Endpoints**: Access all MIRACLE API domains with auto-generated, typed methods.
- **Batch Processing**: Process hundreds of patients in parallel with `MiracleBatch`.
- **IDE Support**: Full autocomplete and type hints for VS Code, PyCharm, and more.
- **Battle-Tested**: Verified with stress tests (16+ concurrent requests, 100% success rate).

---

## 🚀 Installation

```bash
pip install miracle-sdk
```

---

## 📖 Quick Start

### Single Request

```python
from miracle import Miracle

# Initialize the client
client = Miracle()

# Get reference values for a pediatric left ventricle
result = client.pediatric_ventricle_reference_values(
    parameter="LVEDV",
    gender="Male",
    measured=62.5,
    ht_cm=110,
    wt_kg=22
)

print(result)
# {'inputs': {...}, 'results': {'calc_z': 0.5, 'calc_percentile': 69.1, ...}}
```

### Batch Processing

Process an entire CSV of patients with multi-threaded parallelism.

**Input CSV (`patients.csv`):**
```csv
patient_id,gender,height_cm,weight_kg,lv_volume,param_type
001,Male,120,30,75,LVEDV
002,Female,110,25,60,LVEDV
```

**Code:**
```python
from miracle import MiracleBatch

# Initialize the batch processor
processor = MiracleBatch(max_workers=10)

# Define how your CSV columns map to API parameters
mapping = {
    "gender": "gender",
    "ht_cm": "height_cm",
    "wt_kg": "weight_kg",
    "measured": "lv_volume",
    "parameter": "param_type"
}

# Process the CSV
df_results = processor.process_csv(
    file_path="patients.csv",
    domain="Pediatric_Ventricle",
    mapping=mapping
)

# Save the enriched data
df_results.to_csv("patients_with_zscores.csv", index=False)
```

> [!TIP]
> **Performance**: In stress tests, the SDK processed **16 concurrent requests in ~7.5 seconds** with a 100% success rate.

---

## 🗺️ Parameter Mapping Guide

The `mapping` dictionary connects your **CSV column names** to the **API parameter names**.

```python
mapping = {
    "API_PARAMETER": "YOUR_CSV_COLUMN",
    "ht_cm": "Patient_Height",  # Example
}
```

### How to Find API Parameters

1.  **Online Docs**: Visit [miracleapi.readme.io](https://miracleapi.readme.io/) and check the "Query Parameters" for your endpoint.
2.  **Python Help**: Use the built-in docstrings:
    ```python
    help(client.lv_reference_values)
    ```

### Common Parameters

| Parameter   | Type   | Description                                      |
|-------------|--------|--------------------------------------------------|
| `gender`    | `str`  | `"Male"` or `"Female"`                           |
| `age`       | `float`| Patient age in years                             |
| `ht_cm`     | `float`| Height in centimeters                            |
| `wt_kg`     | `float`| Weight in kilograms                              |
| `measured`  | `float`| The measured value (e.g., volume, diameter)      |
| `parameter` | `str`  | The measurement type (e.g., `"LVEDV"`, `"LVEF"`) |

> [!IMPORTANT]
> The `parameter` field is **required** for most domains.

---

## 🏗️ Architecture

This SDK is **auto-generated** from the official [OpenAPI specifications](https://miracleapi.readme.io/). This guarantees:

- **Consistency**: Python methods always match the live API.
- **Type Safety**: Full autocomplete and type hints.
- **Reliability**: API changes are automatically reflected in the SDK.

---

## 🤝 Contributing

Contributions are welcome! Please see the [main MIRACLE-API repository](https://github.com/drankush/MIRACLE-API) for the source of truth.

**Development Setup:**
```bash
git clone https://github.com/drankush/MIRACLE-sdk.git
cd MIRACLE-sdk
pip install -e .[dev]
```

**Regenerate the client from OpenAPI specs:**
```bash
python scripts/generate.py
```

---

## 📖 Citation

If you use this SDK in your research, please cite:

> **MIRACLE: MR Imaging Reference API for Cardiovascular Limits from Evidence**
> *Authors: Ankush et al.*
> Journal of Cardiovascular Magnetic Resonance (2026)

---

## 📄 License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

---

<p align="center">
  Made with ❤️ for the Cardiac Imaging Research Community
</p>
