> ## 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.

# Config matrix

> The full matrix of GoldenPipe pipeline-config knobs and vocabularies -- generated so it never drifts.

The exhaustive, always-current reference for GoldenPipe configuration: the
`PipelineConfig` / `StageSpec` schema, the status/column/fixer vocabularies, and
every `GOLDENPIPE_*` runtime knob. Built for humans and AI agents.

<Info>
  Everything below the line is **generated from code** (`scripts/gen_config_matrix.py`)
  and verified in CI. The guidance above the line is hand-authored. See
  [Overview](/docs/goldenpipe/overview) for a walkthrough.
</Info>

## How GoldenPipe is configured

GoldenPipe is the orchestrator: a `PipelineConfig` is a thin envelope over a list
of **stages**, and each stage delegates its real tuning to the suite tool it
adapts.

* **`stages`** -- a list of `StageSpec{name, use, needs, skip_if, on_error, config}`.
  `use` names the adapter (e.g. `goldencheck.scan`, `goldenflow.transform`,
  `goldenmatch.dedupe`, `goldenanalysis.report`); `config` is a free-form dict
  passed straight to that tool. **So the deep knobs for a stage live in that
  tool's own config matrix** -- see [GoldenMatch](/docs/goldenmatch/config-matrix),
  [GoldenCheck](/docs/goldencheck/config-matrix), [GoldenFlow](/docs/goldenflow/config-matrix),
  [GoldenAnalysis](/docs/goldenanalysis/config-matrix).
* **`on_error`** per stage is `continue` (default) or `abort`.
* Adapter/stage names are packaging **entry points** discovered at runtime
  (`StageRegistry`), so the set is open/extensible and not gated here; the
  built-ins are `load`, `infer_schema`, `goldencheck.scan`, `goldenflow.transform`,
  `goldenmatch.dedupe`, `goldenmatch.dedupe_fused`, `goldenmatch.identity_resolve`,
  `goldenanalysis.report`.

## Config object reference

Every config object in the pydantic tree(s), generated from the package schema. Nested objects link by name.

### `PipelineConfig`

*Top-level pipeline configuration.*

