A Python toolkit for data-quality diagnostics, drift detection, anomaly analysis, and ML-readiness checks on pandas and tabular data.
Install · Quick start · CLI · Roadmap · Contributing
FrameVitals turns a pandas DataFrame or tabular dataset into a structured health report you can inspect, serialize, compare, and eventually enforce in CI.
Instead of stitching together separate profiling, quality, drift, anomaly, and ML-readiness tools, FrameVitals gives you one deliberately small entry point:
import framevitals as fv
report = fv.analyze(df)
drift = fv.compare(reference_df, current_df)
contract = fv.infer_contract(reference_df)
validation = fv.validate(current_df, contract)The goal is simple: catch bad data before it becomes a bad model, a broken dashboard, or a production incident.
┌──────────────────────────┐
DataFrame / file ─► ANALYZE │
│ profile · health · ML │
│ stats · anomalies · risk │
└────────────┬─────────────┘
│
▼
structured report
Reference + current ───────────► COMPARE ─────► drift verdict
Most data checks answer one narrow question. FrameVitals is designed around the questions that show up repeatedly in real data and ML workflows:
| Question | FrameVitals |
|---|---|
| Is this dataset structurally healthy? | Missingness, duplicates, cardinality, schema and quality diagnostics |
| Is it ready for modelling? | ML-readiness scoring, target-aware checks and model diagnostics |
| Are there suspicious rows or features? | Statistical diagnostics, anomaly detection, leakage and multicollinearity checks |
| Has production data changed? | Reference-vs-current drift analysis with numeric and categorical tests |
| Can I use the result in code? | JSON-friendly structured output through a Python API and CLI |
| Will analysis unexpectedly write files? | No — filesystem artifacts are opt-in |
FrameVitals is package-first. The core library lives under src/framevitals/; the Flask API and React dashboard are optional interfaces around the same analysis engine.
FrameVitals supports Python 3.11, 3.12, and 3.13. The current public release is 0.1.0 (alpha) and is available on PyPI.
pip install framevitalsOptional feature groups keep heavier dependencies out of the default install:
pip install "framevitals[ml]" # XGBoost, LightGBM, PyOD, SHAP
pip install "framevitals[ai]" # Ollama-backed AI features
pip install "framevitals[web]" # Flask web runtime
pip install "framevitals[all]" # all optional runtime featuresimport pandas as pd
import framevitals as fv
customers = pd.read_csv("customers.csv")
report = fv.analyze(customers)
print(report["health"]["overall_score"])
print(report["ml_readiness"])File paths work too:
report = fv.analyze("customers.csv", mode="quick")FrameVitals supports pandas DataFrames and common tabular file formats including CSV, TSV, Excel, and JSON.
report = fv.analyze(
customers,
target="churn",
mode="deep",
)
print(report["model_leaderboard"])
print(report["explainability"])Target-aware analysis can surface modelling risks such as leakage, imbalance, redundant features, unstable relationships, and weak baselines.
reference = pd.read_csv("training_data.csv")
current = pd.read_csv("production_batch.csv")
result = fv.compare(reference, current)
print(result["summary"]["overall_verdict"])
print(result["columns"][:3])Numeric drift uses PSI, Kolmogorov-Smirnov statistics, and standardized mean shift. Categorical drift uses PSI and chi-square diagnostics.
Infer a contract once from a trusted reference dataset, then validate later batches before they reach downstream jobs:
contract = fv.infer_contract(reference)
result = fv.validate(current, contract)
if not result["valid"]:
for finding in result["errors"]:
print(finding["message"])Contracts capture required columns, broad data types, nullability, and finite numeric bounds. They are plain JSON-friendly dictionaries, so a contract can be committed with a pipeline or stored with a dataset baseline.
The public API is intentionally small while FrameVitals is in alpha.
| API | Status | Purpose |
|---|---|---|
framevitals.analyze(...) |
Available in 0.1.0 |
Profile and diagnose one dataset |
framevitals.compare(...) |
Available in 0.1.0 |
Compare reference and current data for drift |
framevitals.infer_contract(...) |
Available on dev |
Infer a reusable data contract from reference data |
framevitals.validate(...) |
Available on dev |
Validate data against an inferred or explicit contract |
| snapshots / monitoring | Roadmap | Reuse baselines for recurring schema and drift checks |
This keeps the library easy to learn while leaving room for the result model and validation system to mature before 1.0.
| Area | Examples |
|---|---|
| Structure | shape, dtypes, semantic column roles, date/text detection |
| Data quality | missingness, duplicates, constants, cardinality, outliers |
| Health scoring | overall dataset health plus component-level diagnostics |
| ML readiness | modelling readiness, risky columns, preprocessing recommendations |
| Statistics | distribution checks, normality, correlations, effect-size style diagnostics |
| Anomalies | multivariate and robust outlier detectors, optional ensemble methods |
| Target intelligence | task inference, leakage hints, multicollinearity, feature/model diagnostics |
| Drift | PSI, KS, chi-square, mean shift, new or disappearing categories |
| Time series | date-aware diagnostics, stationarity, decomposition and forecast previews |
| Text | text-column profiling, vocabulary and lightweight semantic diagnostics |
| Explainability | model feature importance and SHAP when the optional ML stack is installed |
Not every analysis runs on every dataset. FrameVitals uses dataset signals, selected mode, target availability, and installed optional dependencies to decide what is useful and safe to execute.
fv.analyze(df, mode="quick")
fv.analyze(df, mode="standard")
fv.analyze(df, mode="deep")
fv.analyze(df, mode="research")| Mode | Best for |
|---|---|
quick |
Fast structural, quality, and ML-readiness checks |
standard |
Everyday analysis with broader diagnostics |
deep |
Target-aware and heavier statistical analysis |
research |
Largest analysis budget for exploratory work |
FrameVitals is designed to behave like a library first. Calling the Python API does not need to scatter reports and cleaned files around your working directory.
report = fv.analyze(df)
assert report["cleaning"]["output_path"] is None
report = fv.analyze(df, artifacts=True)
print(report["cleaning"]["output_path"])FrameVitals also ships with a CLI for scripts, terminals, and future CI workflows.
Start by discovering the available commands and options:
framevitals --help
framevitals analyze --help
framevitals compare --help
framevitals --versionAnalyze a dataset:
framevitals analyze dataset.csv
framevitals analyze dataset.csv --mode quick
framevitals analyze dataset.csv --target churn --mode deep
framevitals analyze dataset.csv --output report.json
framevitals analyze dataset.csv --artifactsA useful end-to-end smoke test is:
framevitals analyze dataset.csv --target churn --mode deep --artifacts --output report.jsonCompare two datasets for drift:
framevitals compare train.csv production.csv
framevitals compare train.csv production.csv --columns age,income
framevitals compare train.csv production.csv --output drift.jsonCreate and use a contract from the terminal:
framevitals infer-contract training_data.csv --output contract.json
framevitals validate production_batch.csv --contract contract.jsonThe validation command exits with status 1 when the contract has errors,
which makes it suitable for CI jobs and scheduled ingestion checks.
In 0.1.0, framevitals analyze prints a compact analysis summary to the terminal. --output report.json writes that CLI summary to the requested path. --artifacts enables generated files in the current working directory, including a cleaned dataset under cleaned/ and generated charts under static/charts/. The full structured analysis result is available through the Python API with framevitals.analyze(...).
The default package contains the core data-health engine. Heavier features are separated into extras so a simple install stays predictable.
pip install "framevitals[ml]"Adds optional integrations including XGBoost, LightGBM, PyOD and SHAP.
pip install "framevitals[ai]"Adds Ollama-backed interpretation and question-answering features. AI is treated as an optional explanation layer; computed diagnostics remain usable without a reachable model.
The repository includes an optional Flask API + React/TypeScript dashboard for interactive exploration.
pip install -e ".[web]"
python app.pyThen in another terminal:
cd frontend
npm ci
npm run devTypical local endpoints:
- Flask API:
http://127.0.0.1:5055 - React dashboard:
http://127.0.0.1:5173
The public project website will remain separate from the package runtime so the library does not depend on a hosted service.
FrameVitals is being built around a few constraints that are easy to lose in analytics projects:
- DataFrame first — use it directly from Python without routing through a web app.
- Structured results — return reusable data, not only screenshots or prose.
- Safe defaults — no unexpected artifact writes and graceful optional-feature fallbacks.
- Small public API — make the common path obvious before exposing every internal module.
- Optional heavy dependencies — ML, AI, and web features should not bloat a basic install.
- Production direction — drift, contracts, snapshots, and CI quality gates are first-class roadmap items.
.
├── src/framevitals/ # canonical installable Python package
├── tests/ # automated test suite
├── frontend/ # optional React + TypeScript dashboard
├── templates/ # Flask report pages
├── static/ # web/report assets
├── app.py # optional Flask API/server
├── pyproject.toml # package metadata and dependency groups
└── .github/workflows/ # CI, package validation and publishing
New reusable Python code belongs in src/framevitals/ and should import through the framevitals.* namespace.
git clone https://github.com/parthdongre/FrameVitals.git
cd FrameVitals
git switch dev
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[all,dev]"
pytest
python -m build
python -m twine check dist/*On Windows PowerShell:
.venv\Scripts\Activate.ps1CI validates the core package across Python 3.11–3.13, optional features, the React build, wheel contents, distribution metadata, and a clean-wheel install.
Development is integrated through dev; main is kept release-ready.
FrameVitals is moving toward a complete data-health quality gate:
0.1 ANALYZE + COMPARE
data health · ML readiness · target diagnostics · drift
0.2 VALIDATE + SNAPSHOTS
data contracts · CI gates · reusable baselines
0.3 RESULT OBJECTS + ADVANCED DRIFT
stronger result model · large-data handling · richer monitoring
0.4 EXTENSIBILITY + INTEGRATIONS
configurable checks · adapters · monitoring workflows
1.0 STABLE DATA-HEALTH API
dependable analyze → compare → validate → monitor workflow
Near-term work is tracked through issues and the dev branch.
FrameVitals 0.1.x is alpha software. The core API is usable, but the project is intentionally still refining naming, result schemas, thresholds, and extension points before 1.0.
If you are using FrameVitals in a project, feedback about real datasets, false positives, missing diagnostics, performance, and API ergonomics is especially valuable.
Contributions are welcome.
A good contribution is focused, tested, and improves either the reliability of a diagnostic or the clarity of the public workflow.
Start with CONTRIBUTING.md, and please read the Code of Conduct and Security Policy.
Releases are built and validated in GitHub Actions and published through PyPI Trusted Publishing. See RELEASING.md and CHANGELOG.md.
FrameVitals is open source under the MIT License.
If FrameVitals is useful to you, consider starring the repository — it helps the project grow.