mdi-llmkit 1.1.1 → 1.1.3

package/dist/src/semanticMatch/compareLists.d.ts

@@ -1,38 +1,22 @@
 /**
- * Utilities for semantic comparison of two item lists using deterministic pre-processing
- * plus LLM-assisted decisions for ambiguous cases.
+ * Semantic comparison for before/after item lists.
  *
- * High-level flow:
- * 1) Normalize/sort items and remove obvious case-insensitive exact matches.
- * 2) Ask the LLM to classify remaining "before" items as removed or renamed.
- * 3) Ask the LLM whether remaining "after" items should be considered added.
- * 4) Return `removed`, `added`, `renamed`, and `unchanged` buckets.
+ * This module compares two lists that represent the same domain at different points
+ * in time (for example, before and after a migration) and classifies items as:
+ * - unchanged,
+ * - renamed,
+ * - removed, or
+ * - added.
  *
- * Key assumptions:
- * - Item names are unique within each input list (case-insensitive).
- * - Comparison is name-based (`string` value or object `name` field).
- * - Optional object `description` is context-only and does not affect identity.
- *
- * Progress reporting:
- * - `OnComparingItemCallback` can be provided to receive start/finish events for each item,
- *   including source list, result classification, optional rename target, and running counts.
+ * It is designed for cases where exact string comparison is not sufficient because
+ * names may change while meaning stays the same.
  */
 import { OpenAI } from 'openai';
-/**
- * Item shape accepted by `compareItemLists` for semantic comparison.
- *
- * - A raw string is treated as the item's comparable name.
- * - An object uses `name` as the comparable value and may include optional
- *   `description` to provide additional LLM context.
- */
-export type SemanticallyComparableListItem = string | {
-    name: string;
-    description?: string;
-};
+import { SemanticItem } from './semanticItem.js';
 /**
  * Final classification of an item during comparison.
  */
