mdi-llmkit 0.1.0 → 1.0.1

package/README.md

@@ -13,14 +13,14 @@ npm install mdi-llmkit openai
 ### `gptSubmit`
 
 ```ts
-import OpenAI from "openai";
-import { gptSubmit } from "mdi-llmkit";
+import OpenAI from 'openai';
+import { gptSubmit } from 'mdi-llmkit';
 
 const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
 const reply = await gptSubmit(
-	[{ role: "user", content: "Say hello." }],
-	client,
+  [{ role: 'user', content: 'Say hello.' }],
+  client
 );
 
 console.log(reply);
@@ -29,52 +29,132 @@ console.log(reply);
 ### `GptConversation`
 
 ```ts
-import OpenAI from "openai";
-import { GptConversation } from "mdi-llmkit";
+import OpenAI from 'openai';
+import { GptConversation } from 'mdi-llmkit';
 
 const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 const conversation = new GptConversation([], { openaiClient: client });
 
-const reply = await conversation.submitUserMessage("Give me three project name ideas.");
+const reply = await conversation.submitUserMessage(
+  'Give me three project name ideas.'
+);
 console.log(reply);
 ```
 
 ### `JSONSchemaFormat`
 
 ```ts
-import { JSONSchemaFormat, JSON_INTEGER, gptSubmit } from "mdi-llmkit";
+import { JSONSchemaFormat, JSON_INTEGER, gptSubmit } from 'mdi-llmkit';
 
 const responseFormat = JSONSchemaFormat(
-	{
-		answer: "The final answer",
-		confidence: ["Confidence score", [0, 100], []],
-		rank: JSON_INTEGER,
-	},
-	{
-		name: "answer_payload",
-		description: "Structured answer payload",
-	},
+  'answer_payload',
+  {
+    answer: 'The final answer',
+    confidence: ['Confidence score', [0, 100], []],
+    rank: JSON_INTEGER,
+  },
+  'Structured answer payload'
 );
 
 const result = await gptSubmit(
-	[{ role: "user", content: "Return answer as structured JSON." }],
-	client,
-	{ jsonResponse: responseFormat },
+  [{ role: 'user', content: 'Return answer as structured JSON.' }],
+  client,
+  { jsonResponse: responseFormat }
+);
+```
+
+## `jsonSurgery`
+
+`jsonSurgery` applies iterative, model-guided edits to a JSON-compatible object using
+structured JSON-path operations (`assign`, `append`, `insert`, `delete`, `rename`).
+
+```ts
+import { jsonSurgery } from 'mdi-llmkit/jsonSurgery';
+```
+
+- It deep-copies the input object and returns the modified copy.
+- It supports optional schema guidance and key-skipping for model-visible context.
+- It supports validation/progress callbacks and soft iteration/time limits.
+
+## `compareItemLists` (comparison)
+
+`compareItemLists` performs a semantic diff between a "before" list and an "after" list,
+including LLM-assisted rename/add/remove decisions.
+
+Types:
+
+- `SemanticallyComparableListItem`
+  - `string`
+  - `{ name: string; description?: string }`
+- `ItemComparisonResult`
+  - `Removed | Added | Renamed | Unchanged`
+- `OnComparingItemCallback`
+  - `(item, isFromBeforeList, isStarting, result, newName, error, totalProcessedSoFar, totalLeftToProcess) => void`
+
+Behavior notes:
+
+- Item matching is name-based and case-insensitive.
+- `description` provides extra model context but is not identity.
+- Names are expected to be unique within each list (case-insensitive).
+- Progress callback is fired at item start (`isStarting=true`) and finish (`isStarting=false`).
+
+Example:
+
+```ts
+import OpenAI from 'openai';
+import {
+  compareItemLists,
+  ItemComparisonResult,
+  type OnComparingItemCallback,
+} from 'mdi-llmkit/comparison';
+
+const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+const onComparingItem: OnComparingItemCallback = (
+  item,
+  isFromBeforeList,
+  isStarting,
+  result,
+  newName,
+  error,
+  processed,
+  left
+) => {
+  if (error) {
+    console.warn('Comparison warning:', error);
+  }
+  if (!isStarting && result === ItemComparisonResult.Renamed) {
+    console.log('Renamed:', item, '->', newName);
+  }
+  console.log({ isFromBeforeList, isStarting, result, processed, left });
+};
+
+const comparison = await compareItemLists(
+  client,
+  [{ name: 'Widget A', description: 'Legacy widget' }, 'Widget B'],
+  [
+    { name: 'Widget Alpha', description: 'Migrated name for Widget A' },
+    'Widget B',
+  ],
+  'Widgets migrated from legacy catalog to new naming standards.',
+  onComparingItem
 );
+
+console.log(comparison);
 ```
 
 ## JSON Response Mode
 
 ```ts
