tabaudit 0.1.0__tar.gz

tabaudit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sadia Samia
+
+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.

tabaudit-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: tabaudit
+Version: 0.1.0
+Summary: Audit tabular ML datasets for leakage, duplicates, label noise and imbalance before you train.
+Author: Sadia Samia
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sadiasamia121912/tabaudit
+Project-URL: Issues, https://github.com/sadiasamia121912/tabaudit/issues
+Keywords: machine-learning,data-quality,data-leakage,label-noise,cleanlab,audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: cleanlab>=2.5
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: jinja2>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pyarrow; extra == "dev"
+Dynamic: license-file
+
+# tabaudit
+
+**Find the problems in your dataset before your model does.**
+
+`tabaudit` is a command-line tool that audits a tabular ML dataset for the defects that
+quietly inflate metrics and break models in production — target leakage, train/test
+contamination, duplicates, label noise, class imbalance and schema problems — and gives it
+a single **Data Health Score** with concrete, prioritised fixes.
+
+```
+pip install tabaudit
+tabaudit audit train.csv --target churn --test test.csv --html report.html
+```
+
+![tabaudit demo](https://raw.githubusercontent.com/sadiasamia121912/tabaudit/main/docs/demo.gif)
+
+---
+
+## Why
+
+A model that scores 99% on a leaked dataset is worse than useless: it looks finished and
+fails silently in production. Most of these defects take one line of pandas to fix — the
+hard part is *noticing* them. `tabaudit` makes the check automatic, fast, and repeatable
+(it runs in CI with `--fail-under`).
+
+## What it checks
+
+| check         | finds                                                                                                     | severity |
+| ------------- | --------------------------------------------------------------------------------------------------------- | -------- |
+| `leakage`     | single features that predict the target almost perfectly on their own (incl. *missingness* leaks), identifier columns, columns named after the target | CRITICAL / HIGH / MEDIUM |
+| `duplicates`  | exact duplicate rows, feature-identical rows with conflicting labels, **test rows that also appear in train** | CRITICAL → LOW |
+| `label_noise` | probably-mislabeled rows via confident learning ([cleanlab](https://github.com/cleanlab/cleanlab)), ranked and tiered | HIGH → INFO |
+| `imbalance`   | class ratio, classes with < 10 examples                                                                   | HIGH → LOW |
+| `schema`      | ≥ 50 % missing columns, missing labels, constant / near-constant columns, numbers stored as text, leftover index columns | HIGH → INFO |
+
+Every finding carries a plain-English explanation of *why it matters* and *what to do*.
+Findings are weighted into a 0–100 score and an A–F grade.
+
+## Quick start
+
+```bash
+pip install tabaudit
+
+# See every check fire on a synthetic dataset with planted defects
+tabaudit demo
+
+# Audit your own data
+tabaudit audit data.csv --target label
+tabaudit audit train.parquet -t label --test test.parquet --html report.html --json report.json
+
+# Only some checks, sampled for speed, gate a CI pipeline
+tabaudit audit data.csv -t label -c leakage,duplicates --max-rows 20000 --fail-under 75
+```
+
+Supported inputs: CSV, TSV, Parquet, Feather, JSON-lines. Classification and regression
+targets are inferred automatically; omit `--target` to run only the unsupervised checks.
+
+`--html` writes a self-contained report you can send to whoever owns the data:
+
+![tabaudit HTML report](https://raw.githubusercontent.com/sadiasamia121912/tabaudit/main/docs/report_screenshot.png)
+
+### Python API
+
+```python
+from tabaudit import run_audit
+
+report = run_audit("train.csv", target="churn", test="test.csv")
+print(report.score, report.grade)          # 6 'F'
+for f in report.sorted_findings():
+    print(f.severity.value, f.title, f.columns)
+report.to_dict()                            # JSON-serialisable
+```
+
+## Example output
+
+```
+┌────────────────────────────────── Verdict ──────────────────────────────────┐
+│  Data Health Score  6/100   F                                               │
+│  ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░                                             │
+│  Do not train on this dataset as-is                                         │
+│   CRITICAL  2    MEDIUM  4    LOW  2                                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+┌─  CRITICAL   105 test rows (8.2%) also appear in the training set ──────────┐
+│  The model has already seen these rows. Any test-set score is partly        │
+│  memorisation, not generalisation.                                          │
+│  → Remove overlapping rows from the test set, or re-split with a            │
+│  group-aware splitter if rows belong to entities.                           │
+└──────────────────────────────────────────────────────────────── duplicates ─┘
+┌─  CRITICAL   1 feature(s) predict the target almost perfectly on their own ─┐
+│  churn_reason (AUC=1.000) - its *missingness alone* has AUC 1.00            │
+│  → This is target leakage: the column encodes the answer (recorded after    │
+│  the outcome, or derived from it). Remove it - any model trained with it    │
+│  will look excellent and fail in production.                                │
+└─────────────────────────────────────────────────────────────────── leakage ─┘
+```
+
+## Results on real datasets
+
+Ten well-known public datasets, loaded straight from OpenML and audited with **default
+settings** — no tuning, no column dropping. Full write-up, including what the tool got
+wrong on the first run and how it was fixed: [`docs/benchmarks.md`](https://github.com/sadiasamia121912/tabaudit/blob/main/docs/benchmarks.md).
+
+| dataset | rows | score | headline finding |
+|---|---:|:-:|---|
+| titanic | 1 309 | 64 C | **HIGH** `boat` predicts survival alone (AUC 0.97 vs next-best 0.74) — target leakage |
+| spambase | 4 601 | 75 B | **HIGH** 391 exact duplicate rows (8.5 %) |
+| creditcard | 284 807 | 78 B | **HIGH** 578 : 1 class imbalance; 9 144 duplicate rows |
+| telco-customer-churn | 7 043 | 80 B | `TotalCharges` is numeric but stored as text; 18 conflicting-label groups |
+| breast-w | 699 | 82 B | **HIGH** 236 exact duplicate rows (34 %) |
+| bank-marketing | 45 211 | 83 B | `duration` stands far above every other feature (AUC 0.81 vs 0.65) — a documented leak |
+| adult | 48 842 | 84 B | 5 groups of rows with identical features but different labels |
+| credit-g | 1 000 | 93 A | ~6 % of rows likely mislabeled |
+| heart-statlog | 270 | 93 A | ~6 % of rows likely mislabeled |
+| diabetes | 768 | 93 A | ~5 % of rows likely mislabeled |
+
+- **4 of 10 have a CRITICAL/HIGH finding; 10 of 10 have at least one MEDIUM.** Every HIGH
+  is a documented property of the dataset (Titanic's lifeboat column, spambase and
+  breast-w duplicates, creditcard's 0.17 % fraud rate).
+- The leakage check catches both the near-perfect leak (`boat`) and the *soft* one
+  (bank-marketing `duration`, which the dataset's own documentation says to drop), while
+  correctly reporting breast-w's six strong-but-honest features as "easy task", not leakage.
+- Label-noise suspects were checked by hand on two datasets: of the 10 top-ranked rows,
+  5 look genuinely mislabeled, 5 are ambiguous, 0 look like false alarms
+  ([review sheet](https://github.com/sadiasamia121912/tabaudit/blob/main/docs/label_noise_review.md)).
+
+Reproduce with `python benchmarks/run_benchmarks.py` (~6 min, downloads ~50 MB).
+
+## How the hard checks work
+
+_Short version. Every threshold, and the reason for it, is in [`docs/checks.md`](https://github.com/sadiasamia121912/tabaudit/blob/main/docs/checks.md)._
+
+**Leakage.** For each feature *alone*, a shallow decision tree is cross-validated against
+the target. A single column with out-of-fold AUC ≥ 0.98 (or R² ≥ 0.98 for regression) is
+almost never a legitimate signal — it is the answer written down after the fact. Below
+that, a leak has to be an *outlier*: the sorted single-feature scores are split at their
+largest gap, and only a feature that sits ≥ 0.15 above every other one is flagged (HIGH if
+it scores ≥ 0.90, MEDIUM "soft leak" if ≥ 0.75). Several strong features bunched together
+mean the task is easy, not leaky — that case is reported at INFO. Missing values are
+encoded so the tree can split on *missingness itself*, which catches the common "this field
+is only filled in for positives" leak.
+
+**Label noise.** An out-of-fold gradient-boosting model produces class probabilities for
+every row; cleanlab's confident-learning filter flags rows whose given label it confidently
+contradicts. The model is deliberately regularised because an over-confident model makes
+cleanlab over-flag. Leaky and identifier columns found by the `leakage` check are excluded
+first — otherwise the leak makes the model agree with every wrong label and the noise is
+invisible.
+
+Suspects are reported in two tiers: **likely** (model gives the given label < 20 %
+probability) and **suspected** (any confident-learning flag), ranked most-confident first.
+
+### Measured on known ground truth
+
+The demo generator knows exactly which labels it flipped, so the detector can be scored
+honestly (`python examples/validate_label_noise.py <noise_rate>`; 6 000 rows, clean-data
+AUC ≈ 0.88):
+
+| planted noise | flipped rows | "likely" flagged | likely precision / recall | top-25 precision |
+| ------------- | ------------ | ---------------- | ------------------------- | ---------------- |
+| 2.2 %         | 110          | 187              | 32 % / 55 %               | 56 %             |
+| 6.4 %         | 317          | 313              | 60 % / 59 %               | 72 %             |
+| 10.3 %        | 514          | 420              | 73 % / 60 %               | 72 %             |
+
+Random label flips on rows the model is genuinely unsure about are indistinguishable from
+correct labels, so no detector can reach high precision *and* recall here. The point is
+the ranked review list, not the raw count — and the count is a useful estimate at realistic
+noise rates.
+
+## Development
+
+```bash
+git clone https://github.com/sadiasamia121912/tabaudit && cd tabaudit
+python -m venv .venv && .venv/Scripts/activate      # or source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check src tests examples && ruff format --check src tests examples
+```
+
+Adding a check: drop a module in `src/tabaudit/checks/` exposing
+`run(ctx: AuditContext) -> list[Finding]` and register it in `checks/__init__.py`.
+Checks run in registry order and may communicate through `ctx.excluded_features`.
+
+## Roadmap
+
+- [ ] Group / time leakage: entity IDs shared across splits, features that peek into the future
+- [ ] Near-duplicate detection (fuzzy text, numeric tolerance)
+- [ ] Label-noise support for regression targets
+- [x] Audit results for popular public benchmark datasets — see [Results on real datasets](#results-on-real-datasets)
+- [ ] `pre-commit` hook and GitHub Action
+
+## License
+
+MIT

tabaudit-0.1.0/README.md

@@ -0,0 +1,193 @@
+# tabaudit
+
+**Find the problems in your dataset before your model does.**
+
+`tabaudit` is a command-line tool that audits a tabular ML dataset for the defects that
+quietly inflate metrics and break models in production — target leakage, train/test
+contamination, duplicates, label noise, class imbalance and schema problems — and gives it
+a single **Data Health Score** with concrete, prioritised fixes.
+
+```
+pip install tabaudit
+tabaudit audit train.csv --target churn --test test.csv --html report.html
+```
+
+![tabaudit demo](https://raw.githubusercontent.com/sadiasamia121912/tabaudit/main/docs/demo.gif)
+
+---
+
+## Why
+
+A model that scores 99% on a leaked dataset is worse than useless: it looks finished and
+fails silently in production. Most of these defects take one line of pandas to fix — the
+hard part is *noticing* them. `tabaudit` makes the check automatic, fast, and repeatable
+(it runs in CI with `--fail-under`).
+
+## What it checks
+
+| check         | finds                                                                                                     | severity |
+| ------------- | --------------------------------------------------------------------------------------------------------- | -------- |
+| `leakage`     | single features that predict the target almost perfectly on their own (incl. *missingness* leaks), identifier columns, columns named after the target | CRITICAL / HIGH / MEDIUM |
+| `duplicates`  | exact duplicate rows, feature-identical rows with conflicting labels, **test rows that also appear in train** | CRITICAL → LOW |
+| `label_noise` | probably-mislabeled rows via confident learning ([cleanlab](https://github.com/cleanlab/cleanlab)), ranked and tiered | HIGH → INFO |
+| `imbalance`   | class ratio, classes with < 10 examples                                                                   | HIGH → LOW |
+| `schema`      | ≥ 50 % missing columns, missing labels, constant / near-constant columns, numbers stored as text, leftover index columns | HIGH → INFO |
+
+Every finding carries a plain-English explanation of *why it matters* and *what to do*.
+Findings are weighted into a 0–100 score and an A–F grade.
+
+## Quick start
+
+```bash
+pip install tabaudit
+
+# See every check fire on a synthetic dataset with planted defects
+tabaudit demo
+
+# Audit your own data
+tabaudit audit data.csv --target label
+tabaudit audit train.parquet -t label --test test.parquet --html report.html --json report.json
+
+# Only some checks, sampled for speed, gate a CI pipeline
+tabaudit audit data.csv -t label -c leakage,duplicates --max-rows 20000 --fail-under 75
+```
+
+Supported inputs: CSV, TSV, Parquet, Feather, JSON-lines. Classification and regression
+targets are inferred automatically; omit `--target` to run only the unsupervised checks.
+
+`--html` writes a self-contained report you can send to whoever owns the data:
+
+![tabaudit HTML report](https://raw.githubusercontent.com/sadiasamia121912/tabaudit/main/docs/report_screenshot.png)
+
+### Python API
+
+```python
+from tabaudit import run_audit
+
+report = run_audit("train.csv", target="churn", test="test.csv")
+print(report.score, report.grade)          # 6 'F'
+for f in report.sorted_findings():
+    print(f.severity.value, f.title, f.columns)
+report.to_dict()                            # JSON-serialisable
+```
+
+## Example output
+
+```
+┌────────────────────────────────── Verdict ──────────────────────────────────┐
+│  Data Health Score  6/100   F                                               │
+│  ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░                                             │
+│  Do not train on this dataset as-is                                         │
+│   CRITICAL  2    MEDIUM  4    LOW  2                                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+┌─  CRITICAL   105 test rows (8.2%) also appear in the training set ──────────┐
+│  The model has already seen these rows. Any test-set score is partly        │
+│  memorisation, not generalisation.                                          │
+│  → Remove overlapping rows from the test set, or re-split with a            │
+│  group-aware splitter if rows belong to entities.                           │
+└──────────────────────────────────────────────────────────────── duplicates ─┘
+┌─  CRITICAL   1 feature(s) predict the target almost perfectly on their own ─┐
+│  churn_reason (AUC=1.000) - its *missingness alone* has AUC 1.00            │
+│  → This is target leakage: the column encodes the answer (recorded after    │
+│  the outcome, or derived from it). Remove it - any model trained with it    │
+│  will look excellent and fail in production.                                │
+└─────────────────────────────────────────────────────────────────── leakage ─┘
+```
+
+## Results on real datasets
+
+Ten well-known public datasets, loaded straight from OpenML and audited with **default
+settings** — no tuning, no column dropping. Full write-up, including what the tool got
+wrong on the first run and how it was fixed: [`docs/benchmarks.md`](https://github.com/sadiasamia121912/tabaudit/blob/main/docs/benchmarks.md).
+
+| dataset | rows | score | headline finding |
+|---|---:|:-:|---|
+| titanic | 1 309 | 64 C | **HIGH** `boat` predicts survival alone (AUC 0.97 vs next-best 0.74) — target leakage |
+| spambase | 4 601 | 75 B | **HIGH** 391 exact duplicate rows (8.5 %) |
+| creditcard | 284 807 | 78 B | **HIGH** 578 : 1 class imbalance; 9 144 duplicate rows |
+| telco-customer-churn | 7 043 | 80 B | `TotalCharges` is numeric but stored as text; 18 conflicting-label groups |
+| breast-w | 699 | 82 B | **HIGH** 236 exact duplicate rows (34 %) |
+| bank-marketing | 45 211 | 83 B | `duration` stands far above every other feature (AUC 0.81 vs 0.65) — a documented leak |
+| adult | 48 842 | 84 B | 5 groups of rows with identical features but different labels |
+| credit-g | 1 000 | 93 A | ~6 % of rows likely mislabeled |
+| heart-statlog | 270 | 93 A | ~6 % of rows likely mislabeled |
+| diabetes | 768 | 93 A | ~5 % of rows likely mislabeled |
+
+- **4 of 10 have a CRITICAL/HIGH finding; 10 of 10 have at least one MEDIUM.** Every HIGH
+  is a documented property of the dataset (Titanic's lifeboat column, spambase and
+  breast-w duplicates, creditcard's 0.17 % fraud rate).
+- The leakage check catches both the near-perfect leak (`boat`) and the *soft* one
+  (bank-marketing `duration`, which the dataset's own documentation says to drop), while
+  correctly reporting breast-w's six strong-but-honest features as "easy task", not leakage.
+- Label-noise suspects were checked by hand on two datasets: of the 10 top-ranked rows,
+  5 look genuinely mislabeled, 5 are ambiguous, 0 look like false alarms
+  ([review sheet](https://github.com/sadiasamia121912/tabaudit/blob/main/docs/label_noise_review.md)).
+
+Reproduce with `python benchmarks/run_benchmarks.py` (~6 min, downloads ~50 MB).
+
+## How the hard checks work
+
+_Short version. Every threshold, and the reason for it, is in [`docs/checks.md`](https://github.com/sadiasamia121912/tabaudit/blob/main/docs/checks.md)._
+
+**Leakage.** For each feature *alone*, a shallow decision tree is cross-validated against
+the target. A single column with out-of-fold AUC ≥ 0.98 (or R² ≥ 0.98 for regression) is
+almost never a legitimate signal — it is the answer written down after the fact. Below
+that, a leak has to be an *outlier*: the sorted single-feature scores are split at their
+largest gap, and only a feature that sits ≥ 0.15 above every other one is flagged (HIGH if
+it scores ≥ 0.90, MEDIUM "soft leak" if ≥ 0.75). Several strong features bunched together
+mean the task is easy, not leaky — that case is reported at INFO. Missing values are
+encoded so the tree can split on *missingness itself*, which catches the common "this field
+is only filled in for positives" leak.
+
+**Label noise.** An out-of-fold gradient-boosting model produces class probabilities for
+every row; cleanlab's confident-learning filter flags rows whose given label it confidently
+contradicts. The model is deliberately regularised because an over-confident model makes
+cleanlab over-flag. Leaky and identifier columns found by the `leakage` check are excluded
+first — otherwise the leak makes the model agree with every wrong label and the noise is
+invisible.
+
+Suspects are reported in two tiers: **likely** (model gives the given label < 20 %
+probability) and **suspected** (any confident-learning flag), ranked most-confident first.
+
+### Measured on known ground truth
+
+The demo generator knows exactly which labels it flipped, so the detector can be scored
+honestly (`python examples/validate_label_noise.py <noise_rate>`; 6 000 rows, clean-data
+AUC ≈ 0.88):
+
+| planted noise | flipped rows | "likely" flagged | likely precision / recall | top-25 precision |
+| ------------- | ------------ | ---------------- | ------------------------- | ---------------- |
+| 2.2 %         | 110          | 187              | 32 % / 55 %               | 56 %             |
+| 6.4 %         | 317          | 313              | 60 % / 59 %               | 72 %             |
+| 10.3 %        | 514          | 420              | 73 % / 60 %               | 72 %             |
+
+Random label flips on rows the model is genuinely unsure about are indistinguishable from
+correct labels, so no detector can reach high precision *and* recall here. The point is
+the ranked review list, not the raw count — and the count is a useful estimate at realistic
+noise rates.
+
+## Development
+
+```bash
+git clone https://github.com/sadiasamia121912/tabaudit && cd tabaudit
+python -m venv .venv && .venv/Scripts/activate      # or source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check src tests examples && ruff format --check src tests examples
+```
+
+Adding a check: drop a module in `src/tabaudit/checks/` exposing
+`run(ctx: AuditContext) -> list[Finding]` and register it in `checks/__init__.py`.
+Checks run in registry order and may communicate through `ctx.excluded_features`.
+
+## Roadmap
+
+- [ ] Group / time leakage: entity IDs shared across splits, features that peek into the future
+- [ ] Near-duplicate detection (fuzzy text, numeric tolerance)
+- [ ] Label-noise support for regression targets
+- [x] Audit results for popular public benchmark datasets — see [Results on real datasets](#results-on-real-datasets)
+- [ ] `pre-commit` hook and GitHub Action
+
+## License
+
+MIT

tabaudit-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tabaudit"
+version = "0.1.0"
+description = "Audit tabular ML datasets for leakage, duplicates, label noise and imbalance before you train."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Sadia Samia" }]
+keywords = ["machine-learning", "data-quality", "data-leakage", "label-noise", "cleanlab", "audit"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pandas>=2.0",
+    "numpy>=1.24",
+    "scikit-learn>=1.3",
+    "cleanlab>=2.5",
+    "typer>=0.12",
+    "rich>=13.0",
+    "jinja2>=3.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5", "build", "twine", "pyarrow"]
+
+[project.scripts]
+tabaudit = "tabaudit.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/sadiasamia121912/tabaudit"
+Issues = "https://github.com/sadiasamia121912/tabaudit/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"tabaudit.report" = ["*.html"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "RUF", "SIM"]
+ignore = [
+    "B008",   # typer.Option() in defaults is the documented Typer idiom
+    "E501",   # formatter owns line length
+    "RUF001", "RUF002", "RUF003",  # we print unicode glyphs (×, →) on purpose
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tabaudit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tabaudit-0.1.0/src/tabaudit/__init__.py

@@ -0,0 +1,8 @@
+"""tabaudit — audit tabular ML datasets before you train."""
+
+__version__ = "0.1.0"
+
+from tabaudit.audit import run_audit
+from tabaudit.findings import AuditReport, Finding, Severity
+
+__all__ = ["AuditReport", "Finding", "Severity", "__version__", "run_audit"]

tabaudit-0.1.0/src/tabaudit/audit.py

@@ -0,0 +1,102 @@
+"""Orchestrates loading, task inference and running every registered check."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterable
+from pathlib import Path
+
+import pandas as pd
+
+from tabaudit import __version__
+from tabaudit.checks import REGISTRY
+from tabaudit.context import AuditContext
+from tabaudit.findings import AuditReport, CheckRun, DatasetSummary, Finding
+from tabaudit.loader import dtype_kinds, infer_task, load_table
+
+ProgressFn = Callable[[str, str], None]  # (check_name, status) -> None
+
+
+def run_audit(
+    data: str | Path | pd.DataFrame,
+    target: str | None = None,
+    test: str | Path | pd.DataFrame | None = None,
+    checks: Iterable[str] | None = None,
+    max_rows: int = 50_000,
+    random_state: int = 42,
+    on_progress: ProgressFn | None = None,
+) -> AuditReport:
+    """Audit a dataset and return an :class:`AuditReport`.
+
+    Parameters
+    ----------
+    data:    path to CSV/Parquet/… or a DataFrame.
+    target:  name of the label column (omit for unsupervised checks only).
+    test:    optional held-out set, used to detect train/test contamination.
+    checks:  subset of check names to run (default: all).
+    """
+    df, path = (
+        (data, "<DataFrame>") if isinstance(data, pd.DataFrame) else (load_table(data), str(data))
+    )
+    test_df, test_path = (None, None)
+    if test is not None:
+        test_df, test_path = (
+            (test, "<DataFrame>")
+            if isinstance(test, pd.DataFrame)
+            else (load_table(test), str(test))
+        )
+
+    if target is not None and target not in df.columns:
+        close = [c for c in df.columns if c.lower() == target.lower()]
+        hint = f" Did you mean '{close[0]}'?" if close else ""
+        raise KeyError(f"Target column '{target}' not found.{hint}")
+
+    task = infer_task(df[target]) if target else "unsupervised"
+    n_classes = (
+        int(df[target].nunique(dropna=True)) if target and task == "classification" else None
+    )
+
+    ctx = AuditContext(
+        df=df,
+        target=target,
+        task=task,
+        test_df=test_df,
+        max_rows=max_rows,
+        random_state=random_state,
+    )
+    selected = list(checks) if checks else list(REGISTRY)
+    unknown = [c for c in selected if c not in REGISTRY]
+    if unknown:
+        raise ValueError(f"Unknown check(s): {unknown}. Available: {list(REGISTRY)}")
+
+    findings: list[Finding] = []
+    runs: list[CheckRun] = []
+    for name in selected:
+        fn = REGISTRY[name]
+        if on_progress:
+            on_progress(name, "running")
+        t0 = time.perf_counter()
+        try:
+            out = fn(ctx)
+            findings.extend(out)
+            runs.append(CheckRun(name, "ok", time.perf_counter() - t0, len(out)))
+        except Exception as exc:
+            runs.append(
+                CheckRun(name, "error", time.perf_counter() - t0, 0, f"{type(exc).__name__}: {exc}")
+            )
+        if on_progress:
+            on_progress(name, runs[-1].status)
+
+    summary = DatasetSummary(
+        path=path,
+        n_rows=len(df),
+        n_cols=int(df.shape[1]),
+        target=target,
+        task=task,
+        n_classes=n_classes,
+        test_path=test_path,
+        n_test_rows=len(test_df) if test_df is not None else None,
+        memory_mb=round(float(df.memory_usage(deep=True).sum()) / 1e6, 2),
+        dtypes=dtype_kinds(df),
+    )
+    return AuditReport(summary=summary, findings=findings, checks=runs, version=__version__)

tabaudit-0.1.0/src/tabaudit/checks/__init__.py

@@ -0,0 +1,22 @@
+"""Check registry. Each check is a callable (AuditContext) -> list[Finding]."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from tabaudit.checks import duplicates, imbalance, label_noise, leakage, schema
+from tabaudit.context import AuditContext
+from tabaudit.findings import Finding
+
+CheckFn = Callable[[AuditContext], list[Finding]]
+
+# Ordered: cheap structural checks first, model-based checks last.
+REGISTRY: dict[str, CheckFn] = {
+    "schema": schema.run,
+    "duplicates": duplicates.run,
+    "imbalance": imbalance.run,
+    "leakage": leakage.run,
+    "label_noise": label_noise.run,
+}
+
+__all__ = ["REGISTRY", "CheckFn"]