@memberjunction/ai-vector-dupe 5.42.0 → 5.44.0

package/dist/duplicateRecordDetector.js

@@ -22,6 +22,8 @@ import { KnowledgeHubMetadataEngine, } from "@memberjunction/core-entities";
 import { VectorBase } from "@memberjunction/ai-vectors";
 import { EntityDocumentTemplateParser, EntityVectorSyncer } from "@memberjunction/ai-vector-sync";
 import { TemplateEngineServer } from "@memberjunction/templates";
+import { DuplicateReasoningProvider } from "./reasoning/DuplicateReasoningProvider.js";
+import { MatchedSetDeltaBuilder } from "./reasoning/MatchedSetDeltaBuilder.js";
 /** Default number of nearest neighbors to retrieve per record */
 const DEFAULT_TOP_K = 5;
 /** Default concurrency limit for parallel vector queries */
@@ -49,6 +51,12 @@ const SAVE_BATCH_SIZE = 20;
 export class DuplicateRecordDetector extends VectorBase {
     constructor() {
         super(...arguments);
+        /**
+         * The embedding model's API identifier (e.g. 'Xenova/gte-small', 'text-embedding-3-small'),
+         * resolved from the entity document's AIModel. Passed to `EmbedTexts` — required by local
+         * providers (which load the named ONNX pipeline) and honored by cloud providers.
+         */
+        this.embeddingModelAPIName = null;
         /**
          * Tracks already-seen source↔match pairs across the entire run to suppress inverse duplicates.
          * If A→B is persisted, B→A is skipped. Key format: "smallerID::largerID" for consistent ordering.
@@ -195,10 +203,22 @@ export class DuplicateRecordDetector extends VectorBase {
         const record = records.Results[0];
         const templateParser = EntityDocumentTemplateParser.CreateInstance();
         const templateTexts = await this.GenerateTemplateTexts(templateParser, entityDocument, [record], ContextUser);
-        const embedResult = await this.embedding.EmbedTexts({ texts: templateTexts, model: null });
+        const embedResult = await this.embedding.EmbedTexts({ texts: templateTexts, model: this.embeddingModelAPIName });
         const topK = options.TopK ?? DEFAULT_TOP_K;
         const queryResults = await this.QueryDuplicatesForRecords([record], embedResult.vectors, templateTexts, entityDocument, topK, options, this.GetQueryConcurrency(entityDocument));
-        return queryResults.length > 0 ? queryResults[0].Duplicates : new PotentialDuplicateResult();
+        if (queryResults.length === 0) {
+            return new PotentialDuplicateResult();
+        }
+        // Annotate the (non-persisted) single-record result with LLM reasoning when the entity
+        // has it enabled and the set clears the gate — same gate as the batch path. There are no
+        // match rows to stamp run ids onto here; the verdict rides on the returned result so a
+        // real-time "is this a duplicate?" caller gets recommendation + resolved field map too.
+        const single = queryResults[0];
+        const reasoning = await this.RunReasoningForSet(single, entityInfo, entityDocument, ContextUser);
+        if (reasoning) {
+            this.applyReasoningToResult(single.Duplicates, reasoning.Output, reasoning.FieldMap);
+        }
+        return single.Duplicates;
     }
     // ─────────────────────────────────────────────
     // Batch Processing
@@ -253,7 +273,7 @@ export class DuplicateRecordDetector extends VectorBase {
             // Embed this sub-batch
             this.reportProgress(options, 'Embedding', totalRecords, processedSoFar, matchesSoFar, startTime);
             const subTemplateTexts = await this.GenerateTemplateTexts(templateParser, entityDocument, subRecords, contextUser);
-            const subEmbedResult = await this.embedding.EmbedTexts({ texts: subTemplateTexts, model: null });
+            const subEmbedResult = await this.embedding.EmbedTexts({ texts: subTemplateTexts, model: this.embeddingModelAPIName });
             // Query vector DB for each record in the sub-batch with concurrency control
             this.reportProgress(options, 'Querying', totalRecords, processedSoFar, matchesSoFar, startTime);
             const subQueryResults = await this.QueryDuplicatesForRecords(subRecords, subEmbedResult.vectors, subTemplateTexts, entityDocument, topK, options, concurrency);
@@ -265,7 +285,7 @@ export class DuplicateRecordDetector extends VectorBase {
         await this.FilterNonExistentMatches(allQueryResults, entityInfo);
         // 6e: Persist match results and update run details
         this.reportProgress(options, 'Matching', totalRecords, processedSoFar + records.length, matchesSoFar, startTime);
-        const results = await this.PersistMatchResults(allQueryResults, duplicateRunDetails, entityDocument, options, startTime);
+        const results = await this.PersistMatchResults(allQueryResults, duplicateRunDetails, entityInfo, entityDocument, options, startTime, contextUser);
         const batchMatches = results.reduce((sum, r) => sum + r.Duplicates.length, 0);
         return { Results: results, MatchesFound: batchMatches };
     }
@@ -368,6 +388,11 @@ export class DuplicateRecordDetector extends VectorBase {
             return;
         }
         const aiModel = this.GetAIModel(entityDocument.AIModelID);
+        // The embedding model's API name (e.g. 'Xenova/gte-small') — local providers REQUIRE it
+        // to load the right ONNX pipeline; cloud providers fall back to their own default if absent.
+        this.embeddingModelAPIName = aiModel.APIName;
+        // Captured for the vector query id when the provider keys by EntityDocumentID (SVS).
+        this.entityDocumentID = entityDocument.ID;
         const vectorDB = this.GetVectorDatabase(entityDocument.VectorDatabaseID);
         // Resolve API keys. Empty/null is legitimate for local providers — local
         // embeddings (ONNX runtime) and the in-process SimpleVectorServiceProvider need
@@ -645,6 +670,10 @@ export class DuplicateRecordDetector extends VectorBase {
      * Execute a vector query — uses hybrid search with RRF when the provider supports it.
      */
     async executeVectorQuery(vector, templateText, topK, options) {
+        // Providers that store vectors in MJ keyed by EntityDocumentID (the in-process
+        // SimpleVectorServiceProvider) need the EntityDocumentID as the query id; external/
+        // colocated providers key by the logical index name. See VectorDBBase.QueryKeyIsEntityDocumentID.
+        const queryId = this.vectorDB.QueryKeyIsEntityDocumentID ? this.entityDocumentID : this.indexName;
         if (this.vectorDB.SupportsHybridSearch && templateText) {
             return this.vectorDB.HybridQuery({
                 vector,
@@ -654,15 +683,15 @@ export class DuplicateRecordDetector extends VectorBase {
                 FusionMethod: options.FusionMethod ?? 'rrf',
                 includeMetadata: true,
                 includeValues: false,
-            });
+            }, this.CurrentUser);
         }
         return this.vectorDB.QueryIndex({
-            id: this.indexName,
+            id: queryId,
             vector,
             topK,
             includeMetadata: true,
             includeValues: false,
-        });
+        }, this.CurrentUser);
     }
     /**
      * Parse raw vector DB matches into a PotentialDuplicateResult.
@@ -680,7 +709,14 @@ export class DuplicateRecordDetector extends VectorBase {
                 continue;
             }
             const duplicate = new PotentialDuplicate();
-            duplicate.LoadFromConcatenatedString(match.metadata.RecordID);
+            this.loadCandidateKey(duplicate, match.metadata.RecordID, sourceKey);
+            // Upstream self-match filter: every record is its own nearest neighbor (cosine ~1.0),
+            // so the source record itself comes back as a top "match". Drop it here, the moment we
+            // parse it, with a normalized key-string compare that does NOT depend on
+            // CompositeKey.Equals downstream — a record must never be flagged as its own duplicate.
+            if (sourceKey && this.isSameRecord(duplicate, sourceKey)) {
+                continue;
+            }
             duplicate.ProbabilityScore = match.score;
             // Capture the full vector metadata for rich UI display
             duplicate.VectorMetadata = { ...match.metadata };
@@ -688,6 +724,42 @@ export class DuplicateRecordDetector extends VectorBase {
         }
         return result;
     }
+    /**
+     * True when two composite keys identify the same record. Compares the normalized
+     * (trimmed, lower-cased) URL-segment representation, so it is robust to UUID-casing
+     * differences across platforms (SQL Server upper- vs PostgreSQL lower-case) and to a
+     * bare-PK vs concatenated key shape.
+     */
+    isSameRecord(a, b) {
+        return a.Values().trim().toLowerCase() === b.Values().trim().toLowerCase();
+    }
+    /**
+     * Populate a candidate's composite key from a vector match's RecordID, tolerant of the two
+     * formats different vector providers emit:
+     *   - **Concatenated** ("ID|<guid>", or "F1|v1||F2|v2" for composite PKs) — e.g. providers that
+     *     stored the full key. Parsed via {@link CompositeKey.LoadFromConcatenatedString}.
+     *   - **Bare primary-key value** ("<guid>") — what the in-process SimpleVectorServiceProvider
+     *     returns, since it stores `MJ: Entity Record Documents.RecordID` as the raw PK value. For
+     *     this form we rebuild the key using the source record's PK field name(s).
+     *
+     * Getting this wrong leaves `KeyValuePairs` empty (the bare value has no field delimiter, so
+     * `LoadFromConcatenatedString` no-ops), which silently breaks self-match filtering, candidate
+     * field-delta loading (the reasoner sees an empty candidate), and `MatchRecordID` persistence.
+     */
+    loadCandidateKey(candidate, recordID, sourceKey) {
+        if (recordID.includes(CompositeKey.DefaultValueDelimiter)) {
+            candidate.LoadFromConcatenatedString(recordID);
+            return;
+        }
+        const pkFieldNames = sourceKey?.KeyValuePairs?.map(kv => kv.FieldName) ?? [];
+        if (pkFieldNames.length === 1) {
+            // Bare single-column PK value — pair it with the source's PK field name.
+            candidate.KeyValuePairs = [{ FieldName: pkFieldNames[0], Value: recordID }];
+            return;
+        }
+        // Composite PK delivered without delimiters, or unknown field names — best effort.
+        candidate.LoadFromConcatenatedString(recordID);
+    }
     /**
      * Filter out self-matches where the candidate is the same record as the source.
      */
