---
layout: default
title: Interactive TUI
nav_order: 6
---

# Interactive TUI

GoldenMatch includes a gold-themed terminal UI built with Textual. Launch it with `goldenmatch interactive` or `goldenmatch dedupe` (zero-config mode opens the TUI automatically).

```bash
goldenmatch interactive customers.csv
goldenmatch interactive customers.csv --config config.yaml
```

---

## 7 Tabs

The TUI has 7 tabs, accessible via keyboard shortcuts `1` through `7`.

### Tab 1: Data

Data profiling view. Shows:
- Record count, column names, data types
- Null percentages, unique value counts
- Sample values for each column
- Auto-detected column types (name, email, phone, zip, address)

### Tab 2: Config

Configuration editor. Shows:
- Auto-detected matchkeys, blocking strategy, and golden rules
- Edit thresholds, scorers, and weights inline
- Save configuration to YAML
- Run/Edit/Save buttons

### Tab 3: Matches

Split-view match results:
- **Left panel**: cluster list with IDs, sizes, and confidence scores
- **Right panel**: golden record + individual member details for selected cluster
- Live threshold slider: arrow keys adjust threshold in 0.05 increments with instant cluster count preview
- Click any cluster to inspect member records and field-level scores

### Tab 4: Golden

Golden record viewer:
- Canonical merged records
- Merge strategy applied to each field
- Source provenance for each value
- Export golden records to CSV

### Tab 5: Boost

Active learning for accuracy improvement:
- Shows borderline pairs (near the threshold)
- Label with keyboard: `y` (match), `n` (no match), `s` (skip)
- After labeling ~10 pairs, trains a LogisticRegression classifier
- Reclassifies all borderline pairs with the trained model
- Shows before/after accuracy comparison

### Tab 6: Export

Output options:
- Export golden records, duplicates, unique records
- Choose format: CSV or Parquet
- Export lineage JSON
- Generate HTML report

### Tab 7: Controller (v1.7-v1.12)

AutoConfigController telemetry from the most recent `Ctrl+A` invocation:
- Health verdict badge (green / yellow / red)
- `StopReason` with one-line hover explanation
- Committed matchkeys with `Path Y · N NE` indicator + expandable NE field rows
- Complexity profile cells (pairs, above-threshold, borderline, blocks, p99, clusters, transitivity)
- Indicator column priors table (identity / corruption scores)
- Refit decisions table (iter / rule / rationale / wall-clock)

Same JSON shape as the web `/api/v1/controller/telemetry` endpoint and the CLI `goldenmatch autoconfig` output.

---

## Keyboard shortcuts

| Key | Action |
|-----|--------|
| `1`--`7` | Jump to tab (Data, Config, Matches, Golden, Boost, Export, Controller) |
| `F5` | Run the pipeline |
| `Ctrl+A` | **Auto-configure**: run AutoConfigController; adopt config; switch to Controller tab |
| `?` | Show all keyboard shortcuts |
| `Ctrl+E` | Export results |
| `Left`/`Right` | Adjust threshold (Matches tab) |
| `y` | Label pair as match (Boost tab) |
| `n` | Label pair as non-match (Boost tab) |
| `s` | Skip pair (Boost tab) |
| `q` | Quit |

---

## Pipeline progress

On first run, the TUI shows a full-screen progress view:
- Stage tracker with status indicators (done / running / pending)
- Progress bar for the current stage
- Record count and timing

On re-runs (e.g., after threshold adjustment), progress appears in the footer bar.

---

## Auto-config summary

When launched without a config file, the first screen shows:
- Detected columns and their inferred types
- Suggested scorers for each column
- Proposed blocking strategy
- Three options: **Run** (accept and run), **Edit** (modify config), **Save** (write YAML)

---

## TUI with config file

```bash
goldenmatch interactive customers.csv --config config.yaml
```

When a config file is provided, the TUI skips auto-detection and uses the specified matchkeys, blocking, and golden rules.

---

## Screenshots

The TUI uses a dark theme with gold accents. Key views:

- **Data tab**: column profiling with null rates and type detection
- **Matches tab**: split-view cluster browser with threshold slider
- **Golden tab**: merged records with merge provenance
