https://github.com/drankush/miracle-api
🫀 SCMR 2026 Open Source Innovation Submission. MIRACLE is an open-source API that provides evidence-based reference values for cardiovascular magnetic resonance (CMR) measurements. It standardizes the interpretation of CMR studies by offering instant access to peer-reviewed normal ranges across multiple clinical domains.
https://github.com/drankush/miracle-api
api cardiac cardiology chatbot clinical llm mcp mri radiology reference
Last synced: 26 days ago
JSON representation
🫀 SCMR 2026 Open Source Innovation Submission. MIRACLE is an open-source API that provides evidence-based reference values for cardiovascular magnetic resonance (CMR) measurements. It standardizes the interpretation of CMR studies by offering instant access to peer-reviewed normal ranges across multiple clinical domains.
- Host: GitHub
- URL: https://github.com/drankush/miracle-api
- Owner: drankush
- License: mit
- Created: 2025-08-25T10:17:46.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-28T10:34:07.000Z (10 months ago)
- Last Synced: 2025-08-28T17:23:46.081Z (10 months ago)
- Topics: api, cardiac, cardiology, chatbot, clinical, llm, mcp, mri, radiology, reference
- Language: JavaScript
- Homepage: https://miracleapi.readme.io
- Size: 178 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
MIRACLE API
MR Imaging Reference API for Cardiovascular Limits from Evidence
[](https://github.com/drankush/MIRACLE-API)
[](https://miracleapi.readme.io)
[](https://developers.google.com/apps-script)
[](https://ref.miracle-api.workers.dev/)
[](https://scmr.org)
[](https://opensource.org/licenses/Apache-2.0)
[](https://miracle-chat.netlify.app)
[](https://miracle-app.surge.sh)
[](https://pypi.org/project/miracle-sdk/)
🫀 SCMR 2026 Open Source Innovation Submission
## 🌟 Introduction
MIRACLE is an open-source API that provides evidence-based reference values for cardiovascular magnetic resonance (CMR) measurements. It standardizes the interpretation of CMR studies by offering instant access to peer-reviewed normal ranges, z-scores, and percentiles across multiple clinical domains.
## 🚀 Live Demos
- **Pediatric CMR Reference Calculator**: [miracle-app.surge.sh](https://miracle-app.surge.sh/) [](https://miracle-app.surge.sh) [](https://github.com/drankush/MIRACLE-webapp/tree/main)
- **Interactive Chatbot**: [miracle-chat.netlify.app](https://miracle-chat.netlify.app) [](https://app.netlify.com/projects/miracle-chat/deploys) [](https://github.com/drankush/MIRACLE-ChatBot/tree/main)
## ✨ Key Features
- 📊 Evidence-based reference values
- 🔓 Open-access API
- 🏥 Multiple clinical domains
- 🧮 Real-time z-score calculations
- 📈 Percentile computations
- 🤖 AI/LLM integration ready
- 📱 REST API with flexible endpoints
## 🛠️ Getting Started
### Basic API Call
```bash
curl --request GET \
--url 'https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle¶meter=LVEDV&gender=Male' \
--header 'accept: application/json'
```
### Code Examples
Python
```python
import requests
url = "https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle¶meter=LVEDV&gender=Male"
headers = {"accept": "application/json"}
response = requests.get(url, headers=headers)
print(response.text)
```
JavaScript
```javascript
const options = {method: 'GET', headers: {accept: 'application/json'}};
fetch('https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle¶meter=LVEDV&gender=Male', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
```
## 📚 API Endpoints
### Adult Cardiac
| **Left Ventricle** | [Volumetric](https://miracleapi.readme.io/reference/getlvreferencevalues#/) | [Volumetric by Age](https://miracleapi.readme.io/reference/getlv_agereferencevalues#/) | [Functional and Geometric](https://miracleapi.readme.io/reference/getlvreference#/) | [Myocardial Thickness](https://miracleapi.readme.io/reference/getlvmtreferencevalues#/) |
|:--|:--|:--|:--|:--|
| | [Global Strain](https://miracleapi.readme.io/reference/getlv_strain_values#/) | [Fractal Dimension by BMI](https://miracleapi.readme.io/reference/getlv_fd_bmi_values#/) | [Fractal Dimension by Ethnicity](https://miracleapi.readme.io/reference/getlv_fd_ethnicity_values#/) | |
| **Right Ventricle** | [Volumetric](https://miracleapi.readme.io/reference/getrv_values#/) | [Volumetric by Age](https://miracleapi.readme.io/reference/getrv_age_values#/) | | |
| **Left Atrium** | [Diameter & Area](https://miracleapi.readme.io/reference/getla_da_values#/) | [Volume & Function](https://miracleapi.readme.io/reference/getla_vf_values#/) | | |
| **Right Atrium** | [Diameter & Area](https://miracleapi.readme.io/reference/getra_da_values#/) | [Volume & Function](https://miracleapi.readme.io/reference/getra_vf_values#/) | | |
| **Other** | [Athletes](https://miracleapi.readme.io/reference/getathletereferencevalues#/) | [T1/ECV](https://miracleapi.readme.io/reference/gett1_relax_values#/) | [T2 Relaxation](https://miracleapi.readme.io/reference/gett2relaxationvalues#/) | [Myocardial Blood Flow](https://miracleapi.readme.io/reference/getmbf_values#/) |
### Adult Vascular
| Aortic Root & Valve | Ascending Aorta | Thoraco-Abdominal Aorta | Aortic Elasticity | Pulmonary Artery |
|:---:|:---:|:---:|:---:|:---:|
| [Aortic Root Diameter](https://miracleapi.readme.io/reference/getaortic_root_d_values#/) | [Ascending Aortic Diameter](https://miracleapi.readme.io/reference/getaa_d_values#/) | [Thoraco-Abdominal Aorta Diameter](https://miracleapi.readme.io/reference/getta_d_values) | [Aortic Distensibility by Age](https://miracleapi.readme.io/reference/getadult_aa_distensibility_values#/) | [Adult Pulmonary Artery Dimensions](https://miracleapi.readme.io/reference/getadultpareferencevalues#/) |
| [Aortic Sinus Diameters and Area](https://miracleapi.readme.io/reference/getasl_da_values#/) | [Ascending Aorta Peak Velocity by Age](https://miracleapi.readme.io/reference/getmpsv_aa_4d_values#/) | | [Aortic PWV by Age](https://miracleapi.readme.io/reference/getadult_pwv_values#/) | |
| [Aortic Valve Peak Velocity](https://miracleapi.readme.io/reference/getmavpv_4d_values#/) | | | | |
### Pediatric Cardiac
| Cardiac | Vascular |
|:---:|:---:|
| [Atrial Volumes](https://miracleapi.readme.io/reference/getpediatricreferencevalues-1#/) | [Aortic CSA](https://miracleapi.readme.io/reference/getpeds_aorta_csa_zscore#/) |
| [Ventricular Parameters](https://miracleapi.readme.io/reference/getpediatricventriclereferencevalues#/) | [Ascending Aorta Distensibility](https://miracleapi.readme.io/reference/getpeds_aa_distensibility_zscore#/) |
| | [Pulse Wave Velocity](https://miracleapi.readme.io/reference/getpeds_pwv_zscore#/) |
| | [Aortic Diameter](https://miracleapi.readme.io/reference/getpedsaorticd#/) |
| | [Pulmonary Artery Diameters](https://miracleapi.readme.io/reference/getpeds_pa_values#/) |
Full documentation available at [miracleapi.readme.io](https://miracleapi.readme.io)
## 🏥 For the SCMR Community
### Ready-to-Use Applications
1. **Pediatric CMR Z-score Calculator Web App**
- React-based frontend with Material-UI components
- Real-time validation and calculation
- RESTful API integration with error handling
- Mobile-responsive design
- Print support
- [Live Demo](https://miracle-app.surge.sh/) | [Source Code](https://github.com/drankush/MIRACLE-webapp)
2. **Virtual CMR Report Generator**
- Batch processing of multiple parameters
- Customizable report templates using Handlebars
- Export options: PDF, DOCX, JSON
- Integration examples with clinical systems
```javascript
// Example report generation
const report = await miracleAPI.generateReport({
patient: { gender: "Male", height: 110, weight: 22 },
measurements: {
LVEDV: 62,
LVEF: 60,
LVM: 45
},
template: "pediatric_standard"
});
```
3. **LLM-Powered Chatbot**
- OpenAI/Groq function calling architecture
- Natural language parsing with structured output
- Context-aware conversation handling
- Error boundary implementation
- [Live Demo](https://miracle-chat.netlify.app) | [Source Code](https://github.com/drankush/MIRACLE-ChatBot)
```javascript
// Example function calling schema
{
"name": "getPediatricVentricleZScore",
"parameters": {
"type": "object",
"properties": {
"gender": { "type": "string", "enum": ["Male", "Female"] },
"parameter": { "type": "string", "enum": ["LVEDV", "LVEF", "LVM"] },
"measured": { "type": "number" },
"ht_cm": { "type": "number" },
"wt_kg": { "type": "number" }
}
}
}
```
### AI/LLM Integration
#### LLM-Ready Documentation
- Structured markdown format at `/llms.txt`
- Automated updates via GitHub Actions
- Endpoint schemas in OpenAPI 3.0
```bash
curl https://miracleapi.readme.io/llms.txt
# Returns markdown-formatted documentation
```
#### Model Context Protocol (MCP)
- OpenAPI specification at `/mcp`
- JSON Schema validation
- Rate limiting information
- Authentication requirements
- Read [Documentation](https://miracleapi.readme.io/reference/mcp#/)
```bash
curl https://miracleapi.readme.io/mcp
# Returns OpenAPI specification
```
#### Function Calling Support
- OpenAI-compatible function definitions
- Anthropic Claude-ready schemas
- Groq API integration examples
- Error handling patterns
```python
# Example function registration with OpenAI
tools = [{
"type": "function",
"function": {
"name": "getPediatricReferenceValues",
"description": "Get z-scores for pediatric CMR measurements",
"parameters": { ... }
}
}]
```
### Research Tools
#### Current Capabilities
```python
# Example: Basic batch processing with current API
import pandas as pd
import requests
def process_cmr_data(data_df):
base_url = "https://ref.miracle-api.workers.dev/exec"
results = []
for _, row in data_df.iterrows():
params = {
"domain": "Pediatric_Ventricle",
"parameter": row["parameter"],
"gender": row["gender"],
"measured": row["value"],
"ht_cm": row["height"],
"wt_kg": row["weight"]
}
response = requests.get(base_url, params=params)
results.append(response.json())
return pd.DataFrame(results)
# Usage
df = pd.read_csv("measurements.csv")
results_df = process_cmr_data(df)
results_df.to_csv("results_with_zscores.csv")
```
#### 🛣️ Future Roadmap (Planned Features)
- DICOM SR templates
- REDCap integration
- Data validation suite
### 🐍 Python SDK
The official Python SDK is now available for batch processing and research workflows.
[](https://pypi.org/project/miracle-sdk/)
[](https://github.com/drankush/MIRACLE-sdk)
**Installation:**
```bash
pip install miracle-sdk
```
**Usage:**
```python
from miracle import Miracle, MiracleBatch
# Single request
client = Miracle()
result = client.pediatric_ventricle_reference_values(
parameter="LVEDV",
gender="Male",
measured=62.5,
ht_cm=110,
wt_kg=22
)
print(result)
# Batch processing (parallel, high-performance)
processor = MiracleBatch(max_workers=10)
df_results = processor.process_csv(
file_path="patients.csv",
domain="Pediatric_Ventricle",
mapping={"gender": "gender", "ht_cm": "height_cm", ...}
)
df_results.to_csv("results_with_zscores.csv")
```
> 📦 **PyPI**: [pypi.org/project/miracle-sdk](https://pypi.org/project/miracle-sdk/) | **GitHub**: [github.com/drankush/MIRACLE-sdk](https://github.com/drankush/MIRACLE-sdk)
## 📖 Citation
```bibtex
@article{ankush2026miracle,
title = {MIRACLE: An Open-Access API for Evidence-Based Reference Values in Cardiovascular MRI},
author = {Ankush, Ankush and Ponnatapura, Janardhana and Sakthivel, Muthu and Sellamuthu, Eswara},
journal = {Journal of Cardiovascular Magnetic Resonance},
volume = {28},
pages = {102338},
year = {2026},
doi = {10.1016/j.jocmr.2025.102338}
}
```
Ankush A, et al. **MIRACLE: An Open-Access API for Evidence-Based Reference Values in Cardiovascular MRI.** *Journal of Cardiovascular Magnetic Resonance*. 2026;28:102338. https://doi.org/10.1016/j.jocmr.2025.102338
## 📄 License
Apache License 2.0 - See [LICENSE](LICENSE) for details
---