goldenmatch 0.1.0

package/dist/types-DhUdX5Rc.d.cts

@@ -0,0 +1,304 @@
+/**
+ * types.ts — GoldenMatch config interfaces and result types.
+ * Edge-safe: no Node.js imports, no `process`.
+ */
+type ColumnValue = string | number | boolean | null;
+type Row = Readonly<Record<string, unknown>>;
+/** A canonical pair key in the form "minId:maxId". Only produced by pairKey(). */
+type PairKey = string & {
+    readonly __brand: "PairKey";
+};
+interface MatchkeyField {
+    readonly field: string;
+    readonly transforms: readonly string[];
+    readonly scorer: string;
+    readonly weight: number;
+    readonly model?: string;
+    readonly columns?: readonly string[];
+    readonly columnWeights?: Readonly<Record<string, number>>;
+    readonly levels?: number;
+    readonly partialThreshold?: number;
+}
+interface ExactMatchkey {
+    readonly name: string;
+    readonly type: "exact";
+    readonly fields: readonly MatchkeyField[];
+}
+interface WeightedMatchkey {
+    readonly name: string;
+    readonly type: "weighted";
+    readonly fields: readonly MatchkeyField[];
+    readonly threshold: number;
+    readonly autoThreshold?: boolean;
+    readonly rerank?: boolean;
+    readonly rerankModel?: string;
+    readonly rerankBand?: number;
+}
+interface ProbabilisticMatchkey {
+    readonly name: string;
+    readonly type: "probabilistic";
+    readonly fields: readonly MatchkeyField[];
+    readonly threshold?: number;
+    readonly emIterations?: number;
+    readonly convergenceThreshold?: number;
+    readonly linkThreshold?: number;
+    readonly reviewThreshold?: number;
+}
+type MatchkeyConfig = ExactMatchkey | WeightedMatchkey | ProbabilisticMatchkey;
+interface BlockingKeyConfig {
+    readonly fields: readonly string[];
+    readonly transforms: readonly string[];
+}
+interface SortKeyField {
+    readonly column: string;
+    readonly transforms: readonly string[];
+}
+interface CanopyConfig {
+    readonly fields: readonly string[];
+    readonly looseThreshold: number;
+    readonly tightThreshold: number;
+    readonly maxCanopySize: number;
+}
+interface BlockingConfig {
+    readonly strategy: "static" | "adaptive" | "sorted_neighborhood" | "multi_pass" | "ann" | "canopy" | "ann_pairs" | "learned";
+    readonly keys: readonly BlockingKeyConfig[];
+    readonly maxBlockSize: number;
+    readonly skipOversized: boolean;
+    readonly autoSuggest?: boolean;
+    readonly autoSelect?: boolean;
+    readonly subBlockKeys?: readonly BlockingKeyConfig[];
+    readonly windowSize?: number;
+    readonly sortKey?: readonly SortKeyField[];
+    readonly passes?: readonly BlockingKeyConfig[];
+    readonly unionMode?: boolean;
+    readonly maxTotalComparisons?: number;
+    readonly annColumn?: string;
+    readonly annModel?: string;
+    readonly annTopK?: number;
+    readonly canopy?: CanopyConfig;
+    readonly learnedSampleSize?: number;
+    readonly learnedMinRecall?: number;
+    readonly learnedMinReduction?: number;
+    readonly learnedPredicateDepth?: number;
+    readonly learnedCachePath?: string;
+}
+interface GoldenFieldRule {
+    readonly strategy: "most_complete" | "majority_vote" | "source_priority" | "most_recent" | "first_non_null";
+    readonly dateColumn?: string;
+    readonly sourcePriority?: readonly string[];
+}
+interface GoldenRulesConfig {
+    readonly defaultStrategy: string;
+    readonly fieldRules: Readonly<Record<string, GoldenFieldRule>>;
+    readonly maxClusterSize: number;
+    readonly autoSplit: boolean;
+    readonly qualityWeighting: boolean;
+    readonly weakClusterThreshold: number;
+}
+interface StandardizationConfig {
+    readonly rules: Readonly<Record<string, readonly string[]>>;
+}
+interface ValidationRuleConfig {
+    readonly column: string;
+    readonly ruleType: "regex" | "min_length" | "max_length" | "not_null" | "in_set" | "format";
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly action: "null" | "quarantine" | "flag";
+}
+interface ValidationConfig {
+    readonly rules: readonly ValidationRuleConfig[];
+    readonly autoFix: boolean;
+}
+interface QualityConfig {
+    readonly enabled: boolean;
+    readonly mode: "silent" | "announced" | "disabled";
+    readonly fixMode: "safe" | "moderate" | "none";
+    readonly domain?: string;
+}
+interface TransformConfig {
+    readonly enabled: boolean;
+    readonly mode: "silent" | "announced" | "disabled";
+}
+interface BudgetConfig {
+    readonly maxCostUsd?: number;
+    readonly maxCalls?: number;
+    readonly escalationModel?: string;
+    readonly escalationBand?: readonly number[];
+    readonly escalationBudgetPct?: number;
+    readonly warnAtPct?: number;
+}
+interface LLMScorerConfig {
+    readonly enabled: boolean;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly autoThreshold: number;
+    readonly candidateLo: number;
+    readonly candidateHi: number;
+    readonly batchSize: number;
+    readonly maxWorkers: number;
+    readonly budget?: BudgetConfig;
+    readonly mode: "pairwise" | "cluster";
+    readonly clusterMaxSize?: number;
+    readonly clusterMinSize?: number;
+}
+interface DomainConfig {
+    readonly enabled: boolean;
+    readonly mode?: string;
+    readonly confidenceThreshold: number;
+    readonly llmValidation: boolean;
+    readonly budget?: BudgetConfig;
+}
+interface LearningConfig {
+    readonly thresholdMinCorrections: number;
+    readonly weightsMinCorrections: number;
+}
+interface MemoryConfig {
+    readonly enabled: boolean;
+    readonly backend: "sqlite" | "postgres";
+    readonly path?: string;
+    readonly trust: number;
+    readonly learning: LearningConfig;
+}
+interface InputFileConfig {
+    readonly path: string;
+    readonly idColumn?: string;
+    readonly sourceLabel?: string;
+    readonly sourceName?: string;
+    readonly columnMap?: Readonly<Record<string, string>>;
+    readonly delimiter?: string;
+    readonly encoding?: string;
+    readonly sheet?: string;
+    readonly parseMode?: string;
+    readonly headerRow?: number;
+    readonly hasHeader?: boolean;
+    readonly skipRows?: readonly number[];
+}
+interface InputConfig {
+    readonly files: readonly InputFileConfig[];
+    readonly fileA?: InputFileConfig;
+    readonly fileB?: InputFileConfig;
+}
+interface OutputConfig {
+    readonly path?: string;
+    readonly format?: string;
+    readonly directory?: string;
+    readonly runName?: string;
+}
+interface GoldenMatchConfig {
+    readonly matchkeys?: readonly MatchkeyConfig[];
+    readonly matchSettings?: readonly MatchkeyConfig[];
+    readonly blocking?: BlockingConfig;
+    readonly threshold?: number;
+    readonly goldenRules?: GoldenRulesConfig;
+    readonly standardization?: StandardizationConfig;
+    readonly validation?: ValidationConfig;
+    readonly quality?: QualityConfig;
+    readonly transform?: TransformConfig;
+    readonly llmScorer?: LLMScorerConfig;
+    readonly domain?: DomainConfig;
+    readonly memory?: MemoryConfig;
+    readonly input?: InputConfig;
+    readonly output?: OutputConfig;
+    readonly backend?: string;
+    readonly llmAuto?: boolean;
+    readonly llmBoost?: boolean;
+}
+interface ScoredPair {
+    readonly idA: number;
+    readonly idB: number;
+    readonly score: number;
+}
+interface ClusterInfo {
+    readonly members: readonly number[];
+    readonly size: number;
+    readonly oversized: boolean;
+    readonly pairScores: ReadonlyMap<PairKey, number>;
+    readonly confidence: number;
+    readonly bottleneckPair: readonly [number, number] | null;
+    readonly clusterQuality: "strong" | "weak" | "split";
+}
+interface DedupeStats {
+    readonly totalRecords: number;
+    readonly totalClusters: number;
+    readonly matchRate: number;
+    readonly matchedRecords: number;
+    readonly uniqueRecords: number;
+}
+interface DedupeResult {
+    readonly goldenRecords: readonly Row[];
+    readonly clusters: ReadonlyMap<number, ClusterInfo>;
+    readonly dupes: readonly Row[];
+    readonly unique: readonly Row[];
+    readonly stats: DedupeStats;
+    readonly scoredPairs: readonly ScoredPair[];
+    readonly config: GoldenMatchConfig;
+}
+interface MatchResult {
+    readonly matched: readonly Row[];
+    readonly unmatched: readonly Row[];
+    readonly stats: Readonly<Record<string, unknown>>;
+}
+interface FieldProvenance {
+    readonly value: unknown;
+    readonly sourceRowId: number;
+    readonly strategy: string;
+    readonly confidence: number;
+    readonly candidates: readonly Readonly<Record<string, unknown>>[];
+}
+interface ClusterProvenance {
+    readonly clusterId: number;
+    readonly clusterQuality: string;
+    readonly clusterConfidence: number;
+    readonly fields: Readonly<Record<string, FieldProvenance>>;
+}
+interface BlockResult {
+    readonly blockKey: string;
+    readonly rows: readonly Row[];
+    readonly strategy: string;
+    readonly depth: number;
+    readonly parentKey?: string;
+    readonly preScoredPairs?: readonly ScoredPair[];
+}
+declare const VALID_SCORERS: Set<"exact" | "jaro_winkler" | "levenshtein" | "token_sort" | "soundex_match" | "embedding" | "record_embedding" | "ensemble" | "dice" | "jaccard">;
+declare const VALID_TRANSFORMS: Set<"token_sort" | "lowercase" | "uppercase" | "strip" | "strip_all" | "soundex" | "metaphone" | "digits_only" | "alpha_only" | "normalize_whitespace" | "first_token" | "last_token">;
+declare const VALID_STRATEGIES: Set<"most_complete" | "majority_vote" | "source_priority" | "most_recent" | "first_non_null">;
+declare const VALID_STANDARDIZERS: Set<"strip" | "email" | "name_proper" | "name_upper" | "name_lower" | "phone" | "zip5" | "address" | "state" | "trim_whitespace">;
+/**
+ * Create a ScoredPair guaranteeing idA <= idB (canonical order).
+ * Always use this instead of constructing `{ idA, idB, score }` directly.
+ */
+declare function makeScoredPair(a: number, b: number, score: number): ScoredPair;
+/** Create a MatchkeyField with sensible defaults. */
+declare function makeMatchkeyField(partial: Partial<MatchkeyField> & Pick<MatchkeyField, "field">): MatchkeyField;
+/**
+ * Shape accepted by `makeMatchkeyConfig`. All variant-specific fields are
+ * optional; the factory picks the right variant based on `type`.
+ */
+interface MakeMatchkeyConfigInput {
+    readonly name: string;
+    readonly type?: "exact" | "weighted" | "probabilistic";
+    readonly fields?: readonly MatchkeyField[];
+    readonly threshold?: number;
+    readonly autoThreshold?: boolean;
+    readonly rerank?: boolean;
+    readonly rerankModel?: string;
+    readonly rerankBand?: number;
+    readonly emIterations?: number;
+    readonly convergenceThreshold?: number;
+    readonly linkThreshold?: number;
+    readonly reviewThreshold?: number;
+}
+/** Create a MatchkeyConfig with sensible defaults. Produces the correct variant. */
+declare function makeMatchkeyConfig(partial: MakeMatchkeyConfigInput): MatchkeyConfig;
+/** Create a BlockingConfig with sensible defaults. */
+declare function makeBlockingConfig(partial?: Partial<BlockingConfig>): BlockingConfig;
+/** Create a GoldenRulesConfig with sensible defaults. */
+declare function makeGoldenRulesConfig(partial?: Partial<GoldenRulesConfig>): GoldenRulesConfig;
+/** Create a full GoldenMatchConfig with sensible defaults. */
+declare function makeConfig(partial?: Partial<GoldenMatchConfig>): GoldenMatchConfig;
+/**
+ * Return matchkeys from config, checking both `matchkeys` and `matchSettings`.
+ * Mirrors Python's `GoldenMatchConfig.get_matchkeys()`.
+ */
+declare function getMatchkeys(config: GoldenMatchConfig): readonly MatchkeyConfig[];
+
+export { makeConfig as A, type BlockResult as B, type CanopyConfig as C, type DedupeResult as D, type ExactMatchkey as E, type FieldProvenance as F, type GoldenMatchConfig as G, makeGoldenRulesConfig as H, type InputConfig as I, makeMatchkeyConfig as J, makeMatchkeyField as K, type LLMScorerConfig as L, type MatchkeyConfig as M, makeScoredPair as N, type OutputConfig as O, type PairKey as P, type QualityConfig as Q, type Row as R, type ScoredPair as S, type TransformConfig as T, VALID_SCORERS as V, type WeightedMatchkey as W, type MatchResult as a, type BlockingConfig as b, type BlockingKeyConfig as c, type BudgetConfig as d, type ClusterInfo as e, type ClusterProvenance as f, type ColumnValue as g, type DedupeStats as h, type DomainConfig as i, type GoldenFieldRule as j, type GoldenRulesConfig as k, type InputFileConfig as l, type LearningConfig as m, type MakeMatchkeyConfigInput as n, type MatchkeyField as o, type MemoryConfig as p, type ProbabilisticMatchkey as q, type SortKeyField as r, type StandardizationConfig as s, VALID_STANDARDIZERS as t, VALID_STRATEGIES as u, VALID_TRANSFORMS as v, type ValidationConfig as w, type ValidationRuleConfig as x, getMatchkeys as y, makeBlockingConfig as z };

