# Model Cards

A model card is a short document that travels with a trained model and says what it's for, what it must not be used for, what data it learned from, how well it does overall and for each group, its limits, and when it was trained, as Mitchell and colleagues proposed in Model Cards for Model Reporting (2019).

Journeyman · AI Basics · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Name the sections of a model card and say what each one tells the people who use the model
- Write a model card for a trained model, with its intended use, uses it isn't for, data, performance overall and by group, limits and date

## Key takeaways

- A saved model file says nothing about what it's for. A model card is the short document that goes with it, so the people who use it know what it can and can't do.
- A card states the intended use and the uses it isn't for, the data it learned from, its measured performance overall and for each group, its limits, and when it was trained.
- Performance by group can show what one overall number hides. A group with few examples gives a shaky number, and the card says so.
- The card is written for people who aren't technical, in plain words and the label's units, and it's updated whenever the model is retrained.

`delivery_model.joblib` is saved, and two teams at Pine Ridge Delivery want it. The catering team wants estimates for its new 13-mile runs to the business park. The operations manager wants to rank drivers by how often they beat the estimate. Both sound reasonable, and both are mistakes, but nothing in the file says so. Any model you hand over, at work, to a client or in a portfolio project, needs a page that tells people what it's for before they find out the hard way.

The example is Pine Ridge Delivery's `deliveries.csv`, from *Exercise: Model Check-Up*, and the model from *Saving and Loading a Model*.

## A model with no instructions

Think of a box of medicine. The box tells you what it's for, who shouldn't take it, how much, and what to watch for. Without the box, the pills inside are the same pills, but nobody can use them safely. A saved model is the pills without the box.

The two requests show what goes missing. The catering runs are farther than any order the model learned from (*When the World Changes*), so its guesses there are guesses about something it never saw. And the model was built to give customers a rough estimate, not to judge people: its misses come mostly from things no column shows, such as traffic jams, so a driver who "loses" to the estimate may have been stuck in one.

## What a model card is

In 2019, Margaret Mitchell and eight colleagues proposed a fix in a paper called *Model Cards for Model Reporting*: a **model card**, a short document that goes with every trained model. Their card has nine sections, including model details (who made it, when, what kind of model), intended use (with the uses that are out of scope), the data, the measures used and the results. They describe the out-of-scope section as inspired by the warning labels on food and toys. The paper says the sections can be tailored to the model, so a small model can have a short card.

This course's card keeps the parts every reader needs:

- **Model:** what it is, its version, who made it.
- **Date trained**, and when it should be checked again.
- **Intended use:** what it predicts, for whom, and under what conditions.
- **Not for:** uses people might try that it wasn't built for.
- **Data:** what it learned from, and the ranges it covers.
- **Performance:** measured on test data, overall and for each group that matters.
- **Limits:** what it can't know, and where it's been wrong.

## Performance, overall and by group

One overall number can hide that a model does better for some orders than for others. The paper's word for the groups is *factors*: groups of people for a model about people, and conditions, such as the weather, for one like this. So the card reports the test error overall and for each group:

```python
import pandas as pd
from sklearn.linear_model import LinearRegression
from sklearn.metrics import mean_absolute_error, root_mean_squared_error
from sklearn.model_selection import train_test_split
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler

deliveries = pd.read_csv("deliveries.csv")
features = ["distance_miles", "stops_before", "is_raining"]
train, test = train_test_split(deliveries, test_size=0.2, random_state=42)
model = make_pipeline(StandardScaler(), LinearRegression())
model.fit(train[features], train["minutes"])
guesses = model.predict(test[features])

print("MAE:", round(mean_absolute_error(test["minutes"], guesses), 2))
print("RMSE:", round(root_mean_squared_error(test["minutes"], guesses), 2))
results = pd.DataFrame({
    "weather": test["is_raining"].map({0: "dry", 1: "raining"}),
    "miss": (test["minutes"] - guesses).abs(),
})
print(results.groupby("weather")["miss"].agg(["count", "mean"]).round(2))
```

