goldenmatch 0.1.0

package/examples/02-match-two-datasets.ts

@@ -0,0 +1,48 @@
+/**
+ * Match records in a "target" dataset against a "reference" dataset.
+ * Useful for: incoming leads vs. CRM, transactions vs. customers, etc.
+ *
+ * Run: npx tsx examples/02-match-two-datasets.ts
+ */
+import { match } from "goldenmatch";
+
+// Reference dataset: known customers
+const customers = [
+  { id: "C001", name: "Acme Corp",     city: "Seattle",  phone: "555-1000" },
+  { id: "C002", name: "Globex Inc",    city: "Portland", phone: "555-2000" },
+  { id: "C003", name: "Initech LLC",   city: "Austin",   phone: "555-3000" },
+  { id: "C004", name: "Umbrella Co",   city: "Boston",   phone: "555-4000" },
+];
+
+// Target dataset: incoming leads (possibly dupes of customers, possibly new)
+const leads = [
+  { id: "L1", name: "ACME Corporation", city: "Seattle",  phone: "555-1000" },
+  { id: "L2", name: "Globex, Inc.",     city: "Portland", phone: "555-2000" },
+  { id: "L3", name: "Stark Industries", city: "New York", phone: "555-9000" },
+  { id: "L4", name: "Initech",          city: "Austin",   phone: "555-3000" },
+];
+
+const result = match(leads, customers, {
+  fuzzy: { name: 0.75 },
+  blocking: ["city"],
+  threshold: 0.75,
+});
+
+console.log(`Matched leads:   ${result.matched.length}`);
+console.log(`Unmatched leads: ${result.unmatched.length}\n`);
+
+console.log("Matched (likely existing customers):");
+for (const row of result.matched) {
+  console.log(" ", row);
+}
+
+console.log("\nUnmatched (likely new leads):");
+for (const row of result.unmatched) {
+  console.log(" ", row);
+}
+
+/**
+ * Python -> TS differences:
+ *   - Python `match()` returns a MatchResult with DataFrames; TS returns arrays.
+ *   - `result.stats` is a generic record; shape differs slightly across modes.
+ */

package/examples/03-csv-file-pipeline.ts

@@ -0,0 +1,62 @@
+/**
+ * CSV file pipeline: read CSV -> dedupe -> write golden records back to CSV.
+ *
+ * This example uses `goldenmatch/node` (the Node-only subpackage) for
+ * file I/O. The core `goldenmatch` package is edge-safe and doesn't
+ * import `node:fs`.
+ *
+ * Run: npx tsx examples/03-csv-file-pipeline.ts
+ *
+ * Prereq: a file `customers.csv` in the working directory. We create one
+ * inline for demo purposes.
+ */
+import { writeFileSync, unlinkSync } from "node:fs";
+import { dedupe } from "goldenmatch";
+import { readFile, writeCsv } from "goldenmatch/node";
+
+// --- Step 0: create a demo CSV (you'd skip this step in real life) ---
+const DEMO_PATH = "customers_demo.csv";
+const GOLDEN_PATH = "golden_demo.csv";
+writeFileSync(
+  DEMO_PATH,
+  [
+    "id,name,email,zip",
+    "1,John Smith,john@example.com,12345",
+    "2,Jon Smith,john@example.com,12345",
+    "3,Jane Doe,jane@example.com,54321",
+    "4,J. Smith,john@example.com,12345",
+    "5,Janet Doe,janet@example.com,54321",
+  ].join("\n"),
+);
+
+// --- Step 1: read the CSV (auto-coerces numbers, handles BOM) ---
+const rows = readFile(DEMO_PATH);
+console.log(`Read ${rows.length} rows from ${DEMO_PATH}`);
+
+// --- Step 2: dedupe ---
+const result = dedupe(rows, {
+  exact: ["email"],
+  fuzzy: { name: 0.8 },
+  blocking: ["zip"],
+  threshold: 0.8,
+});
+
+console.log(
+  `Found ${result.stats.totalClusters} clusters from ${result.stats.totalRecords} records`,
+);
+
+// --- Step 3: write golden records back to CSV ---
+writeCsv(GOLDEN_PATH, result.goldenRecords);
+console.log(`Wrote ${result.goldenRecords.length} golden records to ${GOLDEN_PATH}`);
+
+// Cleanup demo files
+unlinkSync(DEMO_PATH);
+unlinkSync(GOLDEN_PATH);
+
+/**
+ * `readFile()` auto-detects CSV vs JSON by extension. Use `readCsv()` /
+ * `readJson()` directly if you want to pass options (delimiter, encoding).
+ *
+ * `writeCsv()` serializes an array of objects; columns are inferred from
+ * the union of keys across all rows.
+ */

