datasets-lint 0.1.0__tar.gz

datasets_lint-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - name: Install
+        run: uv pip install -e ".[dev]"
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Tests
+        run: uv run pytest --cov=datasets_lint --cov-report=term-missing
+
+  self-lint:
+    # dogfood: the linter must run cleanly on its own fixtures
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+      - name: Audit fixtures
+        run: |
+          uvx --from . datasets-lint run tests/fixtures/clean.jsonl --report clean.html
+          uvx --from . datasets-lint run tests/fixtures/dirty.jsonl --fail-on none --report dirty.html
+      - uses: actions/upload-artifact@v4
+        with:
+          name: self-lint-reports
+          path: "*.html"
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: Smoke-test the wheel in a clean venv
+        run: |
+          python -m venv /tmp/venv
+          /tmp/venv/bin/pip install dist/*.whl
+          /tmp/venv/bin/datasets-lint --version
+          /tmp/venv/bin/datasets-lint run tests/fixtures/dirty.jsonl --fail-on none
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

datasets_lint-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  id-token: write # trusted publishing to PyPI (no API token needed)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

datasets_lint-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.html
+!docs/**/*.html
+uv.lock
+.DS_Store

datasets_lint-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,7 @@
+- id: datasets-lint
+  name: datasets-lint
+  description: Audit datasets for duplicates, PII and distribution problems
+  entry: datasets-lint
+  language: python
+  pass_filenames: true
+  args: ["run", "--fail-on", "error"]

datasets_lint-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing
+
+Thanks for helping! This project is built to be contributed to: every check is a
+single small file, and the plugin API is intentionally tiny.
+
+## Setup
+
+```console
+git clone https://github.com/horizonbymuneeb/datasets-lint
+cd datasets-lint
+uv venv && uv pip install -e ".[dev]"
+pytest
+ruff check . && ruff format .
+```
+
+No GPU, no API keys, no network needed for tests.
+
+## Add a check (the main way to contribute)
+
+1. Copy an existing check, e.g. `src/datasets_lint/checks/stats.py`.
+2. Implement `run(self, ds: Dataset, ctx: Context) -> CheckResult`.
+   - read data via `ds.texts()` or `ds.rows` (already sampled)
+   - read thresholds via `ctx.threshold(self.id, "name", default)`
+   - return `severity`, a one-line `summary`, numeric `metrics`, and up to ~50 `Finding`s
+   - **never** put raw PII in `message` — use `datasets_lint.checks.pii.redact`
+3. Register it in `src/datasets_lint/checks/__init__.py`.
+4. Add a tiny fixture under `tests/fixtures/` and a test in `tests/test_checks.py`.
+5. Document the id, what it finds and its default threshold in `README.md`.
+
+That's it — a reviewable PR of ~100 lines.
+
+## Check design rules
+
+- **Deterministic**: seed everything; the same input must give the same report.
+- **Bounded**: cap findings and any quadratic work; sample if needed.
+- **Fast**: a check should stay under ~10 s for 100k rows on 4 vCPUs.
+- **Honest**: if a metric is an estimate, say so in the `summary` or `metrics` key name.
+- **Actionable**: the finding message should tell the user what to do, not just what is wrong.
+
+## Ideas that are not built yet
+
+`contamination`, `leakage`, `langid`, `schema`, `toxicity`, `dedup-apply`,
+SARIF output, HuggingFace Hub input (`hf:org/name`), WASM playground.
+Open an issue before starting a big one so we don't duplicate work.
+
+## Commit style
+
+`check(dup): report cross-split clusters` — conventional-ish, no ceremony.

datasets_lint-0.1.0/LICENSE

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