package/dist/types-DhUdX5Rc.d.ts

@@ -0,0 +1,304 @@
+/**
+ * types.ts — GoldenMatch config interfaces and result types.
+ * Edge-safe: no Node.js imports, no `process`.
+ */
+type ColumnValue = string | number | boolean | null;
+type Row = Readonly<Record<string, unknown>>;
+/** A canonical pair key in the form "minId:maxId". Only produced by pairKey(). */
+type PairKey = string & {
+    readonly __brand: "PairKey";
+};
+interface MatchkeyField {
+    readonly field: string;
+    readonly transforms: readonly string[];
+    readonly scorer: string;
+    readonly weight: number;
+    readonly model?: string;
+    readonly columns?: readonly string[];
+    readonly columnWeights?: Readonly<Record<string, number>>;
+    readonly levels?: number;
+    readonly partialThreshold?: number;
+}
+interface ExactMatchkey {
+    readonly name: string;
+    readonly type: "exact";
+    readonly fields: readonly MatchkeyField[];
+}
+interface WeightedMatchkey {
+    readonly name: string;
+    readonly type: "weighted";
+    readonly fields: readonly MatchkeyField[];
+    readonly threshold: number;
+    readonly autoThreshold?: boolean;
+    readonly rerank?: boolean;
+    readonly rerankModel?: string;
+    readonly rerankBand?: number;
+}
+interface ProbabilisticMatchkey {
+    readonly name: string;
+    readonly type: "probabilistic";
+    readonly fields: readonly MatchkeyField[];
+    readonly threshold?: number;
+    readonly emIterations?: number;
+    readonly convergenceThreshold?: number;
+    readonly linkThreshold?: number;
+    readonly reviewThreshold?: number;
+}
+type MatchkeyConfig = ExactMatchkey | WeightedMatchkey | ProbabilisticMatchkey;
+interface BlockingKeyConfig {
+    readonly fields: readonly string[];
+    readonly transforms: readonly string[];
+}
+interface SortKeyField {
+    readonly column: string;
+    readonly transforms: readonly string[];
+}
+interface CanopyConfig {
+    readonly fields: readonly string[];
+    readonly looseThreshold: number;
+    readonly tightThreshold: number;
+    readonly maxCanopySize: number;
+}
+interface BlockingConfig {
+    readonly strategy: "static" | "adaptive" | "sorted_neighborhood" | "multi_pass" | "ann" | "canopy" | "ann_pairs" | "learned";
+    readonly keys: readonly BlockingKeyConfig[];
+    readonly maxBlockSize: number;
+    readonly skipOversized: boolean;
+    readonly autoSuggest?: boolean;
+    readonly autoSelect?: boolean;
+    readonly subBlockKeys?: readonly BlockingKeyConfig[];
+    readonly windowSize?: number;
+    readonly sortKey?: readonly SortKeyField[];
+    readonly passes?: readonly BlockingKeyConfig[];
+    readonly unionMode?: boolean;
+    readonly maxTotalComparisons?: number;
+    readonly annColumn?: string;
+    readonly annModel?: string;
+    readonly annTopK?: number;
+    readonly canopy?: CanopyConfig;
+    readonly learnedSampleSize?: number;
+    readonly learnedMinRecall?: number;
+    readonly learnedMinReduction?: number;
+    readonly learnedPredicateDepth?: number;
+    readonly learnedCachePath?: string;
+}
+interface GoldenFieldRule {
+    readonly strategy: "most_complete" | "majority_vote" | "source_priority" | "most_recent" | "first_non_null";
+    readonly dateColumn?: string;
+    readonly sourcePriority?: readonly string[];
+}
+interface GoldenRulesConfig {
+    readonly defaultStrategy: string;
+    readonly fieldRules: Readonly<Record<string, GoldenFieldRule>>;
+    readonly maxClusterSize: number;
+    readonly autoSplit: boolean;
+    readonly qualityWeighting: boolean;
+    readonly weakClusterThreshold: number;
+}
+interface StandardizationConfig {
+    readonly rules: Readonly<Record<string, readonly string[]>>;
+}
+interface ValidationRuleConfig {
+    readonly column: string;
+    readonly ruleType: "regex" | "min_length" | "max_length" | "not_null" | "in_set" | "format";
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly action: "null" | "quarantine" | "flag";
+}
+interface ValidationConfig {
+    readonly rules: readonly ValidationRuleConfig[];
+    readonly autoFix: boolean;
+}
+interface QualityConfig {
+    readonly enabled: boolean;
+    readonly mode: "silent" | "announced" | "disabled";
+    readonly fixMode: "safe" | "moderate" | "none";
+    readonly domain?: string;
+}
+interface TransformConfig {
+    readonly enabled: boolean;
+    readonly mode: "silent" | "announced" | "disabled";
+}
+interface BudgetConfig {
+    readonly maxCostUsd?: number;
+    readonly maxCalls?: number;
+    readonly escalationModel?: string;
+    readonly escalationBand?: readonly number[];
+    readonly escalationBudgetPct?: number;
+    readonly warnAtPct?: number;
+}
+interface LLMScorerConfig {
+    readonly enabled: boolean;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly autoThreshold: number;
+    readonly candidateLo: number;
+    readonly candidateHi: number;
+    readonly batchSize: number;
+    readonly maxWorkers: number;
+    readonly budget?: BudgetConfig;
+    readonly mode: "pairwise" | "cluster";
+    readonly clusterMaxSize?: number;
+    readonly clusterMinSize?: number;
+}
+interface DomainConfig {
+    readonly enabled: boolean;
+    readonly mode?: string;
+    readonly confidenceThreshold: number;
+    readonly llmValidation: boolean;
+    readonly budget?: BudgetConfig;
+}
+interface LearningConfig {
+    readonly thresholdMinCorrections: number;
+    readonly weightsMinCorrections: number;
+}
+interface MemoryConfig {
+    readonly enabled: boolean;
+    readonly backend: "sqlite" | "postgres";
+    readonly path?: string;
+    readonly trust: number;
+    readonly learning: LearningConfig;
+}
+interface InputFileConfig {
+    readonly path: string;
+    readonly idColumn?: string;
+    readonly sourceLabel?: string;
+    readonly sourceName?: string;
+    readonly columnMap?: Readonly<Record<string, string>>;
+    readonly delimiter?: string;
+    readonly encoding?: string;
+    readonly sheet?: string;
+    readonly parseMode?: string;
+    readonly headerRow?: number;
+    readonly hasHeader?: boolean;
+    readonly skipRows?: readonly number[];
+}
+interface InputConfig {
+    readonly files: readonly InputFileConfig[];
+    readonly fileA?: InputFileConfig;
+    readonly fileB?: InputFileConfig;
+}
+interface OutputConfig {
+    readonly path?: string;
+    readonly format?: string;
+    readonly directory?: string;
+    readonly runName?: string;
+}
+interface GoldenMatchConfig {
+    readonly matchkeys?: readonly MatchkeyConfig[];
+    readonly matchSettings?: readonly MatchkeyConfig[];
+    readonly blocking?: BlockingConfig;
+    readonly threshold?: number;
+    readonly goldenRules?: GoldenRulesConfig;
+    readonly standardization?: StandardizationConfig;
+    readonly validation?: ValidationConfig;
+    readonly quality?: QualityConfig;
+    readonly transform?: TransformConfig;
+    readonly llmScorer?: LLMScorerConfig;
+    readonly domain?: DomainConfig;
+    readonly memory?: MemoryConfig;
+    readonly input?: InputConfig;
+    readonly output?: OutputConfig;
+    readonly backend?: string;
+    readonly llmAuto?: boolean;
+    readonly llmBoost?: boolean;
+}
+interface ScoredPair {
+    readonly idA: number;
+    readonly idB: number;
+    readonly score: number;
+}
+interface ClusterInfo {
+    readonly members: readonly number[];
+    readonly size: number;
+    readonly oversized: boolean;
+    readonly pairScores: ReadonlyMap<PairKey, number>;
+    readonly confidence: number;
+    readonly bottleneckPair: readonly [number, number] | null;
+    readonly clusterQuality: "strong" | "weak" | "split";
+}
+interface DedupeStats {
+    readonly totalRecords: number;
+    readonly totalClusters: number;
+    readonly matchRate: number;
+    readonly matchedRecords: number;
+    readonly uniqueRecords: number;
+}
+interface DedupeResult {
+    readonly goldenRecords: readonly Row[];
+    readonly clusters: ReadonlyMap<number, ClusterInfo>;
+    readonly dupes: readonly Row[];
+    readonly unique: readonly Row[];
+    readonly stats: DedupeStats;
+    readonly scoredPairs: readonly ScoredPair[];
+    readonly config: GoldenMatchConfig;
+}
+interface MatchResult {
+    readonly matched: readonly Row[];
+    readonly unmatched: readonly Row[];
+    readonly stats: Readonly<Record<string, unknown>>;
+}
+interface FieldProvenance {
+    readonly value: unknown;
+    readonly sourceRowId: number;
+    readonly strategy: string;
+    readonly confidence: number;
+    readonly candidates: readonly Readonly<Record<string, unknown>>[];
+}
+interface ClusterProvenance {
+    readonly clusterId: number;
+    readonly clusterQuality: string;
+    readonly clusterConfidence: number;
+    readonly fields: Readonly<Record<string, FieldProvenance>>;
+}
+interface BlockResult {
+    readonly blockKey: string;
+    readonly rows: readonly Row[];
+    readonly strategy: string;
+    readonly depth: number;
+    readonly parentKey?: string;
+    readonly preScoredPairs?: readonly ScoredPair[];
+}
+declare const VALID_SCORERS: Set<"exact" | "jaro_winkler" | "levenshtein" | "token_sort" | "soundex_match" | "embedding" | "record_embedding" | "ensemble" | "dice" | "jaccard">;
+declare const VALID_TRANSFORMS: Set<"token_sort" | "lowercase" | "uppercase" | "strip" | "strip_all" | "soundex" | "metaphone" | "digits_only" | "alpha_only" | "normalize_whitespace" | "first_token" | "last_token">;
+declare const VALID_STRATEGIES: Set<"most_complete" | "majority_vote" | "source_priority" | "most_recent" | "first_non_null">;
+declare const VALID_STANDARDIZERS: Set<"strip" | "email" | "name_proper" | "name_upper" | "name_lower" | "phone" | "zip5" | "address" | "state" | "trim_whitespace">;
+/**
+ * Create a ScoredPair guaranteeing idA <= idB (canonical order).
+ * Always use this instead of constructing `{ idA, idB, score }` directly.
+ */
+declare function makeScoredPair(a: number, b: number, score: number): ScoredPair;
+/** Create a MatchkeyField with sensible defaults. */
+declare function makeMatchkeyField(partial: Partial<MatchkeyField> & Pick<MatchkeyField, "field">): MatchkeyField;
+/**
+ * Shape accepted by `makeMatchkeyConfig`. All variant-specific fields are
+ * optional; the factory picks the right variant based on `type`.
+ */
+interface MakeMatchkeyConfigInput {
+    readonly name: string;
+    readonly type?: "exact" | "weighted" | "probabilistic";
+    readonly fields?: readonly MatchkeyField[];
+    readonly threshold?: number;
+    readonly autoThreshold?: boolean;
+    readonly rerank?: boolean;
+    readonly rerankModel?: string;
+    readonly rerankBand?: number;
+    readonly emIterations?: number;
+    readonly convergenceThreshold?: number;
+    readonly linkThreshold?: number;
+    readonly reviewThreshold?: number;
+}
+/** Create a MatchkeyConfig with sensible defaults. Produces the correct variant. */
+declare function makeMatchkeyConfig(partial: MakeMatchkeyConfigInput): MatchkeyConfig;
+/** Create a BlockingConfig with sensible defaults. */
+declare function makeBlockingConfig(partial?: Partial<BlockingConfig>): BlockingConfig;
+/** Create a GoldenRulesConfig with sensible defaults. */
+declare function makeGoldenRulesConfig(partial?: Partial<GoldenRulesConfig>): GoldenRulesConfig;
+/** Create a full GoldenMatchConfig with sensible defaults. */
+declare function makeConfig(partial?: Partial<GoldenMatchConfig>): GoldenMatchConfig;
+/**
+ * Return matchkeys from config, checking both `matchkeys` and `matchSettings`.
+ * Mirrors Python's `GoldenMatchConfig.get_matchkeys()`.
+ */
+declare function getMatchkeys(config: GoldenMatchConfig): readonly MatchkeyConfig[];
+
+export { makeConfig as A, type BlockResult as B, type CanopyConfig as C, type DedupeResult as D, type ExactMatchkey as E, type FieldProvenance as F, type GoldenMatchConfig as G, makeGoldenRulesConfig as H, type InputConfig as I, makeMatchkeyConfig as J, makeMatchkeyField as K, type LLMScorerConfig as L, type MatchkeyConfig as M, makeScoredPair as N, type OutputConfig as O, type PairKey as P, type QualityConfig as Q, type Row as R, type ScoredPair as S, type TransformConfig as T, VALID_SCORERS as V, type WeightedMatchkey as W, type MatchResult as a, type BlockingConfig as b, type BlockingKeyConfig as c, type BudgetConfig as d, type ClusterInfo as e, type ClusterProvenance as f, type ColumnValue as g, type DedupeStats as h, type DomainConfig as i, type GoldenFieldRule as j, type GoldenRulesConfig as k, type InputFileConfig as l, type LearningConfig as m, type MakeMatchkeyConfigInput as n, type MatchkeyField as o, type MemoryConfig as p, type ProbabilisticMatchkey as q, type SortKeyField as r, type StandardizationConfig as s, VALID_STANDARDIZERS as t, VALID_STRATEGIES as u, VALID_TRANSFORMS as v, type ValidationConfig as w, type ValidationRuleConfig as x, getMatchkeys as y, makeBlockingConfig as z };