| Field       | Type                    | Default      | Choices / notes                                                                                                                             |
| ----------- | ----------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `pipeline`  | str                     | **required** | Name of the pipeline, identifying this end-to-end configuration in runs and logs.                                                           |
| `source`    | str \| None             | `None`       | Optional default input location that stages read from when they do not specify their own source.                                            |
| `output`    | str \| None             | `None`       | Optional default destination where the pipeline writes its final results.                                                                   |
| `stages`    | list\[StageSpec \| str] | **required** | [`StageSpec`](#stagespec) -- Ordered list of stages to run, each given as a full StageSpec or a shorthand string naming the adapter to use. |
| `decisions` | list\[str]              | `[]`         | Recorded pipeline decision entries that capture the choices and rationale behind this configuration.                                        |

### `StageSpec`

*Configuration for a single pipeline stage.*

| Field      | Type            | Default      | Choices / notes                                                                                                             |
| ---------- | --------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `name`     | str \| None     | `None`       | Optional human-readable label for this stage, used in logs and as the key other stages reference in their needs list.       |
| `use`      | str             | **required** | Identifier of the adapter that runs this stage, such as goldenmatch.dedupe, naming which suite tool to invoke.              |
| `needs`    | list\[str]      | `[]`         | Names of stages that must finish before this one runs, defining the dependency order in the pipeline graph.                 |
| `skip_if`  | str \| None     | `None`       | Condition expression that, when it evaluates true at runtime, causes this stage to be skipped rather than executed.         |
| `on_error` | Literal         | `'continue'` | `continue`, `abort` -- What to do when this stage raises an error: continue on to later stages or abort the whole pipeline. |
| `config`   | dict\[str, Any] | `{}`         | Free-form settings dictionary passed straight through to the named adapter to configure how the tool runs.                  |

## CLI

Every command and its options/arguments, generated from the Typer app. `choice`-typed options list their allowed values.

| Command       | Option                      | Type    | Default      | Notes                                                                                                               |
| ------------- | --------------------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `agent-serve` | `--port`                    | integer | `8250`       | Port for A2A server                                                                                                 |
| `init`        | `--dir`                     | text    | `'.'`        | Directory to create config in                                                                                       |
| `interactive` | `source`                    | text    | `None`       | Optional data file to load (press 'r' to run).                                                                      |
| `interactive` | `--config`                  | text    | `None`       | Optional pipeline YAML config.                                                                                      |
| `mcp-serve`   | `--transport`               | text    | `'stdio'`    | Transport type: stdio or http                                                                                       |
| `mcp-serve`   | `--host`                    | text    | `'0.0.0.0'`  | Host for HTTP transport                                                                                             |
| `mcp-serve`   | `--port`                    | integer | `8250`       | Port for HTTP transport                                                                                             |
| `run`         | `source`                    | text    | **required** | Input file path                                                                                                     |
| `run`         | `--config`                  | text    | `None`       | Pipeline YAML config                                                                                                |
| `run`         | `--output`                  | text    | `None`       | Output file path                                                                                                    |
| `run`         | `--verbose`                 | boolean | `False`      | Show reasoning and timing                                                                                           |
| `run`         | `--identity-path`           | text    | `None`       | Enable Identity Graph; persist to this SQLite path                                                                  |
| `run`         | `--identity-dataset`        | text    | `None`       | Identity Graph dataset namespace                                                                                    |
| `run`         | `--identity-source-pk`      | text    | `None`       | Column to derive `&#123;source&#125;:&#123;source_pk&#125;` record\_id from                                         |
| `run`         | `--identity-weak-threshold` | float   | `None`       | Auto-flag bottleneck pair as conflicts\_with when cluster confidence \< this. Defaults to 0.6 (per IdentityConfig). |
| `serve`       | `--port`                    | integer | `8000`       | Port for REST API                                                                                                   |
| `validate`    | `--config`                  | text    | **required** | Pipeline YAML config                                                                                                |

## MCP tools

4 MCP tool(s) exposed by `goldenpipe.mcp.server` -- the programmatic / agent surface. Config-bearing tools take the same knobs as above.

| Tool                | Description                                                                                                                                                                                                                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `explain_pipeline`  | Explain what a pipeline config does                                                                                                                                                                                                                                                                                          |
| `list_stages`       | List all discovered pipeline stages                                                                                                                                                                                                                                                                                          |
| `run_pipeline`      | Run a pipeline on a file OR inline data (records / csv\_text) and return per-stage status, reasoning and timing PLUS the deduped output (golden-record count + preview, unique/duplicate counts, cluster count, match stats). Give a `stages` list or `config_path` to control the chain, or omit both for zero-config auto. |
| `validate_pipeline` | Validate pipeline wiring                                                                                                                                                                                                                                                                                                     |

## Enumerated vocabularies

Allowed values for the `str`-typed / registry-backed fields above.

### Stage status

*`StageStatus` -- per-stage result status.*

| Value     | Meaning                                  |
| --------- | ---------------------------------------- |
| `failed`  | Stage raised an error.                   |
| `skipped` | Stage skipped by its skip\_if condition. |
| `success` | Stage completed successfully.            |

### Pipeline status

*`PipeStatus` -- run result status.*

| Value     | Meaning                                |
| --------- | -------------------------------------- |
| `failed`  | One or more stages failed the run.     |
| `partial` | Some stages succeeded and some failed. |
| `success` | Every stage succeeded.                 |

### Column types

*`ColumnType` -- column classification.*

| Value         | Meaning                  |
| ------------- | ------------------------ |
| `address`     | Postal address.          |
| `date`        | Date/time value.         |
| `description` | Long free text.          |
| `email`       | Email address.           |
| `geo`         | Geographic coordinate.   |
| `identifier`  | Unique identifier / key. |
| `name`        | Person or entity name.   |
| `numeric`     | Numeric measure.         |
| `phone`       | Phone number.            |
| `string`      | Free-form string.        |
| `zip`         | Postal/ZIP code.         |

### Cardinality bands

*`CardinalityBand` -- column cardinality band.*

| Value  | Meaning                             |
| ------ | ----------------------------------- |
| \`\`   | Unset / unknown.                    |
| `high` | Many distinct values (near-unique). |
| `low`  | Few distinct values.                |
| `mid`  | Moderate distinct values.           |
| `skip` | Excluded from cardinality analysis. |

### Repair fixers

*`FIXERS` -- repair-op allowlist.*

| Value               | Meaning                                   |
| ------------------- | ----------------------------------------- |
| `date_parse`        | Parse a date into ISO form.               |
| `email_canonical`   | Canonicalize an email (dedupe dots/plus). |
| `email_normalize`   | Lowercase/normalize an email.             |
| `fix_mojibake`      | Repair UTF-8/Latin-1 mojibake.            |
| `name_proper`       | Proper-case a name.                       |
| `normalize_unicode` | Normalize to Unicode NFC.                 |
| `phone_national`    | Normalize a phone to national format.     |
| `zip_normalize`     | Normalize a ZIP code.                     |

### Stages

*`BUILTIN_STAGES` -- `StageSpec.use`.*

| Value                          | Meaning                                      |
| ------------------------------ | -------------------------------------------- |
| `goldenanalysis.report`        | Run GoldenAnalysis metrics + reporting.      |
| `goldencheck.scan`             | Run a GoldenCheck data-quality scan.         |
| `goldenflow.transform`         | Run GoldenFlow transforms / standardization. |
| `goldenmatch.dedupe`           | Run GoldenMatch dedupe / entity resolution.  |
| `goldenmatch.dedupe_fused`     | Run the fused GoldenMatch dedupe kernel.     |
| `goldenmatch.identity_resolve` | Resolve records against the identity graph.  |
| `infer_schema`                 | Infer the source schema (via infermap).      |
| `load`                         | Load a source file into the pipeline frame.  |

## Environment variables (index)

1 `GOLDENPIPE_*` runtime knob(s) read by the package, scanned from source so this is complete. Grouped by area:

* **NATIVE** (1): `GOLDENPIPE_NATIVE`

## See also

* [Overview](/docs/goldenpipe/overview) and each stage tool's own config matrix (linked above).