package/examples/04-string-scoring.ts

@@ -0,0 +1,63 @@
+/**
+ * String scoring: compare every scorer on the same string pairs.
+ *
+ * This is pedagogical — each scorer has different strengths:
+ *   - jaro_winkler: short strings, common-prefix bonus (great for names)
+ *   - levenshtein:  edit distance (typos)
+ *   - token_sort:   order-independent (word reordering)
+ *   - soundex_match: phonetic (Smith/Smyth)
+ *   - dice / jaccard: bigram/set overlap
+ *   - ensemble:     weighted combination (default for names)
+ *
+ * Run: npx tsx examples/04-string-scoring.ts
+ */
+import { scoreStrings } from "goldenmatch";
+
+const pairs: [string, string, string][] = [
+  ["John Smith",    "Jon Smith",        "typo / common name variant"],
+  ["John Smith",    "Smith, John",      "word reorder"],
+  ["Smith",         "Smyth",            "phonetic equivalent"],
+  ["Robert",        "Bob",              "nickname (no scorer handles well)"],
+  ["123 Main St",   "123 Main Street",  "abbreviation"],
+  ["apple inc",     "Apple, Inc.",      "punctuation/case noise"],
+  ["totally",       "different",        "no similarity"],
+];
+
+const scorers = [
+  "exact",
+  "jaro_winkler",
+  "levenshtein",
+  "token_sort",
+  "soundex_match",
+  "dice",
+  "jaccard",
+  "ensemble",
+];
+
+// Header
+const pad = (s: string, n: number) => s.padEnd(n);
+const colWidths = [28, 28, ...scorers.map(() => 14)];
+
+process.stdout.write(pad("A", colWidths[0]!));
+process.stdout.write(pad("B", colWidths[1]!));
+for (let i = 0; i < scorers.length; i++) {
+  process.stdout.write(pad(scorers[i]!, colWidths[i + 2]!));
+}
+process.stdout.write("\n");
+process.stdout.write("-".repeat(colWidths.reduce((a, b) => a + b, 0)) + "\n");
+
+for (const [a, b, _label] of pairs) {
+  process.stdout.write(pad(a, colWidths[0]!));
+  process.stdout.write(pad(b, colWidths[1]!));
+  for (let i = 0; i < scorers.length; i++) {
+    const score = scoreStrings(a, b, scorers[i]!);
+    process.stdout.write(pad(score.toFixed(2), colWidths[i + 2]!));
+  }
+  process.stdout.write("\n");
+}
+
+/**
+ * Expected: jaro_winkler typically wins on short names, token_sort crushes
+ * word-reorder cases, soundex_match catches Smith/Smyth, and ensemble is
+ * the most balanced default.
+ */

package/examples/05-custom-config.ts

