goldencheck 0.1.0__tar.gz

goldencheck-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: benzsevern

goldencheck-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,41 @@
+name: Bug Report
+description: Report a bug in GoldenCheck
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: A clear description of what happened
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: |
+        1. Run `goldencheck ...`
+        2. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: GoldenCheck version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12"
+    validations:
+      required: true

goldencheck-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Discussions
+    url: https://github.com/benzsevern/goldencheck/discussions
+    about: Ask questions and share ideas

goldencheck-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,23 @@
+name: Feature Request
+description: Suggest a new feature
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem are you trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you like this to work?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What else have you tried?

goldencheck-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## What
+
+Brief description of the change.
+
+## Why
+
+What problem does this solve?
+
+## How
+
+Key implementation details.
+
+## Testing
+
+- [ ] Tests added/updated
+- [ ] `pytest` passes
+- [ ] `ruff check .` passes

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

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

goldencheck-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --tb=short -v
+      - run: ruff check .

goldencheck-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.csv
+*.parquet
+*.xlsx
+goldencheck.yml
+.ruff_cache/
+.testing/

goldencheck-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+* Trolling, insulting or derogatory comments, and personal attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to **benzsevern@gmail.com**. All complaints will be reviewed and
+investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

goldencheck-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to GoldenCheck
+
+Thanks for your interest in improving GoldenCheck!
+
+## Getting Started
+
+```bash
+git clone https://github.com/benzsevern/goldencheck.git
+cd goldencheck
+pip install -e ".[dev]"
+pytest
+```
+
+## Ways to Contribute
+
+- **Bug reports** -- open an issue with reproduction steps
+- **Feature requests** -- describe the problem you're solving
+- **Code** -- fork, branch, PR. All PRs need tests.
+- **Documentation** -- README, docstrings, examples
+
+## Development Standards
+
+- **Python 3.11+** with type hints
+- **Polars** for all data operations (not pandas)
+- **Ruff** for linting: `ruff check .` (100 char line length)
+- **Pytest** for testing: `pytest --tb=short`
+- **Conventional commits**: `feat:`, `fix:`, `docs:`, `test:`, `chore:`
+
+## Architecture
+
+```
+goldencheck/
+├── cli/         # Typer CLI entry points
+├── profilers/   # Column-level profilers (one per type)
+├── relations/   # Cross-column profilers
+├── engine/      # Scanner, validator, reader, sampler
+├── config/      # YAML config schema, loader, writer
+├── tui/         # Textual TUI
+├── reporters/   # Rich, JSON, CI output
+└── models/      # Finding, Profile data models
+```
+
+Each profiler is independent. Add a new one by:
+1. Create `goldencheck/profilers/your_profiler.py` extending `BaseProfiler`
+2. Add tests in `tests/profilers/test_your_profiler.py`
+3. Register it in `goldencheck/engine/scanner.py`
+
+## Pull Requests
+
+1. Fork and create a feature branch
+2. Write tests first (TDD)
+3. Run `pytest` and `ruff check .`
+4. Open a PR with a clear description
+5. One approval required to merge

goldencheck-0.1.0/LICENSE

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

