goldenmatch 0.1.0

package/examples/11-evaluate.ts

@@ -0,0 +1,61 @@
+/**
+ * Evaluate predicted pairs against ground truth: precision, recall, F1.
+ *
+ * Two evaluation modes:
+ *   - evaluatePairs: compare the predicted ScoredPair[] to ground truth
+ *   - evaluateClusters: expand clusters into pairs, then compare
+ *
+ * Run: npx tsx examples/11-evaluate.ts
+ */
+import { dedupe, evaluatePairs, evaluateClusters } from "goldenmatch";
+
+// Dataset with known ground truth
+const rows = [
+  { id: 0, name: "John Smith",  zip: "12345" },
+  { id: 1, name: "Jon Smith",   zip: "12345" },  // dupe of 0
+  { id: 2, name: "Johnny Smth", zip: "12345" },  // dupe of 0
+  { id: 3, name: "Jane Doe",    zip: "54321" },
+  { id: 4, name: "Janet Doe",   zip: "54321" },  // dupe of 3
+  { id: 5, name: "Bob Jones",   zip: "99999" },
+];
+
+// Ground truth: pairs that SHOULD match (canonicalized min:max)
+const truth: [number, number][] = [
+  [0, 1],
+  [0, 2],
+  [1, 2],
+  [3, 4],
+];
+
+// Run dedupe
+const result = dedupe(rows, {
+  fuzzy: { name: 0.85 },
+  blocking: ["zip"],
+  threshold: 0.85,
+});
+
+// --- Evaluate via pair set ---
+const pairEval = evaluatePairs(result.scoredPairs, truth);
+console.log("=== Pair-based evaluation ===");
+console.log(`  Precision: ${pairEval.precision.toFixed(3)}`);
+console.log(`  Recall:    ${pairEval.recall.toFixed(3)}`);
+console.log(`  F1:        ${pairEval.f1.toFixed(3)}`);
+console.log(`  TP=${pairEval.truePositives}  FP=${pairEval.falsePositives}  FN=${pairEval.falseNegatives}`);
+
+// --- Evaluate via cluster expansion ---
+const allIds = rows.map((r) => r.id);
+const clusterEval = evaluateClusters(result.clusters, truth, allIds);
+console.log("\n=== Cluster-based evaluation ===");
+console.log(`  Precision: ${clusterEval.precision.toFixed(3)}`);
+console.log(`  Recall:    ${clusterEval.recall.toFixed(3)}`);
+console.log(`  F1:        ${clusterEval.f1.toFixed(3)}`);
+
+/**
+ * Cluster-based eval is typically more favorable than pair-based because
+ * transitive closures pick up pairs the direct scorer missed (if A~B and
+ * B~C cluster together, A~C counts as a TP even if A~C scored below
+ * threshold directly).
+ *
+ * Python parity: `evaluate_pairs()` / `evaluate_clusters()` in
+ * `goldenmatch.core.evaluate`. CLI: `goldenmatch evaluate --ground-truth gt.csv`.
+ */

package/examples/README.md

