GoldenCheck

Moved. This repo has moved into the benzsevern/goldenmatch monorepo at packages/python/goldencheck (and packages/typescript/goldencheck)/. This repo is archived; new development happens in the monorepo.

GoldenCheck

Data validation that discovers rules from your data so you don't have to write them. Built by Ben Severn.

Every competitor makes you write rules first. GoldenCheck flips it: validate first, keep the rules you care about.

Why GoldenCheck?

Install

pip install goldencheck

With LLM boost support:

pip install goldencheck[llm]

With deep profiling & baseline support (scipy, numpy):

pip install goldencheck[baseline]

With semantic type inference for baseline (sentence-transformers):

pip install goldencheck[baseline,semantic]

JavaScript / TypeScript

npm install goldencheck

Edge-safe core (browsers, Cloudflare Workers, Vercel Edge):

import { scanData, TabularData } from "goldencheck/core";

Node.js (file reading, CLI, MCP):

import { readFile, scanData } from "goldencheck/node";

Quick Start

# 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

Learn baseline (one-time, deep analysis)

goldencheck baseline data.csv

Scan with drift detection (fast, uses saved baseline)

goldencheck scan new_data.csv

TypeScript Quick Start

// Scan an array of records (edge-safe — works anywhere)

import { scanData, TabularData, Severity } from "goldencheck";

const data = new TabularData([ { id: 1, email: "alice@example.com", age: 30, status: "active" }, { id: 2, email: "bob@test.com", age: -5, status: "inactive" }, { id: 3, email: "not-an-email", age: 25, status: "active" }, ]);

const { findings, profile } = scanData(data); for (const f of findings) { console.log([${f.severity === Severity.ERROR ? "ERROR" : "WARNING"}] ${f.column}: ${f.message}); }

// Scan a CSV file (Node.js)

import { readFile, scanData, applyConfidenceDowngrade, healthScore } from "goldencheck/node";

const data = readFile("data.csv"); const result = scanData(data, { domain: "healthcare" }); const findings = applyConfidenceDowngrade(result.findings, false);

// Health score const byCol = {}; for (const f of findings) { if (f.severity >= 2) { byCol[f.column] ??= { errors: 0, warnings: 0 }; byColf.column++; } } const { grade, points } = healthScore(byCol); console.log(Health: ${grade} (${points}/100));

// Validate against pinned rules

import { readFile, scanData, validateConfig, validateData } from "goldencheck/node"; import { readFileSync } from "node:fs"; import YAML from "yaml";

const config = validateConfig(YAML.parse(readFileSync("goldencheck.yml", "utf-8"))); const data = readFile("data.csv"); const findings = validateData(data, config);

// Create baseline and detect drift

import { readFile, createBaseline, serializeBaseline, scanData } from "goldencheck/node"; import { runDriftChecks, deserializeBaseline } from "goldencheck"; import { writeFileSync, readFileSync } from "node:fs";

// Learn baseline const data = readFile("reference.csv"); const baseline = createBaseline(data); writeFileSync("baseline.json", serializeBaseline(baseline));

// Later: detect drift const newData = readFile("production.csv"); const saved = deserializeBaseline(readFileSync("baseline.json", "utf-8")); const driftFindings = runDriftChecks(newData, saved);

// LLM-enhanced scanning (edge-safe)

import { scanData, TabularData, callLlm, parseLlmResponse, mergeLlmFindings, buildSampleBlocks } from "goldencheck";

const data = new TabularData(records); const result = scanData(data, { returnSample: true }); const blocks = buildSampleBlocks(result.sample, result.findings); const { text } = await callLlm("anthropic", JSON.stringify(blocks)); const llmResponse = parseLlmResponse(text); if (llmResponse) { const enhanced = mergeLlmFindings(result.findings, llmResponse); }

How It Works

1. SCAN     →  goldencheck data.csv

GoldenCheck profiles your data and discovers what "healthy" looks like

1. REVIEW → Interactive TUI shows findings sorted by severity Each finding has: description, affected rows, sample values

1. PIN → Press Space to promote findings into permanent rules Dismiss false positives — they won't come back

1. EXPORT → Press F2 to save rules to goldencheck.yml Human-readable YAML with your pinned rules

1. VALIDATE → goldencheck validate data.csv Enforce rules in CI with exit codes (0 = pass, 1 = fail)

What It Detects

Column-Level Profilers

Cross-Column Profilers

Baseline Deep Profiling & Drift Detection

Run goldencheck baseline once to build a statistical profile of healthy data. On every subsequent scan, GoldenCheck compares the new data against the saved baseline and reports drift across 13 check types:

The baseline is built using 6 techniques: statistical profiler (distributions, Benford's Law, entropy), constraint miner (functional dependencies, temporal orders), semantic type inferrer (embeddings + keywords), correlation analyzer (Pearson, Cramér's V), pattern grammar inducer, and confidence prior builder.

Domain Packs

Improve detection accuracy with domain-specific type definitions:

goldencheck scan data.csv --domain healthcare   # NPI, ICD, insurance, patient types

goldencheck scan data.csv --domain finance # accounts, routing, CUSIP, transactions goldencheck scan data.csv --domain ecommerce # SKUs, orders, tracking, products

Domain packs add semantic types that reduce false positives and improve classification for industry-specific data.

Schema Diff

Compare two versions of a data file:

goldencheck diff data.csv                  # compare against git HEAD

goldencheck diff old.csv new.csv # compare two files goldencheck diff data.csv --ref main # compare against a branch

Auto-Fix

Apply automated fixes to clean your data:

goldencheck fix data.csv                          # safe: trim, normalize, fix encoding

goldencheck fix data.csv --mode moderate # + standardize case goldencheck fix data.csv --mode aggressive --force # + coerce types goldencheck fix data.csv --dry-run # preview changes

Watch Mode

Continuously monitor a directory for data quality:

goldencheck watch data/ --interval 30        # re-scan every 30s

goldencheck watch data/ --exit-on error # CI mode: fail on first error

REST API

Run GoldenCheck as a microservice:

goldencheck serve --port 8000