Train your model your way. ModelBrief analyses it and turns the results into a complete model report.
ModelBrief accepts an already-trained model plus any available train, validation, and test data. It never calls fit, never retrains the model, and produces console, standalone HTML, and PDF reports.
ModelBrief is an open-source Python library for analysing trained machine-learning models and automatically generating structured reports. Reports can include:
Model overview and parameters, Dataset summary, Task detection, Feature importance, Model performance and evaluation metrics, Confusion matrix, Error analysis, Visualisations, Optional AI-generated explanation and recommendations
- Scikit-learn classifiers, regressors, clusters and compatible estimators
- XGBoost, LightGBM and CatBoost through optional extras
- PyTorch and TensorFlow/Keras classification models
- CNN/image classification data, plus extensible detection and segmentation metrics
- NLP pipelines, PyTorch/TensorFlow text models, token and text error utilities
- Regression, classification, clustering, time-series forecast evaluation and anomaly detection
Deep-learning inputs differ by project. Pass model-ready tensors or arrays. For custom data loaders, output schemas, object detection, generation, segmentation, or unusual prediction APIs, subclass BaseAdapter and pass adapter=YourAdapter(model).
ModelBrief(model, X_test=X_test, y_test=y_test, task="time_series")
ModelBrief(model, X_test=images, y_test=labels, task="computer_vision")
ModelBrief(model, X_test=texts, y_test=labels, task="nlp")
ModelBrief(model, X_test=X, task="clustering")- The supplied model is treated as trained and is never fitted.
- Validation is optional and independently reported when present.
- Optional frameworks are not heavily imported.
- A failed optional analysis is recorded as a warning rather than destroying the whole report.
- HTML is standalone. PDF creation uses ReportLab.
Current version: 0.2.2 Python: 3.10+
pip install modelbrieffrom modelbrief import ModelBrief
report = ModelBrief(
model=model,
X_train=X_train, y_train=y_train,
X_val=X_val, y_val=y_val, # optional
X_test=X_test, y_test=y_test,
ai=False,
)
print(report.show())
report.pdf("reports/model.pdf")
report.html("reports/model.html")Reports include: Model overview, Dataset, Task, Parameters, Feature importance, Model performance, Confusion matrix, Error analysis, Charts, and Optional AI guidance.
pip install modelbrief
pip install "modelbrief[xgboost]"
pip install "modelbrief[lightgbm]"
pip install "modelbrief[catboost]"
pip install "modelbrief[pytorch]" # includes torch and torchvision
pip install "modelbrief[tensorflow]"
pip install "modelbrief[vision]"
pip install "modelbrief[nlp]" # transformers and torch
pip install "modelbrief[ai]" # Groq SDK
pip install "modelbrief[all]" # every integrationgit clone <your-fork-url>
cd modelbrief
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
pytest- Create or retrieve an API key from GroqCloud.
- Install the optional client:
pip install "modelbrief[ai]". - Set the key in the environment. Never put it in source code or commit it.
PowerShell:
$env:GROQ_API_KEY="your-api-key"
$env:MODELBRIEF_GROQ_MODEL="openai/gpt-oss-20b" # optionalWindows CMD:
set GROQ_API_KEY=your-api-key
set MODELBRIEF_GROQ_MODEL=openai/gpt-oss-20bmacOS/Linux:
export GROQ_API_KEY="your-api-key"
export MODELBRIEF_GROQ_MODEL="openai/gpt-oss-20b" # optionalUsing pip: pip install --upgrade modelbrief # Get the latest features!, if you already have modelbrief installed .
pytest
Then use ModelBrief(..., ai=True). With ai=False, Groq is neither imported nor called. AI output is supplementary and should be reviewed by a qualified human.
Contributions are welcome! ModelBrief is intended to be an open-source project where developers and data scientists can add adapters, analyses, visualisations, tests and improvements.
See examples/ for classification, regression, clustering, time series, anomaly detection, PyTorch, TensorFlow, computer vision, CNN, object detection, segmentation, NLP, sentiment, Transformers, and text generation examples.
Fork, clone, create a branch, install .[dev], add code and tests, run pytest, and open a pull request. Keep framework-specific dependencies optional. Do not commit secrets, datasets, checkpoints, or large model weights.
main→ Production-ready codedev→ Active developmentfeature/*→ New featuresfix/*→ Bug fixes
ModelBrief is maintained by a data scientist and software developer:
| Name | GitHub | |
|---|---|---|
| Chidiebere Njoku | @ChidiebereNjoku | [email protected] |
| Micheal Adegoro | @micheal | [email protected] |
MIT License. See LICENSE for the full text.
Have you used ModelBrief? We'd love to hear from you.
Whether you've generated your first report, explored the optional Groq-powered AI explanations and recommendations, or have ideas for future features, your feedback can help shape the project.