smart-model-card
Advanced tools
A Python library for generating standardized AI/ML model cards with OMOP Common Data Model integration
A Python library for generating standardized AI/ML model documentation cards with OMOP Common Data Model integration for healthcare applications.
SMART Model Card provides tools for creating structured model documentation following healthcare AI/ML best practices. The library includes:
Healthcare AI/ML models require rigorous documentation for regulatory compliance, clinical validation, deployment safety, reproducibility, and transparency. This library automates the documentation process while maintaining flexibility for diverse use cases.
pip install smart-model-card
git clone https://github.com/ankurlohachab/smart-model-card.git
cd smart-model-card
pip install -e .
OMOP integration support:
pip install smart-model-card[omop]
Visualization support:
pip install smart-model-card[viz]
Development tools:
pip install smart-model-card[dev]
All dependencies:
pip install smart-model-card[all]
Create a model card using the interactive CLI:
smart-model-card interactive
The wizard provides:
Example session:
SECTION 1: Model Details
Model Name: COPD-Risk-Predictor
Version [1.0.0]: 1.0.0
Release Date (YYYY-MM-DD): 2025-01-15
Support Contact (email): researcher@hospital.org
✓ Model Card Creation Complete!
Your model card has been saved to:
• HTML: /path/to/output/model_card.html
• JSON: /path/to/output/model_card.json
To view your model card:
open /path/to/output/model_card.html
Basic example:
from smart_model_card import ModelCard, ModelDetails, IntendedUse
from smart_model_card.sections import DataFactors, SourceDataset
from smart_model_card.exporters import HTMLExporter
# Create model card
card = ModelCard()
# Section 1: Model Details
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",
intended_purpose="decision_support",
algorithms_used="XGBoost Classifier",
licensing="MIT",
support_contact="ai-team@hospital.org"
))
# Section 2: Intended Use
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"
))
# Section 3: Data Factors
card.set_data_factors(DataFactors(
source_datasets=[
SourceDataset(
name="Hospital EHR Database",
origin="Academic Medical Center",
size=15000,
collection_period="2018-2023",
population_characteristics="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, HIPAA-compliant data access"
))
# Export to HTML
HTMLExporter.export(card, "output/diabetes_model_card.html")
The interactive wizard validates:
| Input Type | Validation Rule |
|---|---|
| Dates | YYYY-MM-DD format (e.g., 2025-01-15) |
| Emails | Standard email format (user@example.com) |
| Metrics | Numeric range 0.0-1.0 |
| Dataset Sizes | Integer >= 0 |
| Retry Limit | Maximum 5 attempts per field |
Integrate observational health data:
HTML:
JSON:
Markdown:
All model cards include 7 sections:
smart-model-card interactive
Launch interactive wizard for model card creation.
smart-model-card validate model_card.json
Validate existing model card against schema.
# Export to HTML
smart-model-card export model_card.json --format html -o output.html
# Export to JSON
smart-model-card export model_card.json --format json -o output.json
# Export to Markdown
smart-model-card export model_card.json --format markdown -o output.md
smart-model-card create --model-name "MyModel" -o scaffold.json
Generate template model card with placeholder values.
# Compute hash
smart-model-card hash --card model_card.json
# Compare versions
smart-model-card diff old_card.json new_card.json
smart-model-card fairness-check model_card.json
Analyze fairness metrics and demographic performance.
Main container for model card sections.
from smart_model_card import ModelCard
card = ModelCard()
card.set_model_details(details)
card.set_intended_use(use)
card.set_data_factors(data)
card.set_features_outputs(features)
card.set_performance_validation(perf)
card.set_methodology(method)
card.set_additional_info(info)
# Serialize
card_dict = card.to_dict()
Section 1: Model information.
from smart_model_card import ModelDetails
details = ModelDetails(
model_name="MyModel", # Required
version="1.0.0", # Required
developer_organization="Org Name", # Required
release_date="2025-01-15", # Optional (YYYY-MM-DD)
description="Model description", # Required
intended_purpose="decision_support", # Required
algorithms_used="Algorithm name", # Required
licensing="MIT", # Optional
support_contact="email@org.com" # Required (validated)
)
Purpose options: decision_support, screening, diagnosis, prognosis, other
Section 2: Clinical context.
from smart_model_card import IntendedUse
use = IntendedUse(
primary_intended_users="Clinicians",
clinical_indications="Use cases",
patient_target_group="Patient population",
intended_use_environment="hospital_outpatient",
contraindications="When not to use", # Optional
out_of_scope_applications="Out of scope", # Optional
warnings="Important warnings" # Optional
)
Environment options: hospital_inpatient, hospital_outpatient, clinic, home, mobile, other
from smart_model_card.exporters import HTMLExporter, JSONExporter, MarkdownExporter
# Export to different formats
HTMLExporter.export(card, "output/card.html")
JSONExporter.export(card, "output/card.json")
MarkdownExporter.export(card, "output/card.md")
When creating a model card interactively, the wizard prompts for OMOP integration in Section 3:
Would you like to add OMOP data? [y/N]: y
Choose integration method:
1. Fetch existing cohort from OHDSI WebAPI
2. Create new cohort from scratch
3. Use locally saved cohort data
Select number: 1
OHDSI WebAPI URL: https://atlas.yourorg.org/WebAPI
Available CDM sources (2):
1. KAGGLECOPD - Kaggle COPD Dataset
2. SYNPUF1K - Synthetic Data
Select source number (1-2): 1
Cohort ID: 168
Include Heracles characterization reports? [Y/n]: y
✓ Successfully fetched cohort: COPD Patients 2023
✓ Cohort has 95 persons (status: COMPLETE)
The system includes:
from smart_model_card.integrations import OMOPIntegration
# Connect to OHDSI WebAPI
with OMOPIntegration(
webapi_url="https://atlas.yourorg.org/WebAPI",
source_key="YOUR_CDM_SOURCE"
) as omop:
# Fetch cohort with reports
cohort_data = omop.get_cohort_with_reports(
cohort_id=168,
include_heracles=True
)
# The cohort_data includes:
# - Cohort definition
# - Person count
# - Demographics (age, gender, race)
# - Condition distributions
# - Drug exposures
# - Procedure counts
# - Pre-built DataFactors section
# Add to model card
card.set_data_factors(cohort_data['data_factors'])
When Heracles characterization is included:
The examples/ directory contains working demonstrations:
python examples/quickstart.py
Creates minimal model card with required fields.
python examples/demo_smart_omop_integration.py
Demonstrates OMOP cohort fetching and demographic visualization generation.
python examples/demo_multi_dataset.py
Documents models trained on multiple datasets with different characteristics.
python examples/demo_complete_workflow.py
End-to-end example including OMOP integration and multiple export formats.
pytest tests/ -v
pytest tests/ --cov=smart_model_card --cov-report=html
Total: 16 tests
# Standardization tests only
pytest tests/test_standardization.py -v
# Model card tests only
pytest tests/test_model_card.py -v
# Clone repository
git clone https://github.com/ankurlohachab/smart-model-card.git
cd smart-model-card
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .[dev]
# Run tests
pytest tests/
This project follows PEP 8:
# Format code
black src/ tests/
# Check style
flake8 src/ tests/
# Install build tools
pip install build twine
# Build distribution
python -m build
# Check distribution
twine check dist/*
# Upload to PyPI
twine upload dist/*
Contributions are welcome. Please:
git checkout -b feature/my-feature)pytest tests/)git commit -m 'Add my feature')git push origin feature/my-feature)See CONTRIBUTING.md for details.
MIT License - see LICENSE file.
If you use this library in research or projects, please cite:
@software{smart_model_card,
title={SMART Model Card: Standardized 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}
}
examples/ directoryAnkur Lohachab,
Department of Advanced Computing Sciences,
Maastricht University
FAQs
A Python library for generating standardized AI/ML model cards with OMOP Common Data Model integration
We found that smart-model-card demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Product
Socket Firewall Free is now bundled into Docker Hardened Images, adding build-time and dependency-install supply chain protection on top of hardened base images for Node.js, Python, and Rust.
Security News
Season’s greetings from Socket, and here’s to a calm end of year: clean dependencies, boring pipelines, no surprises.
Research
/Security News
Impostor NuGet package Tracer.Fody.NLog typosquats Tracer.Fody and its author, using homoglyph tricks, and exfiltrates Stratis wallet JSON/passwords to a Russian IP address.