goldenmatch 0.1.0

package/dist/node/index.d.ts

@@ -0,0 +1,554 @@
+import { R as Row, G as GoldenMatchConfig, D as DedupeResult, a as MatchResult, B as BlockResult, M as MatchkeyConfig, P as PairKey, S as ScoredPair } from '../types-DhUdX5Rc.js';
+export { b as BlockingConfig, c as BlockingKeyConfig, d as BudgetConfig, C as CanopyConfig, e as ClusterInfo, f as ClusterProvenance, g as ColumnValue, h as DedupeStats, i as DomainConfig, E as ExactMatchkey, F as FieldProvenance, j as GoldenFieldRule, k as GoldenRulesConfig, I as InputConfig, l as InputFileConfig, L as LLMScorerConfig, m as LearningConfig, n as MakeMatchkeyConfigInput, o as MatchkeyField, p as MemoryConfig, O as OutputConfig, q as ProbabilisticMatchkey, Q as QualityConfig, r as SortKeyField, s as StandardizationConfig, T as TransformConfig, V as VALID_SCORERS, t as VALID_STANDARDIZERS, u as VALID_STRATEGIES, v as VALID_TRANSFORMS, w as ValidationConfig, x as ValidationRuleConfig, W as WeightedMatchkey, y as getMatchkeys, z as makeBlockingConfig, A as makeConfig, H as makeGoldenRulesConfig, J as makeMatchkeyConfig, K as makeMatchkeyField, N as makeScoredPair } from '../types-DhUdX5Rc.js';
+export { ANNBlocker, ANNBlockerBase, ANNBlockerOptions, AutoFixLog, AutoconfigOptions, BudgetSnapshot, BudgetTracker, BuildANNOptions, CCMSResult, ClusterExplanation, ColumnProfile, Correction, CreateANNBlockerOptions, CrossEncoderHttpError, CrossEncoderModel, CrossEncoderModelOptions, CrossEncoderOptions, CrossEncoderProvider, CrossEncoderReranker, DatasetProfile, DomainProfile, EMResult, Embedder, EmbedderError, EmbedderOptions, EmbedderProvider, EmbeddingResult, EvalResult, GatedResult, GraphERResult, HNSWANNBlocker, HNSWIndexLike, HNSWModule, HNSWOptions, LLMScoreResult, LearnedParams, LearnedPredicate, LearnedRules, LineageBundle, LineageEdge, MemoryLearner, MemoryStore, MemoryStoreConfig, PPRLConfig, PPRLResult, PairExplanation, QualityFinding, Relationship, ReviewItem, SensitivityResult, StreamProcessor, SweepParam, SweepPoint, TableSchema, TabularData, UnionFind, ValidationReport, ValidationRule, _resetCrossEncoderModelCache, addRowIds, addSourceColumn, addToCluster, applyColumnMap, applyCorrections, applyLearnedBlocks, applyStandardization, applyStandardizer, applyTransform, applyTransforms, asString, autoConfigurePPRL, autoConfigureRows, autoFixRows, buildANNBlocks, buildANNPairBlocks, buildAdaptiveBlocks, buildBlocks, buildBlocksAsync, buildClusters, buildComparisonVector, buildGoldenRecord, buildGoldenRecordWithProvenance, buildLineage, buildMst, buildMultiPassBlocks, buildStaticBlocks, compareClusters, computeClusterConfidence, computeMatchkeyValue, computeMatchkeys, concatRows, configToYaml, cosineSim, countTokensApprox, createANNBlocker, dedupe, detectDomain, diceCoefficient, ensembleScore, euclideanDist, evaluateClusters, evaluatePairs, explainCluster, explainPair, extractFeatures, findExactMatches, findExactMatchesOne, findFuzzyMatches, gatePairs, getClusterPairScores, getEmbedder, hashRow, indelDistance, indelSimilarity, isNullish, jaccardSimilarity, jaro, jaroWinkler, learnBlockingRules, levenshteinDistance, levenshteinSimilarity, lineageFromJson, lineageToJson, llmClusterPairs, llmScorePairs, loadGroundTruthPairs, match, matchOne, mergeField, metaphone, pairKey, parseConfig, parseConfigYaml, parsePairKey, profileRows, rerankPair, rerankTopPairs, runDedupePipeline, runGraphER, runMatchPipeline, runPPRL, runQualityCheck, runSensitivity, scanQuality, scoreBlocksSequential, scoreField, scoreMatrix, scorePair, scorePairRecord, scoreProbabilistic, scoreStrings, scoreStringsWithLlm, selectBestBlockingKey, soundex, soundexMatch, splitOversizedCluster, stabilityReport, toColumnValue, tokenSortRatio, trainEM, unmergeCluster, unmergeRecord, validateColumns, validateRows } from '../core/index.js';
+import { createServer } from 'node:http';
+
+/**
+ * file.ts -- CSV/JSON/JSONL file I/O connector.
+ *
+ * Node-only: uses node:fs, node:path. NOT edge-safe.
+ *
+ * CSV parser rules (CRITICAL):
+ *   - Quoted fields preserve embedded commas and newlines
+ *   - Doubled quotes inside quoted fields unescape to a single quote
+ *   - Empty unquoted fields become null
+ *   - Leading-zero strings (zip codes "01234", SSNs, phones) are NEVER
+ *     coerced to numbers
+ *   - Booleans "true"/"false" (case-insensitive) coerce to boolean
+ *   - Numeric strings coerce to number only when fully numeric and not
+ *     leading-zero
+ *   - Supports both `\n` and `\r\n` line endings
+ */
+
+interface ReadCsvOptions {
+    readonly delimiter?: string;
+    readonly hasHeader?: boolean;
+    readonly encoding?: BufferEncoding;
+}
+/**
+ * Read a CSV (or TSV, via `delimiter: "\t"`) file from disk.
+ *
+ * Returns an array of `Row` objects (header -> coerced value). If
+ * `hasHeader` is false, synthetic headers `col_0`, `col_1`, ... are used.
+ */
+declare function readCsv(path: string, options?: ReadCsvOptions): Row[];
+/**
+ * Read a JSON or JSONL file.
+ *
+ * - `.json`: expects an array of objects at the top level.
+ * - `.jsonl` / `.ndjson`: one JSON object per line.
+ *
+ * Auto-detected based on whether the first non-whitespace character is `[`.
+ */
+declare function readJson(path: string): Row[];
+/**
+ * Dispatch to readCsv / readJson based on file extension.
+ *
+ * Supported: `.csv`, `.tsv`, `.json`, `.jsonl`, `.ndjson`.
+ */
+declare function readFile(path: string): Row[];
+interface WriteCsvOptions {
+    readonly columns?: readonly string[];
+    readonly delimiter?: string;
+}
+/**
+ * Write rows to a CSV file. Creates parent directories as needed.
+ *
+ * If `columns` is not supplied, the union of keys from all rows is used,
+ * ordered by first appearance.
+ */
+declare function writeCsv(path: string, rows: readonly Row[], options?: WriteCsvOptions): void;
+/** Write rows to a JSON file as a pretty-printed array. */
+declare function writeJson(path: string, rows: readonly Row[]): void;
+
+/**
+ * dedupe-file.ts -- File-based convenience wrappers around dedupe() / match().
+ *
+ * Node-only: reads from disk, tags rows with __source__, delegates to the
+ * edge-safe core API.
+ */
+
+/**
+ * File specification. Either a bare path (source name is derived from the
+ * file's basename without extension) or a tuple `[path, sourceName]`.
+ */
+type FileSpec = string | readonly [string, string];
+interface FileDedupeOptions {
+    /** Input files. Required when calling `dedupeFile(opts)`. */
+    readonly files?: readonly FileSpec[];
+    /** Full config -- takes precedence over shorthand fields below. */
+    readonly config?: GoldenMatchConfig;
+    readonly exact?: readonly string[];
+    readonly fuzzy?: Readonly<Record<string, number>>;
+    readonly blocking?: readonly string[];
+    readonly threshold?: number;
+    /** Enable LLM scorer for borderline pairs (not yet implemented in JS). */
+    readonly llmScorer?: boolean;
+    /** Write golden records to this path (.csv or .json). */
+    readonly outputPath?: string;
+}
+/**
+ * Deduplicate records across one or more files.
+ *
+ * Each file's rows are tagged with `__source__ = <sourceName>` before being
+ * concatenated and passed to `dedupe()`.
+ *
+ * @throws if no files are provided or any file cannot be read.
+ */
+declare function dedupeFile(opts: FileDedupeOptions): DedupeResult;
+/**
+ * Match target records against a reference file.
+ *
+ * Reads both files, tags with `__source__`, and delegates to `match()`.
+ * `opts.files` (if provided) is ignored in favor of the explicit paths.
+ */
+declare function matchFiles(targetPath: string, referencePath: string, opts?: FileDedupeOptions): MatchResult;
+
+/**
+ * config-file.ts -- YAML config loading/saving from disk.
+ *
+ * Node-only. Uses `createRequire` so the optional `yaml` peer dependency
+ * is resolved lazily without breaking edge-safe ESM builds.
+ */
+
+/**
+ * Load and parse a YAML config file into a typed GoldenMatchConfig.
+ *
+ * @throws if the file cannot be read, `yaml` is not installed, or the
+ *   document does not describe a valid config.
+ */
+declare function loadConfigFile(path: string): GoldenMatchConfig;
+/**
+ * Serialize a GoldenMatchConfig to YAML and write it to disk.
+ * Creates parent directories as needed.
+ */
+declare function writeConfigFile(path: string, config: GoldenMatchConfig): void;
+
+/**
+ * base.ts -- Base connector interface and registry.
+ *
+ * Mirrors goldenmatch.connectors.base from the Python package: a small
+ * abstraction over external data sources (Snowflake, BigQuery, etc.) that
+ * exposes connect/read/close lifecycle and a name-based registry.
+ */
+
+interface ConnectorConfig {
+    readonly [key: string]: unknown;
+}
+interface ConnectorQuery {
+    readonly table: string;
+    readonly columns?: readonly string[];
+    readonly limit?: number;
+}
+interface BaseConnector {
+    readonly name: string;
+    connect(): Promise<void>;
+    read(query: string | ConnectorQuery): Promise<Row[]>;
+    close(): Promise<void>;
+}
+interface ConnectorFactory<C extends ConnectorConfig = ConnectorConfig> {
+    (config: C): BaseConnector;
+}
+declare function registerConnector(name: string, factory: ConnectorFactory): void;
+declare function loadConnector<C extends ConnectorConfig = ConnectorConfig>(name: string, config: C): BaseConnector;
+declare function listConnectors(): readonly string[];
+
+/**
+ * snowflake.ts -- Snowflake connector via the optional `snowflake-sdk` peer dep.
+ */
+
+interface SnowflakeConfig {
+    readonly account: string;
+    readonly username: string;
+    readonly password?: string;
+    readonly privateKey?: string;
+    readonly warehouse?: string;
+    readonly database?: string;
+    readonly schema?: string;
+    readonly role?: string;
+}
+declare function createSnowflakeConnector(config: SnowflakeConfig): BaseConnector;
+
+/**
+ * bigquery.ts -- Google BigQuery connector via the optional `@google-cloud/bigquery` peer dep.
+ */
+
+interface BigQueryConfig {
+    readonly projectId: string;
+    readonly keyFilename?: string;
+    readonly credentials?: Readonly<Record<string, unknown>>;
+    readonly dataset?: string;
+    readonly location?: string;
+}
+declare function createBigQueryConnector(config: BigQueryConfig): BaseConnector;
+
+/**
+ * databricks.ts -- Databricks SQL warehouse connector via the optional `@databricks/sql` peer dep.
+ */
+
+interface DatabricksConfig {
+    readonly serverHostname: string;
+    readonly httpPath: string;
+    readonly token: string;
+    readonly catalog?: string;
+    readonly schema?: string;
+}
+declare function createDatabricksConnector(config: DatabricksConfig): BaseConnector;
+
+/**
+ * salesforce.ts -- Salesforce connector using the REST API via fetch().
+ *
+ * No SDK dependency: stays edge-adjacent. Supports either a pre-issued
+ * accessToken or the OAuth 2.0 password grant flow.
+ */
+
+interface SalesforceConfig {
+    readonly instanceUrl: string;
+    readonly accessToken?: string;
+    readonly clientId?: string;
+    readonly clientSecret?: string;
+    readonly username?: string;
+    readonly password?: string;
+    readonly securityToken?: string;
+    readonly apiVersion?: string;
+}
+declare function createSalesforceConnector(config: SalesforceConfig): BaseConnector;
+
+/**
+ * hubspot.ts -- HubSpot CRM connector via REST API + fetch().
+ *
+ * `query.table` selects the HubSpot object: "contacts", "companies", "deals", etc.
+ * SQL strings are not supported -- use object queries.
+ */
+
+interface HubSpotConfig {
+    readonly apiKey: string;
+    readonly apiBase?: string;
+}
+declare function createHubSpotConnector(config: HubSpotConfig): BaseConnector;
+
+/**
+ * mcp/server.ts -- GoldenMatch MCP server (stdio transport, JSON-RPC).
+ *
+ * Node-only: uses node:fs, node:path, node:readline. NOT edge-safe.
+ *
+ * Exposes ~20 tools covering dedupe, match, scoring, explanation,
+ * profiling, auto-config (shorthand), evaluation, and listings.
+ *
+ * Every tool dispatch is wrapped in try/catch so a single failure never
+ * crashes the JSON-RPC loop; errors come back as `{ error: "<msg>" }`.
+ *
+ * Ports ideas from goldenmatch/mcp/server.py.
+ */
+
+interface Tool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+declare const TOOLS: readonly Tool[];
+declare function handleTool(name: string, rawArgs: Record<string, unknown>): Promise<unknown>;
+/**
+ * Start the MCP server reading JSON-RPC messages one per line from stdin
+ * and writing responses to stdout. Intended for Claude Desktop / any MCP
+ * client using stdio transport.
+ *
+ * Unknown methods return a JSON-RPC error. Bad JSON is logged to stderr
+ * (via console.warn) but does not crash the loop.
+ */
+declare function startMcpServer(): void;
+
+/**
+ * api/server.ts -- GoldenMatch REST API server (node:http).
+ *
+ * Node-only: uses node:http, node:path. NOT edge-safe.
+ *
+ * Endpoints:
+ *   GET  /health                     - liveness check
+ *   POST /dedupe                     - dedupe a batch of rows (JSON body)
+ *   POST /match                      - match target vs reference
+ *   POST /score                      - score two strings
+ *   POST /explain                    - explain a pair
+ *   POST /profile                    - profile a batch of rows
+ *   POST /clusters                   - return clusters from dedupe
+ *   GET  /reviews                    - list pending review items
+ *   POST /reviews/decide             - accept/reject a review item
+ *
+ * Ports ideas from goldenmatch/api/server.py.
+ */
+
+interface ReviewItem {
+    readonly id: string;
+    readonly idA: number;
+    readonly idB: number;
+    readonly score: number;
+    readonly rowA: Row;
+    readonly rowB: Row;
+    status: "pending" | "accepted" | "rejected";
+    decidedAt?: string;
+}
+declare class ReviewQueue {
+    private items;
+    enqueue(item: Omit<ReviewItem, "status" | "id"> & {
+        id?: string;
+    }): ReviewItem;
+    pending(): ReviewItem[];
+    decide(id: string, accept: boolean): ReviewItem | null;
+    all(): ReviewItem[];
+}
+interface StartApiOptions {
+    readonly port?: number;
+    readonly host?: string;
+}
+/**
+ * Start the REST API server.
+ * Default: http://127.0.0.1:8000.
+ *
+ * Returns the http.Server so tests can close it.
+ */
+declare function startApiServer(options?: StartApiOptions): ReturnType<typeof createServer>;
+
+/**
+ * a2a/server.ts -- GoldenMatch A2A (Agent-to-Agent) protocol server.
+ *
+ * Node-only: uses node:http, node:crypto. NOT edge-safe.
+ *
+ * Endpoints:
+ *   GET  /.well-known/agent.json   - agent card (10+ skills)
+ *   POST /tasks                    - create a task (skill + input)
+ *   GET  /tasks/{id}               - fetch task status/result
+ *
+ * Ports ideas from goldenmatch/a2a/server.py. This is a simpler
+ * synchronous variant (no SSE streaming, no persistent store).
+ */
+
+interface AgentSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly inputModes: readonly string[];
+    readonly outputModes: readonly string[];
+}
+declare const AGENT_CARD: {
+    readonly name: string;
+    readonly description: string;
+    readonly version: string;
+    readonly provider: {
+        readonly organization: string;
+        readonly url: string;
+    };
+    readonly capabilities: Readonly<Record<string, boolean>>;
+    readonly skills: readonly AgentSkill[];
+};
+interface StartA2aOptions {
+    readonly port?: number;
+    readonly host?: string;
+}
+declare function startA2aServer(options?: StartA2aOptions): ReturnType<typeof createServer>;
+
+/**
+ * workers.ts -- Concurrent and parallel block scoring for Node.
+ *
+ * Python uses ThreadPoolExecutor (rapidfuzz releases the GIL). JS is
+ * single-threaded by default; true parallelism requires `worker_threads`
+ * with serialization overhead that's only worth it for large blocks.
+ *
+ * This module ships two schedulers:
+ *   - `scoreBlocksConcurrent` -- Promise.all batching on the main thread.
+ *     No real parallelism, but zero setup cost and good for small/medium
+ *     block counts.
+ *   - `scoreBlocksParallel`   -- piscina-backed worker pool for true CPU
+ *     parallelism. Optional peer dep; falls back to `scoreBlocksConcurrent`
+ *     when piscina isn't installed.
+ *
+ * Mirrors the shape of `goldenmatch.backends.ray_backend.score_blocks_ray`
+ * from the Python source, but stays inside one Node process.
+ */
+
+interface WorkerPoolOptions {
+    /** Max blocks scored concurrently per batch. Defaults to 4. */
+    readonly batchSize?: number;
+}
+interface ParallelWorkerOptions {
+    /** Max worker threads. Defaults to min(8, max(2, blocks.length)). */
+    readonly maxThreads?: number;
+    /** Min worker threads kept warm. Defaults to 1. */
+    readonly minThreads?: number;
+    /** Idle timeout in ms before workers exit. Defaults to 1000. */
+    readonly idleTimeout?: number;
+}
+/**
+ * Score blocks with cooperative concurrency.
+ *
+ * - For 0 blocks: returns empty.
+ * - For <= 2 blocks: skips batching overhead and runs sequentially via
+ *   `scoreBlocksSequential` (mirrors Python's small-block fast path).
+ * - Otherwise: schedules blocks in batches of `batchSize`, awaiting each
+ *   batch with `Promise.all` so the event loop can interleave I/O.
+ *
+ * Note: `matchedPairs` is mutated as new pairs are discovered (consistent
+ * with `scoreBlocksSequential`). A frozen snapshot is used per block so
+ * concurrent batches see a stable exclusion set, matching Python's
+ * `score_blocks_parallel` contract.
+ */
+declare function scoreBlocksConcurrent(blocks: readonly BlockResult[], mk: MatchkeyConfig, matchedPairs: Set<PairKey>, options?: WorkerPoolOptions): Promise<readonly ScoredPair[]>;
+/**
+ * Score blocks in true parallel via piscina worker_threads.
+ *
+ * - For 0 blocks: returns empty.
+ * - For <= 2 blocks: runs sequentially (spinning up workers isn't worth it).
+ * - Otherwise: dispatches each block to a piscina worker that runs
+ *   `findFuzzyMatches` in its own V8 isolate, giving true CPU parallelism.
+ *
+ * Falls back to `scoreBlocksConcurrent` with a console warning if piscina
+ * isn't installed (it's an optional peer dep).
+ *
+ * `matchedPairs` is mutated in place with newly discovered pairs, matching
+ * the contract of `scoreBlocksSequential` / `scoreBlocksConcurrent`.
+ */
+declare function scoreBlocksParallel(blocks: readonly BlockResult[], mk: MatchkeyConfig, matchedPairs: Set<PairKey>, options?: ParallelWorkerOptions): Promise<readonly ScoredPair[]>;
+
+/**
+ * duckdb.ts -- Optional DuckDB connector for Node.
+ *
+ * Mirrors `goldenmatch.backends.duckdb_backend.DuckDBBackend` from Python.
+ *
+ * Peer dependency (NOT in package.json -- install on demand):
+ *   npm install @duckdb/node-api
+ *
+ * The dep is loaded via `createRequire` so the package stays importable
+ * on edge runtimes and in environments without DuckDB.
+ */
+
+interface DuckDBConfig {
+    /** Database path. Defaults to `:memory:`. */
+    readonly path?: string;
+}
+interface DuckDBConnector {
+    readTable(table: string): Promise<Row[]>;
+    readQuery(sql: string): Promise<Row[]>;
+    writeTable(table: string, rows: readonly Row[], schema?: Readonly<Record<string, string>>): Promise<void>;
+    listTables(): Promise<string[]>;
+    close(): void;
+}
+/**
+ * Create a DuckDB connector. Throws if `@duckdb/node-api` isn't installed.
+ *
+ * Async because the underlying DuckDB API is async-only (instance + connection
+ * setup both return Promises).
+ */
+declare function createDuckDBConnector(config?: DuckDBConfig): Promise<DuckDBConnector>;
+
+/**
+ * postgres.ts -- Optional Postgres connector for Node.
+ *
+ * Mirrors `goldenmatch.db.connector.PostgresConnector` from Python.
+ *
+ * Peer dependency (NOT in package.json -- install on demand):
+ *   npm install pg
+ *
+ * The dep is loaded via `createRequire` so the package stays importable
+ * on edge runtimes and in environments without Postgres.
+ */
+
+interface PostgresConfig {
+    readonly connectionString?: string;
+    readonly host?: string;
+    readonly port?: number;
+    readonly database?: string;
+    readonly user?: string;
+    readonly password?: string;
+    readonly ssl?: boolean;
+}
+interface PostgresWriteOptions {
+    readonly upsert?: boolean;
+    readonly primaryKey?: string;
+}
+interface PostgresConnector {
+    connect(): Promise<void>;
+    query<T = Row>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    readTable(table: string): Promise<Row[]>;
+    writeTable(table: string, rows: readonly Row[], options?: PostgresWriteOptions): Promise<void>;
+    listTables(schema?: string): Promise<string[]>;
+    close(): Promise<void>;
+}
+/**
+ * Create a Postgres connector. Throws if `pg` isn't installed.
+ *
+ * The returned connector requires `connect()` before any query. Inserts
+ * are batched in chunks of 1000 rows. When `options.upsert` is set, the
+ * write uses `INSERT ... ON CONFLICT (primaryKey) DO UPDATE`.
+ */
+declare function createPostgresConnector(config: PostgresConfig): PostgresConnector;
+
+/**
+ * sync.ts -- Postgres-backed dedupe sync + watch helpers.
+ *
+ * Mirrors `goldenmatch.db.sync` from Python: read source table, run
+ * dedupe, write golden + cluster tables back to Postgres.
+ */
+
+interface SyncOptions {
+    readonly pg: PostgresConfig;
+    readonly sourceTable: string;
+    readonly goldenTable: string;
+    /** Optional table to write cluster summaries (cluster_id, members, size, ...). */
+    readonly clustersTable?: string;
+    readonly config: GoldenMatchConfig;
+}
+/**
+ * Run a single dedupe pass against Postgres.
+ *
+ * 1. Read all rows from `sourceTable`.
+ * 2. Dedupe via the core pipeline.
+ * 3. Write golden records to `goldenTable`.
+ * 4. Optionally write cluster summaries to `clustersTable`.
+ *
+ * Always closes the connection on the way out.
+ */
+declare function syncDedupe(options: SyncOptions): Promise<DedupeResult>;
+interface WatchSyncOptions extends SyncOptions {
+    /** Polling interval in ms. Defaults to 60_000 (1 minute). */
+    readonly intervalMs?: number;
+}
+/**
+ * Run `syncDedupe` on a recurring interval.
+ *
+ * Returns a `stop` function. Errors in any iteration are logged via
+ * `console.warn` so the loop keeps running; callers should monitor
+ * `onResult` to confirm forward progress.
+ */
+declare function watchSync(options: WatchSyncOptions, onResult?: (result: DedupeResult) => void): Promise<() => void>;
+
+/**
+ * app.ts -- GoldenMatch interactive TUI built on `ink` (React for CLIs).
+ *
+ * This module loads `ink` and `react` lazily via `createRequire` so the rest
+ * of the package stays usable without those optional peer dependencies.
+ *
+ * The UI mirrors the Python Textual TUI: 6 tabs (Data, Config, Matches,
+ * Golden, Boost, Export) with keyboard navigation [1..6], [Tab] to cycle,
+ * [r] to run dedupe, [q] / [Esc] to quit.
+ *
+ * Richer ink-ecosystem addons (ink-table, ink-select-input, ink-text-input,
+ * ink-spinner, ink-gradient) are optional peer deps loaded lazily via
+ * ./widgets.js. Each tab degrades gracefully to plain text when an addon is
+ * not installed.
+ *
+ * Implementation notes:
+ *   - Uses React.createElement directly (no JSX) so we don't need a JSX
+ *     transform in the existing tsup build.
+ *   - The `ink` / `react` modules are typed as `any` at the boundary because
+ *     they're optional peer deps; we don't want to require `@types/react`
+ *     just to satisfy strict typecheck.
+ */
+
+interface TuiOptions {
+    readonly files?: readonly string[];
+    readonly config?: GoldenMatchConfig;
+}
+/**
+ * Launch the GoldenMatch TUI. Resolves once the user quits.
+ */
+declare function startTui(options?: TuiOptions): Promise<void>;
+
+export { AGENT_CARD, type AgentSkill, type BaseConnector, type BigQueryConfig, BlockResult, type ConnectorConfig, type ConnectorFactory, type ConnectorQuery, type DatabricksConfig, DedupeResult, type DuckDBConfig, type DuckDBConnector, type FileDedupeOptions, type FileSpec, GoldenMatchConfig, type HubSpotConfig, MatchResult, MatchkeyConfig, PairKey, type ParallelWorkerOptions, type PostgresConfig, type PostgresConnector, type PostgresWriteOptions, type ReadCsvOptions, ReviewQueue, Row, type SalesforceConfig, ScoredPair, type SnowflakeConfig, type StartA2aOptions, type StartApiOptions, type SyncOptions, TOOLS, type TuiOptions, type WatchSyncOptions, type WorkerPoolOptions, type WriteCsvOptions, createBigQueryConnector, createDatabricksConnector, createDuckDBConnector, createHubSpotConnector, createPostgresConnector, createSalesforceConnector, createSnowflakeConnector, dedupeFile, handleTool, listConnectors, loadConfigFile, loadConnector, matchFiles, readCsv, readFile, readJson, registerConnector, scoreBlocksConcurrent, scoreBlocksParallel, startA2aServer, startApiServer, startMcpServer, startTui, syncDedupe, watchSync, writeConfigFile, writeCsv, writeJson };