FrameVitals

Know if your data is healthy, stable, and ML-ready — before your model finds out.

FrameVitals is a source-aware Python toolkit for data health, drift detection, anomaly analysis, data contracts, quality gates, and ML-readiness diagnostics on tabular data.

Installation · Quick Start · Workflows · CLI · Docs · Contributing

---

FrameVitals helps you decide whether a dataset is healthy enough to trust before it reaches a model, analytics workflow, dashboard, or production pipeline.

It provides one consistent API for inspecting data quality, ML readiness, anomalies, drift, contracts, validation, snapshots, and CI-friendly quality gates.

import framevitals as fv

report = fv.analyze(data)
drift = fv.compare(reference, current)
contract = fv.infer_contract(reference)
validation = fv.validate(current, contract)
gate = fv.gate(current, reference=reference, contract=contract)

The goal is simple: catch bad data before it becomes a bad model, broken dashboard, or production incident.

Installation

Install the package from PyPI:

pip install framevitals

FrameVitals supports Python 3.11, 3.12, and 3.13.

Optional capabilities are available as extras:

pip install "framevitals[arrow]"   # Arrow and Parquet interoperability
pip install "framevitals[duckdb]"  # DuckDB relations
pip install "framevitals[plot]"    # plotting and report charts
pip install "framevitals[ml]"      # optional ML diagnostics
pip install "framevitals[ai]"      # Ollama-backed AI capabilities
pip install "framevitals[web]"     # Flask web runtime
pip install "framevitals[all]"     # all optional runtime capabilities

Quick Start

Analyze a file directly:

import framevitals as fv

report = fv.analyze("customers.csv")

print(report.health["overall_score"])
print(report.ml_readiness)
print(report.findings[:3])

Or pass a pandas DataFrame:

import pandas as pd
import framevitals as fv

customers = pd.read_csv("customers.csv")
report = fv.analyze(customers)

FrameVitals also supports Parquet, PyArrow data, and lazy DuckDB relations when the corresponding optional dependencies are installed.

Common Workflows

Run only the diagnostic you need

The focused APIs let you inspect one part of a dataset without running the complete analysis pipeline:

fv.profile(data)
fv.health(data)
fv.quality(data)
fv.ml_readiness(data)
fv.statistics(data)
fv.anomalies(data)
fv.relationships(data)

Compare datasets for drift

result = fv.compare(reference, current)

print(result.severity)
print(result["columns"][:3])

Use this to compare training and production data, historical batches, pipeline outputs, or any reference/current pair.

Infer and validate a data contract

contract = fv.infer_contract(reference)
result = fv.validate(current, contract)

if result.status == "fail":
    for finding in result.findings:
        print(finding["message"])

Contracts can capture expectations such as schema, data types, nullability, numeric bounds, allowed values, and uniqueness.

Add a quality gate

result = fv.gate(
    current,
    reference=reference,
    contract=contract,
)

print(result.status)  # pass / warn / fail
print(result.passed)

A gate combines the checks you choose into one verdict that can be used in scripts, pipelines, and CI.

Add domain-specific checks

@fv.check("positive revenue", severity="error")
def positive_revenue(df):
    return {
        "passed": bool((df["revenue"] >= 0).all()),
        "message": "Negative revenue values were found.",
    }

result = fv.gate(data, custom_checks=[positive_revenue])

Custom checks make it possible to enforce application-specific rules without modifying FrameVitals itself.

Run target-aware analysis

report = fv.analyze(
    data,
    target="churn",
    mode="deep",
)

Target-aware analysis can surface modelling risks such as leakage, imbalance, redundant features, multicollinearity, and weak baseline relationships.

Create monitoring snapshots

report = fv.analyze(current)
snapshot = report.snapshot("snapshot.json")

Compare compact snapshots later without retaining every raw dataset:

previous = fv.load_snapshot("previous.json")
latest = fv.load_snapshot("snapshot.json")
change = fv.compare_snapshots(previous, latest)

Analysis Modes

Choose how much work FrameVitals should perform:

fv.analyze(data, mode="quick")
fv.analyze(data, mode="standard")
fv.analyze(data, mode="deep")
fv.analyze(data, mode="research")

Use quick for fast checks and the deeper modes when you want broader statistical or modelling diagnostics.

Source-Aware Execution

FrameVitals is designed to work with more than pandas alone. Supported sources can include DataFrames, files, Arrow-native data, and DuckDB relations.

Where semantics allow it, large or lazy sources can use bounded or streaming execution instead of being loaded fully into pandas. Operations that require exact results can still materialize the full dataset, and execution metadata reports those decisions.

Command Line

The Python package also includes a CLI.

Analyze a dataset:

framevitals analyze customers.csv

Compare two datasets:

framevitals compare reference.csv current.csv

Infer a contract:

framevitals infer-contract reference.csv

Create a monitoring snapshot:

framevitals snapshot customers.csv

Inspect dataset execution capabilities:

framevitals inspect customers.csv

See all commands and options with:

framevitals --help

CI and GitHub Actions

FrameVitals can sit between your data pipeline and downstream work:

Data / ETL
    ↓
FrameVitals Gate
    ↓
PASS / WARN / FAIL
    ↓
Training / Analytics / Production

The repository includes a reusable GitHub Action:

- uses: parthdongre/FrameVitals@v0.2.0
  id: framevitals
  with:
    current: data/production.parquet
    reference: data/training.parquet
    contract: data/contract.json
    output: framevitals-gate.json

For production workflows, pin the action to a released tag or commit.

Python API

The main workflow entry points are available directly from framevitals:

fv.analyze(...)
fv.plan(...)
fv.profile(...)
fv.health(...)
fv.quality(...)
fv.ml_readiness(...)
fv.statistics(...)
fv.anomalies(...)
fv.relationships(...)
fv.compare(...)
fv.infer_contract(...)
fv.validate(...)
fv.check(...)
fv.run_checks(...)
fv.gate(...)
fv.create_snapshot(...)
fv.compare_snapshots(...)

For detailed API behaviour, configuration, source semantics, performance notes, and advanced usage, see docs/.

Development

Clone the repository and install it in development mode:

git clone https://github.com/parthdongre/FrameVitals.git
cd FrameVitals
pip install -e ".[all,dev]"

Run the test suite:

pytest

Contributing

Contributions are welcome, including bug fixes, diagnostics, tests, documentation, integrations, and performance improvements.

Please read CONTRIBUTING.md before opening a pull request.

Documentation

Detailed documentation lives in docs/.

• Changelog
• Contributing Guide
• Issue Tracker

License

FrameVitals is released under the MIT License.