PRACTICAL GUIDE

How to write a model card for a portfolio project

A model card connects an ML result to the data, procedure and limits behind it. It is a concise explanation, not a quality badge.

Purpose and intended use

Define the prediction task, likely users and the decision it might support. State uses you have not evaluated and decisions the model should not make. Keep classroom experiments separate from production claims.

Data and permissions

Record the source, license or synthetic-generation method, target, features and exclusions. Do not include private records. Describe known coverage gaps without claiming the dataset represents everyone.

Split and leakage checks

Explain how training, validation and test data were separated. Keep transformations fitted on training data. If time or repeated entities matter, explain the split boundary. A random split is not automatically appropriate.

Baseline and evaluation

Compare with a simple baseline under the same setup. Choose metrics that match the error costs and class distribution. Record versions, split settings and observed values only after running the experiment.

Errors and limitations

Describe failure examples, subgroup concerns when evidence supports them and uncertainty from a small evaluation. Do not let one headline score hide errors or imply performance on unseen deployment data.

Reproduction and personal changes

Link the environment, steps and artifacts you are allowed to share. State what you changed from a starter notebook or pretrained system. If the live demo has ended, retain dated results and local reproduction instructions.

Build my evidence pack