---
layout: default
title: Home
nav_order: 1
---

# GoldenMatch

**Entity resolution that finds duplicates in your data so you don't have to define the rules yourself.**

> 🟡 **Now part of the Golden Suite monorepo.** This site documents GoldenMatch (entity resolution). The same repository hosts GoldenCheck (data quality), GoldenFlow (transforms), GoldenPipe (orchestrator), InferMap (schema mapping), the Rust SQL extensions, the dbt package, and the GitHub Action — plus a master MCP server (`goldensuite-mcp`), seven `ghcr.io` container images, and 12 drop-in Airflow DAGs. See the [repository README](https://github.com/benseverndev-oss/goldenmatch#readme) and [`examples/`](https://github.com/benseverndev-oss/goldenmatch/tree/main/examples) for the suite-wide picture.

[![PyPI](https://img.shields.io/pypi/v/goldenmatch?color=d4a017)](https://pypi.org/project/goldenmatch/)
[![Downloads](https://static.pepy.tech/badge/goldenmatch/month)](https://pepy.tech/projects/goldenmatch)
[![Tests](https://github.com/benseverndev-oss/goldenmatch/actions/workflows/ci.yml/badge.svg)](https://github.com/benseverndev-oss/goldenmatch/actions)
[![Python](https://img.shields.io/pypi/pyversions/goldenmatch)](https://pypi.org/project/goldenmatch/)
[![Coverage](https://img.shields.io/badge/coverage-72%25-yellow)](https://github.com/benseverndev-oss/goldenmatch)
[![Tests](https://img.shields.io/badge/tests-1300%2B%20passing-brightgreen)](https://github.com/benseverndev-oss/goldenmatch)

---

## What It Does

GoldenMatch takes messy records and figures out which ones refer to the same entity — without requiring you to hand-write matching rules.

```
INGEST → STANDARDIZE → BLOCK → SCORE → CLUSTER → GOLDEN RECORD
```

| Step | What Happens |
|------|-------------|
| **Ingest** | Load CSV, Excel, Parquet, or a DataFrame |
| **Standardize** | Normalize casing, whitespace, phonetic encoding |
| **Block** | Group candidates to avoid N^2 comparisons |
| **Score** | Fuzzy match (jaro-winkler, levenshtein, token sort) |
| **Cluster** | Union-Find with confidence scoring |
| **Golden** | Merge clusters into canonical records |

---

## Quick Install

```bash
pip install goldenmatch
```

```python
import goldenmatch as gm

result = gm.dedupe("customers.csv", exact=["email"], fuzzy={"name": 0.85})
print(f"{result.total_clusters} clusters, {result.match_rate:.0%} match rate")
result.golden.write_csv("golden_records.csv")
```

---

## Benchmarks

| Dataset | Records | Method | F1 | Time |
|---------|---------|--------|-----|------|
| DBLP-ACM (academic) | 4,910 | Fuzzy matching | **97.2%** | 2.1s |
| Abt-Buy (electronics) | 2,162 | Domain + LLM | **72.2%** | 4.2s |
| FEBRL4 (PPRL) | 10,000 | Auto-config bloom filters | **92.4%** | 14s |
| Synthetic | 100K | Fuzzy (name+zip) | -- | 12.8s |
| Synthetic | 1M | Exact dedupe | -- | 7.8s |

Scale: 7,823 records/sec on a laptop (fuzzy + exact + golden).

---

## 8 Ways to Use It

| Interface | Install | Best For |
|-----------|---------|----------|
| [Python API](python-api) | `pip install goldenmatch` | Notebooks, scripts, AI agents |
| [TypeScript / Node.js](typescript) | `npm install goldenmatch` | Edge runtimes, web apps, Node services |
| [CLI](cli) | Same package, 21 commands | Terminal workflows |
| [Interactive TUI](tui) | `goldenmatch tui` | Visual exploration |
| [PostgreSQL](sql-postgres) | [Pre-built .deb/.rpm](https://github.com/benseverndev-oss/goldenmatch-extensions/releases) | Production databases |
| [DuckDB](sql-duckdb) | `pip install goldenmatch-duckdb` | Analytics |
| [REST API / MCP](rest-api) | `goldenmatch serve` / `mcp-serve` | Microservices, AI assistants |
| [ER Agent (A2A)](agent) | `goldenmatch agent-serve` | AI-to-AI discovery, autonomous ER |

---

## Documentation

| Guide | Description |
|-------|-------------|
| [Installation](installation) | pip, apt, rpm, Docker, build from source |
| [Quick Start](quick-start) | First dedupe in 30 seconds |
| [Python API](python-api) | 101 exports: dedupe, match, score, explain, PPRL |
| [TypeScript API](typescript) | npm package with edge-safe core and Node entrypoint |
| [CLI Reference](cli) | 23 commands with examples |
| [Interactive TUI](tui) | 6-tab visual interface |
| [Configuration](configuration) | YAML config with matchkeys, blocking, golden rules |
| [Pipeline](pipeline) | 10-step pipeline architecture |
| [Blocking Strategies](blocking) | Static, learned, ANN blocking |
| [Scoring](scoring) | Fuzzy, exact, probabilistic, LLM scoring |
| [Domain Packs](domain-packs) | 7 built-in YAML rulebooks |
| [PPRL](pprl) | Privacy-preserving record linkage |
| [LLM Integration](llm) | LLM scorer, LLM clustering, budget tracking |
| [Learning Memory](learning-memory) | Persistent corrections + threshold learning (v1.6.0) |
| [Streaming & Incremental](streaming) | Real-time matching, append-only mode |
| [PostgreSQL Extension](sql-postgres) | 18 SQL functions, pipeline schema |
| [DuckDB Extension](sql-duckdb) | 12 Python UDFs |
| [REST API](rest-api) | HTTP endpoints, review queue |
| [MCP Server](mcp) | Claude Desktop integration |
| [Evaluation](evaluation) | Benchmarks, CI/CD quality gates, cluster comparison |
| [ER Agent](agent) | A2A + MCP autonomous agent, confidence gating |
| [Architecture](architecture) | Module map, code patterns |
| [Benchmarks](benchmarks) | Performance and accuracy numbers |

---

## Part of the Golden Suite

| Package | What It Does |
|---------|-------------|
| **[GoldenMatch](https://github.com/benseverndev-oss/goldenmatch)** | Entity resolution (this project) |
| **[GoldenCheck](https://github.com/benseverndev-oss/goldencheck)** | Data validation that discovers rules |
| **[goldenmatch-extensions](https://github.com/benseverndev-oss/goldenmatch-extensions)** | SQL extensions for Postgres + DuckDB |
| **[goldenmatch-duckdb](https://pypi.org/project/goldenmatch-duckdb/)** | DuckDB UDFs for entity resolution |