package/examples/01-basic-dedupe.ts

@@ -0,0 +1,60 @@
+/**
+ * Basic deduplication: find duplicate people in a small array.
+ * Run: npx tsx examples/01-basic-dedupe.ts
+ */
+import { dedupe } from "goldenmatch";
+
+const people = [
+  { id: 1, first_name: "John",   last_name: "Smith", email: "john@example.com",    zip: "12345" },
+  { id: 2, first_name: "Jon",    last_name: "Smith", email: "john@example.com",    zip: "12345" },
+  { id: 3, first_name: "Johnny", last_name: "Smith", email: "j.smith@example.com", zip: "12345" },
+  { id: 4, first_name: "Jane",   last_name: "Doe",   email: "jane@example.com",    zip: "54321" },
+  { id: 5, first_name: "Janet",  last_name: "Doe",   email: "janet@example.com",   zip: "54321" },
+];
+
+const result = dedupe(people, {
+  exact: ["email"],
+  fuzzy: { first_name: 0.8, last_name: 0.85 },
+  blocking: ["zip"],
+  threshold: 0.85,
+});
+
+console.log(`Records:    ${result.stats.totalRecords}`);
+console.log(`Clusters:   ${result.stats.totalClusters}`);
+console.log(`Match rate: ${(result.stats.matchRate * 100).toFixed(1)}%\n`);
+
+console.log("Golden records:");
+for (const rec of result.goldenRecords) {
+  console.log(" ", rec);
+}
+
+console.log("\nDuplicate groups:");
+for (const [cid, cluster] of result.clusters) {
+  if (cluster.size < 2) continue;
+  console.log(
+    `  Cluster ${cid} (${cluster.size} members, confidence ${cluster.confidence.toFixed(2)}):`,
+  );
+  for (const mid of cluster.members) {
+    console.log(`    row ${mid}`);
+  }
+}
+
+/**
+ * Expected output (approximate):
+ *
+ *   Records:    5
+ *   Clusters:   3
+ *   Match rate: 40.0%
+ *
+ *   Golden records:
+ *     { __cluster_id__: 0, id: 1, first_name: 'John', ... }
+ *     ...
+ *
+ *   Duplicate groups:
+ *     Cluster 0 (2 members, confidence 0.95): row 0, row 1
+ *     Cluster 1 (...): ...
+ *
+ * Python -> TS differences:
+ *   - Python returns DataFrames; TS returns plain arrays + ReadonlyMap of clusters.
+ *   - Python `result.stats["total_records"]`; TS `result.stats.totalRecords`.
+ */