@@ -0,0 +1,53 @@
+# GoldenMatch TypeScript Examples
+
+Each example is a standalone `.ts` file runnable with:
+
+```bash
+npx tsx examples/<name>.ts
+```
+
+| # | Example | What it shows |
+|---|---------|---------------|
+| 01 | `01-basic-dedupe.ts` | Dedupe an in-memory array with exact + fuzzy matchkeys |
+| 02 | `02-match-two-datasets.ts` | Match target records against a reference dataset |
+| 03 | `03-csv-file-pipeline.ts` | Read CSV -> dedupe -> write golden records |
+| 04 | `04-string-scoring.ts` | Compare every scorer on the same string pairs |
+| 05 | `05-custom-config.ts` | Build/save/load a full GoldenMatchConfig (YAML) |
+| 06 | `06-probabilistic-fs.ts` | Fellegi-Sunter with EM training |
+| 07 | `07-pprl-privacy.ts` | Privacy-preserving record linkage (3 security levels) |
+| 08 | `08-streaming.ts` | Incremental streaming -- add records one at a time |
+| 09 | `09-llm-scorer.ts` | LLM scorer for borderline pairs (needs OPENAI_API_KEY) |
+| 10 | `10-explain.ts` | Template NL explanation of a pair match |
+| 11 | `11-evaluate.ts` | Evaluate against ground truth (precision/recall/F1) |
+
+## Running
+
+From the repo root:
+
+```bash
+cd packages/goldenmatch-js
+npm install
+npx tsx examples/01-basic-dedupe.ts
+```
+
+Or install `tsx` globally:
+
+```bash
+npm install -g tsx
+tsx examples/01-basic-dedupe.ts
+```
+
+## Optional peer deps by example
+
+Most examples use only the core package. A few need optional peer deps:
+
+| Example | Peer dep required |
+|---------|-------------------|
+| `05-custom-config.ts` (YAML save/load path only) | `yaml` |
+| `09-llm-scorer.ts` | none (uses `fetch`); needs `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` in env |
+
+Install them on demand:
+
+```bash
+npm install yaml
+```

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "goldenmatch",
+  "version": "0.1.0",
+  "description": "Entity resolution toolkit — deduplicate, match, and create golden records",
+  "type": "module",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.cjs" },
+    "./core": { "types": "./dist/core/index.d.ts", "import": "./dist/core/index.js", "require": "./dist/core/index.cjs" },
+    "./node": { "types": "./dist/node/index.d.ts", "import": "./dist/node/index.js", "require": "./dist/node/index.cjs" }
+  },
+  "bin": { "goldenmatch-js": "./dist/cli.cjs" },
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "peerDependencies": {
+    "yaml": "*",
+    "ink": "^5.0.0",
+    "react": "^18.0.0",
+    "hnswlib-node": "^3.0.0",
+    "@huggingface/transformers": "^3.0.0",
+    "piscina": "^5.0.0",
+    "ink-table": "^4.0.0",
+    "ink-select-input": "^6.0.0",
+    "ink-text-input": "^6.0.0",
+    "ink-spinner": "^5.0.0",
+    "ink-gradient": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "yaml": { "optional": true },
+    "ink": { "optional": true },
+    "react": { "optional": true },
+    "hnswlib-node": { "optional": true },
+    "@huggingface/transformers": { "optional": true },
+    "piscina": { "optional": true },
+    "ink-table": { "optional": true },
+    "ink-select-input": { "optional": true },
+    "ink-text-input": { "optional": true },
+    "ink-spinner": { "optional": true },
+    "ink-gradient": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.0",
+    "yaml": "^2.7.0"
+  },
+  "keywords": [
+    "entity-resolution", "deduplication", "record-linkage", "fuzzy-matching",
+    "golden-record", "data-quality", "jaro-winkler", "levenshtein"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/benzsevern/goldenmatch"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+/**
+ * cli.ts -- GoldenMatch command-line interface.
+ *
+ * Built on commander. Exposes `dedupe`, `match`, `score`, `profile`,
+ * `info`, and `demo` subcommands.
+ */
+
+import { Command } from "commander";
+import { extname, basename } from "node:path";
+import {
+  readFile,
+  writeCsv,
+  writeJson,
+} from "./node/connectors/file.js";
+import { dedupe, match, scoreStrings } from "./core/api.js";
+import { loadConfigFile } from "./node/config-file.js";
+import type { Row } from "./core/types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parseFuzzyArg(raw: string): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const pair of raw.split(",")) {
+    const trimmed = pair.trim();
+    if (trimmed === "") continue;
+    const idx = trimmed.indexOf(":");
+    let field: string;
+    let threshold = 0.85;
+    if (idx === -1) {
+      field = trimmed;
+    } else {
+      field = trimmed.slice(0, idx).trim();
+      const rawThreshold = trimmed.slice(idx + 1).trim();
+      const parsed = parseFloat(rawThreshold);
+      if (Number.isFinite(parsed)) threshold = parsed;
+    }
+    if (field !== "") out[field] = threshold;
+  }
+  return out;
+}
+
+function parseCsvList(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+function loadFilesWithSource(paths: readonly string[]): Row[] {
+  const rows: Row[] = [];
+  for (let i = 0; i < paths.length; i++) {
+    const p = paths[i]!;
+    const source = basename(p, extname(p)) || `file_${i}`;
+    const fileRows = readFile(p);
+    for (const r of fileRows) {
+      rows.push({ ...r, __source__: source });
+    }
+  }
+  return rows;
+}
+
+interface SharedMatchOpts {
+  config?: string;
+  exact?: string;
+  fuzzy?: string;
+  blocking?: string;
+  threshold?: number;
+  output?: string;
+  format?: string;
+}
+
+function buildOptionsFromFlags(opts: SharedMatchOpts) {
+  const out: {
+    config?: ReturnType<typeof loadConfigFile>;
+    exact?: string[];
+    fuzzy?: Record<string, number>;
+    blocking?: string[];
+    threshold?: number;
+  } = {};
+  if (opts.config) out.config = loadConfigFile(opts.config);
+  if (opts.exact) out.exact = parseCsvList(opts.exact);
+  if (opts.fuzzy) out.fuzzy = parseFuzzyArg(opts.fuzzy);
+  if (opts.blocking) out.blocking = parseCsvList(opts.blocking);
+  if (opts.threshold !== undefined) out.threshold = opts.threshold;
+  return out;
+}
+
+function writeOutputRows(
+  path: string,
+  rows: readonly Row[],
+  format: string,
+): void {
+  const ext = extname(path).toLowerCase();
+  const useJson =
+    format === "json" ||
+    ext === ".json" ||
+    ext === ".jsonl" ||
+    ext === ".ndjson";
+  if (useJson) {
+    writeJson(path, rows);
+  } else {
+    const delimiter = ext === ".tsv" ? "\t" : ",";
+    writeCsv(path, rows, { delimiter });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI definition
+// ---------------------------------------------------------------------------
+
+const program = new Command();
+
+program
+  .name("goldenmatch-js")
+  .description("Entity resolution toolkit -- dedupe, match, build golden records")
+  .version("0.1.0");
+
+// ---------- dedupe ----------
+program
+  .command("dedupe")
+  .description("Deduplicate records in one or more files")
+  .argument("<files...>", "input file paths (.csv, .tsv, .json, .jsonl)")
+  .option("-c, --config <path>", "path to YAML config file")
+  .option("-e, --exact <fields>", "comma-separated exact match fields")
+  .option(
+    "-f, --fuzzy <fields>",
+    "fuzzy match fields, e.g. 'name:0.85,email:0.9'",
+  )
+  .option("-b, --blocking <fields>", "comma-separated blocking keys")
+  .option("-t, --threshold <value>", "overall fuzzy threshold", parseFloat)
+  .option("-o, --output <path>", "output path for golden records")
+  .option("--format <format>", "output format: csv or json", "csv")
+  .action(async (files: string[], opts: SharedMatchOpts) => {
+    const rows = loadFilesWithSource(files);
+    const options = buildOptionsFromFlags(opts);
+    const result = dedupe(rows, options);
+    const pct = (result.stats.matchRate * 100).toFixed(1);
+    process.stdout.write(
+      `Dedupe complete: ${result.stats.totalRecords} records -> ${result.stats.totalClusters} clusters (${pct}% match rate)\n`,
+    );
+    if (opts.output) {
+      writeOutputRows(
+        opts.output,
+        result.goldenRecords,
+        opts.format ?? "csv",
+      );
+      process.stdout.write(
+        `Wrote ${result.goldenRecords.length} golden records to ${opts.output}\n`,
+      );
+    }
+  });
+
+// ---------- match ----------
+program
+  .command("match")
+  .description("Match target records against a reference dataset")
+  .argument("<target>", "target file path")
+  .argument("<reference>", "reference file path")
+  .option("-c, --config <path>", "path to YAML config file")
+  .option("-e, --exact <fields>", "comma-separated exact match fields")
+  .option(
+    "-f, --fuzzy <fields>",
+    "fuzzy match fields, e.g. 'name:0.85,email:0.9'",
+  )
+  .option("-b, --blocking <fields>", "comma-separated blocking keys")
+  .option("-t, --threshold <value>", "overall fuzzy threshold", parseFloat)
+  .option("-o, --output <path>", "output path for matched records")
+  .option("--format <format>", "output format: csv or json", "csv")
+  .action(
+    async (targetPath: string, referencePath: string, opts: SharedMatchOpts) => {
+      const targetRows = readFile(targetPath).map((row) => ({
+        ...row,
+        __source__: "target",
+      }));
+      const referenceRows = readFile(referencePath).map((row) => ({
+        ...row,
+        __source__: "reference",
+      }));
+      const options = buildOptionsFromFlags(opts);
+      const result = match(targetRows, referenceRows, options);
+      process.stdout.write(
+        `Match complete: ${result.matched.length} matched, ${result.unmatched.length} unmatched\n`,
+      );
+      if (opts.output) {
+        writeOutputRows(
+          opts.output,
+          result.matched,
+          opts.format ?? "csv",
+        );
+        process.stdout.write(
+          `Wrote ${result.matched.length} matched records to ${opts.output}\n`,
+        );
+      }
+    },
+  );
+
+// ---------- score ----------
+program
+  .command("score")
+  .description("Score similarity between two strings")
+  .argument("<a>", "first string")
+  .argument("<b>", "second string")
+  .option(
+    "-s, --scorer <name>",
+    "scorer: exact, jaro_winkler, levenshtein, token_sort, soundex_match, dice, jaccard, ensemble",
+    "jaro_winkler",
+  )
+  .action((a: string, b: string, opts: { scorer: string }) => {
+    const score = scoreStrings(a, b, opts.scorer);
+    process.stdout.write(`${opts.scorer}: ${score.toFixed(4)}\n`);
+  });
+
+// ---------- info ----------
+program
+  .command("info")
+  .description("Show information about the package")
+  .action(() => {
+    process.stdout.write("GoldenMatch JS v0.1.0\n");
+    process.stdout.write(
+      "Scorers: exact, jaro_winkler, levenshtein, token_sort, soundex_match, dice, jaccard, ensemble\n",
+    );
+    process.stdout.write(
+      "Strategies: most_complete, majority_vote, source_priority, most_recent, first_non_null\n",
+    );
+    process.stdout.write(
+      "Blocking: static, multi_pass, sorted_neighborhood, adaptive\n",
+    );
+    process.stdout.write(
+      "Transforms: lowercase, uppercase, strip, soundex, metaphone, digits_only, alpha_only, token_sort\n",
+    );
+  });
+
+// ---------- profile ----------
+program
+  .command("profile")
+  .description("Profile a dataset (column stats, nulls, cardinality)")
+  .argument("<file>", "input file")
+  .action((file: string) => {
+    const rows = readFile(file);
+    const total = rows.length;
+    process.stdout.write(`File: ${file}\n`);
+    process.stdout.write(`Rows: ${total}\n`);
+    if (total === 0) return;
+    const columns = new Set<string>();
+    for (const r of rows) for (const k of Object.keys(r)) columns.add(k);
+    process.stdout.write(`Columns: ${columns.size}\n`);
+    process.stdout.write("\n");
+    const colList = [...columns];
+    const nameWidth = Math.max(6, ...colList.map((c) => c.length));
+    const pad = (s: string, w: number) => s + " ".repeat(Math.max(0, w - s.length));
+    process.stdout.write(
+      `${pad("column", nameWidth)}  ${pad("nulls", 8)}  ${pad("null%", 7)}  ${pad("distinct", 9)}  sample\n`,
+    );
+    process.stdout.write(
+      `${"-".repeat(nameWidth)}  ${"-".repeat(8)}  ${"-".repeat(7)}  ${"-".repeat(9)}  ------\n`,
+    );
+    for (const col of colList) {
+      let nulls = 0;
+      const distinct = new Set<string>();
+      let sample: string | null = null;
+      for (const row of rows) {
+        const v = row[col];
+        if (v === null || v === undefined || v === "") {
+          nulls++;
+        } else {
+          const s = String(v);
+          distinct.add(s);
+          if (sample === null) sample = s;
+        }
+      }
+      const nullPct = ((nulls / total) * 100).toFixed(1);
+      const sampleStr = sample === null ? "-" : sample.length > 30 ? sample.slice(0, 27) + "..." : sample;
+      process.stdout.write(
+        `${pad(col, nameWidth)}  ${pad(String(nulls), 8)}  ${pad(nullPct + "%", 7)}  ${pad(String(distinct.size), 9)}  ${sampleStr}\n`,
+      );
+    }
+  });
+
+// ---------- demo ----------
+program
+  .command("demo")
+  .description("Run a quick demo on synthetic data")
+  .action(() => {
+    const rows: Row[] = [
+      { id: 1, name: "John Smith", email: "john@example.com", zip: "01234" },
+      { id: 2, name: "Jon Smith", email: "john@example.com", zip: "01234" },
+      { id: 3, name: "Jane Doe", email: "jane@example.com", zip: "02139" },
+      { id: 4, name: "J. Doe", email: "jane@example.com", zip: "02139" },
+      { id: 5, name: "Bob Jones", email: "bob@example.com", zip: "10001" },
+    ];
+    process.stdout.write(`Input: ${rows.length} synthetic records\n`);
+    const result = dedupe(rows, {
+      exact: ["email"],
+      fuzzy: { name: 0.8 },
+      blocking: ["zip"],
+      threshold: 0.8,
+    });
+    process.stdout.write(
+      `Dedupe: ${result.stats.totalRecords} records -> ${result.stats.totalClusters} clusters\n`,
+    );
+    process.stdout.write(
+      `Match rate: ${(result.stats.matchRate * 100).toFixed(1)}%\n`,
+    );
+    process.stdout.write(`Golden records: ${result.goldenRecords.length}\n`);
+    for (const g of result.goldenRecords) {
+      process.stdout.write(`  ${JSON.stringify(g)}\n`);
+    }
+  });
+
+// ---------- mcp-serve ----------
+program
+  .command("mcp-serve")
+  .description("Start MCP server over stdio (JSON-RPC 2.0)")
+  .action(async () => {
+    const { startMcpServer } = await import("./node/mcp/server.js");
+    startMcpServer();
+  });
+
+// ---------- serve (REST API) ----------
+program
+  .command("serve")
+  .description("Start the REST API server")
+  .option("-p, --port <port>", "port", "8000")
+  .option("-h, --host <host>", "host", "127.0.0.1")
+  .action(async (opts: { port: string; host: string }) => {
+    const { startApiServer } = await import("./node/api/server.js");
+    startApiServer({ port: parseInt(opts.port, 10), host: opts.host });
+  });
+
+// ---------- agent-serve (A2A) ----------
+program
+  .command("agent-serve")
+  .description("Start the A2A agent-to-agent server")
+  .option("-p, --port <port>", "port", "8200")
+  .option("-h, --host <host>", "host", "127.0.0.1")
+  .action(async (opts: { port: string; host: string }) => {
+    const { startA2aServer } = await import("./node/a2a/server.js");
+    startA2aServer({ port: parseInt(opts.port, 10), host: opts.host });
+  });
+
+// ---------- tui ----------
+program
+  .command("tui")
+  .description("Launch interactive TUI (requires optional peer deps: ink + react)")
+  .argument("[files...]", "input files to load on startup")
+  .option("-c, --config <path>", "path to YAML config file")
+  .action(async (files: string[], opts: { config?: string }) => {
+    try {
+      const { startTui } = await import("./node/tui/app.js");
+      const tuiOpts: { files?: string[]; config?: ReturnType<typeof loadConfigFile> } = {};
+      if (files && files.length > 0) tuiOpts.files = files;
+      if (opts.config) tuiOpts.config = loadConfigFile(opts.config);
+      await startTui(tuiOpts);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`TUI error: ${message}\n`);
+      process.exit(1);
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+program.parseAsync(process.argv).catch((err: unknown) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`Error: ${message}\n`);
+  process.exit(1);
+});