@@ -0,0 +1,94 @@
+/**
+ * Build a full GoldenMatchConfig manually (matchkeys, standardization,
+ * blocking, golden rules). Save to YAML, reload, use it.
+ *
+ * Run: npx tsx examples/05-custom-config.ts
+ * Requires: `npm install yaml` (optional peer dep for YAML I/O).
+ */
+import { writeFileSync, unlinkSync } from "node:fs";
+import {
+  dedupe,
+  makeConfig,
+  makeMatchkeyConfig,
+  makeMatchkeyField,
+  makeBlockingConfig,
+  makeGoldenRulesConfig,
+} from "goldenmatch";
+import { loadConfigFile, writeConfigFile } from "goldenmatch/node";
+
+// Build config programmatically
+const config = makeConfig({
+  matchkeys: [
+    makeMatchkeyConfig({
+      name: "email_exact",
+      type: "exact",
+      fields: [makeMatchkeyField({ field: "email", transforms: ["lowercase", "strip"], scorer: "exact" })],
+    }),
+    makeMatchkeyConfig({
+      name: "identity",
+      type: "weighted",
+      threshold: 0.85,
+      fields: [
+        makeMatchkeyField({ field: "first_name", transforms: ["lowercase"], scorer: "jaro_winkler", weight: 0.3 }),
+        makeMatchkeyField({ field: "last_name",  transforms: ["lowercase"], scorer: "jaro_winkler", weight: 0.4 }),
+        makeMatchkeyField({ field: "phone",      transforms: ["digits_only"], scorer: "exact",     weight: 0.3 }),
+      ],
+    }),
+  ],
+  blocking: makeBlockingConfig({
+    strategy: "multi_pass",
+    keys: [{ fields: ["zip"], transforms: ["lowercase", "strip"] }],
+    passes: [
+      { fields: ["zip"],        transforms: ["lowercase", "strip"] },
+      { fields: ["last_name"],  transforms: ["soundex"] },
+    ],
+  }),
+  goldenRules: makeGoldenRulesConfig({
+    defaultStrategy: "most_complete",
+    fieldRules: {
+      email: { strategy: "first_non_null" },
+      phone: { strategy: "most_complete" },
+    },
+  }),
+  standardization: {
+    rules: {
+      email:      ["email"],
+      phone:      ["phone"],
+      first_name: ["strip", "name_proper"],
+      last_name:  ["strip", "name_proper"],
+    },
+  },
+  threshold: 0.85,
+});
+
+// Save to YAML (requires `yaml` peer dep)
+const YAML_PATH = "custom_config_demo.yml";
+try {
+  writeConfigFile(YAML_PATH, config);
+  console.log(`Wrote config to ${YAML_PATH}`);
+
+  const reloaded = loadConfigFile(YAML_PATH);
+  console.log(`Reloaded config has ${reloaded.matchkeys?.length ?? 0} matchkeys`);
+
+  unlinkSync(YAML_PATH);
+} catch (err) {
+  console.warn(`YAML save/load skipped: ${(err as Error).message}`);
+  console.warn("(install the `yaml` peer dep to enable: npm install yaml)");
+}
+
+// Use the config
+const rows = [
+  { id: 1, first_name: "john", last_name: "smith", email: "j@x.com",  phone: "555-123-4567", zip: "12345" },
+  { id: 2, first_name: "John", last_name: "Smyth", email: "J@X.COM",  phone: "(555) 123-4567", zip: "12345" },
+  { id: 3, first_name: "Jane", last_name: "Doe",   email: "jd@x.com", phone: "555-000-0000", zip: "54321" },
+];
+
+const result = dedupe(rows, { config });
+console.log(`\nDeduped: ${result.stats.totalRecords} -> ${result.stats.totalClusters} clusters`);
+
+/**
+ * Python -> TS differences:
+ *   - Python: `StandardizationConfig(rules={...})`; TS: `{ rules: {...} }` plain object.
+ *   - Python: pydantic validation; TS: `makeConfig` normalizes defaults, `parseConfig`
+ *     (used internally by loadConfigFile) validates YAML input.
+ */

package/examples/06-probabilistic-fs.ts

