FrameVitals turns a supported tabular source into a structured health report that can be inspected, serialized, compared, snapshotted, extended with domain rules, and enforced in CI.

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, a broken dashboard, or a production incident.

DataFrame / Arrow / files / DuckDB relation
                    │
                    ▼
              DatasetSource
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
     bounded stream       exact/full path
          │                   │
          └─────────┬─────────┘
                    ▼
                 ANALYZE
                    │
      ┌─────────────┼─────────────┐
      ▼             ▼             ▼
   health        contract      snapshot
                    │             │
            ┌───────┘             ▼
            ▼                  history
         validate                 │
            │                     │
reference ─► compare              │
            │                     │
custom ─────┤                     │
checks      ▼                     │
           GATE ◄─────────────────┘
      PASS / WARN / FAIL

Why FrameVitals?

FrameVitals is package-first. Product logic lives under src/framevitals/; the CLI, Flask API, React dashboard and reusable GitHub Action wrap the same canonical engines.

Installation

FrameVitals supports Python 3.11, 3.12, and 3.13. The current public release is 0.2.0.

pip install framevitals

FrameVitals 0.2.0 publishes native ABI3 wheels for supported Linux, macOS, and Windows targets while retaining a portable pure-Python fallback wheel and source distribution. When a compatible native wheel is available, FrameVitals can route supported hot paths through the Rust backend automatically; otherwise the Python/NumPy fallback remains available.

Optional capabilities are split into extras so the base data-health engine stays focused:

pip install "framevitals[arrow]"   # Parquet + Arrow-backed source interoperability
pip install "framevitals[duckdb]"  # lazy DuckDB relations + Arrow transport
pip install "framevitals[excel]"   # XLS/XLSX readers
pip install "framevitals[plot]"    # Matplotlib/Seaborn charts and report plotting
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 capabilities

On a development checkout:

pip install -e ".[all,dev]"

arrow enables projection-aware Parquet execution, compatible CSV/TSV streaming, native PyArrow table inputs, and Arrow PyCapsule-compatible table producers. duckdb adds lazy DuckDBPyRelation inputs without putting DuckDB in the base dependency set.

Quick start

Analyze a DataFrame or file

import 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)
print(report.findings[:3])

File paths work directly:

report = fv.analyze("customers.parquet", mode="quick")

Analyze Arrow-native data

With the arrow extra installed:

import pyarrow as pa
import framevitals as fv

table = pa.table({
    "age": [21, 34, 48],
    "income": [30_000, 62_000, 81_000],
})

report = fv.analyze(table, mode="quick")
profile = fv.profile(table)

PyArrow Table and RecordBatch inputs enter the source-aware batch path instead of being converted to pandas before analysis. Table-like objects implementing the Arrow C Stream / PyCapsule protocol can use the same interoperability boundary when PyArrow is installed.

Analyze a lazy DuckDB relation

With the duckdb extra installed:

import duckdb
import framevitals as fv

con = duckdb.connect()
orders = con.sql("""
    SELECT *
    FROM read_parquet('orders/*.parquet')
""")

profile = fv.profile(orders)
report = fv.analyze(orders, mode="quick")

FrameVitals obtains exact relation shape metadata, pushes requested column projection into the relation, and consumes Arrow record batches. It does not call .df() for diagnostics that can stay on the streaming path.

Run only the diagnostic you need

profile = fv.profile("customers.parquet")
health = fv.health("customers.parquet")
readiness = fv.ml_readiness("customers.parquet")
quality = fv.quality("customers.parquet")
stats = fv.statistics("customers.parquet", mode="quick")
anomalies = fv.anomalies("customers.parquet", mode="quick")
relationships = fv.relationships("customers.parquet")

Focused APIs avoid running unrelated pipeline stages. Supported streaming sources use bounded execution where the diagnostic permits it and disclose exact, sampled, estimated, or materialized behavior in result metadata.

Add a supervised-learning target

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.

Drift and contracts

Compare datasets for drift

result = fv.compare(reference, current)

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

Numeric drift uses PSI, Kolmogorov-Smirnov statistics and standardized mean shift. Categorical drift uses PSI and chi-square diagnostics. Streaming-capable sources can bound distribution work while preserving exact source-shape metadata.

Infer and validate a contract

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

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

