Configuration

Configuration

GoldenMatch uses YAML config files with Pydantic validation. Every section is optional -- GoldenMatch auto-configures what you leave out.

Matchkeys

Three matchkey types:

Type	Description	Required Fields
exact	Binary match on transformed values	field, optional transforms
weighted	Weighted average of field scores	field, scorer, weight, threshold
probabilistic	Fellegi-Sunter log-likelihood ratios	field, scorer, optional levels

Transforms

Applied to field values before scoring.

Transform	Description
lowercase	Convert to lowercase
uppercase	Convert to uppercase
strip	Remove leading/trailing whitespace
strip_all	Remove all whitespace
soundex	Soundex phonetic encoding
metaphone	Metaphone phonetic encoding
digits_only	Keep only digits
alpha_only	Keep only letters
normalize_whitespace	Collapse multiple spaces
token_sort	Sort tokens alphabetically
first_token	First whitespace-delimited token
last_token	Last whitespace-delimited token
substring:start:end	Substring extraction
qgram:n	Q-gram tokenization
bloom_filter or bloom_filter:ngram:k:size	Bloom filter (for PPRL)

Scorers

Scorer	Description	Best For
exact	Binary 0/1 match	Email, phone, ID
jaro_winkler	Edit distance with prefix bonus	Names
levenshtein	Normalized Levenshtein distance	General strings
token_sort	Order-invariant token matching	Names, addresses
soundex_match	Phonetic match	Names
ensemble	max(jaro_winkler, token_sort, soundex)	Names with reordering
embedding	Cosine similarity of embeddings	Semantic matching
record_embedding	Concatenated multi-field embeddings	Cross-field semantic
dice	Dice coefficient on bloom filters	PPRL
jaccard	Jaccard similarity on bloom filters	PPRL

Cross-encoder reranking

Add rerank: true to a weighted matchkey to re-score borderline pairs with a cross-encoder model:

matchkeys:
  - name: fuzzy_name
    type: weighted
    threshold: 0.85
    rerank: true
    rerank_band: 0.1       # pairs within threshold +/- 0.1 get reranked
    rerank_model: cross-encoder/ms-marco-MiniLM-L-6-v2

Golden rules

Five merge strategies for building canonical records:

Strategy	Description
most_complete	Pick value with fewest nulls
majority_vote	Most common value across cluster members
source_priority	Prefer values from specified sources (requires source_priority list)
most_recent	Latest value by date (requires date_column)
first_non_null	First non-null value encountered

Set a default strategy and override per field:

golden_rules:
  default_strategy: most_complete
  field_rules:
    email: { strategy: majority_vote }
    name: { strategy: source_priority, source_priority: [crm, erp] }

Validation

validation:
  auto_fix: true
  rules:
    - column: email
      rule_type: regex
      params: { pattern: "^.+@.+\\..+$" }
      action: flag
    - column: name
      rule_type: not_null
      action: quarantine
    - column: zip
      rule_type: min_length
      params: { length: 5 }
      action: null

Rule types: regex, min_length, max_length, not_null, in_set, format. Actions: flag (mark but keep), null (set to null), quarantine (remove from matching).

Programmatic config

import goldenmatch as gm

config = gm.GoldenMatchConfig(
    matchkeys=[
        gm.MatchkeyConfig(name="exact_email", type="exact",
            fields=[gm.MatchkeyField(field="email", transforms=["lowercase"])]),
        gm.MatchkeyConfig(name="fuzzy_name", type="weighted", threshold=0.85,
            fields=[
                gm.MatchkeyField(field="name", scorer="jaro_winkler", weight=0.7),
                gm.MatchkeyField(field="zip", scorer="exact", weight=0.3),
            ]),
    ],
    blocking=gm.BlockingConfig(strategy="learned"),
    llm_scorer=gm.LLMScorerConfig(enabled=True, mode="cluster"),
    backend="ray",
)

result = gm.dedupe("data.csv", config=config)

Or auto-generate from data:

config = gm.auto_configure([("data.csv", "source")])