Open research intelligence infrastructure for medicine.
Verifiable clinical AI and verified evidence — FHIR-native · grammar-constrained · validator-grounded · deterministic · reproducible
-orange.svg){kind=icon}
MedScale builds systems whose clinical outputs can be checked mechanically — against FHIR StructureDefinitions, against terminology value sets, and against executable queries — rather than merely judged plausibly. The organizing bet is that in medicine, verifiable form and traceable content are worth more than fluent prose that cannot be checked.
The platform is built around five ideas:
| Idea | Meaning |
|---|---|
| FHIR-native | FHIR is a first-class reasoning representation, not an afterthought. |
| Grammar-constrained generation | Decoding against FHIR grammars guarantees structural validity for free. |
| Validator-grounded verification | The HL7 validator is the ground truth — an exact, scalable oracle. |
| Deterministic benchmarking | Every headline metric is executable; no LLM-as-judge in any primary metric. |
| Reproducible research | No claim without a script and a committed artifact; negative results are first-class. |
The guiding scientific hypothesis: grammar guarantees form; training only teaches content. It is designed to be falsified, not assumed.
MedScale has two pillars on one verification spine (ADR-0005): verifiable clinical generation (FHIR, grammar, validator, benchmark) and verified evidence infrastructure (litdb + the evidence model, ADR-0009). It is infrastructure — not a medical chatbot, and not a clinician-facing answer product.
MedScale is not a from-scratch foundation model, not a medical device, and is never trained or evaluated on PHI. See What MedScale is / is not.
MedScale is an independent research platform. A separate product, Afia, consumes it. The dependency is strict and one-way:
flowchart LR
MS["MedScale<br/>(research platform · synthetic-only)"] -- "versioned artifacts:<br/>package · weights · schemas" --> AF["Afia<br/>(product · real PHI in prod)"]
AF -. "PHI must NEVER flow back" .-x MS
Afia depends on MedScale. MedScale must never depend on Afia. Formalized in ADR-0003.
v0.2.0 — Reproducible research intelligence platform. Deterministic literature database, evidence infrastructure, benchmark replay contracts, Dataset v1, FHIR boundary, optional backends, and reviewer collaboration workflow are implemented. Model training, external healthcare data ingestion, and production deployment remain out of scope. See the Roadmap.
The public API exposes reproducibility primitives, literature database storage, review/screening workflows, deterministic AI triage recommendations, and configuration constants. Domain APIs in full FHIR validation, grammar-constrained generation, and model training arrive in their own phases.
| Path | Contents |
|---|---|
docs/vision/ |
Strategic Blueprint (canonical narrative) + Research Vision (canonical scope) |
docs/research/ |
Research questions, paper taxonomy, reproducibility policy |
docs/governance/ |
Program rules (R1–R7), policies |
docs/adr/ |
Architecture Decision Records |
docs/execution/ |
Phase (T0–T7) planning; fills as work proceeds |
docs/archive/ |
Superseded material (kept for history) |
src/medscale/ |
The medscale Python package |
tests/ |
Test suite |
Start with the Documentation Index and the Glossary.
MedScale uses uv and Python 3.11.
git clone https://github.com/IamShehri/MedScale
cd MedScale
uv sync # create .venv and install dev tooling
uv run pytest # run the test suite
uv run ruff check . # lint
uv run mypy # strict type-checkSee the Developer Guide for the full workflow.
MedScale welcomes contributors under its reproducibility and citation policies. Please read CONTRIBUTING, the Code of Conduct, and the program rules R1–R7 before opening a pull request.
If you use MedScale in academic work, please cite it — see CITATION.cff.
Apache-2.0. Everything MedScale ships is chosen to permit derivative models and commercial use, so that Afia — and others — may build on it.