Quick Start

Quick Start Guide

0. First-Time Setup (Optional)

Run the setup wizard to configure GPU, API keys, and database:

goldenmatch setup

This is optional — GoldenMatch works out of the box with CPU-safe mode.

1. Simplest Usage (Zero-Config)

Point GoldenMatch at a CSV and it figures out the rest:

goldenmatch dedupe customers.csv

GoldenMatch will:

1. Analyze your columns (detect names, emails, phones, etc.)
2. Pick appropriate scorers for each column type
3. Choose a blocking strategy
4. Show a gold-themed auto-config summary screen
5. Let you run immediately, adjust settings, or save for next time

Press F5 to run, E to edit config, or ? to see all keyboard shortcuts.

2. With a Config File

For full control, write a YAML config:

# config.yaml
matchkeys:
  - name: exact_email
    type: exact
    fields:
      - field: email
        transforms: [lowercase, strip]

  - name: fuzzy_name
    type: weighted
    threshold: 0.85
    fields:
      - field: name
        scorer: jaro_winkler
        weight: 1.0
        transforms: [lowercase, strip]

blocking:
  keys:
    - fields: [email]
      transforms: [lowercase]

goldenmatch dedupe customers.csv --config config.yaml --output-all --output-dir results/

3. Match Two Files

goldenmatch match new_leads.csv --against existing_customers.csv --config config.yaml --output-all

4. Database Sync

pip install goldenmatch[postgres]

goldenmatch sync \
  --table customers \
  --connection-string "postgresql://user:pass@localhost/mydb" \
  --config config.yaml

5. Boost Accuracy with LLM

pip install goldenmatch[llm]

# Set API key
export ANTHROPIC_API_KEY=sk-ant-...

# First run labels pairs with Claude (~$0.30), trains local model
goldenmatch dedupe products.csv --llm-boost

# Subsequent runs use saved model ($0)
goldenmatch dedupe products.csv --llm-boost

6. Remember Steward Decisions (Learning Memory, v1.6.0)

If you have humans reviewing borderline pairs, persist their decisions so the same correction never has to be made twice.

# add to your config
memory:
  enabled: true
  backend: sqlite
  path: .goldenmatch/memory.db
  reanchor: true
  dataset: customers

goldenmatch dedupe customers.csv --config goldenmatch.yml   # 1. produce review queue
goldenmatch review              --config goldenmatch.yml   # 2. steward decides
goldenmatch dedupe customers.csv --config goldenmatch.yml   # 3. corrections apply
# > Memory: 12 corrections applied, 0 stale, 0 stale-ambiguous, 0 unanchorable

Corrections re-anchor across row reorders via record_hash. After 10+ corrections accumulate against a matchkey, goldenmatch memory learn adjusts that matchkey's threshold automatically. See Learning-Memory for the full feature.

Output Files

With --output-all, GoldenMatch produces:

File	Contents
golden_records.csv	Merged canonical records
clusters.csv	Which records belong to which cluster
duplicates.csv	Records identified as duplicates
unique.csv	Records with no duplicates