@@ -0,0 +1,72 @@
+/**
+ * Fellegi-Sunter probabilistic matching with Splink-style EM training.
+ *
+ * The F-S model learns per-field "agreement" probabilities under match
+ * vs. non-match hypotheses, producing match weights (log-likelihood
+ * ratios). Train on unlabeled data via EM -- no ground truth required.
+ *
+ * Run: npx tsx examples/06-probabilistic-fs.ts
+ */
+import {
+  trainEM,
+  scoreProbabilistic,
+  makeMatchkeyConfig,
+  makeMatchkeyField,
+} from "goldenmatch";
+
+// Synthetic labeled-ish data (row ids must be on __row_id__)
+const rows = [
+  { __row_id__: 0, first_name: "John",  last_name: "Smith",  zip: "12345" },
+  { __row_id__: 1, first_name: "Jon",   last_name: "Smith",  zip: "12345" },
+  { __row_id__: 2, first_name: "John",  last_name: "Smyth",  zip: "12345" },
+  { __row_id__: 3, first_name: "Jane",  last_name: "Doe",    zip: "54321" },
+  { __row_id__: 4, first_name: "Janet", last_name: "Doe",    zip: "54321" },
+  { __row_id__: 5, first_name: "Bob",   last_name: "Jones",  zip: "99999" },
+  { __row_id__: 6, first_name: "Alice", last_name: "Miller", zip: "11111" },
+  { __row_id__: 7, first_name: "Alice", last_name: "Miller", zip: "11111" },
+];
+
+// Build a probabilistic matchkey
+const mk = makeMatchkeyConfig({
+  name: "fs_identity",
+  type: "probabilistic",
+  threshold: 0.5,
+  linkThreshold: 0.5,
+  fields: [
+    makeMatchkeyField({ field: "first_name", transforms: ["lowercase"], scorer: "jaro_winkler", levels: 3 }),
+    makeMatchkeyField({ field: "last_name",  transforms: ["lowercase"], scorer: "jaro_winkler", levels: 3 }),
+    makeMatchkeyField({ field: "zip",        transforms: [],            scorer: "exact",        levels: 2 }),
+  ],
+});
+
+// Train the EM model
+const em = trainEM(rows, mk, {
+  maxIterations: 25,
+  convergence: 1e-4,
+  blockingFields: ["zip"],  // zip is used for blocking; fix neutral priors
+  seed: 42,
+  nSamplePairs: 200,
+});
+
+console.log(`EM converged: ${em.converged} (${em.iterations} iterations)`);
+console.log(`Estimated p(match): ${em.proportionMatched.toFixed(3)}\n`);
+
+console.log("Match weights (log2 m/u) per field per level:");
+for (const [field, weights] of Object.entries(em.matchWeights)) {
+  console.log(`  ${field.padEnd(12)} [${weights.map((w) => w.toFixed(2)).join(", ")}]`);
+}
+
+// Score all pairs in the block
+const matches = scoreProbabilistic(rows, mk, em, { threshold: 0.5 });
+
+console.log(`\nFound ${matches.length} probabilistic matches:`);
+for (const m of matches) {
+  console.log(`  (${m.idA}, ${m.idB}) -> ${m.score.toFixed(3)}`);
+}
+
+/**
+ * Python -> TS differences:
+ *   - Python `train_em()` vs. TS `trainEM()` (camelCase).
+ *   - Python returns numpy arrays; TS returns `readonly number[]`.
+ *   - TS requires `__row_id__` to be attached; Python adds it in its DF pipeline.
+ */

package/examples/07-pprl-privacy.ts