```text
MAE: 3.63
RMSE: 5.72
         count  mean
weather
dry         82  3.91
raining     18  2.33
```

Each order's miss is its error's size, so a group's `mean` is that group's MAE. Rainy orders look better, 2.33 minutes against 3.91, but there are only 18 of them: one traffic jam among them would change that number a lot. The card gives the count beside each number, so nobody reads more into it than it holds. For a model about people, the groups are groups of people, as in *Measuring Results Group by Group*.

## Pine Ridge's card

Here is the delivery model's card, in plain words and minutes:

| Section | Delivery time model |
|---|---|
| Model | Pine Ridge delivery time estimate, version 1: a linear regression on distance, stops and rain, with scaling, made by the Pine Ridge data team |
| Date trained | November 3, 2025. Check it again every month against new orders |
| Intended use | A rough estimate of minutes for the customer's app ("about 31 minutes") for orders of 0.5 to 9 miles |
| Not for | Orders farther than 9 miles; judging, ranking or paying drivers; promises with a refund if late |
| Data | 500 orders from last year (400 to train, 100 to test): 0.5 to 9 miles, 0 to 3 stops first, rain on about 1 order in 5 |
| Performance | On the 100 test orders: off by 3.63 minutes on average (MAE), RMSE 5.72. Dry: 3.91 (82 orders). Raining: 2.33 (18 orders, too few to be sure) |
| Limits | Can't see traffic jams, which cause the biggest misses (about 20 minutes late). Knows nothing about new neighborhoods or new routing rules: retrain when they change |

Notice what it doesn't say: no "accurate", no "smart", no number with more decimals than anyone needs. Every claim can be checked against the data and the test.

## Keeping the card true

A card is true for one model on one date. When *When the World Changes* found that a stop now takes about 2 minutes longer, this card's *Limits* went out of date, and retraining makes version 2, with a new card: new date, new data, new performance. Keep the card beside the model file and change both together.

## Check yourself

2 questions to try on the lesson page.

## So what

A model file holds what a model learned; its card holds what people need to know to use it well, and to know when not to use it at all.

## Sources

- Margaret Mitchell, Simone Wu, Andrew Zaldivar, Parker Barnes, Lucy Vasserman, Ben Hutchinson, Elena Spitzer, Inioluwa Deborah Raji and Timnit Gebru, [Model Cards for Model Reporting](https://arxiv.org/abs/1810.03993), FAT* '19 (Conference on Fairness, Accountability, and Transparency), 2019: model cards as short documents that accompany trained models; the suggested sections (model details, intended use with out-of-scope uses, factors, metrics, evaluation data, training data, quantitative analyses, ethical considerations, caveats and recommendations), which may be tailored to the model; results broken down by groups and conditions; the out-of-scope section inspired by warning labels on food and toys.
- scikit-learn 1.9.1, [Model persistence](https://scikit-learn.org/stable/model_persistence.html), *Security & maintainability limitations*: the metadata to save with a model: the training data, the code, the package versions and the score.
- scikit-learn 1.9.1, [mean_absolute_error](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.mean_absolute_error.html) and [root_mean_squared_error](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.root_mean_squared_error.html), API reference.

## Key terms

- [Model Card](https://www.ask-codey.com/glossary/model-card)
- [Model](https://www.ask-codey.com/glossary/model-ai)
- [Mean Absolute Error](https://www.ask-codey.com/glossary/mean-absolute-error)
- [Test Data](https://www.ask-codey.com/glossary/test-data)

## Related

- [Saving and Loading a Model](https://www.ask-codey.com/lessons/ml-saving-a-model)
- [When the World Changes](https://www.ask-codey.com/lessons/ml-when-the-world-changes)
- [Measuring Results Group by Group](https://www.ask-codey.com/lessons/ml-fairness-by-group)
- [Exercise: Model Check-Up](https://www.ask-codey.com/lessons/exercise-ml-model-check-up)

Source: https://www.ask-codey.com/lessons/ml-model-cards