Contracts are versioned JSON-friendly dictionaries. Current inference can capture required/optional columns, broad data types, nullability, tolerated null rates, finite numeric bounds, low-cardinality allowed values, and uniqueness expectations.

Validation intentionally remains exact. Constraints such as uniqueness, allowed values and bounds are not silently downgraded to sampled approximations. For a non-pandas source, exact validation may therefore materialize a complete pandas representation, and the execution.full_materialization field reports that decision.

Quality gates

fv.gate(...) combines the checks you choose into one CI-friendly verdict:

result = fv.gate(
    current,
    reference=reference,
    contract=contract,
    drift_warn_on="moderate",
    drift_fail_on="severe",
)

print(result.status)   # pass / warn / fail
print(result.passed)   # True unless the gate failed

You can run only the families you need:

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

Domain-specific custom checks

FrameVitals supports exact application-defined invariants without requiring a fork:

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

checks = fv.run_checks(current, [positive_revenue])
gate = fv.gate(current, custom_checks=[positive_revenue])

fv.run_checks() returns a dict-compatible CheckResult. Arbitrary Python checks run against the complete DataFrame because FrameVitals cannot safely infer whether a user-defined invariant is sampleable. Non-pandas sources therefore report full materialization for this exact path.

Third-party check plugins

Installed packages can register checks through Python entry points under framevitals.checks:

[project.entry-points."framevitals.checks"]
positive_revenue = "acme_data_checks:positive_revenue"

Discovery is deliberately opt-in because loading an entry point executes provider code:

checks = fv.discover_checks()
result = fv.gate(current, custom_checks=checks)

FrameVitals does not import or execute installed check plugins automatically.

GitHub Actions

The repository ships a reusable composite action at action.yml:

- uses: parthdongre/FrameVitals@v0.2.0
  id: framevitals
  with:
    current: data/production.parquet
    reference: data/training.parquet
    contract: data/contract.json
    drift-warn-on: moderate
    drift-fail-on: severe
    output: framevitals-gate.json

- name: Show verdict
  run: echo "FrameVitals status: ${{ steps.framevitals.outputs.status }}"

For production workflows, pin the action to a released tag or commit rather than a moving branch. The action exposes status, passed, and result-path outputs.

Snapshots and monitoring history

An AnalysisResult can be reduced to a compact versioned snapshot:

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

Snapshots retain a fingerprint and compact state such as schema, missingness, health, ML-readiness and finding codes without embedding the full raw dataset.

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

For repeated local monitoring, use SnapshotHistory:

history = fv.SnapshotHistory(".framevitals/history")

history.add(report.snapshot(), label="production")
latest = history.latest()
previous = history.previous()
change = history.compare_latest()

The default .framevitals/ runtime directory is ignored by Git.

The public API

FrameVitals keeps workflow entry points at the package root while retaining focused diagnostics for callers that need one answer rather than the complete pipeline.

framevitals.api remains a lazy compatibility facade over these canonical engines; it does not maintain a second implementation.

What FrameVitals checks

Not every analysis runs on every dataset. FrameVitals uses dataset signals, selected mode, target availability, source capabilities, execution budgets and installed optional dependencies to decide what is useful and safe to execute.

Analysis modes

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

Source-aware execution

FrameVitals separates a dataset source from the diagnostic that consumes it. This lets supported inputs expose exact metadata, projection and record batches without forcing every public API to begin with a full pandas conversion.

Pandas DataFrame
PyArrow Table / RecordBatch
Arrow C Stream / PyCapsule-compatible table
CSV / TSV / Parquet
DuckDB relation
        │
        ▼
   DatasetSource
        │
 ┌──────┴─────────┐
 ▼                ▼
stream/bounded   exact/full
 ▼                ▼
execution provenance

Current source behavior includes:

• Pandas — already materialized, canonical in-memory baseline.
• Parquet — Arrow-backed metadata, projection and record batches.
• CSV/TSV — Arrow streaming when compatible and the arrow extra is installed; pandas fallback otherwise.
• PyArrow Table/RecordBatch — native in-memory Arrow batch path.
• Arrow-compatible table producers — normalized through the standard Arrow C Stream / PyCapsule boundary when available.
• DuckDB relation — exact count/schema metadata, projection pushed into DuckDB, Arrow batch transport, no .df() on streaming-safe diagnostics.
• Other supported files — materialized through the established loader when no streaming adapter exists.

