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

# Installation

> Install GoldenMatch from PyPI, Docker, or as a PostgreSQL/DuckDB extension. Optional extras add embeddings, LLM scoring, database sync, and more.

## pip (recommended)

```bash theme={null}
pip install goldenmatch
```

Requires Python 3.11 or later. Core dependencies: Polars, RapidFuzz, Typer, Pydantic, Textual.

### Native acceleration (default on common platforms)

`pip install goldenmatch` now pulls the compiled `goldenmatch-native` kernel automatically on macOS (x86\_64 + arm64), Linux (x86\_64 + aarch64), and Windows (amd64). No `[native]` extra is needed; the `[native]` extra still works as a back-compat alias. The kernel accelerates the hot paths (block scoring, record fingerprints, cluster build, dedup-pairs) and lets the v3 planner pick the bucket+native backend as the suggested path up to 750k rows on common boxes.

The pure-Python + Polars pipeline is the byte-for-byte reference and the automatic fallback on any platform without a prebuilt wheel. Alpine/musl users may not get a prebuilt wheel yet (a `musllinux` wheel is a separate follow-up) and degrade gracefully to pure-Python.

Opt out with environment variables:

```bash theme={null}
GOLDENMATCH_NATIVE=0            # disable the native kernel entirely
GOLDENMATCH_PLANNER_BUCKET=0    # force the polars-direct backend
```

### Optional extras

```bash theme={null}
pip install goldenmatch[polars]         # optional COMPATIBILITY extra: the classic GOLDENMATCH_FRAME=polars lane + kernel-absent golden replay + cell-quality weighting. NOT needed for speed -- the polars-free install measures faster (the Rust kernels carry the hot paths).
pip install goldenmatch[embeddings]     # sentence-transformers + FAISS
pip install goldenmatch[llm]            # Claude/OpenAI for LLM scoring
pip install goldenmatch[postgres]       # PostgreSQL database sync
pip install goldenmatch[snowflake]      # Snowflake connector
pip install goldenmatch[bigquery]       # BigQuery connector
pip install goldenmatch[databricks]     # Databricks connector
pip install goldenmatch[salesforce]     # Salesforce connector
pip install goldenmatch[duckdb]         # DuckDB out-of-core backend
pip install goldenmatch[quality]        # GoldenCheck data quality scanning
pip install goldenmatch[ray]            # Ray distributed backend
```

Install multiple extras at once:

```bash theme={null}
pip install goldenmatch[embeddings,llm,postgres]
```

## Docker

```bash theme={null}
docker pull ghcr.io/benseverndev-oss/goldenmatch:latest

# Run a dedupe
docker run --rm -v $(pwd):/data ghcr.io/benseverndev-oss/goldenmatch:latest \
    dedupe /data/customers.csv --output-dir /data/results

# Start the REST API
docker run --rm -p 8080:8080 -v $(pwd):/data ghcr.io/benseverndev-oss/goldenmatch:latest \
    serve /data/customers.csv --port 8080
```

## PostgreSQL Extension

Pre-built packages for the SQL extension (separate from the Python package):

```bash theme={null}
# Debian/Ubuntu
sudo dpkg -i goldenmatch-pg-0.7.0-pg16-amd64.deb
sudo systemctl restart postgresql

# RHEL/Fedora
sudo rpm -i goldenmatch-pg-0.7.0-pg16.x86_64.rpm
sudo systemctl restart postgresql
```

Download `.deb` and `.rpm` from the [goldenmatch releases](https://github.com/benseverndev-oss/goldenmatch/releases) page (look for the `goldenmatch-pg-v*` tags).

### Verifying release artifacts

Releases since goldenmatch-pg v0.6.0 ship a `.sigstore` bundle alongside
each tarball. Releases published after 2026-06-05 also ship an
`.intoto.jsonl` build-provenance attestation next to each asset.

Verify a tarball with cosign (keyless, GitHub Actions OIDC):

```bash theme={null}
cosign verify-blob \
  --bundle goldenmatch_pg-0.7.0-pg17-linux-x86_64.tar.gz.sigstore \
  goldenmatch_pg-0.7.0-pg17-linux-x86_64.tar.gz \
  --certificate-identity-regexp 'github.com/benseverndev-oss/goldenmatch' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

A successful run prints `Verified OK`. The `.sigstore` bundle contains the
certificate, transparency-log entry, and signature in a single file -- no
separate key management required.

<Tip>
  Install cosign with `brew install cosign` (macOS) or
  `go install github.com/sigstore/cosign/v2/cmd/cosign@latest` (any platform).
</Tip>

## DuckDB UDFs

```bash theme={null}
pip install goldenmatch-duckdb
```

```python theme={null}
import duckdb, goldenmatch_duckdb

con = duckdb.connect()
goldenmatch_duckdb.register(con)
con.sql("SELECT goldenmatch_score('John', 'Jon', 'jaro_winkler')")
```

## dbt Integration

`dbt-goldensuite` ships inside the monorepo (not on PyPI). Add it to your `packages.yml`:

```yaml theme={null}
packages:
  - git: "https://github.com/benseverndev-oss/goldenmatch.git"
    subdirectory: "packages/dbt/goldensuite"
```

then run `dbt deps`. The package provides macros for running entity resolution, quality gates, transforms, and identity-graph reads inside dbt pipelines (DuckDB, Postgres, and Snowflake).

Zero-config Fellegi-Sunter dedupe needs no hand-written config:

```sql theme={null}
{{ config(materialized='goldenmatch_dedupe', probabilistic=true) }}
SELECT * FROM {{ ref('stg_customers') }}
```

`probabilistic=true` builds the FS model from the data (DuckDB + Postgres). Omit it for standard zero-config dedupe, or pass an explicit `match_config` for full control.

## Verify installation

```bash theme={null}
goldenmatch info
# Shows version, Python, and installed extras

goldenmatch demo
# Runs a built-in demo with sample data
```

```python theme={null}
import goldenmatch as gm
print(gm.__version__)   # "2.8.0"
```

## Environment variables

| Variable                         | Purpose                                           |
| -------------------------------- | ------------------------------------------------- |
| `OPENAI_API_KEY`                 | LLM scorer and LLM boost (OpenAI)                 |
| `ANTHROPIC_API_KEY`              | LLM scorer (Claude)                               |
| `DATABASE_URL`                   | PostgreSQL connection string for `sync` / `watch` |
| `GOOGLE_APPLICATION_CREDENTIALS` | Vertex AI embeddings (GCP service account)        |

## Setup wizard

Run the interactive wizard to configure GPU mode, API keys, and database connections:

```bash theme={null}
goldenmatch setup
```

The wizard guides you through:

* GPU mode selection (CPU, CUDA, MPS, Vertex AI, Colab)
* LLM API key configuration
* PostgreSQL connection setup
* Saved preferences at `~/.goldenmatch/settings.yaml`