GoldenMatch

Group records into clusters given a file and matchkey definition.

Estimate match RECALL without ground truth (unsupervised). Treats each auto-configured matchkey/pass as a decorrelated system and uses capture-recapture over their overlaps to estimate how many true matches were missed. Returns a point estimate (a safe lower bound additionally needs a small labelled audit; see `goldenmatch evaluate --certify --audit-out`). Needs >=3 decorrelated systems.

Certify every declared identity key in a semantic model (dbt/MetricFlow, Cube, or OSI/Ossie -- auto-detected) against its data files. A metric is only correct if the key its joins run on uniquely identifies one entity; this reports, per key, whether it is unique at grain and how much a duplicated key would inflate a SUM/COUNT (fan-out). With resolve=true it ALSO runs entity resolution on each frame's attributes to measure whether distinct declared keys collapse onto one real entity (fragmentation -> undercount) -- the part a semantic layer can't do itself. Returns {dialect, n_certified, all_tr…

Certify that a Customer 360 serving layer's join keys can't double-count. A 360 view joins the golden record to its source records on the durable record_id (`{source}:{source_pk}`); if that key is duplicated, a fact rolled up through the 360 silently double-counts. This walks the store's entities, assembles the record_id join key, and returns a key-integrity certificate over it ({trustworthy, n_entities, n_records, truncated, record_id: {is_unique_at_grain, duplicate_key_groups, max_fan_out, estimate}}).

One call: clean then dedupe a single CSV. Uploads the file, runs GoldenFlow transforms (phone/date/unicode/categorical normalization), then runs entity resolution on the cleaned data and writes golden records. Returns a summary + the golden file path. Requires the transform extra for the clean step.

Compare two ER clustering outcomes on the same rows via CCMS (Case Count Metric System). Pass two clusters-JSON file paths (baseline ER1 and comparison ER2); each file is a mapping of cluster id -> members (a `{"members": [...]}` object or a bare list), optionally under a `{"clusters": {...}}` wrapper. Returns per-case counts (unchanged/merged/partitioned/overlapping) with percentages, record and cluster counts (rc/cc1/cc2), singleton counts (sc1/sc2), and the Talburt-Wang Index (twi). Stateless -- needs no loaded dataset.

Scan a file with every available domain pack (plus base/no-domain) and compare health scores. Recommends the best-fitting domain.

Diagnose weaknesses in the current run's auto-config: columns admitted that shouldn't be (source/provenance labels, per-row IDs), oversized or shared-value blocks, null sinks, low-signal matchkeys, and over-merging. Returns ranked findings, each with a plain-English explanation + a concrete fix, plus a one-paragraph summary. Reads the current run (the last dedupe in this session).

Return the AutoConfigController telemetry from the most recent `auto_configure` or `agent_deduplicate` call in this MCP session. Same JSON shape as the web /api/v1/controller/telemetry endpoint.

Convert a Splink settings JSON (bare or trained) into a GoldenMatch config. Pass the settings as an inline JSON string -- no filesystem access needed. Returns the config as YAML, a findings report (severity/splink_path/message/mapped_to per finding), a summary, and -- when the Splink input carried trained m/u probabilities -- the imported EM model as a dict you can persist yourself. strict=True fails on ANY lossy mapping (not just hard errors).

Create a custom domain extraction rulebook. Define patterns for a specific data domain (medical devices, automotive parts, real estate, etc.).

The unified Customer 360 serving view of one entity, composed from the durable store in one call: the golden record + per-field source provenance, every linked source record, the event timeline, and the relationship neighborhood. This is the same durable entity_id a resolved crosswalk (semantic-layer wedge) groups metrics by, so a metric row drills straight through to the customer. Returns {found: false} when no such entity exists.

Deduplicate records in a file. Returns cluster counts and optional output path.

One call: dedupe a single CSV. Uploads the file, auto-configures matching, runs entity resolution with confidence gating, and writes golden (deduplicated) records to a CSV. Returns a summary + the golden file path.

Detect metric regressions vs a baseline over a run history.

Compare two data files and report differences (added/removed/changed columns and rows).

Generative half of the semantic-layer front door: point GoldenMatch at a set of source tables and it PROPOSES a draft semantic model -- entity types, keys, joins, measures, dimensions -- where every declared key is already graded by the certifier (unique-at-grain + fan-out). Discovery is hypothesis generation; certification is the falsification test, so the draft is pre-proven against the data. Advisory; nothing is auto-applied.

Extract records from documents (PDF/image) against a target schema into rows ready for dedupe_df. Returns records + an ingest report.

Propose a target extraction schema (JSON) from a sample document image/PDF.

Emit a conformed semantic-layer catalog (the `resolved_entity_id` join a MetricFlow / Cube / OSI model should group metrics by) directly from the durable identity store — 'keep the semantic layer's identity join live against the control plane'. Returns the emitted YAML; when `out_path` is set, also writes it to that catalog file (refuses to clobber unless overwrite=true).

Evaluate predicted pairs from a dedupe run against ground truth pairs.

Run dedupe on a file and explain the cluster containing the given row id.

Get a natural-language health narrative for a specific column. Scans the file, profiles the column, and explains all findings.

Explain a single finding in natural language. Requires the finding as a JSON dict and the file_path to load a profile for context.

Explain why two records match or don't match. Shows per-field score breakdown.

Explain why two records match (or don't) using a matchkey definition.

Explain what a pipeline config will do — resolves it into an ordered stage plan.

Human-readable explanation of why each stage is routed the way it is, with the driver-RAM projection that drove it.

Describe a specific transform by name. Returns its metadata or an error if not found.

Write the current run's golden records to a file (csv or json) and return the path and record count.

Find duplicate matches for a record. Provide field values to search against the loaded dataset.

Find exact matches on a field in a file. Returns pairs.

Find fuzzy matches in a block of rows. Returns scored pairs.

Run GoldenCheck scan and apply fixes to a CSV file. Returns the fixed data summary and a manifest of all fixes applied. Requires goldencheck: pip install goldenmatch[quality]

Return one cluster from the current run: its size and member records.

Get detailed profile and findings for a specific column.

Get info about a domain pack — types, hints, suppression rules.

Return the golden (survivorship) record for a cluster in the current run.

Summary statistics for the current run (the last dedupe). Returns record/cluster counts, singleton count, match rate, avg/max cluster size, and pair count.

Trend a metric over a run history (.jsonl/.db ReportHistory).

Get health score (A-F, 0-100) for a data file.

Export the append-only identity audit log in commit order: every event with actor / trust / timestamp / reason, so a reviewer can reconstruct exactly which actor changed what, when, and why. Optionally filtered by dataset / actor.

Anchor the append-only audit log with a tamper-evidence seal: a chained sha256 root over every event since the last seal. Cheap and idempotent (a no-op when nothing new has been logged). Publish/mirror the returned root_hash to make tampering detectable by an external party.

Verify the append-only audit log against its seal chain. Replays the per-event content hashes and the seal roots to detect content edits, deletion, reordering, and insertion of any sealed event. Returns {ok, events_checked, seals_checked} plus the ids of any mismatches.

Claim a record into an identity, moving it out of any prior entity ('this record belongs to that identity'). Emits a `claimed` event on both the gaining and losing entities. Idempotent: claiming a record already in the target entity is a no-op.

List evidence edges marked `conflicts_with`.

Return the temporal event log for an identity.

List identities, optionally filtered by dataset/status.

Manually merge two identities. All records from `absorb_entity_id` are reassigned to `keep_entity_id`.

One entity's full MDM profile: record count + per-source breakdown, golden record, confidence, conflict count, a canonical version (count of structural events), and first/last activity.

Resolve a record_id to its durable identity. Returns the full identity view (members, evidence edges, recent events) or { found: false } when no identity exists for that record.

Adjudicate a `conflicts_with` pair: 'same' keeps the entity intact, 'distinct' splits the second record out into a new identity, 'defer' only logs. Records a durable mediation verdict + event and stops the conflict re-surfacing in the open-conflicts queue.

Fetch the full detail of one identity by entity_id: its member records, evidence edges, and recent event log. Returns {found: false} when no such entity exists.

Split a subset of records off an identity into a brand-new identity. The original keeps the remaining records.

Graph-level identity health: entities by status, total records, records-per-entity distribution, conflict total, source mix, and the largest entities. Optionally scoped to a dataset.

Prioritized queue of active entities needing a steward's attention (open conflicts and/or confidence below weak_confidence), highest conflict count first then lowest confidence.

Match a batch of new records against an existing base dataset (without re-running the whole base). Returns matched (new_row_id, base_row_id, score) pairs plus counts. Auto-configures from the base file if no config is given.

Inspect a data source — show fields, types, sample values, null rates, and unique rates.

Download a community domain pack from the goldencheck-types repository and save it for use in future scans.

Detect the identity layers (parties) a data source refers to — e.g. a loan tape's lender AND borrower, or a claims file's patient, provider and payer. Distinct from domain detection, which returns one industry vertical for the whole source. Each layer is the group of columns describing one party, with its kind (person/organization/asset/place), a score, and the evidence behind it. Unrecognised parties are reported with role 'unknown' rather than dropped; columns belonging to no party land in 'unassigned'.

Generate a YAML config from data patterns. Analyzes the file and returns a recommended config.

Force a MemoryLearner pass over accumulated corrections. Returns the list of LearnedAdjustments produced (matchkey_name, threshold, sample_size, learned_at). Requires >= 10 corrections per matchkey before threshold tuning fires; otherwise returns an empty list.

Field-level provenance for the current run: one lineage record per golden record, with the source rows merged and the per-field survivorship strategy + confidence. Optionally include a natural-language summary per record.

Flag config/env overrides that force a slow path (e.g. CLUSTERING_THRESHOLD=0 when the edge set fits driver RAM). ERROR at scale; would_refuse mirrors the runtime guard.

List the discoverable GoldenAnalysis analyzers.

List all blocking strategy names.

List all available profiler checks and what they detect.

List clusters from the current run, largest first. Filters to clusters of at least `min_size` and returns the first `limit`.

List stored Learning Memory corrections, optionally filtered by dataset. Returns id_a, id_b, decision, source, trust, reason, matchkey_name, dataset, original_score, created_at.

List available domain packs (healthcare, finance, ecommerce).

List all registered goldenmatch plugins by category. Includes the 22 v1.18.2 predefined plugins (numeric/format/business/aggregation) plus any user-registered plugins via entry-points or PluginRegistry.register_*(). Each entry includes name, source (builtin or user), category, and the first line of the merge docstring.

List previous dedupe/match runs (for rollback) from the run log.

List all available similarity scorers.

List all registered pipeline stages with their produces/consumes contracts.

List all golden-record survivorship strategies.

List all available transforms with their metadata (name, input types, mode, priority).

Auto-map schemas between two data files. Returns column mappings with confidence scores.

Match a target file against a reference file. Returns matched/unmatched counts.

Match a single record against the loaded dataset in real-time. Paste a record's fields and instantly see if it matches any existing record. Uses the configured matchkeys, scorers, and thresholds. Example: {"name": "John Smith", "email": "john@test.com", "zip": "10001"}

One call: link two sources. Uploads both files, then runs cross-source matching with intelligent strategy selection and returns the matched pairs (and a matches file path when the engine writes one).

Return all corrections as a list of dicts (CSV-shaped). Caller is responsible for writing the file. Optionally filter by dataset.

Import corrections from a list of dicts (the exact shape memory_export returns). Upserts into the store: higher trust wins, same trust = latest wins. Returns the count imported.

Return Learning Memory status: total correction count, last learn time, and current learned adjustments. Cheap; safe for status checks.

Ontology-layer front door (consume): certify the identity keys an OWL/RDF ontology DECLARES (owl:hasKey, inverse-functional properties) against real instance data. The ontology asserts identity but resolves it only by brittle exact-match; this returns a per-key verdict (unique-at-grain + fan-out) so an over-merging IFP/key is caught before a reasoner trusts it. Advisory. Needs the goldenmatch[ontology] extra.

Ontology-layer front door (generate): point GoldenMatch at a set of class instance tables and it PROPOSES a draft OWL ontology -- one owl:Class per frame whose owl:hasKey is chosen and PRE-GRADED by the certifier (gm:keyTrustworthy / gm:keyUniquenessEstimate). Discovery is hypothesis; certification is the falsification test. Returns the discovery result + the Turtle. Needs the goldenmatch[ontology] extra.

Generate a structured quality attestation for a data file: health score, findings summary, pinned rules, and attestation status (PASS / PASS_WITH_WARNINGS / REVIEW_REQUIRED / FAIL).

Project per-stage distributed routing (scoring/clustering/golden) for a given data shape + cluster. Pure; no controller run.

Analyze the loaded dataset and recommend optimal PPRL (privacy-preserving record linkage) configuration. Returns recommended fields, bloom filter parameters, threshold, and explanation.

Run privacy-preserving record linkage (PPRL) between two parties' CSV files. Encodes each party's fields as Bloom-filter CLKs and matches records without sharing raw values. Stateless -- reads the two files directly. Specify the shared `fields`, a `threshold`, and a `security_level` (standard/high/paranoid picks the ngram/hash/size).

Profile a data file — column types, null%, unique%, min/max, health score.

Get data quality profile: column types, null rates, unique counts, sample values.

Read a CSV/JSON file and return the first N records.

Semantic retrieval (#1089): return the records in a CSV most similar to a free-text query, ranked by cosine similarity. Embeds the chosen column and the query, then runs ANN search. The read side of the RAG entity-canonicalization epic -- fetch candidate records by query without running a full dedupe. EMBEDDER IS CALLER-SUPPLIED: unlike the Python tool (which defaults to a bundled zero-config in-house model), this TS surface carries only the embedding kernel, not a model, so you MUST pass an embedder `provider` (openai/vertex/voyage) plus its credentials; it errors clearly if none is given.

Run the config healer over the loaded dataset: analyze the dedupe run and return ranked, self-verified suggestions for improving the matching config (thresholds, scorers, negative evidence, blocking). Each suggestion carries an id, kind, target, rationale, and a machine-applicable patch. Requires the native kernel (pip install goldenmatch[native]); returns an empty list otherwise.

List all pending review items for a given job (medium-confidence findings needing a decision).

Get review queue statistics for a job — counts of pending, pinned, and dismissed items.

Undo a previous run by DELETING its output files (looked up by run_id in the run log). Destructive: removes the files that run wrote. Use list_runs first to find the run_id.

Run a pipeline on a CSV file. Zero-config or from a YAML config path.

Run GoldenFlow data transforms on a CSV file. Normalizes phone numbers (E.164), dates (ISO), categorical spelling, and Unicode issues. Returns a manifest of transforms applied. Requires goldenflow: pip install goldenmatch[transform]

Scan a data file (CSV, Parquet) for data quality issues. Returns findings with severity, confidence, affected rows.

Run GoldenCheck data quality scan on a CSV file. Returns issues found (encoding errors, Unicode problems, format violations) without applying fixes. Requires goldencheck: pip install goldenmatch[quality]

Auto-map columns between two files with different schemas. Returns proposed (col_a, col_b) mappings with a confidence score and method (exact_name / synonym / name_sim / partial_name / value_overlap / composite). Stateless -- needs no loaded dataset; useful before matching two sources.

Score two record objects across weighted fields. Returns a combined score.

Score similarity between two strings using the requested scorer.

Map GoldenCheck findings to recommended GoldenFlow transforms.

Parameter-sensitivity analysis: sweep one or more config parameters across a range and report how stable the clustering is at each value (CCMS unchanged %). Use it to find robust thresholds. Auto-configures the file if no config is given.

Return metadata about this GoldenMatch MCP server.

Break an entire cluster in the current run into individual records. All members become singletons. Use when a cluster is completely wrong.

Suggest a shorthand dedupe config based on a profile of the dataset.

Preview fixes for a data file without applying them. Shows what would change (columns, fix types, rows affected, before/after samples).

Check if data needs privacy-preserving matching

Search the full Golden Suite tool catalog. list_tools shows only a curated headline subset by default; use this to discover the complete set (~105 tools across goldenmatch, goldencheck, goldenflow, goldenpipe, infermap, goldenanalysis), then call any returned tool by its exact `name` (hidden tools are fully callable, just not listed). Returns each tool's name, package, description, and inputSchema.

Look up Golden Suite config / CLI / MCP tools / vocabularies / env knobs / source-file locations WITHOUT grepping the repo. Serves slices of a generated, CI-gated manifest so answers always match the live code. Usage: no args -> an overview (packages + surface counts); `package` -> that package's counts + where its schema/CLI/MCP live; `package`+`section` -> that slice (section one of config/cli/mcp/vocab/env/source); `section=rust_crates` -> the Rust crate map; `query` alone -> a keyword search across every vocabulary value, tool, config field, env var, CLI command, and crate, each with where…

Test a domain extraction rulebook against the loaded data. Shows what features would be extracted from sample records.

Transform a data file. Reads a CSV, applies transforms (auto or from config), and returns the manifest.

Remove a record from its cluster in the current run and re-cluster the remaining members using the stored pair scores (no re-scoring). The removed record becomes a singleton. Use when one record does not belong in a cluster.

Stage a dataset file server-side (base64 or text) and return its path, so a later dedupe/match tool can reference it. Does not start a run.

Validate a data file against pinned rules in goldencheck.yml. Returns validation findings (existence, required, unique, enum, range checks).

Validate pipeline wiring — every stage's consumes must be produced by an earlier stage.

Write a list of record objects to a CSV file.