A source being streamable does not mean every operation is approximate. FrameVitals chooses execution semantics by diagnostic:

• source shape/schema can remain exact;
• some statistics, anomaly and drift work can operate on explicit bounded samples;
• exact contracts and arbitrary custom checks remain full-data operations;
• every source-aware result should disclose whether data was streamed, sampled, estimated or fully materialized.

0.2.0 performance and fidelity

FrameVitals does not claim a universal speedup. Performance depends on source shape, mode, backend, storage and statistical fidelity. The release comparison below uses the same deterministic physical 10,000 × 64 CSV (640,000 cells), the same Python/dependency stack, one warm-up and three interleaved measured runs per release/mode. FrameVitals 0.2.0 used the native Rust backend and both releases analyzed all rows and all 64 columns.

The large Standard improvement is an end-to-end architectural result, not a same-algorithm Rust-vs-Python microbenchmark. FrameVitals 0.2.0 replaces the old fully materialized, unbounded heavy-statistics path with source-aware bounded/adaptive execution, exact-once reuse and native streaming kernels.

Accuracy was independently graded on five representative columns plus one Pearson pair from that exact benchmark dataset. Tested count/missing/min/max facts remained exact, and the measured mean, standard deviation, skewness/kurtosis and Pearson errors were unchanged from 0.1.0 at the recorded output precision. The deliberate fidelity trade-off is native streaming quantiles: across tested q25/median/q75 values, 0.2.0 measured about 0.08% mean and 0.21% max absolute error normalized to the observed column range.

The repository also contains physical scale validation through 5 billion logical cells and machine-readable benchmark evidence under benchmarks/results/. See CHANGELOG.md for methodology and caveats.

Filesystem artifacts are opt-in

Calling the Python API does not need to scatter reports and cleaned files around the working directory.

report = fv.analyze(data)
assert report["cleaning"]["output_path"] is None

report = fv.analyze(data, artifacts=True)
print(report["cleaning"]["output_path"])

Command-line interface

FrameVitals ships with a CLI for terminals, scripts and CI workflows.

framevitals --help
framevitals analyze --help
framevitals compare --help
framevitals gate --help
framevitals --version

Analyze and plan:

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 plan dataset.csv --mode standard

Compare, contract and gate:

framevitals compare train.csv production.csv --fail-on moderate
framevitals infer-contract training_data.csv --output contract.json
framevitals validate production_batch.csv --contract contract.json
framevitals gate production_batch.csv \
  --reference training_data.csv \
  --contract contract.json \
  --output gate.json

CLI exit behavior is intentional:

• framevitals validate: 0 for pass/warn by default, 1 for warning when --fail-on-warn is enabled, 2 for contract failure.
• framevitals compare: 1 only when --fail-on is supplied and the configured drift severity is reached; otherwise 0.
• framevitals gate: 0 for pass/warn and 1 for fail.

Result objects

The main workflows return dict-compatible result objects so existing mapping-style code keeps working while application/notebook ergonomics improve:

• AnalysisResult
• DriftResult
• ValidationResult
• CheckResult
• GateResult
• AnalysisSnapshot

Example:

report = fv.analyze(data)
report.health
report.findings
report.column("age")
report.to_json("report.json")
report.to_html("report.html")
report.snapshot("snapshot.json")

The 0.x series preserves room to harden result schemas before 1.0 stability guarantees.

Optional capabilities

The default package contains the core data-health engine. Additional integrations are imported only when their feature is requested.

pip install "framevitals[arrow]"

Adds Arrow-backed files and in-memory Arrow interoperability.

pip install "framevitals[duckdb]"

Adds lazy DuckDB relation support plus the Arrow transport required by that adapter.

pip install "framevitals[ml]"

Adds heavier model integrations including XGBoost, LightGBM, PyOD and SHAP.

pip install "framevitals[ai]"

Adds Ollama-backed interpretation and question-answering features. AI remains an optional explanation layer; computed diagnostics remain usable without it.

pip install "framevitals[plot]"

Adds Matplotlib/Seaborn-backed chart rendering and report plotting. Structured diagnostics do not require this extra.

pip install "framevitals[excel]"

