{"id":30827469,"url":"https://github.com/drankush/miracle-api","last_synced_at":"2026-05-18T04:41:57.742Z","repository":{"id":312070204,"uuid":"1044193399","full_name":"drankush/MIRACLE-API","owner":"drankush","description":"🫀 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.","archived":false,"fork":false,"pushed_at":"2025-08-28T10:34:07.000Z","size":182,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T17:23:46.081Z","etag":null,"topics":["api","cardiac","cardiology","chatbot","clinical","llm","mcp","mri","radiology","reference"],"latest_commit_sha":null,"homepage":"https://miracleapi.readme.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drankush.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-25T10:17:46.000Z","updated_at":"2025-08-28T10:34:10.000Z","dependencies_parsed_at":"2025-08-28T17:24:34.124Z","dependency_job_id":"b16c7d77-5e06-419d-a9b9-f29e025f7133","html_url":"https://github.com/drankush/MIRACLE-API","commit_stats":null,"previous_names":["drankush/miracle-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/drankush/MIRACLE-API","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drankush%2FMIRACLE-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drankush%2FMIRACLE-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drankush%2FMIRACLE-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drankush%2FMIRACLE-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drankush","download_url":"https://codeload.github.com/drankush/MIRACLE-API/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drankush%2FMIRACLE-API/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273908522,"owners_count":25189155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cardiac","cardiology","chatbot","clinical","llm","mcp","mri","radiology","reference"],"created_at":"2025-09-06T13:12:23.081Z","updated_at":"2026-05-18T04:41:57.736Z","avatar_url":"https://github.com/drankush.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"miracle_logo.png\" alt=\"MIRACLE API Logo\" width=\"600\"/\u003e\n  \u003ch1\u003eMIRACLE API\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eMR Imaging Reference API for Cardiovascular Limits from Evidence\u003c/strong\u003e\u003c/p\u003e\n\n  [![Open Source](https://img.shields.io/badge/Open-Source-green.svg)](https://github.com/drankush/MIRACLE-API)\n  [![API Documentation](https://img.shields.io/badge/Docs-readme.io-blue.svg)](https://miracleapi.readme.io)\n  [![Google Apps Script](https://img.shields.io/badge/Powered%20by-Google%20Apps%20Script-orange.svg)](https://developers.google.com/apps-script)\n  [![Cloudflare Workers](https://img.shields.io/badge/Cloudflare%20Workers-miracle--api-orange.svg?logo=cloudflare\u0026logoColor=white)](https://ref.miracle-api.workers.dev/)\n\n  [![SCMR 2026](https://img.shields.io/badge/SCMR-2026%20Submission-red.svg)](https://scmr.org)\n  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n  \n  [![Netlify Demo](https://img.shields.io/badge/ChatBot-Netlify-00C7B7.svg)](https://miracle-chat.netlify.app)\n  [![Surge Demo](https://img.shields.io/badge/WebApp-Surge-yellow.svg)](https://miracle-app.surge.sh)\n  [![PyPI](https://img.shields.io/badge/PyPI-miracle--sdk-blue.svg)](https://pypi.org/project/miracle-sdk/)\n\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch2\u003e🫀 SCMR 2026 Open Source Innovation Submission\u003c/h2\u003e\n\u003c/div\u003e\n\n## 🌟 Introduction\n\nMIRACLE 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.\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003e\n    🔗 View and Test Full API Documentation: \n    \u003ca href=\"https://miracleapi.readme.io\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n      miracleapi.readme.io\n    \u003c/a\u003e\n  \u003c/h3\u003e\n\u003c/div\u003e\n\n\n\n## 🚀 Live Demos\n\n- **Pediatric CMR Reference Calculator**: [miracle-app.surge.sh](https://miracle-app.surge.sh/) [![Surge Status](https://img.shields.io/website?url=https%3A%2F%2Fmiracle-app.surge.sh\u0026label=surge\u0026up_message=200%20OK\u0026down_message=down\u0026up_color=brightgreen\u0026down_color=red\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZD0iTTEzIDJMMyAxNGg3bC0xIDggMTAtMTJoLTd6IiBmaWxsPSIjZmZmZmZmIi8+PC9zdmc+\u0026style=flat)](https://miracle-app.surge.sh) [![Source Code](https://img.shields.io/badge/source_code-GitHub-blue?logo=github)](https://github.com/drankush/MIRACLE-webapp/tree/main)\n\n- **Interactive Chatbot**: [miracle-chat.netlify.app](https://miracle-chat.netlify.app) [![Netlify Status](https://api.netlify.com/api/v1/badges/c197c4ee-b90b-4be8-879d-a9305c6b9823/deploy-status)](https://app.netlify.com/projects/miracle-chat/deploys) [![Source Code](https://img.shields.io/badge/source_code-GitHub-blue?logo=github)](https://github.com/drankush/MIRACLE-ChatBot/tree/main)\n\n\n## ✨ Key Features\n\n- 📊 Evidence-based reference values\n- 🔓 Open-access API\n- 🏥 Multiple clinical domains\n- 🧮 Real-time z-score calculations\n- 📈 Percentile computations\n- 🤖 AI/LLM integration ready\n- 📱 REST API with flexible endpoints\n\n\n\n## 🛠️ Getting Started\n\n### Basic API Call\n\n```bash\ncurl --request GET \\\n     --url 'https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle\u0026parameter=LVEDV\u0026gender=Male' \\\n     --header 'accept: application/json'\n```\n\n### Code Examples\n\n\u003cdetails\u003e\n\u003csummary\u003ePython\u003c/summary\u003e\n\n```python\nimport requests\n\nurl = \"https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle\u0026parameter=LVEDV\u0026gender=Male\"\n\nheaders = {\"accept\": \"application/json\"}\n\nresponse = requests.get(url, headers=headers)\n\nprint(response.text)\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eJavaScript\u003c/summary\u003e\n\n```javascript\nconst options = {method: 'GET', headers: {accept: 'application/json'}};\n\nfetch('https://ref.miracle-api.workers.dev/exec?domain=Pediatric_Ventricle\u0026parameter=LVEDV\u0026gender=Male', options)\n  .then(res =\u003e res.json())\n  .then(res =\u003e console.log(res))\n  .catch(err =\u003e console.error(err));\n```\n\u003c/details\u003e\n\n## 📚 API Endpoints\n  \n### Adult Cardiac\n\n\n| **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#/) |\n|:--|:--|:--|:--|:--|\n|  | [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#/) |  |\n| **Right Ventricle** | [Volumetric](https://miracleapi.readme.io/reference/getrv_values#/) | [Volumetric by Age](https://miracleapi.readme.io/reference/getrv_age_values#/) |  |  |\n| **Left Atrium** | [Diameter \u0026 Area](https://miracleapi.readme.io/reference/getla_da_values#/) | [Volume \u0026 Function](https://miracleapi.readme.io/reference/getla_vf_values#/) |  |  |\n| **Right Atrium** | [Diameter \u0026 Area](https://miracleapi.readme.io/reference/getra_da_values#/) | [Volume \u0026 Function](https://miracleapi.readme.io/reference/getra_vf_values#/) |  |  |\n| **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#/) |\n\n\n\n### Adult Vascular\n\n| Aortic Root \u0026 Valve | Ascending Aorta | Thoraco-Abdominal Aorta | Aortic Elasticity | Pulmonary Artery |\n|:---:|:---:|:---:|:---:|:---:|\n| [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#/) |\n| [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#/) |  |\n| [Aortic Valve Peak Velocity](https://miracleapi.readme.io/reference/getmavpv_4d_values#/) |  |  |  |  |\n\n\n### Pediatric Cardiac\n\n| Cardiac | Vascular |\n|:---:|:---:|\n| [Atrial Volumes](https://miracleapi.readme.io/reference/getpediatricreferencevalues-1#/) | [Aortic CSA](https://miracleapi.readme.io/reference/getpeds_aorta_csa_zscore#/) |\n| [Ventricular Parameters](https://miracleapi.readme.io/reference/getpediatricventriclereferencevalues#/) | [Ascending Aorta Distensibility](https://miracleapi.readme.io/reference/getpeds_aa_distensibility_zscore#/) |\n|  | [Pulse Wave Velocity](https://miracleapi.readme.io/reference/getpeds_pwv_zscore#/) |\n|  | [Aortic Diameter](https://miracleapi.readme.io/reference/getpedsaorticd#/) |\n|  | [Pulmonary Artery Diameters](https://miracleapi.readme.io/reference/getpeds_pa_values#/) |\n\n\nFull documentation available at [miracleapi.readme.io](https://miracleapi.readme.io)\n\n\n## 🏥 For the SCMR Community\n\n### Ready-to-Use Applications\n\n1. **Pediatric CMR Z-score Calculator Web App**\n   - React-based frontend with Material-UI components\n   - Real-time validation and calculation\n   - RESTful API integration with error handling\n   - Mobile-responsive design\n   - Print support\n   - [Live Demo](https://miracle-app.surge.sh/) | [Source Code](https://github.com/drankush/MIRACLE-webapp)\n\n2. **Virtual CMR Report Generator**\n   - Batch processing of multiple parameters\n   - Customizable report templates using Handlebars\n   - Export options: PDF, DOCX, JSON\n   - Integration examples with clinical systems\n   ```javascript\n   // Example report generation\n   const report = await miracleAPI.generateReport({\n     patient: { gender: \"Male\", height: 110, weight: 22 },\n     measurements: {\n       LVEDV: 62,\n       LVEF: 60,\n       LVM: 45\n     },\n     template: \"pediatric_standard\"\n   });\n   ```\n\n3. **LLM-Powered Chatbot**\n   - OpenAI/Groq function calling architecture\n   - Natural language parsing with structured output\n   - Context-aware conversation handling\n   - Error boundary implementation\n   - [Live Demo](https://miracle-chat.netlify.app) | [Source Code](https://github.com/drankush/MIRACLE-ChatBot)\n   ```javascript\n   // Example function calling schema\n   {\n     \"name\": \"getPediatricVentricleZScore\",\n     \"parameters\": {\n       \"type\": \"object\",\n       \"properties\": {\n         \"gender\": { \"type\": \"string\", \"enum\": [\"Male\", \"Female\"] },\n         \"parameter\": { \"type\": \"string\", \"enum\": [\"LVEDV\", \"LVEF\", \"LVM\"] },\n         \"measured\": { \"type\": \"number\" },\n         \"ht_cm\": { \"type\": \"number\" },\n         \"wt_kg\": { \"type\": \"number\" }\n       }\n     }\n   }\n   ```\n\n### AI/LLM Integration\n\n#### LLM-Ready Documentation\n- Structured markdown format at `/llms.txt`\n- Automated updates via GitHub Actions\n- Endpoint schemas in OpenAPI 3.0\n```bash\ncurl https://miracleapi.readme.io/llms.txt\n# Returns markdown-formatted documentation\n```\n\n#### Model Context Protocol (MCP)\n- OpenAPI specification at `/mcp`\n- JSON Schema validation\n- Rate limiting information\n- Authentication requirements\n- Read [Documentation](https://miracleapi.readme.io/reference/mcp#/)\n```bash\ncurl https://miracleapi.readme.io/mcp\n# Returns OpenAPI specification\n```\n\n#### Function Calling Support\n- OpenAI-compatible function definitions\n- Anthropic Claude-ready schemas\n- Groq API integration examples\n- Error handling patterns\n```python\n# Example function registration with OpenAI\ntools = [{\n    \"type\": \"function\",\n    \"function\": {\n        \"name\": \"getPediatricReferenceValues\",\n        \"description\": \"Get z-scores for pediatric CMR measurements\",\n        \"parameters\": { ... }\n    }\n}]\n```\n\n### Research Tools\n\n#### Current Capabilities\n```python\n# Example: Basic batch processing with current API\nimport pandas as pd\nimport requests\n\ndef process_cmr_data(data_df):\n    base_url = \"https://ref.miracle-api.workers.dev/exec\"\n    results = []\n    \n    for _, row in data_df.iterrows():\n        params = {\n            \"domain\": \"Pediatric_Ventricle\",\n            \"parameter\": row[\"parameter\"],\n            \"gender\": row[\"gender\"],\n            \"measured\": row[\"value\"],\n            \"ht_cm\": row[\"height\"],\n            \"wt_kg\": row[\"weight\"]\n        }\n        response = requests.get(base_url, params=params)\n        results.append(response.json())\n    \n    return pd.DataFrame(results)\n\n# Usage\ndf = pd.read_csv(\"measurements.csv\")\nresults_df = process_cmr_data(df)\nresults_df.to_csv(\"results_with_zscores.csv\")\n```\n\n#### 🛣️ Future Roadmap (Planned Features)\n\n- DICOM SR templates\n- REDCap integration\n- Data validation suite\n\n### 🐍 Python SDK\n\nThe official Python SDK is now available for batch processing and research workflows.\n\n[![PyPI version](https://img.shields.io/pypi/v/miracle-sdk.svg)](https://pypi.org/project/miracle-sdk/)\n[![GitHub](https://img.shields.io/badge/GitHub-MIRACLE--sdk-blue?logo=github)](https://github.com/drankush/MIRACLE-sdk)\n\n**Installation:**\n```bash\npip install miracle-sdk\n```\n\n**Usage:**\n```python\nfrom miracle import Miracle, MiracleBatch\n\n# Single request\nclient = Miracle()\nresult = client.pediatric_ventricle_reference_values(\n    parameter=\"LVEDV\",\n    gender=\"Male\",\n    measured=62.5,\n    ht_cm=110,\n    wt_kg=22\n)\nprint(result)\n\n# Batch processing (parallel, high-performance)\nprocessor = MiracleBatch(max_workers=10)\ndf_results = processor.process_csv(\n    file_path=\"patients.csv\",\n    domain=\"Pediatric_Ventricle\",\n    mapping={\"gender\": \"gender\", \"ht_cm\": \"height_cm\", ...}\n)\ndf_results.to_csv(\"results_with_zscores.csv\")\n```\n\n\u003e 📦 **PyPI**: [pypi.org/project/miracle-sdk](https://pypi.org/project/miracle-sdk/) | **GitHub**: [github.com/drankush/MIRACLE-sdk](https://github.com/drankush/MIRACLE-sdk)\n\n\n## 📖 Citation\n\n```bibtex\n@article{ankush2026miracle,\n  title   = {MIRACLE: An Open-Access API for Evidence-Based Reference Values in Cardiovascular MRI},\n  author  = {Ankush, Ankush and Ponnatapura, Janardhana and Sakthivel, Muthu and Sellamuthu, Eswara},\n  journal = {Journal of Cardiovascular Magnetic Resonance},\n  volume  = {28},\n  pages   = {102338},\n  year    = {2026},\n  doi     = {10.1016/j.jocmr.2025.102338}\n}\n```\n\nAnkush 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\n\n## 📄 License\n\nApache License 2.0 - See [LICENSE](LICENSE) for details\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eMade with ❤️ for the CMR community\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://miracleapi.readme.io\"\u003eDocs\u003c/a\u003e •\n    \u003ca href=\"https://miracle-app.surge.sh\"\u003eWeb App\u003c/a\u003e •\n    \u003ca href=\"https://miracle-chat.netlify.app\"\u003eChatbot\u003c/a\u003e •\n    \u003ca href=\"https://pypi.org/project/miracle-sdk/\"\u003eSDK\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrankush%2Fmiracle-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrankush%2Fmiracle-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrankush%2Fmiracle-api/lists"}