> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bensevern.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API surface

> One page for the whole suite's programmatic surface — Python, TypeScript, CLI, MCP, REST, and agent skills across all six packages, with the primary entry points for each.

Every Golden Suite package exposes the same operation through several surfaces: a
Python library, a TypeScript library, a CLI, an MCP server, and — for the
service-shaped packages — a REST API and an A2A agent server. This page is the
single map of all of them. Pick a package, pick a surface, and follow the link to
its deep reference.

<Note>
  Versions below are the current release versions. Each surface versions
  independently — the TypeScript packages carry their own semver and expose a
  smaller, edge-first surface, not a lagging copy of the Python one. See
  [Python vs TypeScript: the surface boundary](#python-vs-typescript-the-surface-boundary).
</Note>

## Capability matrix

What each package ships, at a glance. **MCP** counts are the Python server's tools
(the TS server exposes a subset — see the
[surface boundary](#python-vs-typescript-the-surface-boundary)). A dash means the
package does not ship that surface.

| Package                           | Python (PyPI) | TypeScript (npm) | CLI              | MCP tools | REST | A2A | Native / SQL              |
| --------------------------------- | :-----------: | :--------------: | ---------------- | :-------: | :--: | :-: | ------------------------- |
| [GoldenMatch](#goldenmatch)       |    `3.8.0`    |     `1.14.0`     | `goldenmatch`    |     82    |   ✓  |  ✓  | wheel · Postgres · DuckDB |
| [GoldenCheck](#goldencheck)       |    `3.2.0`    |      `0.5.0`     | `goldencheck`    |     19    |   ✓  |  ✓  | wheel                     |
| [GoldenFlow](#goldenflow)         |    `2.1.0`    |     `0.16.0`     | `goldenflow`     |     10    |   ✓  |  ✓  | wheel                     |
| [GoldenPipe](#goldenpipe)         |    `1.4.0`    |      `0.3.0`     | `goldenpipe`     |     4     |   ✓  |  ✓  | core (WASM)               |
| [GoldenAnalysis](#goldenanalysis) |    `0.4.0`    |      `0.1.0`     | `goldenanalysis` |     4     |   —  |  —  | core (WASM)               |
| [InferMap](#infermap)             |    `0.6.0`    |      `0.6.0`     | `infermap`       |     4     |   —  |  —  | wheel                     |

## Python vs TypeScript: the surface boundary

The two libraries are not "a full version and a lagging copy" — they are **two
surfaces with different jobs**, and the tool-count gap is a design boundary, not
neglect:

* **Python is the fuller *stateful* server.** It holds datasets, runs, clusters, and
  the identity graph server-side, so it exposes the deeper state tools the TS surface
  doesn't — run *mutation* (`unmerge_record`, `shatter_cluster`), incremental
  resolution, and the `identity_*` audit trio — plus the subsystems that live only
  there: domain packs, PPRL, the routing planner, and document ingest.
* **TypeScript is the *edge-first* surface.** Its edge-safe core `dedupe()` returns
  stats and clusters inline, and — since it added an opt-in, node-only run store plus
  an on-disk run log on the MCP server — it now also serves the read-query tools
  (`get_stats`, `get_cluster`, `list_clusters`, `get_golden_record`, `export_results`)
  over the last run and the rollback subsystem (`list_runs`, `rollback`) over the
  `.goldenmatch_runs.json` log, so those are shared too. (These stateful tools live in
  the node-only MCP server, not the edge-safe core.) It also ships edge primitives the
  Python server doesn't: `score_strings`, `score_pair`, `find_exact_matches`,
  `find_fuzzy_matches`, `read_file`, `write_csv`, and `server_info`.

So GoldenMatch's **59 TS tools vs 82 Python** breaks down as \~51 shared operations,
8 TS-only edge helpers, and \~31 Python-only tools (run mutation, the incremental/audit
state ops, and the Python-only subsystems) — overlapping surfaces sized to their jobs,
not a subset. On the shared core the **public function names match**, and that parity
is enforced in CI by the `api_parity` gate, which fails on any *undeclared* Python↔TS
drift.

**Versions track independently.** Each surface carries its own semver — npm is not
pinned to the PyPI number — so a lower TypeScript version reflects a smaller,
slower-moving surface, not a stale one. (InferMap's TS and Python are at the same
version; GoldenGraph's TS is ahead of its Python.) See the
[versioning policy](/docs/reference/versioning) for why the lines are not kept in
lockstep and how cross-surface parity is guaranteed instead.

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install goldenmatch          # + [native] for the compiled kernel, [mcp] for the server
  pip install goldencheck goldenflow goldenpipe goldenanalysis infermap
  ```

  ```bash npm theme={null}
  npm install goldenmatch          # edge-safe core; enableWasm() opts into the Rust kernel
  npm install goldencheck goldenflow goldenpipe goldenanalysis infermap
  ```
</CodeGroup>

Each package's MCP server ships in the same distribution: `pip install <pkg>[mcp]`
(Python) or the `<pkg>-mcp` npm bin.

***

## GoldenMatch

Zero-config entity resolution: dedupe, match, cluster, survivorship, identity
graph, privacy-preserving linkage. The flagship — a native wheel, SQL extensions
(Postgres + DuckDB), REST, and A2A; the only package with a SQL surface.

**Python** — `import goldenmatch`

| Entry point                               | Does                                                                         |
| ----------------------------------------- | ---------------------------------------------------------------------------- |
| `dedupe_df(df, ...)` / `dedupe(path)`     | Deduplicate a DataFrame or file into clusters + golden records               |
| `match_df(...)` / `match(...)`            | Match a target dataset against reference sources                             |
| `auto_configure_df(df)`                   | Zero-config: infer the full `GoldenMatchConfig` from the data                |
| `AgentSession()`                          | Stateful, agent-facing ER session (`autoconfigure`, `deduplicate`, `review`) |
| `run_pprl(...)` / `pprl_link(...)`        | Privacy-preserving record linkage (Bloom filters, SMC)                       |
| `IdentityStore` / `resolve_clusters(...)` | Durable Identity Graph — stable `entity_id`s across runs                     |
| `record_fingerprint(record)`              | Stable cross-surface record-id hash                                          |

**TypeScript** — `import { dedupe, match, autoConfigureRows, enableWasm } from "goldenmatch"`

**CLI** — `goldenmatch <cmd>`: `autoconfig`, `dedupe`, `match`, `review`, `explain`,
`identity`, `pprl`, `memory`, `serve`, `serve-ui`, `mcp-serve`, `agent-serve`, … (30+ commands)

**Servers** — REST (`goldenmatch serve`: `/match`, `/autoconfig`, `/clusters`,
`/reviews`, `/controller/telemetry`, …) · A2A (`goldenmatch agent-serve`) · local
web UI (`goldenmatch serve-ui`) · **82 MCP tools**.

**Native / SQL** — `goldenmatch-native` wheel, a Postgres extension (pgrx:
`goldenmatch_dedupe`, `goldenmatch_autoconfig`, `goldenmatch_connected_components`, …),
and a DuckDB extension.

→ [Python API](/docs/goldenmatch/python-api) · [TypeScript](/docs/goldenmatch/typescript) ·
[REST](/docs/goldenmatch/rest-api) · [MCP](/docs/goldenmatch/mcp) · [Agent](/docs/goldenmatch/agent) ·
[API quick reference](/docs/goldenmatch/api-quick-reference)

***

## GoldenCheck

Data-quality scanning: profile a dataset, discover rules automatically, emit
findings with severities, auto-triage and fix, diff two versions.

**Python** — `import goldencheck`

| Entry point                              | Does                                                              |
| ---------------------------------------- | ----------------------------------------------------------------- |
| `scan_file(path)` / `scan_dataframe(df)` | Run a quality scan → `ScanResult` (findings, severities, profile) |
| `scan_file_with_llm(path)`               | Scan with LLM-assisted checks                                     |
| `validate_file(path)`                    | Rule-based validation                                             |
| `auto_triage(result)` → `TriageResult`   | Rank/route findings                                               |
| `apply_fixes(...)` → `FixReport`         | Apply suggested fixes                                             |
| `diff_files(a, b)` → `DiffReport`        | Schema / finding / stat drift between versions                    |

**TypeScript** — `import { scanData, createBaseline, runDriftChecks } from "goldencheck"`

**CLI** — `goldencheck <cmd>`: `scan`, `validate`, `fix`, `diff`, `baseline`,
`refs`, `scan-db`, `serve`, `mcp-serve`, `agent-serve`, …

**Servers** — REST (`goldencheck serve`: `/scan`, `/checks`, `/domains`) · A2A
(9 skills) · **19 MCP tools**.

**Native** — `goldencheck-native` wheel.

→ [Overview](/docs/goldencheck/overview) · [CLI](/docs/goldencheck/cli) ·
[Native](/docs/goldencheck/native) · [Integrations](/docs/goldencheck/integrations)

***

## GoldenFlow

Data transformation: 113 built-in transforms across categories (phone, date,
address, name, categorical, identifiers, …), a transform registry, schema mapping,
and owned identifier kernels (card / IBAN / ISBN / EAN / VAT / SWIFT / ABA / IMEI).

**Python** — `import goldenflow`

| Entry point                                         | Does                                    |
| --------------------------------------------------- | --------------------------------------- |
| `transform_df(df, config)` / `transform_file(path)` | Apply a transform pipeline              |
| `TransformEngine(config)`                           | Configurable engine → `TransformResult` |
| `canonicalize(value, rules)`                        | Pure scalar canonicalizers              |
| `select_transforms(profile)`                        | Auto-pick transforms from a profile     |
| `register_transform(...)` / `list_transforms()`     | The transform registry                  |
| `SchemaMapper` / `load_domain(name)`                | Schema mapping + domain packs           |

**TypeScript** — `import { TransformEngine, canonicalize, enableWasm } from "goldenflow"`

**CLI** — `goldenflow <cmd>`: `transform`, `map`, `profile`, `learn`, `diff`,
`stream`, `serve`, `mcp-serve`, `agent-serve`, …

**Servers** — REST (`goldenflow serve`: `/transforms`, `/transform`, `/map`) · A2A
(6 skills) · **10 MCP tools**.

**Native** — `goldenflow-native` wheel; the pure canonicalizers are also compiled
to a `goldenflow-core` Rust kernel (opt-in WASM in TS).

→ [Overview](/docs/goldenflow/overview) · [CLI](/docs/goldenflow/cli) · [Performance](/docs/goldenflow/performance)

***

## GoldenPipe

Pipeline orchestration: chains Check → Flow → Match into one adaptive call, with a
planner that validates stage wiring (`consumes`/`produces`), routes on decision
gates, and explains every choice.

**Python** — `import goldenpipe as gp`

| Entry point                                         | Does                                         |
| --------------------------------------------------- | -------------------------------------------- |
| `gp.run(source)` / `run_df(df)`                     | Execute the default or a configured pipeline |
| `run_stages([...])`                                 | Run an explicit list of stages               |
| `Pipeline(config)` / `PipelineConfig` / `StageSpec` | Build a custom pipeline                      |
| `stage` (decorator) / `Stage`                       | Define a programmatic stage                  |
| `severity_gate` / `pii_router` / `row_count_gate`   | Built-in decision stages                     |

The planner is a pyo3-free `goldenpipe-core` Rust kernel — the single reference
that Python and edge-TS compute identically. It auto-prepends the `load` stage,
validates each stage's `consumes` against the artifacts produced upstream (in
declared order), and raises a typed `WiringError` when an input isn't produced.
Opt into the WASM kernel in TypeScript with `enableWasm()`.

**TypeScript** — `import { runDf, Pipeline, StageRegistry, enableWasm } from "goldenpipe"`

**CLI** — `goldenpipe <cmd>`: `run`, `stages`, `validate`, `init`, `serve`,
`mcp-serve`, `agent-serve`, `interactive`.

**Servers** — REST (`goldenpipe serve`: `/stages`, `/validate`, `/run`) · A2A
(4 skills) · **4 MCP tools** (`run_pipeline`, `validate_pipeline`, `list_stages`,
`explain_pipeline`).

→ [Overview](/docs/goldenpipe/overview)

***

## GoldenAnalysis

Read-only cross-cutting reporting: run analyzers over any package's artifacts,
build trends across runs, and gate regressions.

**Python** — `import goldenanalysis`

| Entry point                                      | Does                               |
| ------------------------------------------------ | ---------------------------------- |
| `analyze(frame_or_artifacts)` → `AnalysisReport` | Run analyzers → metrics            |
| `analyze_match(...)` / `analyze_pipeline(...)`   | Package-specific entry points      |
| `ReportHistory` / `RegressionPolicy`             | Trend tracking + regression gating |

**TypeScript** — `import { analyze, buildTrend, detectRegressions } from "goldenanalysis"`

**CLI** — `goldenanalysis <cmd>`: `report`, `trend`, `regressions`, `mcp-serve`.

**Servers** — **4 MCP tools** (`analyze_frame`, `detect_regressions`, `get_trend`,
`list_analyzers`). No REST or A2A server — it is a reporting library, not a service.

→ [Overview](/docs/goldenanalysis/overview) · [Cross-run](/docs/goldenanalysis/cross-run) ·
[Native](/docs/goldenanalysis/native)

***

## InferMap

Schema / column mapping: align source columns to a target schema with Hungarian
assignment over pluggable field scorers, plus domain detection.

**Python** — `import infermap`

| Entry point                             | Does                                    |
| --------------------------------------- | --------------------------------------- |
| `map(source, target)` → `MapResult`     | Map a source schema/dataset to a target |
| `MapEngine.from_config(...)`            | Configurable mapping engine             |
| `detect_domain(...)`                    | Infer the domain pack                   |
| `extract_schema(source)` → `SchemaInfo` | Pull a schema from data                 |
| `write_aliases_from_mapping(...)`       | Persist a mapping as aliases            |

**TypeScript** — `import { map, MapEngine, detectDomain } from "infermap"`

**CLI** — `infermap <cmd>`: `map`, `apply`, `inspect`, `validate`, `mcp-serve`.

**Servers** — **4 MCP tools** (`map`, `apply`, `inspect`, `validate`). Ships the
`infermap-native` wheel (Rust core; WASM/SQL deferred); no SQL, REST, or A2A.

→ [Overview](/docs/infermap/overview)

***

## Same operation, every surface

The suite's design goal is one computation reachable identically from anywhere.
GoldenMatch's auto-config is the canonical example — the same config + telemetry
comes back whether you call it from Python, the CLI, REST, MCP, an agent, or SQL:

```python theme={null}
from goldenmatch import AgentSession
result = AgentSession().autoconfigure("customers.csv")
# result["config"]     — GoldenMatchConfig as a JSON-safe dict
# result["telemetry"]  — stop_reason, health, decisions, column priors
```

| Surface | Call                                              |
| ------- | ------------------------------------------------- |
| Python  | `AgentSession().autoconfigure(path)`              |
| CLI     | `goldenmatch autoconfig customers.csv`            |
| REST    | `POST /autoconfig` · `GET /controller/telemetry`  |
| MCP     | `auto_configure` tool                             |
| A2A     | `autoconfig` skill                                |
| SQL     | `goldenmatch_autoconfig(...)` (Postgres / DuckDB) |

## Coverage notes

* **Two surfaces, one core.** Every package has a TS twin. Python is the fuller
  stateful server; TypeScript is the edge-first surface, with its own independent
  semver. The tool-count and version differences are a design boundary,
  not lag — see [Python vs TypeScript: the surface boundary](#python-vs-typescript-the-surface-boundary).
* **REST + A2A are for the service-shaped packages only** — GoldenMatch,
  GoldenCheck, GoldenFlow, and GoldenPipe. GoldenAnalysis and InferMap ship a CLI
  and an MCP server but no long-running HTTP service.
* **Native acceleration** is a compiled Rust kernel behind a pure-Python/TS
  fallback. GoldenMatch, GoldenCheck, GoldenFlow, GoldenAnalysis, and InferMap ship
  it; GoldenPipe's `goldenpipe-core` is the planner-only reference (execution stays
  in the host language).
* **SQL extensions** (Postgres + DuckDB) are GoldenMatch-only.

<Note>
  Authoritative type signatures live in each package's source (`<pkg>/__init__.py`
  and the config schema modules). This page maps the surface; the linked deep pages
  carry the full signatures and examples.
</Note>