-import OpenAI from "openai";
-import { gptSubmit } from "mdi-llmkit";
+import OpenAI from 'openai';
+import { gptSubmit } from 'mdi-llmkit';
 
 const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
 const result = await gptSubmit(
-	[{ role: "user", content: "Return JSON with keys a and b." }],
-	client,
-	{ jsonResponse: true },
+  [{ role: 'user', content: 'Return JSON with keys a and b.' }],
+  client,
+  { jsonResponse: true }
 );
 
 console.log(result);
@@ -83,6 +163,8 @@ console.log(result);
 ## Notes
 
 - Current TypeScript parity slices include `gptSubmit`, `GptConversation`, and `JSONSchemaFormat`.
+- You can import GPT API symbols via subpath imports, e.g. `import { GptConversation } from "mdi-llmkit/gptApi"`.
+- Comparison symbols are available via `mdi-llmkit/comparison`.
 - Integer schemas can be expressed with `JSON_INTEGER`; numeric (float-capable) schemas can use `JSON_NUMBER`.
 
 ## Migration from Python
@@ -91,18 +173,18 @@ console.log(result);
 - Argument style: Python keyword args map to a TypeScript options object.
 - Conversation submit methods: Python `submit_user_message(...)` maps to `submitUserMessage(...)`.
 - JSON schema DSL: Python tuple metadata uses TypeScript array metadata.
-	- Python: `("Age", (0, 120), int)`
-	- TypeScript: `["Age", [0, 120], JSON_INTEGER]`
+  - Python: `("Age", (0, 120), int)`
+  - TypeScript: `["Age", [0, 120], JSON_INTEGER]`
 - JSON schema type markers in TypeScript:
-	- `JSON_INTEGER` for integer-only values.
-	- `JSON_NUMBER` for float-capable numeric values.
+  - `JSON_INTEGER` for integer-only values.
+  - `JSON_NUMBER` for float-capable numeric values.
 
 ## CI and Release
 
 - CI workflow: `.github/workflows/typescript-ci.yml`
-	- Runs on push to `main` and on pull requests when TypeScript package files change.
-	- Executes `npm ci`, `npm test`, and `npm run build` in `packages/typescript-mdi-llmkit`.
+  - Runs on push to `main` and on pull requests when TypeScript package files change.
+  - Executes `npm ci`, `npm test`, and `npm run build` in `packages/typescript-mdi-llmkit`.
 - Release workflow: `.github/workflows/typescript-release.yml`
-	- Runs on tags matching `typescript-v*` (for example: `typescript-v0.1.0`).
-	- Requires repository secret `NPM_TOKEN` with publish permission to npm.
-	- Executes tests/build before `npm publish --access public --provenance`.
+  - Runs on tags matching `typescript-v*` (for example: `typescript-v1.0.1`).
+  - Requires repository secret `NPM_TOKEN` with publish permission to npm.
+  - Executes tests/build before `npm publish --access public --provenance`.

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

@@ -0,0 +1,97 @@
+/**
+ * Utilities for semantic comparison of two item lists using deterministic pre-processing
+ * plus LLM-assisted decisions for ambiguous cases.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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;
+};
+/**
+ * Final classification of an item during comparison.
+ */
+export declare enum ItemComparisonResult {
+    /** Item existed in "before" and is considered deleted in "after". */
+    Removed = "removed",
+    /** Item exists in "after" and is considered newly introduced. */
+    Added = "added",
+    /** Item from "before" was matched to a different name in "after". */
+    Renamed = "renamed",
+    /** Item is treated as unchanged or unresolved for downstream purposes. */
+    Unchanged = "unchanged"
+}
+/**
+ * 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.
+ * @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
+ */
+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[];
+}>;

package/dist/src/comparison/compareLists.js

@@ -0,0 +1,375 @@
+import { GptConversation } from '../gptApi/gptConversation.js';
+import { JSONSchemaFormat } from '../gptApi/jsonSchemaFormat.js';
+/**
+ * Final classification of an item during comparison.
+ */
+export var ItemComparisonResult;
+(function (ItemComparisonResult) {
+    /** Item existed in "before" and is considered deleted in "after". */
+    ItemComparisonResult["Removed"] = "removed";
+    /** Item exists in "after" and is considered newly introduced. */
+    ItemComparisonResult["Added"] = "added";
+    /** Item from "before" was matched to a different name in "after". */
+    ItemComparisonResult["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(', ')}`);
+    }
+};
+/**
+ * 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.
+ * @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
+ */
+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.',
+                    ],
+                }),
+            });
+            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 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;
+        }
+    }
+    return {
+        removed: [...new Set(retval.removed)].sort(),
+        added: [...new Set(retval.added)].sort(),
+        renamed: retval.renamed,
+        unchanged: [...new Set(retval.unchanged)].sort(),
+    };
+};