-export declare enum ItemComparisonResult {
+export declare enum ItemComparisonClassification {
     /** Item existed in "before" and is considered deleted in "after". */
     Removed = "removed",
     /** Item exists in "after" and is considered newly introduced. */
@@ -42,56 +26,23 @@ export declare enum ItemComparisonResult {
     /** Item is treated as unchanged or unresolved for downstream purposes. */
     Unchanged = "unchanged"
 }
+export declare const ItemComparisonResult: typeof ItemComparisonClassification;
+export type ItemComparisonResult = {
+    item: SemanticItem;
+    classification: ItemComparisonClassification;
+    newName: string | undefined;
+};
 /**
- * Progress callback for per-item comparison lifecycle.
- *
- * @param item The concrete item currently being evaluated.
- * @param isFromBeforeList `true` when the item comes from `listBefore`, `false` when
- * it comes from `listAfter`.
- * @param isStarting `true` when evaluation for this item begins, `false` when that
- * evaluation completes.
- * @param result Current/final classification for this callback event. For start events,
- * this is a provisional value; for finish events, it is final for that item.
- * @param newName The matched new name when `result` is `Renamed`; otherwise `undefined`.
- * @param error Optional warning/error message for this event; `undefined` when none.
- * @param totalProcessedSoFar Number of items fully processed so far.
- * @param totalLeftToProcess Number of items remaining after this event.
- */
-export type OnComparingItemCallback = (item: SemanticallyComparableListItem, isFromBeforeList: boolean, isStarting: boolean, result: ItemComparisonResult, newName: string | undefined, error: string | undefined, totalProcessedSoFar: number, totalLeftToProcess: number) => void;
-/**
- * Result of comparing two lists of strings.
- */
-export interface StringListComparison {
-    removed: string[];
-    added: string[];
-    renamed: Record<string, string>;
-    unchanged: string[];
-}
-/**
- * Compares two lists of strings and identifies differences, including potential renames.
- * The lists presumably use strings. However, in situations where the AI might benefit from
- * additional context, the lists may contain objects with `name` and optional `description`
- * properties; in these situations, it's the `name` property that is compared.
- * The comparison is case insensitive.
- *
- * IMPORTANT: Item names are expected to be unique within each input list (case-insensitive).
- * Duplicate names in either list are not supported and may produce incorrect results.
- * @param before - The list of strings/items before the changes.
- * @param after - The list of strings/items after the changes.
+ * Compares two lists of items and classifies each item from the "before" list as removed,
+ * renamed, or unchanged based on whether it has a semantic match in the "after" list.
+ * Any items in the "after" list that don't match to an item in the "before" list are
+ * classified as added.
+ * @param before - The list of items before the changes.
+ * @param after - The list of items after the changes.
  * @param explanation Optional explanation that provides context for the comparison, e.g.
  * a description of the items or the nature of the changes.
- * @param onComparingItem Optional callback invoked at the start and end of each item
- * evaluation. It receives the current item, whether it is from the "before" list,
- * whether processing is starting (`true`) or finishing (`false`), the
- * current/final classification, renamed target (if applicable), and
- * optional warning/error message, and processed/remaining item counts.
- * `totalProcessedSoFar` increases only when an item
- * finishes; `totalLeftToProcess` is the number of items not yet finished.
- * @returns An object containing removed, added, renamed, and unchanged strings
+ * @returns An array of item comparison results. This includes all items from the "before"
+ * list with their classification (removed/renamed/unchanged), and any unmatched items from
+ * the "after" list classified as added.
  */
-export declare const compareItemLists: (openaiClient: OpenAI, listBefore: SemanticallyComparableListItem[], listAfter: SemanticallyComparableListItem[], explanation?: string, onComparingItem?: OnComparingItemCallback) => Promise<{
-    removed: string[];
-    added: string[];
-    renamed: Record<string, string>;
-    unchanged: string[];
-}>;
+export declare const compareItemLists: (openaiClient: OpenAI, listBefore: SemanticItem[], listAfter: SemanticItem[], explanation?: string) => Promise<ItemComparisonResult[]>;

package/dist/src/semanticMatch/compareLists.js

@@ -1,375 +1,87 @@
-import { GptConversation } from '../gptApi/gptConversation.js';
-import { JSONSchemaFormat } from '../gptApi/jsonSchemaFormat.js';
+/**
+ * Semantic comparison for before/after item lists.
+ *
+ * This module compares two lists that represent the same domain at different points
+ * in time (for example, before and after a migration) and classifies items as:
+ * - unchanged,
+ * - renamed,
+ * - removed, or
+ * - added.
+ *
+ * It is designed for cases where exact string comparison is not sufficient because
+ * names may change while meaning stays the same.
+ */
+import { areItemsEqual, getItemName } from './semanticItem.js';
+import { findSemanticMatch } from './find.js';
 /**
  * Final classification of an item during comparison.
  */
-export var ItemComparisonResult;
-(function (ItemComparisonResult) {
+export var ItemComparisonClassification;
+(function (ItemComparisonClassification) {
     /** Item existed in "before" and is considered deleted in "after". */
-    ItemComparisonResult["Removed"] = "removed";
+    ItemComparisonClassification["Removed"] = "removed";
     /** Item exists in "after" and is considered newly introduced. */
-    ItemComparisonResult["Added"] = "added";
+    ItemComparisonClassification["Added"] = "added";
     /** Item from "before" was matched to a different name in "after". */
-    ItemComparisonResult["Renamed"] = "renamed";
+    ItemComparisonClassification["Renamed"] = "renamed";
     /** Item is treated as unchanged or unresolved for downstream purposes. */
-    ItemComparisonResult["Unchanged"] = "unchanged";
-})(ItemComparisonResult || (ItemComparisonResult = {}));
-/**
- * Returns the comparable name for a list item.
- */
-const getItemName = (item) => {
-    return typeof item === 'string' ? item : item.name;
-};
-/**
- * Ensures a list has no duplicate item names after case-insensitive normalization.
- * Throws an error listing duplicates when the uniqueness precondition is violated.
- */
-const assertUniqueNamesInList = (listToCheck, listName) => {
-    const seenNames = new Set();
-    const duplicateNames = new Set();
-    for (const item of listToCheck) {
-        const name = getItemName(item).trim().toLowerCase();
-        if (seenNames.has(name)) {
-            duplicateNames.add(name);
-        }
-        else {
-            seenNames.add(name);
-        }
-    }
-    if (duplicateNames.size > 0) {
-        throw new Error(`compareItemLists: Duplicate item names found in ${listName} list (case-insensitive): ` +
-            `${Array.from(duplicateNames)
-                .sort()
-                .map((name) => JSON.stringify(name))
-                .join(', ')}`);
-    }
-};
+    ItemComparisonClassification["Unchanged"] = "unchanged";
+})(ItemComparisonClassification || (ItemComparisonClassification = {}));
+export const ItemComparisonResult = ItemComparisonClassification;
 /**
- * Formats a list item for prompt inclusion, including optional description context.
- */
-const itemToPromptString = (item) => {
-    if (typeof item === 'string') {
-        return `- ${JSON.stringify(item)}`;
-    }
-    else {
-        let s = `- ${JSON.stringify(item.name)}`;
-        if (item.description &&
-            item.description.trim().toLowerCase() !== item.name.trim().toLowerCase()) {
-            s += ` (details: ${JSON.stringify(item.description)})`;
-        }
-        return s;
-    }
-};
-/**
- * Sort comparator for list items by case-insensitive name.
- */
-const compareItemsByName = (a, b) => {
-    const nameA = getItemName(a).toLowerCase();
-    const nameB = getItemName(b).toLowerCase();
-    return nameA.localeCompare(nameB);
-};
-/**
- * Compares two names case-insensitively while tolerating JSON-escaped variants.
- */
-const areNamesEquivalent = (a, b) => {
-    a = a.trim().toLowerCase();
-    b = b.trim().toLowerCase();
-    if (a === b || a === JSON.stringify(b) || JSON.stringify(a) === b) {
-        return true;
-    }
-    return false;
-};
-/**
- * Removes every item whose name matches the target (case-insensitive, JSON-tolerant).
- */
-const removeItemsByName = (listToModify, itemNameToRemove) => {
-    itemNameToRemove = itemNameToRemove.trim().toLowerCase();
-    return listToModify.filter((item) => {
-        const name = getItemName(item).trim().toLowerCase();
-        if (areNamesEquivalent(name, itemNameToRemove)) {
-            return false; // Remove this item
-        }
-        return true; // Keep this item
-    });
-};
-/**
- * Compares two lists of strings and identifies differences, including potential renames.
- * The lists presumably use strings. However, in situations where the AI might benefit from
- * additional context, the lists may contain objects with `name` and optional `description`
- * properties; in these situations, it's the `name` property that is compared.
- * The comparison is case insensitive.
- *
- * IMPORTANT: Item names are expected to be unique within each input list (case-insensitive).
- * Duplicate names in either list are not supported and may produce incorrect results.
- * @param before - The list of strings/items before the changes.
- * @param after - The list of strings/items after the changes.
+ * Compares two lists of items and classifies each item from the "before" list as removed,
+ * renamed, or unchanged based on whether it has a semantic match in the "after" list.
+ * Any items in the "after" list that don't match to an item in the "before" list are
+ * classified as added.
+ * @param before - The list of items before the changes.
+ * @param after - The list of items after the changes.
  * @param explanation Optional explanation that provides context for the comparison, e.g.
  * a description of the items or the nature of the changes.
- * @param onComparingItem Optional callback invoked at the start and end of each item
- * evaluation. It receives the current item, whether it is from the "before" list,
- * whether processing is starting (`true`) or finishing (`false`), the
- * current/final classification, renamed target (if applicable), and
- * optional warning/error message, and processed/remaining item counts.
- * `totalProcessedSoFar` increases only when an item
- * finishes; `totalLeftToProcess` is the number of items not yet finished.
- * @returns An object containing removed, added, renamed, and unchanged strings
+ * @returns An array of item comparison results. This includes all items from the "before"
+ * list with their classification (removed/renamed/unchanged), and any unmatched items from
+ * the "after" list classified as added.
  */
-export const compareItemLists = async (openaiClient, listBefore, listAfter, explanation, onComparingItem) => {
-    // Make sure we don't modify the original lists.
-    listBefore = JSON.parse(JSON.stringify(listBefore));
-    listAfter = JSON.parse(JSON.stringify(listAfter));
-    const retval = {
-        removed: [],
-        added: [],
-        renamed: {},
-        unchanged: [],
-    };
-    assertUniqueNamesInList(listBefore, 'before');
-    assertUniqueNamesInList(listAfter, 'after');
-    listBefore.sort(compareItemsByName);
-    listAfter.sort(compareItemsByName);
-    const setStringsBefore = new Set(listBefore.map((item) => getItemName(item)));
-    const setStringsAfter = new Set(listAfter.map((item) => getItemName(item)));
-    // Determine which strings are common to both lists.
-    // We can't just do a simple set intersection, because we want the comparison
-    // to be case insensitive. So we have to do it manually.
-    // We'll just perform an n^2 comparison since the lists are expected to be small.
-    const setStringsCommon = new Set();
-    for (const strBefore of setStringsBefore) {
-        for (const strAfter of setStringsAfter) {
-            if (strBefore.toLowerCase() === strAfter.toLowerCase()) {
-                setStringsCommon.add(strBefore);
-                break;
-            }
-        }
-    }
-    // This already gives us the unchanged items.
-    retval.unchanged = Array.from(setStringsCommon).sort();
-    // Remove the unchanged items from both lists, leaving only items that might have been
-    // removed, added, or renamed.
-    // Remember that we can't just do set subtraction because of case insensitivity, and
-    // because the original lists may contain objects rather than just strings.
-    for (const strCommon of setStringsCommon) {
-        listBefore = removeItemsByName(listBefore, strCommon);
-        listAfter = removeItemsByName(listAfter, strCommon);
-    }
-    // Now the two lists contain only items with different names.
-    // However, some of these items may be renames rather than pure additions/removals.
-    // The only way to tell is with AI.
-    const convo = new GptConversation([], { openaiClient });
-    convo.addSystemMessage(`
-You are a data analyst who has been hired to try to preserve the integrity of a list of
-data items that have recently undergone migration from one data system to another.
-
-You will be given two lists of items: a "before" list and an "after" list.
-(The exact nature of the items is not important. They could be names of products from
-receipts or purchase orders, for example.)
-
-In the migration from the old data system to the new, some items may have been removed,
-some items may have been added, and some items may have been renamed. We can't tell
-just by performing string comparisons on the two lists, because the renames may be subtle.
-
-We're going to go through the items in the "before" list, one by one. For each one,
-you will look for the best matching item in the "after" list. If you find a good match,
-you will consider that item to be a rename of the original item. If you don't find a
-good match, you will consider that item to have been removed.
-`);
-    if (explanation) {
-        convo.addSystemMessage(`
-Here is some additional context that may help you make better decisions about which items
-have been renamed versus removed/added:
-
-${explanation}
-`);
-    }
-    convo.addUserMessage(`
-"BEFORE" LIST:
-
-${listBefore.map(itemToPromptString).join('\n')}
-`);
-    // Counts used for onComparingItem telemetry across both loops.
-    let totalProcessedItems = 0;
-    // First, go through each item in the "before" list, and submit it to the LLM
-    // for presentation.
-    for (let iItem = 0; iItem < listBefore.length; iItem++) {
-        const itemBefore = listBefore[iItem];
-        onComparingItem?.(itemBefore, true, true, ItemComparisonResult.Unchanged, undefined, undefined, totalProcessedItems, listBefore.length - iItem + listAfter.length);
-        try {
-            const convoIter = convo.clone();
-            // We rebuild the "after" list each time, since items may get removed from it
-            // as they get matched.
-            convoIter.addUserMessage(`
-"AFTER" LIST:
-
-${listAfter.map(itemToPromptString).join('\n')}
-`);
-            convoIter.addUserMessage(`
-For the moment, let's focus on this item from the "before" list:
-
-${itemToPromptString(itemBefore)}
-
-Look through the entire "after" list and try to find an item that might be a rename 
-or alternative version of this item.
-
-Feel free to think aloud, brainstorm, and reason through the possibilities. Later on,
-I'll ask you to formalize your decision in JSON format; but for now, just explore the options.
-
-If you find an item that seems like a good match, tell us what it is.
-!IMPORTANT: You may only pick *one* item from the "after" list as a potential rename of this item.
-
-If you don't find any good match, simply say that no good match was found. In this situation,
-we'll consider this item as having been removed/deleted.
-
-Naturally, if you have any higher-level instructions or context that apply to this item,
-please take them into account as you reason through the possibilities.
-`);
-            await convoIter.submit();
-            await convoIter.submit(undefined, undefined, {
-                jsonResponse: JSONSchemaFormat('list_comparison_item_rename_exploration', {
-                    is_renamed: [
-                        Boolean,
-                        'Whether the item from the "before" list has been renamed in the "after" list.',
-                    ],
-                    new_name: [
-                        String,
-                        'The new name of the item in the "after" list, if it has been renamed. ' +
-                            'This needs to be an *exact character-for-character match* of the name of ' +
-                            'exactly *one* item in the "after" list, written *exactly* as it appears ' +
-                            'in the "after" list. If the item was not renamed, this should be an empty string.',
-                    ],
-                    is_deleted: [
-                        Boolean,
-                        'Whether the item from the "before" list has been deleted/removed in the ' +
-                            '"after" list. Presumably, if is_renamed is true, this should be false, ' +
-                            'and vice versa.',
-                    ],
-                }),
+export const compareItemLists = async (openaiClient, listBefore, listAfter, explanation) => {
+    // We're going to be removing items from the "after" list as we match them,
+    // so we make a copy of it to avoid mutating the original array.
+    listAfter = [...listAfter];
+    const retval = [];
+    for (const itemBefore of listBefore) {
+        const indexMatchedInAfter = await findSemanticMatch(openaiClient, listAfter, itemBefore, explanation);
+        if (indexMatchedInAfter === -1) {
+            // No good match found in "after" list, so this item is probably removed.
+            retval.push({
+                item: itemBefore,
+                classification: ItemComparisonClassification.Removed,
+                newName: undefined,
             });
-            const isItemDeleted = convoIter.getLastReplyDictField('is_deleted');
-            const isItemRenamed = convoIter.getLastReplyDictField('is_renamed');
-            if (!isItemDeleted && !isItemRenamed) {
-                // Item is unchanged - shouldn't happen since we already filtered those out,
-                // but just in case, we handle it.
-                const warningMessage = `LLM indicated item is neither renamed nor deleted, which should not happen. ` +
-                    `Marking as unchanged: ${getItemName(itemBefore)}`;
-                retval.unchanged.push(getItemName(itemBefore));
-                totalProcessedItems++;
-                onComparingItem?.(itemBefore, true, false, ItemComparisonResult.Unchanged, undefined, warningMessage, totalProcessedItems, listBefore.length - (iItem + 1) + listAfter.length);
-                continue;
-            }
-            if (isItemDeleted) {
-                // This is the easy case - item was deleted.
-                retval.removed.push(getItemName(itemBefore));
-                totalProcessedItems++;
-                onComparingItem?.(itemBefore, true, false, ItemComparisonResult.Removed, undefined, undefined, totalProcessedItems, listBefore.length - (iItem + 1) + listAfter.length);
-                continue;
-            }
-            if (isItemRenamed) {
-                const newNameAccordingToLLM = `${convoIter.getLastReplyDictField('new_name', '')}`.trim();
-                if (!newNameAccordingToLLM) {
-                    // Invalid response - no new name provided.
-                    // Do not mark the item as removed. Mark it as unchanged.
-                    const warningMessage = `LLM indicated item was renamed but did not provide a new name. ` +
-                        `Skipping rename for item: ${getItemName(itemBefore)}`;
-                    retval.unchanged.push(getItemName(itemBefore));
-                    totalProcessedItems++;
-                    onComparingItem?.(itemBefore, true, false, ItemComparisonResult.Unchanged, undefined, warningMessage, totalProcessedItems, listBefore.length - (iItem + 1) + listAfter.length);
-                    continue;
-                }
-                // Find the actual item in listAfter that matches this name.
-                // We do this because the LLM might return a name that is slightly different
-                // from the actual name in the list (e.g. different casing, or with/without
-                // quotes, etc.)
-                let nameOfMatchedItem = null;
-                for (const itemAfter of listAfter) {
-                    const nameAfter = getItemName(itemAfter);
-                    if (areNamesEquivalent(nameAfter, newNameAccordingToLLM)) {
-                        nameOfMatchedItem = nameAfter;
-                        break;
-                    }
-                }
-                if (!nameOfMatchedItem) {
-                    // Couldn't find a matching item in listAfter.
-                    // Do not mark the item as removed. Mark it as unchanged.
-                    const warningMessage = `LLM indicated item was renamed to "${newNameAccordingToLLM}", ` +
-                        `but no matching item was found in the "after" list. ` +
-                        `Skipping rename for item: ${getItemName(itemBefore)}`;
-                    retval.unchanged.push(getItemName(itemBefore));
-                    totalProcessedItems++;
-                    onComparingItem?.(itemBefore, true, false, ItemComparisonResult.Unchanged, undefined, warningMessage, totalProcessedItems, listBefore.length - (iItem + 1) + listAfter.length);
-                    continue;
-                }
-                // Valid rename.
-                retval.renamed[getItemName(itemBefore)] = nameOfMatchedItem;
-                // Remove the matched item from listAfter so it can't be matched again.
-                listAfter = removeItemsByName(listAfter, nameOfMatchedItem);
-                totalProcessedItems++;
-                onComparingItem?.(itemBefore, true, false, ItemComparisonResult.Renamed, nameOfMatchedItem, undefined, totalProcessedItems, listBefore.length - (iItem + 1) + listAfter.length);
-            }
-        }
-        catch (error) {
-            const warningMessage = `LLM processing failed for "before" item ${JSON.stringify(getItemName(itemBefore))}; marking as unchanged.`;
-            retval.unchanged.push(getItemName(itemBefore));
-            totalProcessedItems++;
-            onComparingItem?.(itemBefore, true, false, ItemComparisonResult.Unchanged, undefined, warningMessage, totalProcessedItems, listBefore.length - (iItem + 1) + listAfter.length);
             continue;
         }
-    }
-    // At this point, any remaining items in listAfter are probably added.
-    // However, there could be additional instructions that indicate otherwise.
-    for (let iItem = 0; iItem < listAfter.length; iItem++) {
-        const itemAfter = listAfter[iItem];
-        onComparingItem?.(itemAfter, false, true, ItemComparisonResult.Unchanged, undefined, undefined, totalProcessedItems, listAfter.length - iItem);
-        try {
-            const convoIter = convo.clone();
-            convoIter.addUserMessage(`
-At the moment, let's focus on this item from the "after" list:
-
-${itemToPromptString(itemAfter)}
-
-We think that this item was newly added, because we can't find any matching item
-from the "before" list. However, it's possible that we have instructions or context
-that indicate otherwise.
-
-At this point, we don't have the option of matching this item to any item from the "before"
-list, since we've already processed all those items. However, we still have the option
-of rejecting this item from addition -- in which case, it will be considered as not having
-been added at all (or, in other words, it will be ignored in downstream processing).
-
-What do you think? Should we consider this item as truly added, or should we reject / ignore
-this item?
-`);
-            await convoIter.submit();
-            await convoIter.submit(undefined, undefined, {
-                jsonResponse: JSONSchemaFormat('list_comparison_item_addition_decision', {
-                    is_added: [
-                        Boolean,
-                        `Whether this item from the "after" list should be considered as truly added. ` +
-                            `If false, the item will be ignored in downstream processing.`,
-                    ],
-                }),
+        const itemAfter = listAfter[indexMatchedInAfter];
+        if (areItemsEqual(itemBefore, itemAfter)) {
+            retval.push({
+                item: itemBefore,
+                classification: ItemComparisonClassification.Unchanged,
+                newName: undefined,
             });
-            const isItemAdded = convoIter.getLastReplyDictField('is_added');
-            if (isItemAdded) {
-                retval.added.push(getItemName(itemAfter));
-                totalProcessedItems++;
-                onComparingItem?.(itemAfter, false, false, ItemComparisonResult.Added, undefined, undefined, totalProcessedItems, listAfter.length - (iItem + 1));
-                continue;
-            }
-            totalProcessedItems++;
-            onComparingItem?.(itemAfter, false, false, ItemComparisonResult.Unchanged, undefined, undefined, totalProcessedItems, listAfter.length - (iItem + 1));
         }
-        catch (error) {
-            const warningMessage = `LLM processing failed for "after" item ${JSON.stringify(getItemName(itemAfter))}; skipping add classification for this item.`;
-            totalProcessedItems++;
-            onComparingItem?.(itemAfter, false, false, ItemComparisonResult.Unchanged, undefined, warningMessage, totalProcessedItems, listAfter.length - (iItem + 1));
-            continue;
+        else {
+            retval.push({
+                item: itemBefore,
+                classification: ItemComparisonClassification.Renamed,
+                newName: getItemName(itemAfter),
+            });
         }
+        // Remove the matched item from the "after" list so it can't be matched again.
+        listAfter.splice(indexMatchedInAfter, 1);
+    }
+    // All of the remaining items in the "after" list are considered added.
+    for (const itemAfter of listAfter) {
+        retval.push({
+            item: itemAfter,
+            classification: ItemComparisonClassification.Added,
+            newName: undefined,
+        });
     }
-    return {
-        removed: [...new Set(retval.removed)].sort(),
-        added: [...new Set(retval.added)].sort(),
-        renamed: retval.renamed,
-        unchanged: [...new Set(retval.unchanged)].sort(),
-    };
+    return retval;
 };

package/dist/src/semanticMatch/find.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Semantic match finder for migration-style item lists.
+ *
+ * This module provides a helper that determines whether a "test item" is already present
+ * in an existing list, even when names are different. In this context, a semantic match
+ * means two labels point to the same underlying concept (for example, renamed fields,
+ * wording changes, or synonyms).
+ *
+ * Matching strategy:
+ * 1) Check for exact name equality.
+ * 2) If no exact match exists, use an LLM to infer conceptual equivalence.
+ *
+ * The exported function returns the index of the first matching list item when a match
+ * is found, or `-1` when no sufficiently similar item exists.
+ */
+import { OpenAI } from 'openai';
+import { SemanticItem } from './semanticItem.js';
+/**
+ * Finds the best semantic match for a test item within a list of items.
+ *
+ * A semantic match means two items represent the same underlying concept even if their
+ * names differ (for example, due to renaming, wording changes, or synonyms).
+ *
+ * The function first checks for an exact name match and returns its index immediately
+ * if found.
+ * If no exact match exists, it asks the LLM to decide whether the test item is represented
+ * in the list under a different name and returns the index of the first matching list item,
+ * or `-1` when no good semantic match is found.
+ *
+ * @param openaiClient An instance of the OpenAI client to use for LLM interactions.
+ * @param itemlist The list of strings/items to compare.
+ * @param itemToFind The item for which we want to find a semantic match in the list.
+ * @param explanation Optional explanation that provides context for the comparison, e.g.
+ * a description of the items or the nature of the changes.
+ * @returns The index of the first matching item from the list, or `-1` if no good match
+ * is found.
+ */
+export declare const findSemanticMatch: (openaiClient: OpenAI, itemlist: SemanticItem[], itemToFind: SemanticItem, explanation?: string) => Promise<number>;