framevitals 0.1.0__tar.gz

framevitals-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parth Dongre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

framevitals-0.1.0/PKG-INFO

@@ -0,0 +1,415 @@
+Metadata-Version: 2.4
+Name: framevitals
+Version: 0.1.0
+Summary: Data quality, drift detection, anomaly analysis, and ML-readiness diagnostics for pandas and tabular data.
+Author: Parth Dongre
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/parthdongre/FrameVitals#readme
+Project-URL: Repository, https://github.com/parthdongre/FrameVitals
+Project-URL: Issues, https://github.com/parthdongre/FrameVitals/issues
+Project-URL: Changelog, https://github.com/parthdongre/FrameVitals/blob/main/CHANGELOG.md
+Keywords: data-quality,data-profiling,machine-learning,anomaly-detection,data-drift,eda,tabular-data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: seaborn>=0.13
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: xlrd>=2.0
+Requires-Dist: scipy>=1.13
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: scikit-learn>=1.5
+Requires-Dist: pydantic>=2.7
+Provides-Extra: ml
+Requires-Dist: xgboost>=2.0; extra == "ml"
+Requires-Dist: lightgbm>=4.3; extra == "ml"
+Requires-Dist: pyod>=2.0; extra == "ml"
+Requires-Dist: shap>=0.45; extra == "ml"
+Provides-Extra: ai
+Requires-Dist: ollama>=0.3; extra == "ai"
+Provides-Extra: web
+Requires-Dist: flask>=3.0; extra == "web"
+Requires-Dist: gunicorn>=22.0; extra == "web"
+Requires-Dist: werkzeug>=3.0; extra == "web"
+Provides-Extra: all
+Requires-Dist: xgboost>=2.0; extra == "all"
+Requires-Dist: lightgbm>=4.3; extra == "all"
+Requires-Dist: pyod>=2.0; extra == "all"
+Requires-Dist: shap>=0.45; extra == "all"
+Requires-Dist: ollama>=0.3; extra == "all"
+Requires-Dist: flask>=3.0; extra == "all"
+Requires-Dist: gunicorn>=22.0; extra == "all"
+Requires-Dist: werkzeug>=3.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# FrameVitals
+
+### Know if your data is healthy, stable, and ML-ready — before your model finds out.
+
+**A Python toolkit for data-quality diagnostics, drift detection, anomaly analysis, and ML-readiness checks on pandas and tabular data.**
+
+[![Tests](https://github.com/parthdongre/FrameVitals/actions/workflows/test.yml/badge.svg)](https://github.com/parthdongre/FrameVitals/actions/workflows/test.yml)
+[![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12%20%7C%203.13-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![Release](https://img.shields.io/badge/release-0.1.0%20alpha-6f42c1)](CHANGELOG.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/parthdongre/FrameVitals?style=social)](https://github.com/parthdongre/FrameVitals)
+
+[Install](#installation) · [Quick start](#quick-start) · [CLI](#command-line-interface) · [Roadmap](#roadmap) · [Contributing](#contributing)
+
+</div>
+
+---
+
+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:
+
+```python
+import framevitals as fv
+
+report = fv.analyze(df)
+drift = fv.compare(reference_df, current_df)
+```
+
+The goal is simple: **catch bad data before it becomes a bad model, a broken dashboard, or a production incident.**
+
+```text
+                  ┌──────────────────────────┐
+DataFrame / file ─►        ANALYZE           │
+                  │ profile · health · ML    │
+                  │ stats · anomalies · risk │
+                  └────────────┬─────────────┘
+                               │
+                               ▼
+                        structured report
+
+Reference + current ───────────► COMPARE ─────► drift verdict
+```
+
+## Why FrameVitals?
+
+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.
+
+## Installation
+
+FrameVitals supports **Python 3.11, 3.12, and 3.13**.
+
+```bash
+pip install framevitals
+```
+
+Optional feature groups keep heavier dependencies out of the default install:
+
+```bash
+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 features
+```
+
+## Quick start
+
+### Analyze a DataFrame
+
+```python
+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"])
+```
+
+File paths work too:
+
+```python
+report = fv.analyze("customers.csv", mode="quick")
+```
+
+FrameVitals supports pandas DataFrames and common tabular file formats including CSV, TSV, Excel, and JSON.
+
+### Add a supervised-learning target
+
+```python
+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.
+
+### Compare datasets for drift
+
+```python
+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**.
+
+## The public API
+
+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.validate(...)` | In development | 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`.
+
+## What FrameVitals checks
+
+| 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.
+
+## Analysis modes
+
+```python
+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 |
+
+## Filesystem artifacts are opt-in
+
+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.
+
+```python
+report = fv.analyze(df)
+assert report["cleaning"]["output_path"] is None
+
+report = fv.analyze(df, artifacts=True)
+print(report["cleaning"]["output_path"])
+```
+
+## Command-line interface
+
+FrameVitals also ships with a CLI for scripts, terminals, and future CI workflows.
+
+```bash
+framevitals --version
+
+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 --artifacts
+
+framevitals compare train.csv production.csv
+framevitals compare train.csv production.csv --columns age,income
+framevitals compare train.csv production.csv --output drift.json
+```
+
+## Optional ML and AI features
+
+The default package contains the core data-health engine. Heavier features are separated into extras so a simple install stays predictable.
+
+```bash
+pip install "framevitals[ml]"
+```
+
+Adds optional integrations including XGBoost, LightGBM, PyOD and SHAP.
+
+```bash
+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.
+
+## Web dashboard
+
+The repository includes an optional **Flask API + React/TypeScript dashboard** for interactive exploration.
+
+```bash
+pip install -e ".[web]"
+python app.py
+```
+
+Then in another terminal:
+
+```bash
+cd frontend
+npm ci
+npm run dev
+```
+
+Typical 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.
+
+## Design principles
+
+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.
+
+## Project layout
+
+```text
+.
+├── 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.
+
+## Development
+
+```bash
+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:
+
+```powershell
+.venv\Scripts\Activate.ps1
+```
+
+CI 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.
+
+## Roadmap
+
+FrameVitals is moving toward a complete data-health quality gate:
+
+```text
+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.
+
+## Project status
+
+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.
+
+## Contributing
+
+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](CONTRIBUTING.md), and please read the [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md).
+
+## Releases
+
+Releases are built and validated in GitHub Actions and published through PyPI Trusted Publishing. See [RELEASING.md](RELEASING.md) and [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+FrameVitals is open source under the [MIT License](LICENSE).
+
+---
+
+<div align="center">
+
+**If FrameVitals is useful to you, consider starring the repository — it helps the project grow.**
+
+</div>