@memberjunction/ai-vector-dupe 6.2.0-edge.1 → 6.2.0-edge.2

package/dist/reasoning/DecisionReasoningProvider.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview 'Decision' mode reasoning provider.
+ *
+ * Asks a typed decision model one Likelihood per candidate ("the candidate record is the same
+ * real-world entity as the new record") in a single `AIDecisionRunner` call per matched set. The
+ * state is the same fields the prompt provider renders, from the same helper, serialized compactly.
+ *
+ * It only **recommends**: a candidate whose probability is at or above
+ * {@link DecisionReasoningProvider.UncertainAbove} is `Uncertain` and flagged for a person; one below
+ * it is `NotDuplicate`. It never emits `Merge` and never proposes a survivor or a field map, so a
+ * `Decision`-mode set is never auto-merge eligible (typed-decision plan §3.6, rule 8). Survivor and
+ * field choices remain LLM work: see `DecisionThenPromptReasoningProvider`.
+ *
+ * A failed decision is a failed reasoning call, handled as the `Prompt` mode handles one: the
+ * detector saves the set's match rows with empty LLM columns, so every candidate stays `Pending`
+ * for review and none is auto-merge eligible.
+ *
+ * @module @memberjunction/ai-vector-dupe
+ */
+import { AIDecisionParams } from '@memberjunction/ai-prompts';
+import { type DecisionAnsweringModel, type DecisionModelCalibration, type MJAIPromptEntityExtended } from '@memberjunction/ai-core-plus';
+import { type DecisionQuestion, type PlattCalibration } from '@memberjunction/ai';
+import { DuplicateReasoningProvider } from './DuplicateReasoningProvider.js';
+import { DuplicateReasoningInput, DuplicateReasoningOutput, DuplicateReasoningContext, DuplicateReasoningCandidateVerdict, ReasoningCandidate, ReasoningSourceRecord } from './DuplicateReasoningTypes.js';
+/** One candidate's probability of being the same real-world entity as the source record. */
+export interface DuplicateCandidateProbability {
+    /** The candidate record id (matches the input candidate's RecordID). */
+    RecordID: string;
+    /**
+     * The Likelihood's probability in [0, 1], **calibrated** for the model that answered (see
+     * {@link DUPLICATE_DECISION_CALIBRATION}). Null when the decision returned no answer for this
+     * candidate, or when the answering model has no calibration.
+     */
+    Probability: number | null;
+    /** The model's own probability, before calibration; null when there was no answer. */
+    RawProbability?: number | null;
+}
+/**
+ * Platt calibration of the duplicate Likelihood ("the candidate is the same real-world entity as
+ * the new record"), per decision model, each tied to the exact model it was fitted on (see
+ * `FindDecisionCalibration` in `@memberjunction/ai-core-plus`): the MJ decision model that answered
+ * (`ModelName`) and the model the driver reports behind it (`ResolvedModel`). A model's raw
+ * probabilities are not calibrated: Jev ranks candidates almost perfectly (AUC 0.99) but its raw
+ * probabilities run high for similar records that are not duplicates.
+ *
+ * Any other model, including Jev at another version or `LLM Decision` answered by another chat
+ * model, gives no calibrated probability, since its raw one can't be banded. The entry check then
+ * flags nothing, as it does for a failed decision; batch `Decision` mode bands its candidates
+ * `Uncertain` for review; and `DecisionThenPrompt` sends them all to the prompt. The provider logs
+ * the missing calibration once per model. An app that binds another decision model supplies its
+ * calibration by overriding {@link DecisionReasoningProvider.CalibrationFor}.
+ *
+ * Fitted on the duplicate-check measurement (plan Task 3.8, 2026-09-29), on every candidate: 160
+ * labelled new records for MJ: Actions (80 rewrites of an existing action, 80 similar actions that
+ * don't exist), five vector candidates each.
+ * - **Jev** at its pinned `APIName`, `typesafe/jev-1.13-20260917`, which OpenRouter reports back as
+ *   the resolved model.
+ * - **LLM Decision** when its chat model is GPT-OSS-120B, its `LLM Decision` prompt's first choice.
+ *   The stored runs don't record the resolved model; this is the prompt's binding on that day.
+ *
+ * Refit whenever a model's pinned version, its delegated chat model or the question changes.
+ */
+export declare const DUPLICATE_DECISION_CALIBRATION: readonly DecisionModelCalibration<PlattCalibration>[];
+/** The shipped calibration for the exact model that answered, or null when it has none. */
+export declare function DuplicateDecisionCalibrationFor(answeredBy: DecisionAnsweringModel): PlattCalibration | null;
+/**
+ * The duplicate Likelihood calibrated for the exact model that answered, or null when that model
+ * has no calibration.
+ */
+export declare function CalibratedDuplicateProbability(probability: number, answeredBy: DecisionAnsweringModel): number | null;
+/** The outcome of one decision call over a matched set. */
+export interface DuplicateDecisionResult {
+    /** Whether the decision call succeeded. */
+    Success: boolean;
+    /** Why the call failed, when {@link Success} is false. */
+    ErrorMessage?: string;
+    /** One entry per input candidate, in input order. Empty when the call failed. */
+    Candidates: DuplicateCandidateProbability[];
+    /** The decision's `MJ: AI Prompt Runs` row id, when the runner wrote one. */
+    AIPromptRunID: string | null;
+    /**
+     * Set when the exact model that answered has no calibration: the model, as
+     * `DescribeAnsweringModel` names it (`Jev (typesafe/jev-1.14-...)`). Every candidate's
+     * `Probability` is then null and its `RawProbability` holds the model's own answer. The entry
+     * check treats such a result like a failed decision and flags nothing.
+     */
+    UncalibratedModel?: string;
+}
+/**
+ * Typed-decision reasoning provider. Registered under the 'Decision' `ReasoningMode`.
+ */
+export declare class DecisionReasoningProvider extends DuplicateReasoningProvider {
+    /**
+     * The flagging threshold used when none is passed, as it is when the class factory builds the
+     * provider, on **calibrated** probabilities. A flag asks a person to look, so it favours precision:
+     * a missed duplicate is only today's behaviour, and needless flags teach people to ignore them.
+     * At a calibrated 0.7, scored out of fold, Jev flagged the true source at 96.6% precision, caught
+     * 70% of duplicates, and flagged 2.5% of new records; LLM Decision scored 74%, 36% and 12.5%. The
+     * vector threshold alone flagged every candidate. (Duplicate-check measurement, plan Task 3.8,
+     * 2026-09-29, re-scored 2026-09-30.)
+     */
+    static readonly DEFAULT_UNCERTAIN_ABOVE = 0.7;
+    /**
+     * The threshold for the decision stage of `DecisionThenPrompt`, on calibrated probabilities. There
+     * the decision only drops implausible candidates before the prompt reasons over the rest, so it
+     * keeps recall: at a calibrated 0.3, scored out of fold, Jev kept 98.8% of true duplicates and passed
+     * 14.8% of candidates.
+     */
+    static readonly PRE_FILTER_UNCERTAIN_ABOVE = 0.3;
+    /** The seeded decision prompt whose model bindings choose the decision model. */
+    static readonly DEFAULT_PROMPT_NAME = "Default Decision";
+    /** A candidate at or above this probability is `Uncertain` (flagged for a person); below it, `NotDuplicate`. */
+    readonly UncertainAbove: number;
+    /**
+     * @param uncertainAbove the flagging threshold in [0, 1]. Defaults to
+     *   {@link DecisionReasoningProvider.DEFAULT_UNCERTAIN_ABOVE}.
+     */
+    constructor(uncertainAbove?: number);
+    /**
+     * Reason over a matched set with one decision call. A failed call returns `Success: false` with
+     * the error and the decision's run id, and no verdicts: the detector writes no LLM columns for a
+     * failed set, so no candidate is marked `NotDuplicate` and none is merged.
+     */
+    Reason(input: DuplicateReasoningInput, context: DuplicateReasoningContext): Promise<DuplicateReasoningOutput>;
+    /**
+     * Run the decision for a matched set: one `AIDecisionRunner` call, with one Likelihood per
+     * candidate. The context's `CancellationToken` and `TimeoutMS`, when set, bound the model call.
+     * Never throws. A set with no candidates succeeds without a call.
+     */
+    DecideCandidates(input: DuplicateReasoningInput, context: DuplicateReasoningContext): Promise<DuplicateDecisionResult>;
+    /**
+     * Whether a candidate stays in play: its probability is at or above {@link UncertainAbove}, or
+     * unknown. An unknown probability fails toward inclusion.
+     */
+    IsPlausible(probability: number | null): boolean;
+    /** Band one candidate's probability into `Uncertain` or `NotDuplicate`, carrying the probability as its confidence. */
+    BandCandidate(candidate: DuplicateCandidateProbability): DuplicateReasoningCandidateVerdict;
+    /**
+     * Turn a successful decision into the reasoning contract. Recommends only: no `Merge`, no
+     * survivor and no field choices.
+     */
+    RecommendFromDecision(decision: DuplicateDecisionResult): DuplicateReasoningOutput;
+    /** Resolve the decision prompt by name from the AIEngine cache (no DB query). */
+    protected ResolveDecisionPrompt(): MJAIPromptEntityExtended | null;
+    /**
+     * The decision's state: the fields the prompt provider renders, from the same helper
+     * ({@link DuplicateReasoningProvider.buildPromptData}), serialized as compact JSON.
+     */
+    protected BuildDecisionState(input: DuplicateReasoningInput): string;
+    /** One Likelihood per candidate, keyed by {@link QuestionKey}. */
+    protected BuildQuestions(input: DuplicateReasoningInput): Record<string, DecisionQuestion>;
+    /** The question key for the candidate at `index`. A label for code only: the model never reads it. */
+    protected QuestionKey(index: number): string;
+    /**
+     * The statement the model judges for one candidate. It names both records by label and record id,
+     * because the model reads only the instructions and the state, and duplicates often share a label.
+     */
+    protected BuildQuestionInstructions(source: ReasoningSourceRecord, candidate: ReasoningCandidate): string;
+    protected BuildDecisionParams(prompt: MJAIPromptEntityExtended, input: DuplicateReasoningInput, context: DuplicateReasoningContext): AIDecisionParams;
+    /**
+     * The calibration for the exact model that answered (the MJ decision model and the model the
+     * driver reports behind it), or null when it has none. Defaults to
+     * {@link DUPLICATE_DECISION_CALIBRATION}; override to calibrate another model.
+     */
+    protected CalibrationFor(answeredBy: DecisionAnsweringModel): PlattCalibration | null;
+    /** Read each candidate's probability from the run, in input order, calibrated for the model that answered. */
+    private readProbabilities;
+    /** Log a model with no calibration the first time it answers, not on every decision. */
+    private logUncalibratedOnce;
+    private likelihoodOf;
+    private failedDecision;
+    /** A failed decision: `Success: false`, with the error and the decision's run id. */
+    private failedDecisionOutput;
+    private describeBand;
+    private summarize;
+}
+//# sourceMappingURL=DecisionReasoningProvider.d.ts.map

package/dist/reasoning/DecisionReasoningProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecisionReasoningProvider.d.ts","sourceRoot":"","sources":["../../src/reasoning/DecisionReasoningProvider.ts"],"names":[],"mappings":"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"}

package/dist/reasoning/DecisionReasoningProvider.js

@@ -0,0 +1,306 @@
+/**
+ * @fileoverview 'Decision' mode reasoning provider.
+ *
+ * Asks a typed decision model one Likelihood per candidate ("the candidate record is the same
+ * real-world entity as the new record") in a single `AIDecisionRunner` call per matched set. The
+ * state is the same fields the prompt provider renders, from the same helper, serialized compactly.
+ *
+ * It only **recommends**: a candidate whose probability is at or above
+ * {@link DecisionReasoningProvider.UncertainAbove} is `Uncertain` and flagged for a person; one below
+ * it is `NotDuplicate`. It never emits `Merge` and never proposes a survivor or a field map, so a
+ * `Decision`-mode set is never auto-merge eligible (typed-decision plan §3.6, rule 8). Survivor and
+ * field choices remain LLM work: see `DecisionThenPromptReasoningProvider`.
+ *
+ * A failed decision is a failed reasoning call, handled as the `Prompt` mode handles one: the
+ * detector saves the set's match rows with empty LLM columns, so every candidate stays `Pending`
+ * for review and none is auto-merge eligible.
+ *
+ * @module @memberjunction/ai-vector-dupe
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var DecisionReasoningProvider_1;
+import { LogError } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { AIEngine } from '@memberjunction/aiengine';
+import { AIDecisionRunner, AIDecisionParams } from '@memberjunction/ai-prompts';
+import { DescribeAnsweringModel, FindDecisionCalibration } from '@memberjunction/ai-core-plus';
+import { ApplyPlattCalibration } from '@memberjunction/ai';
+import { DuplicateReasoningProvider, DECISION_REASONING_PROVIDER_KEY } from './DuplicateReasoningProvider.js';
+/**
+ * Platt calibration of the duplicate Likelihood ("the candidate is the same real-world entity as
+ * the new record"), per decision model, each tied to the exact model it was fitted on (see
+ * `FindDecisionCalibration` in `@memberjunction/ai-core-plus`): the MJ decision model that answered
+ * (`ModelName`) and the model the driver reports behind it (`ResolvedModel`). A model's raw
+ * probabilities are not calibrated: Jev ranks candidates almost perfectly (AUC 0.99) but its raw
+ * probabilities run high for similar records that are not duplicates.
+ *
+ * Any other model, including Jev at another version or `LLM Decision` answered by another chat
+ * model, gives no calibrated probability, since its raw one can't be banded. The entry check then
+ * flags nothing, as it does for a failed decision; batch `Decision` mode bands its candidates
+ * `Uncertain` for review; and `DecisionThenPrompt` sends them all to the prompt. The provider logs
+ * the missing calibration once per model. An app that binds another decision model supplies its
+ * calibration by overriding {@link DecisionReasoningProvider.CalibrationFor}.
+ *
+ * Fitted on the duplicate-check measurement (plan Task 3.8, 2026-09-29), on every candidate: 160
+ * labelled new records for MJ: Actions (80 rewrites of an existing action, 80 similar actions that
+ * don't exist), five vector candidates each.
+ * - **Jev** at its pinned `APIName`, `typesafe/jev-1.13-20260917`, which OpenRouter reports back as
+ *   the resolved model.
+ * - **LLM Decision** when its chat model is GPT-OSS-120B, its `LLM Decision` prompt's first choice.
+ *   The stored runs don't record the resolved model; this is the prompt's binding on that day.
+ *
+ * Refit whenever a model's pinned version, its delegated chat model or the question changes.
+ */
+export const DUPLICATE_DECISION_CALIBRATION = Object.freeze([
+    Object.freeze({ ModelName: 'Jev', ResolvedModel: 'typesafe/jev-1.13-20260917', Calibration: Object.freeze({ A: 2.5855, B: -4.4485 }) }),
+    Object.freeze({ ModelName: 'LLM Decision', ResolvedModel: 'GPT-OSS-120B', Calibration: Object.freeze({ A: 0.9918, B: -1.4843 }) })
+]);
+/** The shipped calibration for the exact model that answered, or null when it has none. */
+export function DuplicateDecisionCalibrationFor(answeredBy) {
+    return FindDecisionCalibration(DUPLICATE_DECISION_CALIBRATION, answeredBy);
+}
+/**
+ * The duplicate Likelihood calibrated for the exact model that answered, or null when that model
+ * has no calibration.
+ */
+export function CalibratedDuplicateProbability(probability, answeredBy) {
+    const calibration = DuplicateDecisionCalibrationFor(answeredBy);
+    return calibration ? ApplyPlattCalibration(probability, calibration) : null;
+}
+/** Models already logged as having no calibration, so each is logged once per process. */
+const loggedUncalibratedModels = new Set();
+/**
+ * Typed-decision reasoning provider. Registered under the 'Decision' `ReasoningMode`.
+ */
+let DecisionReasoningProvider = class DecisionReasoningProvider extends DuplicateReasoningProvider {
+    static { DecisionReasoningProvider_1 = this; }
+    /**
+     * The flagging threshold used when none is passed, as it is when the class factory builds the
+     * provider, on **calibrated** probabilities. A flag asks a person to look, so it favours precision:
+     * a missed duplicate is only today's behaviour, and needless flags teach people to ignore them.
+     * At a calibrated 0.7, scored out of fold, Jev flagged the true source at 96.6% precision, caught
+     * 70% of duplicates, and flagged 2.5% of new records; LLM Decision scored 74%, 36% and 12.5%. The
+     * vector threshold alone flagged every candidate. (Duplicate-check measurement, plan Task 3.8,
+     * 2026-09-29, re-scored 2026-09-30.)
+     */
+    static { this.DEFAULT_UNCERTAIN_ABOVE = 0.7; }
+    /**
+     * The threshold for the decision stage of `DecisionThenPrompt`, on calibrated probabilities. There
+     * the decision only drops implausible candidates before the prompt reasons over the rest, so it
+     * keeps recall: at a calibrated 0.3, scored out of fold, Jev kept 98.8% of true duplicates and passed
+     * 14.8% of candidates.
+     */
+    static { this.PRE_FILTER_UNCERTAIN_ABOVE = 0.3; }
+    /** The seeded decision prompt whose model bindings choose the decision model. */
+    static { this.DEFAULT_PROMPT_NAME = 'Default Decision'; }
+    /**
+     * @param uncertainAbove the flagging threshold in [0, 1]. Defaults to
+     *   {@link DecisionReasoningProvider.DEFAULT_UNCERTAIN_ABOVE}.
+     */
+    constructor(uncertainAbove = DecisionReasoningProvider_1.DEFAULT_UNCERTAIN_ABOVE) {
+        super();
+        this.UncertainAbove = uncertainAbove;
+    }
+    /**
+     * Reason over a matched set with one decision call. A failed call returns `Success: false` with
+     * the error and the decision's run id, and no verdicts: the detector writes no LLM columns for a
+     * failed set, so no candidate is marked `NotDuplicate` and none is merged.
+     */
+    async Reason(input, context) {
+        const decision = await this.DecideCandidates(input, context);
+        return decision.Success
+            ? this.RecommendFromDecision(decision)
+            : this.failedDecisionOutput(decision);
+    }
+    /**
+     * Run the decision for a matched set: one `AIDecisionRunner` call, with one Likelihood per
+     * candidate. The context's `CancellationToken` and `TimeoutMS`, when set, bound the model call.
+     * Never throws. A set with no candidates succeeds without a call.
+     */
+    async DecideCandidates(input, context) {
+        if (input.Candidates.length === 0) {
+            return { Success: true, Candidates: [], AIPromptRunID: null };
+        }
+        try {
+            await AIEngine.Instance.Config(false, context.ContextUser, context.Provider);
+            const prompt = this.ResolveDecisionPrompt();
+            if (!prompt) {
+                return this.failedDecision(`Decision prompt "${DecisionReasoningProvider_1.DEFAULT_PROMPT_NAME}" not found`, null);
+            }
+            const run = await new AIDecisionRunner().ExecuteDecision(this.BuildDecisionParams(prompt, input, context));
+            return this.readProbabilities(input, run);
+        }
+        catch (e) {
+            LogError(e);
+            return this.failedDecision(e instanceof Error ? e.message : String(e), null);
+        }
+    }
+    /**
+     * Whether a candidate stays in play: its probability is at or above {@link UncertainAbove}, or
+     * unknown. An unknown probability fails toward inclusion.
+     */
+    IsPlausible(probability) {
+        return probability == null || probability >= this.UncertainAbove;
+    }
+    /** Band one candidate's probability into `Uncertain` or `NotDuplicate`, carrying the probability as its confidence. */
+    BandCandidate(candidate) {
+        const flagged = this.IsPlausible(candidate.Probability);
+        return {
+            RecordID: candidate.RecordID,
+            Recommendation: flagged ? 'Uncertain' : 'NotDuplicate',
+            Confidence: candidate.Probability,
+            Reasoning: this.describeBand(candidate.Probability, flagged, candidate.RawProbability)
+        };
+    }
+    /**
+     * Turn a successful decision into the reasoning contract. Recommends only: no `Merge`, no
+     * survivor and no field choices.
+     */
+    RecommendFromDecision(decision) {
+        const verdicts = decision.Candidates.map(c => this.BandCandidate(c));
+        const overall = this.deriveOverall(verdicts);
+        return {
+            Success: true,
+            Recommendation: overall.Recommendation,
+            Confidence: overall.Confidence,
+            Reasoning: this.summarize(verdicts),
+            CandidateVerdicts: verdicts,
+            SurvivorRecordID: null,
+            FieldChoices: [],
+            AIPromptRunID: decision.AIPromptRunID
+        };
+    }
+    /** Resolve the decision prompt by name from the AIEngine cache (no DB query). */
+    ResolveDecisionPrompt() {
+        const target = DecisionReasoningProvider_1.DEFAULT_PROMPT_NAME.toLowerCase();
+        return AIEngine.Instance.Prompts.find(p => (p.Name ?? '').trim().toLowerCase() === target) ?? null;
+    }
+    /**
+     * The decision's state: the fields the prompt provider renders, from the same helper
+     * ({@link DuplicateReasoningProvider.buildPromptData}), serialized as compact JSON.
+     */
+    BuildDecisionState(input) {
+        return JSON.stringify(this.buildPromptData(input));
+    }
+    /** One Likelihood per candidate, keyed by {@link QuestionKey}. */
+    BuildQuestions(input) {
+        const questions = {};
+        input.Candidates.forEach((candidate, index) => {
+            questions[this.QuestionKey(index)] = {
+                Kind: 'Likelihood',
+                Instructions: this.BuildQuestionInstructions(input.SourceRecord, candidate)
+            };
+        });
+        return questions;
+    }
+    /** The question key for the candidate at `index`. A label for code only: the model never reads it. */
+    QuestionKey(index) {
+        return `candidate_${index + 1}`;
+    }
+    /**
+     * The statement the model judges for one candidate. It names both records by label and record id,
+     * because the model reads only the instructions and the state, and duplicates often share a label.
+     */
+    BuildQuestionInstructions(source, candidate) {
+        return `The candidate record "${candidate.Label}" (recordId ${candidate.RecordID}) is the same real-world entity ` +
+            `as the new record, the sourceRecord "${source.Label}" (recordId ${source.RecordID}).`;
+    }
+    BuildDecisionParams(prompt, input, context) {
+        const params = new AIDecisionParams();
+        params.prompt = prompt;
+        params.contextUser = context.ContextUser;
+        params.cancellationToken = context.CancellationToken;
+        params.timeoutMS = context.TimeoutMS;
+        params.State = this.BuildDecisionState(input);
+        params.Questions = this.BuildQuestions(input);
+        return params;
+    }
+    /**
+     * The calibration for the exact model that answered (the MJ decision model and the model the
+     * driver reports behind it), or null when it has none. Defaults to
+     * {@link DUPLICATE_DECISION_CALIBRATION}; override to calibrate another model.
+     */
+    CalibrationFor(answeredBy) {
+        return DuplicateDecisionCalibrationFor(answeredBy);
+    }
+    /** Read each candidate's probability from the run, in input order, calibrated for the model that answered. */
+    readProbabilities(input, run) {
+        const runID = run.promptRun?.ID ?? null;
+        if (!run.success) {
+            return this.failedDecision(run.errorMessage ?? 'Decision execution failed', runID);
+        }
+        const answeredBy = {
+            ModelName: run.modelInfo?.modelName,
+            ResolvedModel: run.DecisionResult?.ResolvedModel
+        };
+        const calibration = this.CalibrationFor(answeredBy);
+        const candidates = input.Candidates.map((candidate, index) => {
+            const raw = this.likelihoodOf(run.Answers[this.QuestionKey(index)]);
+            return {
+                RecordID: candidate.RecordID,
+                Probability: raw == null || !calibration ? null : ApplyPlattCalibration(raw, calibration),
+                RawProbability: raw
+            };
+        });
+        const result = { Success: true, Candidates: candidates, AIPromptRunID: runID };
+        if (!calibration) {
+            result.UncalibratedModel = DescribeAnsweringModel(answeredBy);
+            this.logUncalibratedOnce(result.UncalibratedModel);
+        }
+        return result;
+    }
+    /** Log a model with no calibration the first time it answers, not on every decision. */
+    logUncalibratedOnce(model) {
+        if (loggedUncalibratedModels.has(model)) {
+            return;
+        }
+        loggedUncalibratedModels.add(model);
+        LogError(`Duplicate decision: the model "${model}" has no calibration, so its probabilities can't be banded. ` +
+            'The entry check flags nothing for it, and Decision mode flags its candidates for review. ' +
+            'Add its calibration (DUPLICATE_DECISION_CALIBRATION, or override CalibrationFor).');
+    }
+    likelihoodOf(answer) {
+        return answer?.Kind === 'Likelihood' ? answer.Probability : null;
+    }
+    failedDecision(message, runID) {
+        return { Success: false, ErrorMessage: message, Candidates: [], AIPromptRunID: runID };
+    }
+    /** A failed decision: `Success: false`, with the error and the decision's run id. */
+    failedDecisionOutput(decision) {
+        const output = this.failedOutput(`Decision failed: ${decision.ErrorMessage ?? 'unknown error'}`);
+        output.AIPromptRunID = decision.AIPromptRunID;
+        return output;
+    }
+    describeBand(probability, flagged, rawProbability) {
+        if (probability == null && rawProbability != null) {
+            return `The decision model has no calibration (raw probability ${rawProbability.toFixed(2)}). Flagged for review.`;
+        }
+        if (probability == null) {
+            return 'The decision model returned no answer for this candidate. Flagged for review.';
+        }
+        const p = probability.toFixed(2);
+        const threshold = this.UncertainAbove.toFixed(2);
+        return flagged
+            ? `Decision model: ${p} probability this is the same entity, at or above ${threshold}. Flagged for review.`
+            : `Decision model: ${p} probability this is the same entity, below ${threshold}.`;
+    }
+    summarize(verdicts) {
+        const flagged = verdicts.filter(v => v.Recommendation === 'Uncertain').length;
+        return `Decision model flagged ${flagged} of ${verdicts.length} candidates for review ` +
+            `(probability at or above ${this.UncertainAbove.toFixed(2)}). Decision mode recommends only; it never merges.`;
+    }
+};
+DecisionReasoningProvider = DecisionReasoningProvider_1 = __decorate([
+    RegisterClass(DuplicateReasoningProvider, DECISION_REASONING_PROVIDER_KEY),
+    __metadata("design:paramtypes", [Number])
+], DecisionReasoningProvider);
+export { DecisionReasoningProvider };
+//# sourceMappingURL=DecisionReasoningProvider.js.map

package/dist/reasoning/DecisionReasoningProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecisionReasoningProvider.js","sourceRoot":"","sources":["../../src/reasoning/DecisionReasoningProvider.ts"],"names":[],"mappings":"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"}

package/dist/reasoning/DecisionThenPromptReasoningProvider.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview 'DecisionThenPrompt' mode reasoning provider: an explicit chain.
+ *
+ * The detector resolves exactly one provider per `ReasoningMode`, so a decision cannot feed the
+ * prompt provider through configuration alone. This provider chains them:
+ *
+ *   1. {@link DecisionReasoningProvider} runs one decision over the set and drops every candidate
+ *      whose probability is below its threshold.
+ *   2. `PromptReasoningProvider` reasons over **only the survivors**, so auto-merge still works
+ *      wherever the prompt provider allows it.
+ *
+ * Both stages resolve through the class factory under the 'Decision' and 'Prompt' modes, so an
+ * application's override of either mode applies inside the chain as well.
+ *
+ * With no survivors the set is `NotDuplicate` and the prompt never runs. If the decision fails,
+ * every candidate goes to the prompt provider, which is the `Prompt` mode's behaviour: narrowing is
+ * an optimisation, so its failure must never hide a candidate.
+ *
+ * Each match row points at the run that produced its verdict: a survivor's at the prompt run, a
+ * dropped candidate's at the decision run. A failed decision's run is named in the error log, since
+ * a match row holds only one prompt run id.
+ *
+ * @module @memberjunction/ai-vector-dupe
+ */
+import { DuplicateReasoningProvider } from './DuplicateReasoningProvider.js';
+import { DecisionReasoningProvider, DuplicateCandidateProbability } from './DecisionReasoningProvider.js';
+import { DuplicateReasoningInput, DuplicateReasoningOutput, DuplicateReasoningContext } from './DuplicateReasoningTypes.js';
+/**
+ * Chained reasoning provider: the decision filters, then the prompt reasons over the survivors.
+ * Registered under the 'DecisionThenPrompt' `ReasoningMode`.
+ */
+export declare class DecisionThenPromptReasoningProvider extends DuplicateReasoningProvider {
+    /** The filter stage. Its `UncertainAbove` is the survival threshold. */
+    protected readonly DecisionStage: DecisionReasoningProvider;
+    /** The reasoning stage, which sees only the survivors. */
+    protected readonly PromptStage: DuplicateReasoningProvider;
+    /**
+     * The class factory passes no arguments, so both stages resolve through the class factory
+     * under the 'Decision' and 'Prompt' modes: an application's override of either mode applies
+     * inside the chain too.
+     *
+     * @param decisionStage the filter stage; defaults to {@link ResolveDecisionStage}, at the pre-filter
+     *   threshold ({@link DecisionReasoningProvider.PRE_FILTER_UNCERTAIN_ABOVE}), which keeps recall
+     * @param promptStage the reasoning stage; defaults to {@link ResolvePromptStage}
+     */
+    constructor(decisionStage?: DecisionReasoningProvider, promptStage?: DuplicateReasoningProvider);
+    /**
+     * Filter the set with the decision, then reason over the survivors with the prompt.
+     */
+    Reason(input: DuplicateReasoningInput, context: DuplicateReasoningContext): Promise<DuplicateReasoningOutput>;
+    /**
+     * The input with the dropped candidates removed, from the candidate list and from the field
+     * deltas. A field whose remaining values no longer differ is dropped too, since the deltas carry
+     * differing fields only.
+     */
+    protected NarrowToSurvivors(input: DuplicateReasoningInput, dropped: DuplicateCandidateProbability[]): DuplicateReasoningInput;
+    /**
+     * The filter stage: the provider registered for the 'Decision' mode, built with the pre-filter
+     * threshold ({@link DecisionReasoningProvider.PRE_FILTER_UNCERTAIN_ABOVE}) as its `uncertainAbove`
+     * argument, since here the decision only drops implausible candidates and keeps recall. The chain
+     * needs its probability API, so a registration that is not a `DecisionReasoningProvider` falls
+     * back to the shipped one, at the same threshold.
+     */
+    protected ResolveDecisionStage(): DecisionReasoningProvider;
+    /** The reasoning stage: the provider registered for the 'Prompt' mode, else the shipped one. */
+    protected ResolvePromptStage(): DuplicateReasoningProvider;
+    /**
+     * The provider the class factory registers for a mode, built with `params` as its constructor
+     * arguments, or null when none is registered.
+     */
+    private resolveRegisteredProvider;
+    /** No candidate survived: `NotDuplicate` for the set, from the decision alone, with no prompt call. */
+    private noSurvivorsOutput;
+    /**
+     * Give each dropped candidate its own `NotDuplicate` verdict from the decision, carrying the
+     * decision's run id, so its match row neither falls back to the set-level recommendation nor
+     * points at a prompt run that never saw it. The prompt's verdicts and set-level fields are
+     * otherwise left as the prompt returned them.
+     */
+    private withDroppedVerdicts;
+    /** The failure for the log, naming the decision's run when the runner wrote one. */
+    private describeFailure;
+    private stillDiffers;
+    private recordIDSet;
+    /** Record ids compare case-insensitively (SQL Server and PostgreSQL case UUIDs differently). */
+    private normalizeRecordID;
+}
+//# sourceMappingURL=DecisionThenPromptReasoningProvider.d.ts.map

package/dist/reasoning/DecisionThenPromptReasoningProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DecisionThenPromptReasoningProvider.d.ts","sourceRoot":"","sources":["../../src/reasoning/DecisionThenPromptReasoningProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,EACH,0BAA0B,EAI7B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACH,yBAAyB,EACzB,6BAA6B,EAEhC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACH,uBAAuB,EACvB,wBAAwB,EACxB,yBAAyB,EAE5B,MAAM,2BAA2B,CAAC;AAEnC;;;GAGG;AACH,qBACa,mCAAoC,SAAQ,0BAA0B;IAC/E,wEAAwE;IACxE,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,yBAAyB,CAAC;IAC5D,0DAA0D;IAC1D,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;IAE3D;;;;;;;;OAQG;gBACS,aAAa,CAAC,EAAE,yBAAyB,EAAE,WAAW,CAAC,EAAE,0BAA0B;IAM/F;;OAEG;IACU,MAAM,CACf,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,yBAAyB,GACnC,OAAO,CAAC,wBAAwB,CAAC;IAcpC;;;;OAIG;IACH,SAAS,CAAC,iBAAiB,CACvB,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,6BAA6B,EAAE,GACzC,uBAAuB;IAY1B;;;;;;OAMG;IACH,SAAS,CAAC,oBAAoB,IAAI,yBAAyB;IAM3D,gGAAgG;IAChG,SAAS,CAAC,kBAAkB,IAAI,0BAA0B;IAI1D;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAKjC,uGAAuG;IACvG,OAAO,CAAC,iBAAiB;IAOzB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAgB3B,oFAAoF;IACpF,OAAO,CAAC,eAAe;IAKvB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,WAAW;IAInB,gGAAgG;IAChG,OAAO,CAAC,iBAAiB;CAG5B"}