> ## 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 GoldenAnalysis config options and vocabularies -- generated so it never drifts.

The exhaustive, always-current reference for GoldenAnalysis configuration.
GoldenAnalysis is read-only metrics + reporting, so its config surface is small:
`analyze(...)` keyword arguments, the regression `RegressionPolicy`, and a couple
of vocabularies. This page consolidates them into one gated reference.

<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/goldenanalysis/overview) and [Cross-run](/docs/goldenanalysis/cross-run).
</Info>

## How GoldenAnalysis is configured

* **Run knobs** are `analyze(...)` keyword arguments (see **Runtime options**):
  `analyzers` (which analyzers to run; `None` = all frame-compatible), `dataset`,
  `run_id`, `generated_at`.
* **Regression gating** uses a `RegressionPolicy` (`default_pct` plus optional
  `per_metric` overrides). A metric's `Direction` (`higher_better` /
  `lower_better` / `neutral`) decides which way a change counts as a regression,
  compared against a chosen `Baseline` (`previous` / `rolling_median` /
  `last_known_good`).
* Analyzers are an open registry (`frame.summary`, `match.rates`,
  `cluster.distribution`, `quality.rollup`, plus any third-party entry points), so
  the analyzer set is extensible and not gated here.

## Config object reference

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

### `RegressionPolicy`

*Per-metric regression thresholds (percent). Falls back to `default_pct`.*

| Field         | Type              | Default | Choices / notes                                                                                            |
| ------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `default_pct` | float             | `10.0`  | Percent change from the baseline that counts as a regression for any metric without a per-metric override. |
| `per_metric`  | dict\[str, float] | `{}`    | Per-metric percent thresholds keyed by metric name, overriding default\_pct for those metrics.             |

## Runtime options

Config passed as call keyword arguments (this package has no single config model). Generated from the signature.

### `analyze(...)`

| Argument       | Type              | Default      | Choices / notes |   |
| -------------- | ----------------- | ------------ | --------------- | - |
| `df`           | pl.DataFrame      | **required** |                 |   |
| `analyzers`    | Sequence\[str] \\ | None         | `None`          |   |
| `dataset`      | str \\            | None         | `None`          |   |
| `run_id`       | str \\            | None         | `None`          |   |
| `generated_at` | datetime \\       | None         | `None`          |   |

## CLI

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

| Command       | Option                 | Type    | Default            | Notes                                                          |
| ------------- | ---------------------- | ------- | ------------------ | -------------------------------------------------------------- |
| `mcp-serve`   | `--transport`          | text    | `'stdio'`          | stdio \| http                                                  |
| `mcp-serve`   | `--host`               | text    | `'0.0.0.0'`        | Host interface to bind when transport is http.                 |
| `mcp-serve`   | `--port`               | integer | `8300`             | HTTP port (A2A convention: Analysis = 8300).                   |
| `regressions` | `--dataset`            | text    | **required**       | Dataset name whose run history to check.                       |
| `regressions` | `--history`            | path    | **required**       | ReportHistory path (.jsonl or .db).                            |
| `regressions` | `--baseline`           | text    | `'rolling_median'` | Baseline strategy to compare against, e.g. rolling\_median.    |
| `regressions` | `--window`             | integer | `7`                | Number of prior runs the baseline is computed over.            |
| `regressions` | `--policy`             | text    | `None`             | Per-metric gates: JSON or "key=pct,key=pct".                   |
| `regressions` | `--fail-on-regression` | boolean | `False`            | Exit 1 if any regression is flagged (CI gate).                 |
| `report`      | `input`                | path    | **required**       | A .parquet/.csv frame, or a .json AnalysisReport to re-render. |
| `report`      | `--analyzers`          | text    | `'all'`            | Comma-separated analyzer names, or 'all'.                      |
| `report`      | `--format`             | text    | `'markdown'`       | markdown \| json                                               |
| `report`      | `--out`                | path    | `None`             | Write the report here instead of (also) printing.              |
| `trend`       | `--metric`             | text    | **required**       | Metric key to trend, e.g. cluster.singleton\_ratio.            |
| `trend`       | `--dataset`            | text    | **required**       | Dataset name whose run history to read.                        |
| `trend`       | `--history`            | path    | **required**       | ReportHistory path (.jsonl or .db).                            |
| `trend`       | `--last`               | integer | `30`               | Number of most recent runs to include in the trend.            |

## Enumerated vocabularies

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

### Metric direction

*`Direction` -- `Metric.direction`.*

| Value           | Meaning                                                    |
| --------------- | ---------------------------------------------------------- |
| `higher_better` | A higher value is better; flag a regression on a decrease. |
| `lower_better`  | A lower value is better; flag a regression on an increase. |
| `neutral`       | No preferred direction; never flags a regression.          |

### Regression baseline

*`Baseline` -- `--baseline`.*

| Value             | Meaning                                            |
| ----------------- | -------------------------------------------------- |
| `last_known_good` | Compare against the last run marked good.          |
| `previous`        | Compare against the immediately prior run.         |
| `rolling_median`  | Compare against the rolling median of recent runs. |

### Analyzers

*`_FALLBACK` -- `analyze(analyzers=...)`.*

| Value                  | Meaning                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `cluster.distribution` | GoldenMatch clusters: count, singletons, size percentiles, reduction ratio.               |
| `frame.summary`        | Generic frame stats: row/column counts, null ratio, duplicate ratio, memory.              |
| `match.rates`          | GoldenMatch results: pair count, match rate, threshold, recall estimate, score histogram. |
| `quality.rollup`       | GoldenCheck / GoldenFlow rollup: findings, health score, rows changed, rules fired.       |

## Environment variables (index)

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

* **NATIVE** (1): `GOLDENANALYSIS_NATIVE`

## See also

* [Overview](/docs/goldenanalysis/overview), [Cross-run](/docs/goldenanalysis/cross-run), [Native](/docs/goldenanalysis/native).