MIRACLE API

MR Imaging Reference API for Cardiovascular Limits from Evidence

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.

• Pediatric CMR Reference Calculator: miracle-app.surge.sh

• Interactive Chatbot: miracle-chat.netlify.app

• 📊 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

curl --request GET \
     --url 'https://script.google.com/macros/s/.../exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male' \
     --header 'accept: application/json'

import requests

url = "https://script.google.com/macros/s/.../exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male"

headers = {"accept": "application/json"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {accept: 'application/json'}};

fetch('https://script.google.com/macros/s/.../exec?domain=Pediatric_Ventricle&parameter=LVEDV&gender=Male', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Full documentation available at miracleapi.readme.io

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 | Source Code

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

   // 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 | Source Code

   // 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" }
       }
     }
   }

• Structured markdown format at /llms.txt
• Automated updates via GitHub Actions
• Endpoint schemas in OpenAPI 3.0

curl https://miracleapi.readme.io/llms.txt
# Returns markdown-formatted documentation

• OpenAPI specification at /mcp
• JSON Schema validation
• Rate limiting information
• Authentication requirements
• Read Documentation

curl https://miracleapi.readme.io/mcp
# Returns OpenAPI specification

• OpenAI-compatible function definitions
• Anthropic Claude-ready schemas
• Groq API integration examples
• Error handling patterns

# Example function registration with OpenAI
tools = [{
    "type": "function",
    "function": {
        "name": "getPediatricReferenceValues",
        "description": "Get z-scores for pediatric CMR measurements",
        "parameters": { ... }
    }
}]

# Example: Basic batch processing with current API
import pandas as pd
import requests

def process_cmr_data(data_df):
    base_url = "https://script.google.com/macros/s/.../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")

1. Python Package Development

   • Dedicated miracle-py package
   • Easy-to-use batch processing
   • Statistical analysis utilities

   # Future API (not yet implemented)
   from miracle import MiracleBatch
   processor = MiracleBatch()
   results = processor.process_csv(...)

2. Research Integration Tools

   • DICOM SR templates
   • REDCap integration
   • Data validation suite

   # Planned feature
   from miracle.export import DicomSRExport  # Coming soon

3. Statistical Analysis Module

   • Advanced z-score calculations
   • Multiple BSA formulas
   • Automated outlier detection

   # Future enhancement
   from miracle.stats import calculate_zscore  # Planned

@software{Ankush_MIRACLE_2025,
  author = {Ankush, Ankush},
  title = {MIRACLE: MR Imaging Reference API for Cardiovascular Limits from Evidence},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/drankush/MIRACLE-API}
}

MIT License - See LICENSE for details