@@ -0,0 +1,76 @@
+/**
+ * Privacy-preserving record linkage (PPRL) via bloom filter CLKs.
+ *
+ * Two parties want to find common records without revealing plaintext.
+ * Each side encodes rows as bloom filters (CLKs) over agreed fields,
+ * exchanges only the encoded bit-vectors, and scores via Dice similarity.
+ *
+ * Three security levels:
+ *   - standard:  bloom filter only (fast, demo/low-risk data)
+ *   - high:      HMAC-SHA256 per-party salt (requires coordinated salt)
+ *   - paranoid:  balanced padding + HMAC (resists frequency analysis)
+ *
+ * Run: npx tsx examples/07-pprl-privacy.ts
+ */
+import { runPPRL, autoConfigurePPRL } from "goldenmatch";
+
+// Party A (e.g., hospital)
+const partyA = [
+  { name: "John Smith",   dob: "1980-01-15", city: "Seattle" },
+  { name: "Jane Doe",     dob: "1975-06-22", city: "Portland" },
+  { name: "Bob Johnson",  dob: "1990-11-03", city: "Austin" },
+  { name: "Alice Miller", dob: "1985-03-18", city: "Boston" },
+];
+
+// Party B (e.g., insurance) -- some overlap with A
+const partyB = [
+  { name: "Jon Smith",    dob: "1980-01-15", city: "Seattle" },    // same as A[0]
+  { name: "Jane Doe",     dob: "1975-06-22", city: "Portland" },   // same as A[1]
+  { name: "Carol Young",  dob: "1992-08-09", city: "Denver" },     // new
+];
+
+// --- Standard security: trusted-third-party protocol ---
+console.log("=== Standard security (trusted third party) ===");
+const stdResult = runPPRL(partyA, partyB, {
+  fields: ["name", "dob", "city"],
+  securityLevel: "standard",
+  protocol: "trusted_third_party",
+  threshold: 0.85,
+});
+for (const m of stdResult.matches) {
+  console.log(`  A[${m.idA}] <-> B[${m.idB}]  score=${m.score.toFixed(3)}`);
+}
+
+// --- High security: salted HMAC ---
+console.log("\n=== High security (HMAC salt) ===");
+const highResult = runPPRL(partyA, partyB, {
+  fields: ["name", "dob", "city"],
+  securityLevel: "high",
+  protocol: "trusted_third_party",
+  threshold: 0.85,
+  salt: "shared-secret-agreed-upon-out-of-band",
+});
+console.log(`  ${highResult.matches.length} matches found`);
+
+// --- Paranoid + SMC stub: salted, balanced padding, SMC protocol ---
+console.log("\n=== Paranoid + SMC protocol ===");
+const smcResult = runPPRL(partyA, partyB, {
+  fields: ["name", "dob", "city"],
+  securityLevel: "paranoid",
+  protocol: "smc",
+  threshold: 0.85,
+  salt: "shared-secret-agreed-upon-out-of-band",
+});
+console.log(`  ${smcResult.matches.length} matches found`);
+
+// --- Auto-configure: let GoldenMatch pick the fields / threshold ---
+console.log("\n=== Auto-configured ===");
+const autoConfig = autoConfigurePPRL(partyA, partyB);
+console.log(`  Auto-picked fields: ${autoConfig.fields.join(", ")}`);
+console.log(`  Threshold: ${autoConfig.threshold}`);
+
+/**
+ * NB: standard level leaks frequency info -- names appearing many times
+ * produce identifiable bit patterns. Use "high" or "paranoid" for
+ * anything beyond demos.
+ */

package/examples/08-streaming.ts

