SMART Model Card
A Python package for creating structured model cards (documentation) for medical AI models. Fills in a 7-section template, exports to JSON/HTML/Markdown, and can pull dataset info from OMOP CDM sources.
What This Package Does
- Provides a 7-section template for documenting a medical AI model (what it does, what data it uses, how it performs, etc.)
- Offers 5 pre-filled templates for common use cases (risk prediction, screening, diagnostics, triage, monitoring) so you don't start from scratch
- Exports to HTML (interactive, with tables and charts), JSON (machine-readable), and Markdown
- Can pull dataset information from OMOP CDM via WebAPI to auto-fill the data section
- Supports round-trip editing: export to JSON, reload, modify, re-export
- Includes a CLI and an interactive wizard for step-by-step creation
Installation
pip install smart-model-card
From source:
git clone https://github.com/ankurlohachab/smart-model-card.git
cd smart-model-card
pip install -e .
Optional extras:
pip install smart-model-card[omop] # OMOP CDM integration + charts
pip install smart-model-card[viz] # Matplotlib charts only
pip install smart-model-card[dev] # pytest, black, flake8
pip install smart-model-card[all] # Everything
Requirements: Python >= 3.8, requests >= 2.25.0
Quick Start
Create a Model Card in 5 Lines
from smart_model_card import quick_card
card = quick_card(
model_name="COPD Risk Predictor",
description="Predicts 30-day COPD exacerbation risk from EHR data",
developer="University Hospital Research Lab",
contact="ai-team@hospital.org",
template="copd_risk_predictor",
)
card.to_dict()
This fills all 7 sections with template defaults. You should review and replace the placeholder values with your actual model details.
Override Defaults
card = quick_card(
model_name="My Screening Model",
description="Screens for early-stage disease X",
developer="My Hospital",
contact="team@hospital.org",
template="screening_tool",
algorithms_used="Custom Neural Network",
version="2.5.0",
intended_use__contraindications="Not for pediatric use",
methodology__training_procedure="10-fold CV with early stopping",
)
Flat kwargs override model_details fields. Use section__field syntax for other sections.
Interactive Wizard
smart-model-card interactive
Three modes:
| Mode | What It Does | Questions |
|---|---|---|
| Quick Start | Pick a template, fill in key details | ~8 |
| Full Wizard | Walk through all 7 sections step by step | ~40 |
| Load & Edit | Load an existing JSON card, modify specific sections | Variable |
smart-model-card interactive --template copd_risk_predictor
smart-model-card interactive --load existing_card.json
Programmatic Usage
from smart_model_card import (
ModelCard, ModelDetails, IntendedUse, DataFactors,
FeaturesOutputs, PerformanceValidation, Methodology, AdditionalInfo,
SourceDataset, InputFeature, OutputFeature, ValidationDataset, PerformanceMetric,
)
from smart_model_card.exporters import HTMLExporter, JSONExporter
card = ModelCard()
card.set_model_details(ModelDetails(
model_name="Diabetes Risk Model",
version="2.1.0",
developer_organization="University Hospital Research Lab",
release_date="2025-01-15",
description="Predicts 5-year diabetes risk using EHR data",
clinical_function="decision_support",
algorithms_used="XGBoost Classifier",
licensing="MIT",
support_contact="ai-team@hospital.org",
))
card.set_intended_use(IntendedUse(
primary_intended_users="Primary care physicians",
clinical_indications="Patients aged 40-75 with pre-diabetes indicators",
patient_target_group="Adults with BMI > 25 and family history of diabetes",
intended_use_environment="hospital_outpatient",
contraindications="Not for type 1 diabetes screening",
warnings="Does not replace clinical judgment",
))
card.set_data_factors(DataFactors(
source_datasets=[
SourceDataset("Hospital EHR Database", "Academic Medical Center",
15000, "2018-2023", "Adult patients, 45% female, mean age 62")
],
data_distribution_summary="Balanced dataset with 30% positive cases",
data_representativeness="Representative of urban academic hospital population",
data_governance="IRB-approved data access",
))
card.set_features_outputs(FeaturesOutputs(
input_features=[
InputFeature("age", "numeric", True, "Demographics", "18-100", "years"),
InputFeature("bmi", "numeric", True, "Anthropometrics", "15-60", "kg/m2"),
InputFeature("hba1c", "numeric", True, "Laboratory", "4.0-14.0", "%"),
],
output_features=[
OutputFeature("risk_score", "probability", "probability", "0.0-1.0"),
],
feature_type_distribution="3 numeric features",
uncertainty_quantification="Bootstrap 95% confidence intervals",
output_interpretability="SHAP values for individual predictions",
))
card.set_performance_validation(PerformanceValidation(
validation_datasets=[
ValidationDataset("Internal Holdout", "Same Institution", "n=3000", "internal"),
],
claimed_metrics=[PerformanceMetric("AUC", 0.82, "claimed")],
validated_metrics=[PerformanceMetric("AUC", 0.80, "internal")],
calibration_analysis="Hosmer-Lemeshow test p=0.45",
fairness_assessment="AUC within 0.03 across sex and age subgroups",
metric_validation_status="Internal validation complete",
))
card.set_methodology(Methodology(
model_development_workflow="Data extraction, preprocessing, training, validation",
training_procedure="5-fold stratified cross-validation with early stopping",
data_preprocessing="Missing value imputation (MICE), feature normalization",
explainable_ai_method="SHAP TreeExplainer",
global_vs_local_interpretability="Global feature importance and local explanations",
))
card.set_additional_info(AdditionalInfo(
benefit_risk_summary="Early risk identification enables preventive intervention",
ethical_considerations="Potential bias in underrepresented populations",
caveats_limitations="Not validated for patients under 18",
recommendations_for_safe_use="Use as decision support; clinical judgment required",
post_market_surveillance_plan="Quarterly performance monitoring",
))
HTMLExporter.export(card, "model_card.html")
JSONExporter.export(card, "model_card.json")
Field Options
clinical_function: diagnosis, screening, triage, monitoring, decision_support, workflow_support, other
intended_use_environment: hospital_inpatient, hospital_outpatient, emergency, telemedicine, research, home, other
Templates
Five pre-filled templates for common use cases:
| Template ID | Type | Example Use |
|---|---|---|
copd_risk_predictor |
Risk prediction | COPD exacerbation risk from EHR |
screening_tool |
Screening | Population screening with labs |
diagnostic_classifier |
Diagnostics | Image-based diagnostic classification |
triage_model |
Triage | Emergency triage with vitals |
monitoring_model |
Monitoring | Continuous monitoring with time-series |
Templates fill all 7 sections with placeholder content. Replace with your actual values.
from smart_model_card import TEMPLATES
for tid, tmpl in TEMPLATES.items():
print(f"{tid}: {tmpl['name']}")
Save, Reload, Edit
from smart_model_card import ModelCard
from smart_model_card.exporters import JSONExporter
JSONExporter.export(card, "card.json")
reloaded = ModelCard.from_json("card.json")
reloaded.model_details.model_name = "Updated Name"
JSONExporter.export(reloaded, "card_v2.json")
Also works from a dictionary:
import json
with open("card.json") as f:
data = json.load(f)
card = ModelCard.from_dict(data)
OMOP CDM Integration
If your training data lives in an OMOP CDM, the package can pull cohort and dataset information directly:
from smart_model_card.integrations import OMOPIntegration
with OMOPIntegration(
webapi_url="https://atlas.yourorg.org/WebAPI",
source_key="YOUR_CDM_SOURCE"
) as omop:
cohort_data = omop.get_cohort_with_reports(
cohort_id=168,
include_heracles=True,
)
card.set_data_factors(cohort_data["data_factors"])
This fetches cohort definitions, concept sets, and Heracles characterization reports (demographics, conditions, drugs, procedures) from an OHDSI ATLAS instance and uses them to fill the Data & Factors section of your model card.
Requires pip install smart-model-card[omop].
Export Formats
from smart_model_card.exporters import HTMLExporter, JSONExporter, MarkdownExporter
HTMLExporter.export(card, "card.html")
JSONExporter.export(card, "card.json")
MarkdownExporter.export(card, "card.md")
- HTML: Interactive page with collapsible sections, searchable tables, CSV download, demographic charts (from OMOP data), text zoom, print layout
- JSON: Structured output following the 7-section schema
- Markdown: Plain text, good for version control diffs
JSONExporter.export(card, "card_public.json", public=True) strips internal fields (de-identification report URIs) for sharing.
CLI Reference
smart-model-card interactive # Launch wizard
smart-model-card interactive --template screening_tool # Quick start with template
smart-model-card interactive --load card.json # Edit existing card
smart-model-card create --model-name "MyModel" -o scaffold.json # Generate placeholder JSON
smart-model-card validate card.json # Check against schema
smart-model-card export card.json -f html -o card.html # Export to HTML
smart-model-card export card.json -f json -o card.json # Export to JSON
smart-model-card export card.json -f md -o card.md # Export to Markdown
smart-model-card hash --card card.json # SHA-256 checksum
smart-model-card diff old.json new.json # Field-by-field comparison
smart-model-card annotate card.json --author "Dr. Smith" --note "Approved"
Model Card Structure
| Section | What Goes Here |
|---|---|
| 1. Model Details | Name, version, developer, release date, what it does, algorithms used, license, contact |
| 2. Intended Use | Who uses it, for what clinical purpose, target patients, where it runs, when not to use it |
| 3. Data & Factors | Training datasets, how data was collected, demographics, data governance |
| 4. Features & Outputs | Input variables and types, output format, uncertainty, how to interpret outputs |
| 5. Performance | Validation datasets, metrics (AUC, sensitivity, etc.), calibration, subgroup performance |
| 6. Methodology | How the model was built, training process, preprocessing, explainability approach |
| 7. Additional Info | Benefits vs risks, monitoring plan, ethical considerations, limitations, safe use guidance |
The model card also stores: timestamped notes (annotations), lifecycle status, and creation timestamp.
Some optional text fields exist for documenting things like device identifiers or classification labels if relevant to your context.
Testing
pytest tests/ -v
| Test File | Tests | What It Covers |
|---|---|---|
test_model_card.py |
7 | Card creation, validation, export |
test_provenance.py |
3 | File hashing, card diffing |
test_cac.py |
1 | Keyword-based code lookup |
test_from_dict.py |
45 | Save/load round-trip for all sections |
test_templates.py |
35 | Templates and quick_card |
91 tests total
Development
git clone https://github.com/ankurlohachab/smart-model-card.git
cd smart-model-card
python -m venv venv
source venv/bin/activate
pip install -e .[dev]
pytest tests/ -v
See CONTRIBUTING.md for guidelines.
License
MIT - see LICENSE.
Citation
@software{smart_model_card,
title={SMART Model Card: Structured Model Documentation for Healthcare AI},
author={Lohachab, Ankur},
organization={Department of Advanced Computing Sciences, Maastricht University},
year={2025},
url={https://github.com/ankurlohachab/smart-model-card}
}
Author
Ankur Lohachab, Department of Advanced Computing Sciences, Maastricht University
- Issues: GitHub Issues
- Examples: See
examples/directory - Email: ankur.lohachab@maastrichtuniversity.nl
Metadata
Release files for smart-model-card 3.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| smart_model_card-3.0.0.tar.gz | 106.0 kB | Without provenance | Details for smart_model_card-3.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| smart_model_card-3.0.0-py3-none-any.whl | Python 3 | none | any | Details for smart_model_card-3.0.0-py3-none-any.whl |
Total release size: 183.9 kB
Release files / smart_model_card-3.0.0.tar.gz
| Download URL | smart_model_card-3.0.0.tar.gz |
|---|---|
| Size | 106.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ee8809b80aba63dd455c2c1797bbf908b5b38330ddb1bf66c9aed4da25af8bd2
|
|
BLAKE2b-256 checksum How to use checksums |
66660bf572ef532b55cb74c6a5233d1b9cd1ce0359737ba84a0c765ea90c2208
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.5
|
Release files / smart_model_card-3.0.0-py3-none-any.whl
| Download URL | smart_model_card-3.0.0-py3-none-any.whl |
|---|---|
| Size | 78.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e85234c3aec21ac7c1aca2eb918fdb8c9a352c2d916623dc49072f302b34e10
|
|
BLAKE2b-256 checksum How to use checksums |
f7b1d7a216bf0f8871b0542641bdca4f88abf013604f07dba4a193126c95bc23
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.5
|
Security for smart-model-card 3.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.