goldencheck-0.1.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: goldencheck
+Version: 0.1.0
+Summary: Data validation that discovers rules from your data so you don't have to write them
+Project-URL: Homepage, https://github.com/benzsevern/goldencheck
+Project-URL: Repository, https://github.com/benzsevern/goldencheck
+Project-URL: Issues, https://github.com/benzsevern/goldencheck/issues
+Author-email: Ben Severn <benzsevern@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: csv,data-checks,data-profiling,data-quality,data-validation,llm,parquet,profiling,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: polars>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=1.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.30; extra == 'llm'
+Requires-Dist: openai>=1.30; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# GoldenCheck
+
+Data validation that discovers rules from your data so you don't have to write them.
+
+[![PyPI](https://img.shields.io/pypi/v/goldencheck)](https://pypi.org/project/goldencheck/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)
+[![Tests](https://img.shields.io/badge/tests-103%20passing-brightgreen)](https://github.com/benzsevern/goldencheck)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> Every competitor makes you write rules first. GoldenCheck flips it: **validate first, keep the rules you care about.**
+
+## Why GoldenCheck?
+
+|  | GoldenCheck | Great Expectations | Pandera | Pointblank |
+|---|---|---|---|---|
+| Rules | **Discovered from data** | Written by hand | Written by hand | Written by hand |
+| Config | **Zero to start** | Heavy YAML/Python setup | Decorators/schemas | YAML/Python |
+| Interface | **CLI + interactive TUI** | HTML reports | Exceptions | HTML/notebook |
+| Learning curve | **One command** | Hours/days | Moderate | Moderate |
+| LLM enhancement | **Yes ($0.01/scan)** | No | No | No |
+
+## Install
+
+```bash
+pip install goldencheck
+```
+
+With LLM boost support:
+
+```bash
+pip install goldencheck[llm]
+```
+
+## Quick Start
+
+```bash
+# Scan a file — discovers issues, launches interactive TUI
+goldencheck data.csv
+
+# CLI-only output (no TUI)
+goldencheck data.csv --no-tui
+
+# With LLM enhancement (requires API key)
+goldencheck data.csv --llm-boost --no-tui
+
+# Validate against saved rules (for CI/pipelines)
+goldencheck validate data.csv
+
+# JSON output for CI integration
+goldencheck data.csv --no-tui --json
+```
+
+## How It Works
+
+```
+1. SCAN     →  goldencheck data.csv
+                GoldenCheck profiles your data and discovers what "healthy" looks like
+
+2. REVIEW   →  Interactive TUI shows findings sorted by severity
+                Each finding has: description, affected rows, sample values
+
+3. PIN      →  Press Space to promote findings into permanent rules
+                Dismiss false positives — they won't come back
+
+4. EXPORT   →  Press F2 to save rules to goldencheck.yml
+                Human-readable YAML with your pinned rules
+
+5. VALIDATE →  goldencheck validate data.csv
+                Enforce rules in CI with exit codes (0 = pass, 1 = fail)
+```
+
+## What It Detects
+
+### Column-Level Profilers
+
+| Profiler | What It Catches | Example |
+|----------|----------------|---------|
+| **Type inference** | String columns that are actually numeric | "Column `age` is string but 98% are integer" |
+| **Nullability** | Required vs. optional columns | "0 nulls across 50k rows — likely required" |
+| **Uniqueness** | Primary key candidates, near-duplicates | "100% unique — likely primary key" |
+| **Format detection** | Emails, phones, URLs, dates | "94% email format, 6% malformed" |
+| **Range & distribution** | Outliers, min/max bounds | "3 rows have values >10,000" |
+| **Cardinality** | Low-cardinality enum suggestions | "4 unique values — possible enum" |
+| **Pattern consistency** | Mixed formats within a column | "3 phone formats detected" |
+
+### Cross-Column Profilers
+
+| Profiler | What It Catches |
+|----------|----------------|
+| **Temporal ordering** | start_date > end_date violations |
+| **Null correlation** | Columns that are null together (e.g., address + city + zip) |
+
+## LLM Boost
+
+Add `--llm-boost` to enhance profiler findings with LLM intelligence. The LLM receives a representative sample of your data and:
+
+1. **Finds issues profilers miss** — semantic understanding (e.g., "12345" in a name column)
+2. **Upgrades severity** — knows "emails should be required" even if the profiler only says "INFO"
+3. **Discovers relationships** — identifies temporal ordering between columns like `signup_date` and `last_login`
+4. **Downgrades false positives** — "mixed phone formats are common, not an error"
+
+```bash
+# Using OpenAI
+export OPENAI_API_KEY=sk-...
+goldencheck data.csv --llm-boost --llm-provider openai --no-tui
+
+# Using Anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+goldencheck data.csv --llm-boost --no-tui
+```
+
+**Cost:** ~$0.01 per scan (one API call with representative samples, not per-row).
+
+**Budget control:**
+```bash
+export GOLDENCHECK_LLM_BUDGET=0.50  # max spend per scan in USD
+```
+
+## Configuration (goldencheck.yml)
+
+```yaml
+version: 1
+
+settings:
+  sample_size: 100000
+  fail_on: error
+
+columns:
+  email:
+    type: string
+    required: true
+    format: email
+    unique: true
+
+  age:
+    type: integer
+    range: [0, 120]
+
+  status:
+    type: string
+    enum: [active, inactive, pending, closed]
+
+relations:
+  - type: temporal_order
+    columns: [start_date, end_date]
+
+ignore:
+  - column: notes
+    check: nullability
+```
+
+Only pinned rules appear in this file — not every finding. The `ignore` list prevents dismissed findings from reappearing.
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `goldencheck <file>` | Scan and launch TUI |
+| `goldencheck scan <file>` | Explicit scan |
+| `goldencheck validate <file>` | Validate against goldencheck.yml |
+| `goldencheck review <file>` | Scan + validate, launch TUI |
+
+### Flags
+
+| Flag | Description |
+|------|-------------|
+| `--no-tui` | Print results to console |
+| `--json` | JSON output |
+| `--fail-on <level>` | Exit 1 on severity: `error` or `warning` |
+| `--llm-boost` | Enable LLM enhancement |
+| `--llm-provider <name>` | LLM provider: `anthropic` (default) or `openai` |
+| `--verbose` | Show info-level logs |
+| `--debug` | Show debug-level logs |
+| `--version` | Show version |
+
+## Benchmarks
+
+### Speed
+
+| Dataset | Time | Throughput |
+|---------|------|------------|
+| 1K rows | 0.05s | 19K rows/sec |
+| 10K rows | 0.23s | 43K rows/sec |
+| 100K rows | 2.29s | 44K rows/sec |
+| **1M rows** | **2.07s** | **482K rows/sec** |
+
+### Detection Accuracy
+
+| Mode | Column Recall | Cost |
+|------|--------------|------|
+| Profiler-only | 87% | $0 |
+| **With LLM Boost** | **100%** | ~$0.01 |
+
+Tested on a custom benchmark with 341 planted data quality issues across 9 categories.
+
+### Raha Benchmark Datasets
+
+| Dataset | Column Recall |
+|---------|--------------|
+| Flights (2,376 rows) | **100%** (4/4 columns) |
+| Beers (2,410 rows) | **80%** (4/5 columns) |
+
+## Tech Stack
+
+| Dependency | Purpose |
+|-----------|---------|
+| [Polars](https://pola.rs/) | All data operations |
+| [Typer](https://typer.tiangolo.com/) | CLI framework |
+| [Textual](https://textual.textualize.io/) | Interactive TUI |
+| [Rich](https://rich.readthedocs.io/) | CLI output formatting |
+| [Pydantic 2](https://docs.pydantic.dev/) | Config validation |
+
+**Optional:** [Anthropic SDK](https://docs.anthropic.com/) / [OpenAI SDK](https://platform.openai.com/) for LLM Boost
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+**From the maker of [GoldenMatch](https://github.com/benzsevern/goldenmatch)** — entity resolution toolkit.