@@ -0,0 +1,79 @@
+/**
+ * Streaming / incremental record matching.
+ *
+ * Add records one at a time to a running cluster state. Useful for:
+ *   - Kafka / Kinesis consumers
+ *   - Continuous CDC ingest
+ *   - Web forms (match new signup vs. existing customers on submit)
+ *
+ * Each `add()` does one `matchOne()` against the running set, then
+ * updates the cluster map in-place.
+ *
+ * Run: npx tsx examples/08-streaming.ts
+ */
+import {
+  StreamProcessor,
+  makeMatchkeyConfig,
+  makeMatchkeyField,
+} from "goldenmatch";
+
+const mk = makeMatchkeyConfig({
+  name: "identity",
+  type: "weighted",
+  threshold: 0.85,
+  fields: [
+    makeMatchkeyField({ field: "name",  transforms: ["lowercase", "strip"], scorer: "jaro_winkler", weight: 0.6 }),
+    makeMatchkeyField({ field: "email", transforms: ["lowercase", "strip"], scorer: "exact",        weight: 0.4 }),
+  ],
+});
+
+const stream = new StreamProcessor({
+  matchkey: mk,
+  threshold: 0.85,
+  maxClusterSize: 50,
+});
+
+// Simulated record stream
+const records = [
+  { name: "John Smith",  email: "john@example.com" },
+  { name: "Jane Doe",    email: "jane@example.com" },
+  { name: "Jon Smith",   email: "john@example.com" },  // dupe of #0
+  { name: "Bob Jones",   email: "bob@example.com" },
+  { name: "Janet Doe",   email: "janet@example.com" },
+  { name: "J. Smith",    email: "john@example.com" },  // dupe of #0
+  { name: "Alice Chen",  email: "alice@example.com" },
+  // ... imagine 43 more records
+];
+
+console.log(`Streaming ${records.length} records...\n`);
+
+for (let i = 0; i < records.length; i++) {
+  const rec = records[i]!;
+  const result = stream.add(rec);
+  if (result.matchedIds.length > 0) {
+    console.log(
+      `  #${i} "${rec.name}" -> cluster ${result.clusterId}, matched ${result.matchedIds.length} existing (ids: ${result.matchedIds.join(", ")})`,
+    );
+  } else {
+    console.log(`  #${i} "${rec.name}" -> new cluster ${result.clusterId}`);
+  }
+}
+
+// Final snapshot
+const snap = stream.snapshot();
+console.log(`\nFinal state: ${stream.size} records in ${snap.clusters.size} clusters`);
+
+for (const [cid, info] of snap.clusters) {
+  if (info.size < 2) continue;
+  console.log(
+    `  Cluster ${cid}: ${info.size} members ${JSON.stringify(info.members)} (confidence ${info.confidence.toFixed(2)})`,
+  );
+}
+
+/**
+ * Python -> TS differences:
+ *   - Python `StreamProcessor.add(df_row)`; TS `stream.add(rowObject)`.
+ *   - `matchedIds` is the list of pre-existing rows the new record joined.
+ *   - `clusterId` is the cluster the record ultimately landed in (may be
+ *     a brand-new cluster or an existing one that got merged into).
+ */

package/examples/09-llm-scorer.ts

@@ -0,0 +1,79 @@
+/**
+ * LLM scorer: send borderline pairs to OpenAI/Anthropic for a YES/NO
+ * verdict, with a hard budget cap.
+ *
+ * Flow:
+ *   - score >= autoThreshold: auto-accept (promoted to 1.0, no LLM call)
+ *   - candidateLo <= score < autoThreshold: ask the LLM
+ *   - score < candidateLo: left as-is
+ *
+ * Run: OPENAI_API_KEY=sk-... npx tsx examples/09-llm-scorer.ts
+ */
+import {
+  llmScorePairs,
+  makeScoredPair,
+  type LLMScorerConfig,
+  type Row,
+  type ScoredPair,
+} from "goldenmatch";
+
+// Borderline pairs from a prior dedupe() run (scores 0.65 - 0.92)
+const rows: Row[] = [
+  { __row_id__: 0, name: "Apple Inc",          description: "Consumer electronics manufacturer" },
+  { __row_id__: 1, name: "Apple Incorporated", description: "Maker of iPhones and Macs" },
+  { __row_id__: 2, name: "Apple Orchard Co",   description: "Fruit grower in Washington State" },
+  { __row_id__: 3, name: "Microsoft Corp",     description: "Software company, maker of Windows" },
+  { __row_id__: 4, name: "Microsoft",          description: "Cloud + software + Xbox" },
+];
+
+const candidatePairs: ScoredPair[] = [
+  makeScoredPair(0, 1, 0.87), // borderline -- ask LLM
+  makeScoredPair(0, 2, 0.72), // borderline -- ask LLM (but almost certainly not same)
+  makeScoredPair(3, 4, 0.93), // auto-accept (>= 0.90)
+];
+
+const config: LLMScorerConfig = {
+  enabled: true,
+  provider: "openai",               // or "anthropic"
+  model: "gpt-4o-mini",
+  autoThreshold: 0.90,
+  candidateLo: 0.60,
+  candidateHi: 0.90,
+  batchSize: 10,
+  maxWorkers: 4,
+  mode: "pairwise",
+  budget: {
+    maxCostUsd: 0.05,
+    maxCalls: 50,
+    warnAtPct: 0.8,
+  },
+};
+
+const apiKey = process.env["OPENAI_API_KEY"];
+if (!apiKey) {
+  console.warn("OPENAI_API_KEY not set. Running in no-op mode (candidates pass through).\n");
+}
+
+const result = await llmScorePairs(candidatePairs, rows, config, apiKey);
+
+console.log("After LLM scoring:");
+for (const p of result.pairs) {
+  console.log(`  (${p.idA}, ${p.idB})  score=${p.score.toFixed(2)}`);
+}
+
+if (result.budget) {
+  console.log("\nBudget usage:");
+  console.log(`  Calls:     ${result.budget.calls}`);
+  console.log(`  Cost USD:  ${result.budget.costUsd.toFixed(4)}`);
+  console.log(`  Tokens:    ${result.budget.inputTokens} in / ${result.budget.outputTokens} out`);
+} else {
+  console.log("\nNo budget info (no LLM calls made).");
+}
+
+/**
+ * Python -> TS differences:
+ *   - Python `llm_score_pairs()` is sync-looking via asyncio; TS `llmScorePairs()` is
+ *     an async function returning a Promise.
+ *   - API key is passed explicitly (no env var magic); pass `process.env.OPENAI_API_KEY`
+ *     at the call site. Works on edge runtimes that expose `fetch`.
+ */