datasets_lint-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: datasets-lint
+Version: 0.1.0
+Summary: ruff for training data: audit datasets for duplicates, PII, leakage and contamination
+Project-URL: Homepage, https://github.com/horizonbymuneeb/datasets-lint
+Project-URL: Issues, https://github.com/horizonbymuneeb/datasets-lint/issues
+Author: datasets-lint contributors
+License: MIT
+License-File: LICENSE
+Keywords: data-quality,datasets,deduplication,linter,llm,machine-learning,pii
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: datasketch>=1.6
+Requires-Dist: jinja2>=3.1
+Requires-Dist: polars>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: hf
+Requires-Dist: datasets>=2.18; extra == 'hf'
+Provides-Extra: ner
+Requires-Dist: spacy>=3.7; extra == 'ner'
+Description-Content-Type: text/markdown
+
+# datasets-lint
+
+**ruff for training data.** Audit a dataset for duplicates, PII, distribution problems and
+eval-set contamination — offline, on CPU, in one command, with a CI-friendly exit code.
+
+```console
+$ datasets-lint run train.jsonl --report out.html
+datasets-lint 0.1.0  ·  train.jsonl
+  120,000 rows audited (of 120,000, seed 0)  ·  text=text  label=label
+
+  ✓ stats      0.42s   120,000 rows · 0.00% empty · worst column 0.0% null
+  ✗ dup       12.10s   18.20% near-duplicate (4,211 clusters), 12.00% exact
+  ✗ pii        0.91s   0.41% of rows contain PII (email 487, phone 12, api_key 1)
+
+  verdict: error — 2 errors, 0 warnings, 1 ok · 13.43s
+  report → out.html
+```
+
+## Why
+
+![datasets-lint HTML report](docs/report.png)
+
+Every team that fine-tunes or publishes a dataset re-writes the same checks in a
+throwaway notebook: duplicates, PII, contamination. It is slow, inconsistent, and never
+runs in CI. `datasets-lint` packages it once:
+
+- **fast** — samples 100k rows by default and finishes in seconds, not hours
+- **offline** — no API keys, no cloud, no data leaves the machine
+- **CI-native** — `exit 1` on threshold breach, JSON output, baseline diffing
+- **readable** — one self-contained HTML report you can attach to a dataset card or a PR
+- **extensible** — one check = one file; the plugin API is ~20 lines
+
+## Install
+
+```console
+uvx datasets-lint --help        # run without installing
+# or
+pip install datasets-lint
+```
+
+## Usage
+
+```console
+datasets-lint run data.jsonl                       # text summary
+datasets-lint run data.parquet --report out.html   # single-file HTML report
+datasets-lint run train.jsonl test.jsonl --checks dup   # cross-split duplicate check
+datasets-lint run data.csv --json-out report.json --fail-on warn
+datasets-lint run data.jsonl --baseline prev.json  # did this PR make the data worse?
+datasets-lint checks                               # list checks
+```
+
+Supported inputs: `.jsonl`, `.ndjson`, `.json`, `.csv`, `.parquet`.
+
+Exit codes: `0` ok · `1` threshold breached · `2` usage/input error.
+
+## Checks
+
+| id | what it finds | default severity |
+|---|---|---|
+| `stats` | empty rows, nulls, length percentiles, label balance | `error` if >1% empty |
+| `dup` | exact + near duplicates (MinHash/LSH), cross-file overlap | `error` if >2% near-dup |
+| `pii` | emails, phones, IPs, IBANs, SSNs, API keys (redacted) | `error` on secrets |
+| `contamination` | overlap with eval sets (GSM8K, MMLU, HumanEval) | _planned for v0.2_ |
+
+## Configuration
+
+`datasets-lint.toml` in the working directory (or `--config path`):
+
+```toml
+[defaults]
+sample = 100000
+seed = 0
+fail_on = "error"          # none | warn | error
+
+[checks.dup]
+threshold = 0.9            # Jaccard threshold for near-duplicates
+num_perm = 64
+shingle_size = 5
+max_near_dup_pct = 2.0
+
+[checks.pii]
+max_error_findings_pct = 0.1
+max_warn_findings_pct = 5.0
+
+[checks.stats]
+max_empty_pct = 1.0
+max_null_pct = 50.0
+min_label_pct = 1.0
+```
+
+## Writing a check
+
+```python
+# src/datasets_lint/checks/short.py
+from datasets_lint.checks.base import Check, Context
+from datasets_lint.dataset import Dataset
+from datasets_lint.result import CheckResult, Severity
+
+
+class ShortRowsCheck(Check):
+    id = "short"
+    title = "Short rows"
+    description = "Flags texts under N characters."
+
+    def run(self, ds: Dataset, ctx: Context) -> CheckResult:
+        limit = ctx.threshold(self.id, "min_chars", 20)
+        bad = [i for i, t in ds.texts() if 0 < len(t) < limit]
+        pct = round(100 * len(bad) / max(ds.audited_rows, 1), 2)
+        return CheckResult(
+            check_id=self.id,
+            title=self.title,
+            severity=Severity.WARN if bad else Severity.OK,
+            summary=f"{pct}% of rows are shorter than {limit} chars",
+            metrics={"short_pct": pct},
+            findings=[],  # add Finding(...) entries for samples
+        )
+```
+
+Register it in `src/datasets_lint/checks/__init__.py`. Add a fixture and a test — that's it.
+
+## License
+
+MIT

datasets_lint-0.1.0/README.md