@@ -862,50 +934,77 @@ export class DuplicateRecordDetector extends VectorBase {
     }
     /**
      * Persist match results and update run detail records.
+     *
+     * When LLM reasoning is enabled on the entity document AND a matched set clears the
+     * reasoning gate (top vector score >= ReasoningThreshold), reasoning runs ONCE for the
+     * whole set; the verdict is written onto every match row's LLM* columns and carried on
+     * the result for the auto-merge step. When reasoning is disabled the loop is unchanged.
      */
-    async PersistMatchResults(queryResults, duplicateRunDetails, entityDocument, options, startTime) {
+    async PersistMatchResults(queryResults, duplicateRunDetails, entityInfo, entityDocument, options, startTime, contextUser) {
         const results = [];
         let matchesFound = 0;
         for (const qr of queryResults) {
-            // Filter out inverse duplicates: if A→B was already persisted, skip B→A
-            const sourceId = qr.SourceKey.Values();
-            qr.Duplicates.Duplicates = qr.Duplicates.Duplicates.filter(dupe => {
-                const matchId = dupe.Values();
-                const pairKey = sourceId < matchId ? `${sourceId}::${matchId}` : `${matchId}::${sourceId}`;
-                if (this._seenPairs.has(pairKey)) {
-                    return false; // Inverse already recorded
-                }
-                this._seenPairs.add(pairKey);
-                return true;
-            });
+            this.suppressInverseDuplicates(qr);
             results.push(qr.Duplicates);
             matchesFound += qr.Duplicates.Duplicates.length;
-            const sourceKey = qr.SourceKey;
-            const detail = duplicateRunDetails.find((d) => {
-                const detailKey = new CompositeKey();
-                detailKey.LoadFromConcatenatedString(d.RecordID);
-                return detailKey.Equals(sourceKey);
-            });
-            if (detail) {
-                const matchRecords = await this.CreateMatchRecordsForDetail(detail.ID, qr.Duplicates);
-                qr.Duplicates.DuplicateRunDetailMatchRecordIDs = matchRecords.map((m) => m.ID);
-                detail.MatchStatus = 'Complete';
-                const success = await this.SaveEntity(detail);
-                if (!success) {
-                    LogError(`Failed to update Duplicate Run Detail record ${detail.ID}`);
-                }
-            }
-            else {
-                LogError(`No Duplicate Run Detail found for ${qr.SourceKey.ToString()}`);
+            // Reasoning gate: runs once per set, only when enabled + above threshold.
+            // Returns undefined (and is byte-for-byte inert) when reasoning is disabled.
+            const reasoning = await this.RunReasoningForSet(qr, entityInfo, entityDocument, contextUser);
+            if (reasoning) {
+                this.applyReasoningToResult(qr.Duplicates, reasoning.Output, reasoning.FieldMap);
             }
+            await this.persistDetailMatches(qr, duplicateRunDetails, reasoning?.Output);
             this.reportProgress(options, 'Matching', queryResults.length, results.length, matchesFound, startTime);
         }
         return results;
     }
+    /**
+     * Drop inverse duplicates in place: if A→B was already persisted this run, skip B→A.
+     */
+    suppressInverseDuplicates(qr) {
+        const sourceId = qr.SourceKey.Values();
+        qr.Duplicates.Duplicates = qr.Duplicates.Duplicates.filter(dupe => {
+            const matchId = dupe.Values();
+            const pairKey = sourceId < matchId ? `${sourceId}::${matchId}` : `${matchId}::${sourceId}`;
+            if (this._seenPairs.has(pairKey)) {
+                return false; // Inverse already recorded
+            }
+            this._seenPairs.add(pairKey);
+            return true;
+        });
+    }
+    /**
+     * Locate the matching run-detail row, create the per-candidate match records (carrying
+     * the set's LLM verdict when present), mark the detail complete, and stamp the created
+     * match-record IDs back onto the result (kept in lockstep with Duplicates for auto-merge).
+     */
+    async persistDetailMatches(qr, duplicateRunDetails, reasoning) {
+        const sourceKey = qr.SourceKey;
+        const detail = duplicateRunDetails.find((d) => {
+            const detailKey = new CompositeKey();
+            detailKey.LoadFromConcatenatedString(d.RecordID);
+            return detailKey.Equals(sourceKey);
+        });
+        if (!detail) {
+            LogError(`No Duplicate Run Detail found for ${qr.SourceKey.ToString()}`);
+            return;
+        }
+        const matchRecords = await this.CreateMatchRecordsForDetail(detail.ID, qr.Duplicates, reasoning);
+        qr.Duplicates.DuplicateRunDetailMatchRecordIDs = matchRecords.map((m) => m.ID);
+        detail.MatchStatus = 'Complete';
+        const success = await this.SaveEntity(detail);
+        if (!success) {
+            LogError(`Failed to update Duplicate Run Detail record ${detail.ID}`);
+        }
+    }
     /**
      * Create match records for a single run detail, saving in parallel batches.
+     *
+     * When a per-set {@link DuplicateReasoningOutput} is supplied, each match row gets THIS
+     * candidate's own verdict (recommendation / confidence / reasoning), while the set-level
+     * proposed survivor / field map / run id ride along on every row.
      */
-    async CreateMatchRecordsForDetail(duplicateRunDetailID, duplicateResult) {
+    async CreateMatchRecordsForDetail(duplicateRunDetailID, duplicateResult, reasoning) {
         const matchRecords = [];
         for (const batch of chunkArray(duplicateResult.Duplicates, SAVE_BATCH_SIZE)) {
             const batchResults = await Promise.all(batch.map(async (dupe) => {
@@ -919,6 +1018,9 @@ export class DuplicateRecordDetector extends VectorBase {
                 match.ApprovalStatus = 'Pending';
                 match.MergeStatus = 'Pending';
                 match.RecordMetadata = dupe.VectorMetadata ? JSON.stringify(dupe.VectorMetadata) : null;
+                if (reasoning && reasoning.Success) {
+                    this.applyReasoningToMatch(match, reasoning, dupe.Values());
+                }
                 const success = await this.SaveEntity(match);
                 return success ? match : null;
             }));
@@ -929,6 +1031,213 @@ export class DuplicateRecordDetector extends VectorBase {
         }
         return matchRecords;
     }
+    /**
+     * Write the LLM verdict + run id onto a single match row's generated columns. The
+     * recommendation / confidence / reasoning are taken from THIS candidate's own verdict (judged
+     * independently), so a false-positive candidate reads NotDuplicate even when another candidate
+     * in the same set is a confident Merge. Falls back to the set-level summary only when the
+     * reasoner returned no per-candidate verdict for this record. The proposed survivor + field
+     * map stay set-level (they describe the merge of the set's true duplicates).
+     *
+     * @param candidateRecordID this candidate's record id (matches the input candidate RecordID)
+     */
+    applyReasoningToMatch(match, reasoning, candidateRecordID) {
+        const verdict = reasoning.CandidateVerdicts.find(v => this.recordIdMatches(v.RecordID, candidateRecordID));
+        match.LLMRecommendation = verdict ? verdict.Recommendation : reasoning.Recommendation;
+        match.LLMConfidence = verdict ? verdict.Confidence : reasoning.Confidence;
+        match.LLMReasoning = (verdict?.Reasoning || reasoning.Reasoning) || null;
+        match.LLMProposedSurvivorRecordID = reasoning.SurvivorRecordID;
+        match.LLMProposedFieldMap = reasoning.FieldChoices.length > 0
+            ? JSON.stringify(reasoning.FieldChoices)
+            : null;
+        match.AIPromptRunID = reasoning.AIPromptRunID ?? null;
+        match.AIAgentRunID = reasoning.AIAgentRunID ?? null;
+    }
+    // ─────────────────────────────────────────────
+    // LLM Reasoning (gated, per matched set)
+    // ─────────────────────────────────────────────
+    /**
+     * Run LLM reasoning for one source record's matched set, ONCE, only when:
+     *   1. the entity document has EnableLLMReasoning = true, AND
+     *   2. the set is non-empty, AND
+     *   3. the set's top MatchProbability >= the (non-null) ReasoningThreshold.
+     *
+     * Returns `undefined` in every other case — including when reasoning is disabled — so
+     * the surrounding persist/merge path stays byte-for-byte identical to the vector-only
+     * behavior. A failed reasoning call returns an output with Success = false (never throws),
+     * so one bad set never aborts the run.
+     */
+    async RunReasoningForSet(qr, entityInfo, entityDocument, contextUser) {
+        if (!this.IsReasoningGateOpen(qr, entityDocument)) {
+            return undefined;
+        }
+        const provider = this.ResolveReasoningProvider(entityDocument);
+        if (!provider) {
+            return undefined;
+        }
+        const input = await this.BuildReasoningInput(qr, entityInfo, entityDocument, contextUser);
+        const output = await provider.Reason(input, { Provider: this._provider, ContextUser: contextUser });
+        if (!output.Success) {
+            LogError(`Reasoning failed for set ${qr.SourceKey.ToString()}: ${output.ErrorMessage ?? 'unknown error'}`);
+            return { Output: output, FieldMap: [] };
+        }
+        // Guard the LLM's structured choices against the actual set before persisting/merging:
+        //  - a SurvivorRecordID that isn't one of the set's records is hallucinated → null it out.
+        //  - per-field choices are resolved to literal values (and empty overrides dropped) below.
+        this.validateSurvivor(output, input);
+        // Resolve the reasoner's per-field choices to literal survivor values now, while the
+        // matched-set deltas (loaded for the prompt) are in hand.
+        const fieldMap = this.resolveReasoningFieldMap(output, input.FieldDeltas);
+        return { Output: output, FieldMap: fieldMap };
+    }
+    /**
+     * Null out a hallucinated survivor: the reasoner can return a SurvivorRecordID that isn't
+     * any record in the set (a made-up GUID, or a candidate that was filtered out). Persisting
+     * it would carry a phantom id to the UI and auto-merge. Validate against the set's record
+     * ids (source + candidates) and drop it if it doesn't match.
+     */
+    validateSurvivor(output, input) {
+        if (!output.SurvivorRecordID) {
+            return;
+        }
+        const setRecordIDs = [input.SourceRecord.RecordID, ...input.Candidates.map(c => c.RecordID)];
+        const matches = setRecordIDs.some(id => this.recordIdMatches(id, output.SurvivorRecordID));
+        if (!matches) {
+            LogError(`Reasoning returned a SurvivorRecordID not in the set ('${output.SurvivorRecordID}') — ignoring.`);
+            output.SurvivorRecordID = null;
+        }
+    }
+    /**
+     * Resolve the reasoner's per-field survivor choices ({FieldName, SourceRecordID}) into
+     * literal `{FieldName, Value}` entries for {@link RecordMergeRequest.FieldMap}, by reading
+     * the chosen record's value out of the matched-set deltas. Choices whose field or record
+     * can't be located in the deltas are skipped (the survivor's existing value then stands),
+     * so a partial/garbled choice can never inject an undefined override into the merge.
+     */
+    resolveReasoningFieldMap(output, fieldDeltas) {
+        const resolved = [];
+        for (const choice of output.FieldChoices ?? []) {
+            const delta = fieldDeltas.find(d => d.FieldName === choice.FieldName);
+            const cell = delta?.Values.find(v => this.recordIdMatches(v.RecordID, choice.SourceRecordID));
+            // Skip a choice whose resolved value is empty: overriding the survivor's field with an
+            // empty value would BLANK OUT good data. An empty override carries no information, so
+            // the survivor's existing value should stand.
+            if (cell && cell.Value != null && cell.Value.trim().length > 0) {
+                resolved.push({ FieldName: choice.FieldName, Value: cell.Value });
+            }
+        }
+        return resolved;
+    }
+    /** Case-insensitive, trimmed equality of two record-id (URL-segment) strings. */
+    recordIdMatches(a, b) {
+        return a.trim().toLowerCase() === b.trim().toLowerCase();
+    }
+    /**
+     * Gate predicate: reasoning enabled + non-empty set + top score clears the threshold.
+     * A null ReasoningThreshold means "no gate" — reasoning runs for any non-empty set.
+     */
+    IsReasoningGateOpen(qr, entityDocument) {
+        if (!entityDocument.EnableLLMReasoning) {
+            return false;
+        }
+        const dupes = qr.Duplicates.Duplicates;
+        if (dupes.length === 0) {
+            return false;
+        }
+        const threshold = entityDocument.ReasoningThreshold;
+        if (threshold == null) {
+            return true;
+        }
+        const topScore = Math.max(...dupes.map(d => d.ProbabilityScore));
+        return topScore >= threshold;
+    }
+    /**
+     * Resolve the reasoning provider for this entity document's ReasoningMode via the
+     * ClassFactory. Returns null when ClassFactory falls back to the abstract base (no
+     * implementation registered for the mode) so the caller can skip gracefully.
+     */
+    ResolveReasoningProvider(entityDocument) {
+        const provider = MJGlobal.Instance.ClassFactory.CreateInstance(DuplicateReasoningProvider, entityDocument.ReasoningMode);
+        // A bare abstract-base instance means no concrete provider was registered for the
+        // mode (CreateInstance falls back to the base class). Its Reason() is abstract, so
+        // treat it as "no provider" rather than calling and throwing.
+        if (!provider || provider.constructor === DuplicateReasoningProvider) {
+            LogError(`No DuplicateReasoningProvider registered for ReasoningMode '${entityDocument.ReasoningMode}'`);
+            return null;
+        }
+        return provider;
+    }
+    /**
+     * Assemble the reasoning input for a matched set: source description, candidate
+     * descriptions, and the differing-field deltas loaded for the whole set.
+     */
+    async BuildReasoningInput(qr, entityInfo, entityDocument, contextUser) {
+        // Load the field deltas first — the same pass yields a record-id → name label map, which
+        // gives BOTH the source and the candidates real names (loaded from the records) instead of
+        // raw GUIDs. The vector-metadata name is a weaker fallback; the GUID is the last resort.
+        const deltaBuilder = new MatchedSetDeltaBuilder(this.RunView);
+        const allKeys = [qr.SourceKey, ...qr.Duplicates.Duplicates];
+        const { FieldDeltas: fieldDeltas, Labels: labels } = await deltaBuilder.Build(entityInfo, allKeys, contextUser);
+        const candidates = qr.Duplicates.Duplicates.map(d => ({
+            RecordID: d.Values(),
+            Label: this.resolveRecordLabel(labels, d.Values(), this.reasoningLabel(d.VectorMetadata)),
+            VectorScore: d.ProbabilityScore,
+            Provenance: 'Local',
+            DependentCount: entityInfo.RelatedEntities.length,
+        }));
+        const sourceRecordID = qr.SourceKey.Values();
+        return {
+            EntityName: entityInfo.Name,
+            EntityDescription: entityInfo.Description ?? null,
+            EntityDocument: entityDocument,
+            SourceRecord: {
+                RecordID: sourceRecordID,
+                Label: this.resolveRecordLabel(labels, sourceRecordID, null),
+                Provenance: 'Local',
+                DependentCount: entityInfo.RelatedEntities.length,
+            },
+            Candidates: candidates,
+            FieldDeltas: fieldDeltas,
+        };
+    }
+    /**
+     * Resolve a record's display label: prefer the name loaded from the record (via the delta
+     * builder), then a secondary fallback (e.g. a candidate's vector-metadata name), then the
+     * raw record-id key as a last resort. Guards against the loaded label itself being the
+     * record key (the engine's own fallback) so we still try the secondary source.
+     */
+    resolveRecordLabel(labels, recordID, fallback) {
+        const loaded = labels.get(recordID);
+        if (loaded && loaded.trim().length > 0 && loaded !== recordID) {
+            return loaded;
+        }
+        if (fallback && fallback.trim().length > 0) {
+            return fallback;
+        }
+        return recordID;
+    }
+    /** Extract a display label from a candidate's vector metadata snapshot, if present. */
+    reasoningLabel(metadata) {
+        if (metadata && typeof metadata['Name'] === 'string' && metadata['Name'].trim().length > 0) {
+            return metadata['Name'];
+        }
+        return null;
+    }
+    /**
+     * Carry the set-level verdict + resolved survivor field map onto the result so the
+     * auto-merge step (AutoMergeAboveAbsolute) can consult the recommendation and apply the
+     * literal {FieldName, Value} overrides via {@link RecordMergeRequest.FieldMap}. The UI
+     * still reads the persisted per-row {@link MJDuplicateRunDetailMatchEntity.LLMProposedFieldMap}
+     * (the raw choices) and lets the reviewer override before a manual merge.
+     */
+    applyReasoningToResult(result, output, fieldMap) {
+        if (!output.Success) {
+            return;
+        }
+        result.ReasoningRecommendation = output.Recommendation;
+        result.ReasoningFieldMap = fieldMap.length > 0 ? fieldMap : undefined;
+        result.ReasoningText = output.Reasoning?.trim() ? output.Reasoning : undefined;
+    }
     // ─────────────────────────────────────────────
     // Auto-Merge
     // ─────────────────────────────────────────────
@@ -948,30 +1257,61 @@ export class DuplicateRecordDetector extends VectorBase {
         const absoluteThreshold = options.AbsoluteMatchThreshold ?? entityDocument.AbsoluteMatchThreshold;
         for (const dupeResult of response.PotentialDuplicateResult) {
             for (const [index, dupe] of dupeResult.Duplicates.entries()) {
-                if (dupe.ProbabilityScore < absoluteThreshold) {
+                if (!this.IsAutoMergeEligible(dupe, dupeResult, entityDocument, absoluteThreshold)) {
                     continue;
                 }
-                const mergeParams = new RecordMergeRequest();
-                mergeParams.EntityName = entityDocument.Entity;
-                mergeParams.SurvivingRecordCompositeKey = dupeResult.RecordCompositeKey;
-                mergeParams.RecordsToMerge = [dupe];
-                // Guard each merge so a single failure (e.g. a permission or FK issue on
-                // one pair) is logged and skipped rather than aborting the entire run.
-                try {
-                    const mergeResult = await this.Metadata.MergeRecords(mergeParams, this.CurrentUser);
-                    if (mergeResult.Success) {
-                        await this.updateMatchRecordAfterMerge(dupeResult.DuplicateRunDetailMatchRecordIDs[index]);
-                    }
-                    else {
-                        LogError(`Failed to merge ${dupeResult.RecordCompositeKey.ToString()} and ${dupe.ToString()}: ${mergeResult.OverallStatus ?? 'unknown error'}`);
-                    }
-                }
-                catch (err) {
-                    LogError(`Auto-merge threw for ${dupeResult.RecordCompositeKey.ToString()} and ${dupe.ToString()}`, undefined, err);
-                }
+                await this.executeAutoMerge(dupe, dupeResult, entityDocument, index);
             }
         }
     }
+    /**
+     * Decide whether a single candidate is eligible for automatic merge.
+     *
+     * Back-compat path (EnableLLMReasoning = false): eligible iff the vector score meets the
+     * absolute threshold — byte-for-byte the original behavior. `AutomationLevel` is ignored.
+     *
+     * Reasoning path (EnableLLMReasoning = true): `AutomationLevel` governs.
+     *   - ReviewAll / LLMGated → never auto-merge (everything goes to human review).
+     *   - AutoMergeAboveAbsolute → at/above the absolute threshold AND the set's LLM
+     *     recommendation is 'Merge'.
+     */
+    IsAutoMergeEligible(dupe, dupeResult, entityDocument, absoluteThreshold) {
+        const aboveAbsolute = dupe.ProbabilityScore >= absoluteThreshold;
+        if (!entityDocument.EnableLLMReasoning) {
+            return aboveAbsolute;
+        }
+        if (entityDocument.AutomationLevel !== 'AutoMergeAboveAbsolute') {
+            return false;
+        }
+        return aboveAbsolute && dupeResult.ReasoningRecommendation === 'Merge';
+    }
+    /**
+     * Execute one guarded auto-merge for an eligible candidate, applying the LLM's resolved
+     * field map when present, and stamp the match record on success.
+     */
+    async executeAutoMerge(dupe, dupeResult, entityDocument, index) {
+        const mergeParams = new RecordMergeRequest();
+        mergeParams.EntityName = entityDocument.Entity;
+        mergeParams.SurvivingRecordCompositeKey = dupeResult.RecordCompositeKey;
+        mergeParams.RecordsToMerge = [dupe];
+        if (dupeResult.ReasoningFieldMap && dupeResult.ReasoningFieldMap.length > 0) {
+            mergeParams.FieldMap = dupeResult.ReasoningFieldMap;
+        }
+        // Guard each merge so a single failure (e.g. a permission or FK issue on
+        // one pair) is logged and skipped rather than aborting the entire run.
+        try {
+            const mergeResult = await this.Metadata.MergeRecords(mergeParams, this.CurrentUser);
+            if (mergeResult.Success) {
+                await this.updateMatchRecordAfterMerge(dupeResult.DuplicateRunDetailMatchRecordIDs[index]);
+            }
+            else {
+                LogError(`Failed to merge ${dupeResult.RecordCompositeKey.ToString()} and ${dupe.ToString()}: ${mergeResult.OverallStatus ?? 'unknown error'}`);
+            }
+        }
+        catch (err) {
+            LogError(`Auto-merge threw for ${dupeResult.RecordCompositeKey.ToString()} and ${dupe.ToString()}`, undefined, err);
+        }
+    }
     /**
      * Update a match record's status after a successful merge.
      */