package/examples/10-explain.ts

@@ -0,0 +1,60 @@
+/**
+ * Explain why two records matched (or didn't).
+ *
+ * `explainPair()` re-runs per-field scoring with the matchkey config and
+ * produces an NL explanation plus per-field scores. Zero LLM cost.
+ *
+ * Run: npx tsx examples/10-explain.ts
+ */
+import {
+  explainPair,
+  makeMatchkeyConfig,
+  makeMatchkeyField,
+} from "goldenmatch";
+
+const mk = makeMatchkeyConfig({
+  name: "identity",
+  type: "weighted",
+  threshold: 0.85,
+  fields: [
+    makeMatchkeyField({ field: "first_name", transforms: ["lowercase"], scorer: "jaro_winkler", weight: 0.3 }),
+    makeMatchkeyField({ field: "last_name",  transforms: ["lowercase"], scorer: "jaro_winkler", weight: 0.4 }),
+    makeMatchkeyField({ field: "email",      transforms: ["lowercase"], scorer: "exact",        weight: 0.3 }),
+  ],
+});
+
+// --- Case 1: strong match ---
+const a1 = { first_name: "John", last_name: "Smith", email: "john@example.com" };
+const b1 = { first_name: "Jon",  last_name: "Smith", email: "john@example.com" };
+
+const exp1 = explainPair(a1, b1, mk);
+console.log("=== Case 1: strong match ===");
+console.log(`Overall score: ${exp1.score.toFixed(3)} (confidence: ${exp1.confidence})`);
+console.log(`Explanation: ${exp1.explanation}`);
+console.log("Per-field scores:");
+for (const [field, score] of Object.entries(exp1.fieldScores)) {
+  console.log(`  ${field.padEnd(12)} ${score === null ? "missing" : score.toFixed(3)}`);
+}
+
+// --- Case 2: weak match ---
+const a2 = { first_name: "John",  last_name: "Smith", email: "john@example.com" };
+const b2 = { first_name: "Johan", last_name: "Smyth", email: "j.smith@other.com" };
+
+const exp2 = explainPair(a2, b2, mk);
+console.log("\n=== Case 2: weak match ===");
+console.log(`Overall score: ${exp2.score.toFixed(3)} (confidence: ${exp2.confidence})`);
+console.log(`Explanation: ${exp2.explanation}`);
+console.log("Reasoning steps:");
+for (const step of exp2.reasoning) {
+  console.log(`  - ${step}`);
+}
+
+/**
+ * `details` also contains the full `FieldScoreDetail` array (normalized values
+ * after transforms, diff classification). Useful for building review-queue UIs.
+ */
+for (const d of exp2.details) {
+  console.log(
+    `  [details] ${d.field}: "${d.valueA}" vs "${d.valueB}"  (${d.diffType})`,
+  );
+}