@@ -0,0 +1,123 @@
+# datasets-lint
+
+**ruff for training data.** Audit a dataset for duplicates, PII, distribution problems and
+eval-set contamination — offline, on CPU, in one command, with a CI-friendly exit code.
+
+```console
+$ datasets-lint run train.jsonl --report out.html
+datasets-lint 0.1.0  ·  train.jsonl
+  120,000 rows audited (of 120,000, seed 0)  ·  text=text  label=label
+
+  ✓ stats      0.42s   120,000 rows · 0.00% empty · worst column 0.0% null
+  ✗ dup       12.10s   18.20% near-duplicate (4,211 clusters), 12.00% exact
+  ✗ pii        0.91s   0.41% of rows contain PII (email 487, phone 12, api_key 1)
+
+  verdict: error — 2 errors, 0 warnings, 1 ok · 13.43s
+  report → out.html
+```
+
+## Why
+
+![datasets-lint HTML report](docs/report.png)
+
+Every team that fine-tunes or publishes a dataset re-writes the same checks in a
+throwaway notebook: duplicates, PII, contamination. It is slow, inconsistent, and never
+runs in CI. `datasets-lint` packages it once:
+
+- **fast** — samples 100k rows by default and finishes in seconds, not hours
+- **offline** — no API keys, no cloud, no data leaves the machine
+- **CI-native** — `exit 1` on threshold breach, JSON output, baseline diffing
+- **readable** — one self-contained HTML report you can attach to a dataset card or a PR
+- **extensible** — one check = one file; the plugin API is ~20 lines
+
+## Install
+
+```console
+uvx datasets-lint --help        # run without installing
+# or
+pip install datasets-lint
+```
+
+## Usage
+
+```console
+datasets-lint run data.jsonl                       # text summary
+datasets-lint run data.parquet --report out.html   # single-file HTML report
+datasets-lint run train.jsonl test.jsonl --checks dup   # cross-split duplicate check
+datasets-lint run data.csv --json-out report.json --fail-on warn
+datasets-lint run data.jsonl --baseline prev.json  # did this PR make the data worse?
+datasets-lint checks                               # list checks
+```
+
+Supported inputs: `.jsonl`, `.ndjson`, `.json`, `.csv`, `.parquet`.
+
+Exit codes: `0` ok · `1` threshold breached · `2` usage/input error.
+
+## Checks
+
+| id | what it finds | default severity |
+|---|---|---|
+| `stats` | empty rows, nulls, length percentiles, label balance | `error` if >1% empty |
+| `dup` | exact + near duplicates (MinHash/LSH), cross-file overlap | `error` if >2% near-dup |
+| `pii` | emails, phones, IPs, IBANs, SSNs, API keys (redacted) | `error` on secrets |
+| `contamination` | overlap with eval sets (GSM8K, MMLU, HumanEval) | _planned for v0.2_ |
+
+## Configuration
+
+`datasets-lint.toml` in the working directory (or `--config path`):
+
+```toml
+[defaults]
+sample = 100000
+seed = 0
+fail_on = "error"          # none | warn | error
+
+[checks.dup]
+threshold = 0.9            # Jaccard threshold for near-duplicates
+num_perm = 64
+shingle_size = 5
+max_near_dup_pct = 2.0
+
+[checks.pii]
+max_error_findings_pct = 0.1
+max_warn_findings_pct = 5.0
+
+[checks.stats]
+max_empty_pct = 1.0
+max_null_pct = 50.0
+min_label_pct = 1.0
+```
+
+## Writing a check
+
+```python
+# src/datasets_lint/checks/short.py
+from datasets_lint.checks.base import Check, Context
+from datasets_lint.dataset import Dataset
+from datasets_lint.result import CheckResult, Severity
+
+
+class ShortRowsCheck(Check):
+    id = "short"
+    title = "Short rows"
+    description = "Flags texts under N characters."
+
+    def run(self, ds: Dataset, ctx: Context) -> CheckResult:
+        limit = ctx.threshold(self.id, "min_chars", 20)
+        bad = [i for i, t in ds.texts() if 0 < len(t) < limit]
+        pct = round(100 * len(bad) / max(ds.audited_rows, 1), 2)
+        return CheckResult(
+            check_id=self.id,
+            title=self.title,
+            severity=Severity.WARN if bad else Severity.OK,
+            summary=f"{pct}% of rows are shorter than {limit} chars",
+            metrics={"short_pct": pct},
+            findings=[],  # add Finding(...) entries for samples
+        )
+```
+
+Register it in `src/datasets_lint/checks/__init__.py`. Add a fixture and a test — that's it.
+
+## License
+
+MIT