Adds XLS/XLSX reader engines. CSV/TSV/JSON workflows remain available without them.

Web dashboard

The repository includes an optional Flask API + React/TypeScript dashboard for interactive exploration.

pip install -e ".[web]"
python app.py

Then in another terminal:

cd frontend
npm ci
npm run dev

The web extra contains the server runtime only. Install plot for server-side chart/report artifacts and ai for the agentic Q&A path. Optional stacks are loaded lazily rather than blocking Flask startup.

Typical local endpoints:

• Flask API: http://127.0.0.1:5055
• React dashboard: http://127.0.0.1:5173

Design principles

• Package first — Python APIs are canonical; interfaces wrap them.
• Structured results — return reusable data, not only screenshots or prose.
• Source aware — inspect and stream supported inputs before choosing materialization.
• Bounded execution — expensive diagnostics operate within explicit scale budgets.
• Transparent approximations — sampled or estimated results disclose provenance.
• Exact where correctness requires it — contracts and arbitrary custom checks are not silently weakened.
• Safe defaults — no unexpected artifact writes or automatic plugin execution.
• Small workflow surface — analyze → compare → validate → gate → monitor stays obvious.
• Optional integrations — Arrow, DuckDB, Excel, plotting, ML, AI and web are independently installable.
• Extensible without forks — domain checks and opt-in entry-point plugins can extend the gate.

Project layout

.
├── src/framevitals/          # canonical installable Python package
├── tests/                    # automated test suite
├── benchmarks/               # scale/performance harnesses
├── rust/                     # native acceleration core
├── frontend/                 # optional React + TypeScript dashboard
├── templates/                # Flask report pages
├── static/                   # web/report assets
├── examples/                 # focused usage examples
├── action.yml                # reusable GitHub Actions quality gate
├── app.py                    # optional Flask API/server
├── pyproject.toml            # package metadata and dependency groups
└── .github/workflows/        # CI, interop, package, benchmark and release workflows

New reusable Python code belongs in src/framevitals/ and should import through the framevitals.* namespace.

Development

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.ps1

CI validates the core package across Python 3.11–3.13, Arrow streaming paths, Arrow/DuckDB interoperability, optional dependency boundaries, the reusable Gate Action, the Rust workspace/native bridge, React build, wheel contents, distribution metadata, release-version consistency, and clean-wheel installation. A separate benchmark workflow records reproducible time and peak-RSS measurements.

Development is integrated through dev; main is kept release-ready.

Roadmap

FrameVitals is moving toward a dependable data-health quality gate rather than an ever-growing collection of unrelated analytics modules.

0.1  FOUNDATION
     analyze · focused diagnostics · drift · package/CLI baseline

0.2  SOURCE-AWARE QUALITY GATES
     bounded streaming · native execution · contracts · validate · gate · snapshots · provenance

0.3  STABLE RESULTS + PERFORMANCE
     result-schema hardening · planner/cost fidelity · regression budgets · richer history

0.4  EXTENSIBILITY + INTEROPERABILITY
     ecosystem checks · source protocols · integrations · advanced streaming statistics

1.0  STABLE DATA-HEALTH API
     dependable analyze → compare → validate → gate → monitor workflow

FrameVitals 0.2.0 delivers the source-aware quality-gate architecture. Before 1.0, naming, thresholds, result schemas and extension points may still evolve.

Project status

FrameVitals 0.2.x is pre-1.0 software. The project now has a package API, CLI, native/portable execution paths, contracts, gates, snapshots, source-aware streaming, exact-once statistical reuse, reproducible performance evidence, broad CI coverage and release tooling, while the 0.x series deliberately leaves room to refine schemas, thresholds, dependency boundaries and extension points before stability guarantees begin.

Feedback on real datasets, false positives, missing diagnostics, performance, source compatibility and API ergonomics is especially valuable.

Contributing

Contributions are welcome. A good contribution is focused, tested, and improves diagnostic reliability, public workflow clarity, source compatibility, execution transparency or extension ergonomics.

Start with CONTRIBUTING.md, and read the Code of Conduct and Security Policy.

Releases

Releases are built and validated in GitHub Actions and published through PyPI Trusted Publishing. See RELEASING.md and CHANGELOG.md.

License

FrameVitals is open source under the MIT License.