datasets_lint-0.1.0/ROADMAP.md

@@ -0,0 +1,173 @@
+# datasets-lint — Roadmap & Build Plan
+
+> `ruff` for training data. A fast, CI-friendly linter that audits a dataset for
+> duplicates, PII, label leakage, contamination and distribution problems, then
+> emits a JSON + HTML report and a non-zero exit code when thresholds are breached.
+
+**Status:** v0.1 core built — contamination + launch pending · **License:** MIT · **Stack:** Python 3.10+ (uv, polars, datasketch, jinja2)
+
+---
+
+## 1. Problem
+
+Before fine-tuning or publishing a dataset, people hand-roll the same checks in
+throwaway notebooks:
+
+- exact/near-duplicate rows (inflate loss, leak eval answers)
+- PII (emails, phones, keys) that must not ship
+- train/test contamination against MMLU / GSM8K / HumanEval
+- label leakage (target encoded in a feature)
+- class imbalance, length outliers, empty/near-empty rows
+
+Nothing packaged, nothing CI-able, nothing that produces a report a reviewer can read.
+`datasets-lint` is that tool.
+
+## 2. Non-goals (v0.1)
+
+- No model training, no GPU, no LLM judges (must run offline on a laptop)
+- No dataset hosting/versioning (we read local files + HF `datasets`)
+- No automatic "fixing" of data — we report, the user decides
+- No web UI/server in v1 (static HTML report only)
+
+## 3. Success criteria
+
+| Metric | Target |
+|---|---|
+| 100k-row JSONL audit (4 vCPU) | < 60 s, < 2 GB RSS |
+| Checks shipped in v0.1 | 4 (`stats`, `dup`, `pii`, `contamination`) |
+| Test coverage of core | ≥ 85% |
+| Contributor on-ramp | one new check = one file + one fixture |
+| Install | `uvx datasets-lint` works with zero config |
+
+---
+
+## 4. Phases
+
+### Phase 0 — Skeleton (½ day)
+- [x] Repo init, MIT license, `.gitignore`, README with the one-command demo
+- [x] `pyproject.toml` (hatchling, src-layout, `console_scripts: datasets-lint`)
+- [x] `uv sync`, ruff + pytest config
+- **Exit:** `uv run datasets-lint --help` prints help.
+
+### Phase 1 — Core engine (1 day)
+- [x] `Dataset` loader: `.jsonl`, `.csv`, `.parquet` (HF `datasets` input is backlog)
+- [x] Plugin API:
+      `class Check(Protocol): id, name, run(ds, ctx) -> CheckResult`
+- [x] `CheckResult` = severity, summary, metrics dict, findings (capped sample)
+- [x] Registry + config file `datasets-lint.toml` (thresholds, ignore rules)
+- [x] CLI: `datasets-lint run PATH [--checks ...] [--sample N] [--fail-on error]`
+- **Exit:** two dummy checks run end-to-end and print a text summary.
+
+### Phase 2 — First real checks (2–3 days)
+- [x] `stats`: row count, nulls, token-length histogram, class balance, empty rows
+- [x] `dup`: exact hash + MinHash/LSH near-dup, cluster report, % duplicated
+- [x] `pii`: regex pack (email, phone, IBAN, IP, API-key shapes) + optional
+      small NER via `[ner]` extra; findings redacted in report
+- **Exit:** on a 50k sample of a public dataset, `dup` and `pii` produce
+  plausible numbers in < 30 s.
+
+### Phase 3 — Differentiator: contamination (2 days)
+- [ ] Bundled mini eval-set fingerprints (GSM8K, MMLU sample, HumanEval) as n-gram
+      sketches, downloaded on demand and cached
+- [ ] `contamination`: n-gram overlap + MinHash match, per-eval-set hit rate
+- [ ] Clear verdict: "3.1% of rows overlap GSM8K (threshold 1%)"
+- **Exit:** a known-contaminated public dataset is correctly flagged; a clean one is not.
+
+### Phase 4 — Reports (1–2 days)
+- [x] JSON schema (stable, versioned) for machine consumption
+- [x] HTML report via jinja2: summary cards, per-check sections, sample findings,
+      histogram charts (inline SVG, no JS deps)
+- [x] `--report out.html`, `--format json|text|html`
+- [x] `--baseline prev.json` diff mode (did this PR make the data worse?)
+- **Exit:** report opens standalone, looks good, includes exit-code rationale.
+
+### Phase 5 — Packaging & distribution (1 day)
+- [x] `uv build` → sdist + wheel; install into a clean venv and run the CLI
+- [x] Extras: `[ner]`, `[hf]`, `[dev]`
+- [ ] TestPyPI dry run → PyPI publish (Trusted Publishing via GitHub OIDC on tag)
+- [ ] GitHub Action (`action.yml`): runs the linter, uploads report as artifact,
+      posts a PR comment
+- [ ] pre-commit hook definition
+- **Exit:** `uvx datasets-lint run x.jsonl` works from a clean machine.
+
+### Phase 6 — Launch (1 day)
+- [ ] README: problem → 30-second demo → GIF of the HTML report → install → checks table
+- [ ] `CONTRIBUTING.md` + `docs/writing-a-check.md` (10-line check example)
+- [ ] 5–8 `good first issue` entries (one per missing check)
+- [ ] CI matrix: Python 3.10–3.13, ruff, pytest, self-lint a fixture dataset
+- [ ] Show HN / r/MachineLearning / HF forum post draft with real numbers
+- **Exit:** a stranger can add a check in < 30 minutes using only the docs.
+
+---
+
+## 5. Repo layout
+
+```
+datasets-lint/
+├── pyproject.toml
+├── README.md  ROADMAP.md  CONTRIBUTING.md  LICENSE
+├── action.yml                      # GitHub Action
+├── .pre-commit-hooks.yaml
+├── src/datasets_lint/
+│   ├── cli.py
+│   ├── dataset.py                  # loaders + sampling
+│   ├── config.py                   # datasets-lint.toml
+│   ├── registry.py                 # plugin discovery
+│   ├── result.py                   # CheckResult, Severity, Report
+│   ├── checks/{stats,dup,pii,contamination}.py
+│   └── report/{json_out.py,html_out.py,templates/report.html.j2}
+├── tests/{test_cli.py,test_checks/,fixtures/*.jsonl}
+└── .github/workflows/{ci.yml,publish.yml}
+```
+
+## 6. Key design decisions
+
+| Decision | Choice | Why |
+|---|---|---|
+| Data engine | `polars` (+ `pyarrow`) | fast on CPU, low RAM, lazy scans |
+| Near-dup | `datasketch` MinHashLSH | battle-tested, tunable threshold |
+| Sampling | default cap 100k rows, seeded | keeps CI fast and deterministic |
+| Plugin model | plain Python protocol + registry | no entrypoint magic needed for v1 |
+| Reports | jinja2 + inline SVG | single-file, no CDN, offline |
+| Findings cap | 50 samples per check in report | avoid 500 MB HTML files |
+| Exit codes | 0 ok, 1 threshold breach, 2 usage error | CI-friendly |
+
+## 7. Risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Near-dup too slow on big files | sampling + LSH band tuning; `--sample` flag; benchmark in CI |
+| Eval-set fingerprints are large | store 5-gram sketches, not text; lazy download + cache |
+| PII regex false positives | severity `warn` by default, `error` only for high-confidence patterns |
+| Scope creep (10 checks) | v0.1 ships 4; everything else is a `good first issue` |
+| Name collision later | `datasets-lint` verified free on PyPI (2026-10-31) |
+
+## 8. Day-by-day (compressed)
+
+| Day | Deliverable |
+|---|---|
+| 1 | Phase 0 + Phase 1: skeleton, loader, plugin API, CLI |
+| 2 | `stats` + `dup` working, tests |
+| 3 | `pii`, config file, sampling, benchmarks |
+| 4–5 | `contamination` + eval-set fingerprints |
+| 6 | HTML/JSON reports + baseline diff |
+| 7 | Packaging, TestPyPI, GitHub Action, pre-commit |
+| 8 | Docs, launch README, good-first-issues, publish v0.1.0 |
+
+## 9. Backlog after v0.1
+
+`leakage` (target in features) · `dedup-apply` (emit cleaned file) · `langid` mix check ·
+`toxicity` (small model) · `schema` check · SARIF output for GitHub code scanning ·
+HF Hub integration (`datasets-lint run hf:org/name`) · Rust/`polars` fast path ·
+web playground (WASM) · leaderboard of "lint scores" for popular public datasets.
+
+---
+
+## 10. Definition of done for v0.1.0
+
+1. `uvx datasets-lint run data.jsonl --report out.html` works on a clean machine
+2. 4 checks, documented, each with tests and a fixture
+3. HTML + JSON report, exit codes correct
+4. Published on PyPI, tag `v0.1.0`, GitHub Action usable
+5. README has real benchmark numbers from this VM (4 vCPU / 8 GB)
+6. ≥ 5 `good first issue`s open