mdi-llmkit 1.1.0 → 1.1.3

package/dist/tests/semanticMatch/compareLists.test.js

@@ -0,0 +1,177 @@
+import { OpenAI } from 'openai';
+import { describe, expect, it } from 'vitest';
+import { compareItemLists, ItemComparisonClassification, } from '../../src/semanticMatch/compareLists.js';
+import { getItemName } from '../../src/semanticMatch/semanticItem.js';
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY?.trim();
+if (!OPENAI_API_KEY) {
+    throw new Error('OPENAI_API_KEY is required for compareItemLists live API tests. Configure your test environment to provide it.');
+}
+const createClient = () => new OpenAI({
+    apiKey: OPENAI_API_KEY,
+});
+const getByClassification = (results, classification) => results.filter((entry) => entry.classification === classification);
+const getNamesByClassification = (results, classification) => getByClassification(results, classification).map((entry) => getItemName(entry.item));
+const getRenamedMap = (results) => {
+    const renamed = {};
+    for (const entry of getByClassification(results, ItemComparisonClassification.Renamed)) {
+        renamed[getItemName(entry.item)] = entry.newName || '';
+    }
+    return renamed;
+};
+describe('compareItemLists (live API)', () => {
+    // IMPORTANT: These tests intentionally use live OpenAI calls and DO NOT mock findSemanticMatch.
+    // We are validating end-to-end behavior for the current record-based result contract.
+    describe('current return contract', () => {
+        it('returns per-item records with classification and optional newName', async () => {
+            const results = await compareItemLists(createClient(), ['Legacy Plan Alpha'], ['Modern Plan Alpha'], 'Legacy Plan Alpha was renamed to Modern Plan Alpha.');
+            expect(Array.isArray(results)).toBe(true);
+            expect(results.length).toBe(1);
+            expect(results[0].item).toBe('Legacy Plan Alpha');
+            expect(results[0].classification).toBe(ItemComparisonClassification.Renamed);
+            expect(results[0].newName).toBe('Modern Plan Alpha');
+        }, 180000);
+    });
+    describe('deterministic exact-match behavior', () => {
+        it('classifies exact string matches as unchanged and does not mutate inputs', async () => {
+            const before = ['String Item A', 'String Item B'];
+            const after = ['string item a', 'STRING ITEM B'];
+            const beforeSnapshot = JSON.parse(JSON.stringify(before));
+            const afterSnapshot = JSON.parse(JSON.stringify(after));
+            const results = await compareItemLists(createClient(), before, after);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Unchanged)).toEqual([
+                'String Item A',
+                'String Item B',
+            ]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Removed)).toEqual([]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Added)).toEqual([]);
+            expect(getRenamedMap(results)).toEqual({});
+            expect(before).toEqual(beforeSnapshot);
+            expect(after).toEqual(afterSnapshot);
+        }, 180000);
+        it('classifies object-vs-string same-name pair as unchanged', async () => {
+            const results = await compareItemLists(createClient(), [
+                {
+                    name: 'Georgia',
+                    description: 'A sovereign country in the South Caucasus. Capital: Tbilisi.',
+                },
+            ], ['georgia']);
+            expect(results).toHaveLength(1);
+            expect(results[0].classification).toBe(ItemComparisonClassification.Unchanged);
+            expect(results[0].newName).toBeUndefined();
+        }, 180000);
+    });
+    describe('added and removed behavior', () => {
+        it('classifies before-only item as removed', async () => {
+            const results = await compareItemLists(createClient(), ['Delete Me Item'], [], 'Delete Me Item was intentionally removed and has no replacement.');
+            expect(getNamesByClassification(results, ItemComparisonClassification.Removed)).toEqual([
+                'Delete Me Item',
+            ]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Added)).toEqual([]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Unchanged)).toEqual([]);
+            expect(getRenamedMap(results)).toEqual({});
+        }, 180000);
+        it('classifies after-only items as added', async () => {
+            const results = await compareItemLists(createClient(), [], ['Brand New Additive Item', 'Second New Item']);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Added)).toEqual([
+                'Brand New Additive Item',
+                'Second New Item',
+            ]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Removed)).toEqual([]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Unchanged)).toEqual([]);
+            expect(getRenamedMap(results)).toEqual({});
+        }, 180000);
+    });
+    describe('rename behavior', () => {
+        it('detects a single guided rename', async () => {
+            const results = await compareItemLists(createClient(), ['ACME Legacy Plan'], ['ACME Modern Plan'], 'There is exactly one rename in this migration. ' +
+                'ACME Legacy Plan was renamed to ACME Modern Plan. ' +
+                'Treat this as rename, not add/remove.');
+            expect(getRenamedMap(results)).toEqual({
+                'ACME Legacy Plan': 'ACME Modern Plan',
+            });
+            expect(getNamesByClassification(results, ItemComparisonClassification.Removed)).toEqual([]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Added)).toEqual([]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Unchanged)).toEqual([]);
+        }, 180000);
+        it('handles two guided renames in one run', async () => {
+            const results = await compareItemLists(createClient(), ['Legacy Product Alpha', 'Legacy Product Beta'], ['Modern Product Alpha', 'Modern Product Beta'], 'Two renames occurred with one-to-one mapping. ' +
+                'Legacy Product Alpha -> Modern Product Alpha. ' +
+                'Legacy Product Beta -> Modern Product Beta. ' +
+                'No deletions or net additions in this migration.');
+            expect(getRenamedMap(results)).toEqual({
+                'Legacy Product Alpha': 'Modern Product Alpha',
+                'Legacy Product Beta': 'Modern Product Beta',
+            });
+            expect(getNamesByClassification(results, ItemComparisonClassification.Removed)).toEqual([]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Added)).toEqual([]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Unchanged)).toEqual([]);
+        }, 180000);
+    });
+    describe('mixed outcomes', () => {
+        it('returns records for unchanged + renamed + removed + added in one run', async () => {
+            const results = await compareItemLists(createClient(), ['Shared Constant Item', 'Legacy Rename Target', 'Delete Candidate'], ['shared constant item', 'Modern Rename Target', 'Add Candidate'], 'Legacy Rename Target was renamed to Modern Rename Target. ' +
+                'Delete Candidate was removed. ' +
+                'Add Candidate was newly added. ' +
+                'Shared Constant Item is unchanged.');
+            expect(getNamesByClassification(results, ItemComparisonClassification.Unchanged)).toEqual([
+                'Shared Constant Item',
+            ]);
+            expect(getRenamedMap(results)).toEqual({
+                'Legacy Rename Target': 'Modern Rename Target',
+            });
+            expect(getNamesByClassification(results, ItemComparisonClassification.Removed)).toEqual([
+                'Delete Candidate',
+            ]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Added)).toEqual([
+                'Add Candidate',
+            ]);
+        }, 180000);
+        it('returns one result record per before-item plus unmatched after-items', async () => {
+            const before = ['A', 'B', 'C'];
+            const after = ['a', 'B-NEW', 'D'];
+            const results = await compareItemLists(createClient(), before, after, 'A is unchanged (case only). B was renamed to B-NEW. C was removed. D was added.');
+            expect(results.length).toBe(4);
+        }, 180000);
+    });
+    describe('additional behavior coverage', () => {
+        it('consumes a matched after-item once, leaving subsequent similar item as removed', async () => {
+            const results = await compareItemLists(createClient(), ['Legacy Item Alpha', 'Legacy Item Alpha Copy'], ['Modern Item Alpha'], 'Only Legacy Item Alpha was renamed to Modern Item Alpha. Legacy Item Alpha Copy was removed.');
+            expect(getRenamedMap(results)).toEqual({
+                'Legacy Item Alpha': 'Modern Item Alpha',
+            });
+            expect(getNamesByClassification(results, ItemComparisonClassification.Removed)).toEqual([
+                'Legacy Item Alpha Copy',
+            ]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Added)).toEqual([]);
+        }, 180000);
+        it('preserves order of added records from remaining after-list items', async () => {
+            const results = await compareItemLists(createClient(), [], [
+                { name: 'Added First', description: 'first' },
+                { name: 'Added Second', description: 'second' },
+                'Added Third',
+            ]);
+            expect(getNamesByClassification(results, ItemComparisonClassification.Added)).toEqual([
+                'Added First',
+                'Added Second',
+                'Added Third',
+            ]);
+        }, 180000);
+        it('does not mutate before or after lists in mixed classification scenarios', async () => {
+            const before = [
+                'Stable Name',
+                'Legacy Rename Candidate',
+                'Legacy Removed Candidate',
+            ];
+            const after = [
+                'stable name',
+                'Modern Rename Candidate',
+                'Newly Added Candidate',
+            ];
+            const beforeSnapshot = JSON.parse(JSON.stringify(before));
+            const afterSnapshot = JSON.parse(JSON.stringify(after));
+            await compareItemLists(createClient(), before, after, 'Legacy Rename Candidate was renamed to Modern Rename Candidate. Legacy Removed Candidate was removed. Newly Added Candidate was added.');
+            expect(before).toEqual(beforeSnapshot);
+            expect(after).toEqual(afterSnapshot);
+        }, 180000);
+    });
+});

package/dist/tests/semanticMatch/find.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/semanticMatch/find.test.js

@@ -0,0 +1,234 @@
+import { OpenAI } from 'openai';
+import { describe, expect, it } from 'vitest';
+import { findSemanticMatch } from '../../src/semanticMatch/find.js';
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY?.trim();
+if (!OPENAI_API_KEY) {
+    throw new Error('OPENAI_API_KEY is required for findSemanticMatch live API tests. Configure your test environment to provide it.');
+}
+const createClient = () => new OpenAI({
+    apiKey: OPENAI_API_KEY,
+});
+const expectMatch = async (list, testItem, expectedIndex, explanation) => {
+    const result = await findSemanticMatch(createClient(), list, testItem, explanation);
+    expect(result).toBe(expectedIndex);
+};
+const expectNoMatch = async (list, testItem, explanation) => {
+    const result = await findSemanticMatch(createClient(), list, testItem, explanation);
+    expect(result).toBe(-1);
+};
+const expectOneOfMatches = async (list, testItem, expectedIndexes, explanation) => {
+    const result = await findSemanticMatch(createClient(), list, testItem, explanation);
+    expect(expectedIndexes).toContain(result);
+};
+describe('findSemanticMatch (live API)', () => {
+    // IMPORTANT: These tests intentionally use live OpenAI calls and DO NOT mock GptConversation.
+    // We are validating real prompt+schema behavior end-to-end.
+    describe('exact-match short-circuit behavior', () => {
+        it('returns case-insensitive exact match without needing LLM resolution', async () => {
+            const invalidClient = new OpenAI({
+                apiKey: `${OPENAI_API_KEY}-INTENTIONALLY-INVALID-FOR-EXACT-MATCH-TEST`,
+            });
+            const result = await findSemanticMatch(invalidClient, ['Chickenpox', 'Measles', 'Cold sore'], 'measles');
+            expect(result).toBe(1);
+        }, 180000);
+        it('returns the first index when multiple string items match case-insensitively', async () => {
+            const invalidClient = new OpenAI({
+                apiKey: `${OPENAI_API_KEY}-INTENTIONALLY-INVALID-FOR-DUPLICATE-INDEX-TEST`,
+            });
+            const result = await findSemanticMatch(invalidClient, ['Georgia', 'France', 'GEORGIA'], 'georgia');
+            expect(result).toBe(0);
+        }, 180000);
+        it('short-circuits when list item has description but test item is string', async () => {
+            const invalidClient = new OpenAI({
+                apiKey: `${OPENAI_API_KEY}-INTENTIONALLY-INVALID-FOR-STRING-OBJECT-SHORTCUT-TEST`,
+            });
+            const result = await findSemanticMatch(invalidClient, [
+                {
+                    name: 'Georgia',
+                    description: 'A sovereign country in the South Caucasus. Capital: Tbilisi.',
+                },
+                {
+                    name: 'France',
+                    description: 'A country in Western Europe. Capital: Paris.',
+                },
+            ], 'Georgia');
+            expect(result).toBe(0);
+        }, 180000);
+        it('short-circuits when both name/desc items have equal descriptions after trimming', async () => {
+            const invalidClient = new OpenAI({
+                apiKey: `${OPENAI_API_KEY}-INTENTIONALLY-INVALID-FOR-EQUAL-DESCRIPTION-SHORTCUT-TEST`,
+            });
+            const result = await findSemanticMatch(invalidClient, [
+                {
+                    name: 'Georgia',
+                    description: 'A U.S. state in the southeastern U.S. Capital: Atlanta.',
+                },
+                {
+                    name: 'France',
+                    description: 'A country in Western Europe. Capital: Paris.',
+                },
+            ], {
+                name: 'Georgia',
+                description: '  A U.S. state in the southeastern U.S. Capital: Atlanta.  ',
+            });
+            expect(result).toBe(0);
+        }, 180000);
+        it('does not short-circuit when names match but descriptions conflict', async () => {
+            const invalidClient = new OpenAI({
+                apiKey: `${OPENAI_API_KEY}-INTENTIONALLY-INVALID-FOR-CONFLICTING-DESCRIPTION-TEST`,
+            });
+            await expect(findSemanticMatch(invalidClient, [
+                {
+                    name: 'Georgia',
+                    description: 'A U.S. state in the southeastern United States. Capital: Atlanta.',
+                },
+                {
+                    name: 'France',
+                    description: 'A country in Western Europe. Capital: Paris.',
+                },
+            ], {
+                name: 'Georgia',
+                description: 'A sovereign country in the South Caucasus. Capital: Tbilisi.',
+            })).rejects.toThrow();
+        }, 180000);
+    });
+    describe('medicine colloquial vs clinical names', () => {
+        it('maps Varicella to Chickenpox', async () => {
+            await expectMatch(['Chickenpox', 'Measles', 'Cold sore'], 'Varicella', 0);
+        }, 180000);
+        it('maps Pertussis to Whooping cough', async () => {
+            await expectMatch(['Whooping cough', 'Mumps', 'Tetanus'], 'Pertussis', 0);
+        }, 180000);
+        it('maps Rubella to German measles', async () => {
+            await expectMatch(['German measles', 'Scarlet fever', 'Shingles'], 'Rubella', 0);
+        }, 180000);
+        it('maps Conjunctivitis to Pink eye', async () => {
+            await expectMatch(['Pink eye', 'Flu', 'Strep throat'], 'Conjunctivitis', 0);
+        }, 180000);
+        it('maps Infectious mononucleosis to Mono', async () => {
+            await expectMatch(['Mono', 'Chickenpox', 'Bronchitis'], 'Infectious mononucleosis', 0);
+        }, 180000);
+        it('returns -1 for unrelated clinical condition', async () => {
+            await expectNoMatch(['Migraine', 'Asthma', 'Eczema'], 'Appendicitis');
+        }, 180000);
+    });
+    describe('geography modern vs historical names', () => {
+        it('maps Nippon to Japan', async () => {
+            await expectMatch(['China', 'Japan', 'Singapore'], 'Nippon', 1);
+        }, 180000);
+        it('maps Persia to Iran', async () => {
+            await expectMatch(['Iran', 'Iraq', 'Turkey'], 'Persia', 0);
+        }, 180000);
+        it('maps Siam to Thailand', async () => {
+            await expectMatch(['Thailand', 'Vietnam', 'Laos'], 'Siam', 0);
+        }, 180000);
+        it('maps Ceylon to Sri Lanka', async () => {
+            await expectMatch(['Sri Lanka', 'India', 'Nepal'], 'Ceylon', 0);
+        }, 180000);
+        it('maps Burma to Myanmar', async () => {
+            await expectMatch(['Myanmar', 'Bangladesh', 'Bhutan'], 'Burma', 0);
+        }, 180000);
+        it('returns -1 when no country in list is semantically related', async () => {
+            await expectNoMatch(['Canada', 'Mexico', 'Brazil'], 'Prussia');
+        }, 180000);
+    });
+    describe('geography same-name disambiguation (Georgia)', () => {
+        it('chooses Georgia the country when both state and country are present as name/desc items', async () => {
+            await expectMatch([
+                {
+                    name: 'Georgia',
+                    description: 'A U.S. state in the southeastern United States. Capital: Atlanta.',
+                },
+                {
+                    name: 'Georgia',
+                    description: 'A sovereign country in the South Caucasus. Capital: Tbilisi.',
+                },
+                {
+                    name: 'France',
+                    description: 'A country in Western Europe. Capital: Paris.',
+                },
+            ], {
+                name: 'Georgia',
+                description: 'A country in the South Caucasus bordered by Turkey, Armenia, and Azerbaijan. Capital: Tbilisi.',
+            }, 1);
+        }, 180000);
+        it('chooses Georgia the U.S. state when both state and country are present as name/desc items', async () => {
+            await expectMatch([
+                {
+                    name: 'Georgia',
+                    description: 'A U.S. state in the southeastern United States. Capital: Atlanta.',
+                },
+                {
+                    name: 'Georgia',
+                    description: 'A sovereign country in the South Caucasus. Capital: Tbilisi.',
+                },
+                {
+                    name: 'France',
+                    description: 'A country in Western Europe. Capital: Paris.',
+                },
+            ], {
+                name: 'Georgia',
+                description: 'A U.S. state in the southeastern U.S. with Atlanta as its capital.',
+            }, 0);
+        }, 180000);
+        it('accepts either Georgia index for string-only test item with several red herrings', async () => {
+            await expectOneOfMatches([
+                {
+                    name: 'Georgia',
+                    description: 'A U.S. state in the southeastern United States. Capital: Atlanta.',
+                },
+                {
+                    name: 'Georgia',
+                    description: 'A sovereign country in the South Caucasus. Capital: Tbilisi.',
+                },
+                {
+                    name: 'France',
+                    description: 'A country in Western Europe. Capital: Paris.',
+                },
+                {
+                    name: 'Florida',
+                    description: 'A U.S. state in the southeastern U.S. Capital: Tallahassee.',
+                },
+                {
+                    name: 'Armenia',
+                    description: 'A country in the South Caucasus. Capital: Yerevan.',
+                },
+            ], 'Georgia', [0, 1]);
+        }, 180000);
+        it('matches the single Georgia string item when test item provides state description', async () => {
+            await expectMatch(['Georgia', 'France', 'Japan'], {
+                name: 'Georgia',
+                description: 'A U.S. state in the southeastern United States. Capital: Atlanta.',
+            }, 0);
+        }, 180000);
+        it('returns -1 when list contains Georgia country but test item describes Georgia state', async () => {
+            await expectNoMatch([
+                {
+                    name: 'Georgia',
+                    description: 'A sovereign country in the South Caucasus. Capital: Tbilisi.',
+                },
+                {
+                    name: 'France',
+                    description: 'A country in Western Europe. Capital: Paris.',
+                },
+                {
+                    name: 'Alabama',
+                    description: 'A U.S. state in the southeastern United States. Capital: Montgomery.',
+                },
+            ], {
+                name: 'Georgia',
+                description: 'A U.S. state in the southeastern United States. Capital: Atlanta.',
+            });
+        }, 180000);
+    });
+    describe('context-guided disambiguation', () => {
+        it('uses explanation to choose the correct Congo variant', async () => {
+            await expectMatch([
+                'Republic of the Congo',
+                'Democratic Republic of the Congo',
+                'Gabon',
+            ], 'Congo-Brazzaville', 0, 'Interpret Congo-Brazzaville as the country whose capital is Brazzaville. ' +
+                'Do not map it to the Democratic Republic of the Congo.');
+        }, 180000);
+    });
+});

package/dist/tests/semanticMatch/semanticItem.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/semanticMatch/semanticItem.test.js

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest';
+import { areItemsEqual, compareItems, getItemDescription, getItemName, itemToPromptString, removeItemFromList, } from '../../src/semanticMatch/semanticItem.js';
+describe('semanticItem helpers', () => {
+    describe('getItemName', () => {
+        it('returns the raw value for string items', () => {
+            expect(getItemName('Widget')).toBe('Widget');
+        });
+        it('returns the name field for object items', () => {
+            expect(getItemName({ name: 'Widget', description: 'A part' })).toBe('Widget');
+        });
+    });
+    describe('getItemDescription', () => {
+        it('returns undefined for string items', () => {
+            expect(getItemDescription('Widget')).toBeUndefined();
+        });
+        it('returns undefined when object description is missing', () => {
+            expect(getItemDescription({ name: 'Widget' })).toBeUndefined();
+        });
+        it('returns undefined when description equals name ignoring case and whitespace', () => {
+            expect(getItemDescription({
+                name: 'Product Alpha',
+                description: '  product alpha  ',
+            })).toBeUndefined();
+        });
+        it('returns description when it provides additional context', () => {
+            expect(getItemDescription({
+                name: 'Product Alpha',
+                description: 'Legacy tier retained for existing contracts',
+            })).toBe('Legacy tier retained for existing contracts');
+        });
+        it('preserves original description text when returning value', () => {
+            expect(getItemDescription({
+                name: 'Product Alpha',
+                description: '  Legacy tier retained for existing contracts  ',
+            })).toBe('  Legacy tier retained for existing contracts  ');
+        });
+    });
+    describe('itemToPromptString', () => {
+        it('formats string items as a bullet with JSON-escaped content', () => {
+            expect(itemToPromptString('Line "A"\nLine B')).toBe('- "Line \\"A\\"\\nLine B"');
+        });
+        it('formats object items with only the name when description is absent', () => {
+            expect(itemToPromptString({ name: 'Product Alpha' })).toBe('- "Product Alpha"');
+        });
+        it('omits details when description equals name ignoring case and whitespace', () => {
+            expect(itemToPromptString({
+                name: 'Product Alpha',
+                description: '  product alpha  ',
+            })).toBe('- "Product Alpha"');
+        });
+        it('includes details when description is meaningfully different', () => {
+            expect(itemToPromptString({
+                name: 'Product Alpha',
+                description: 'Replaces legacy alpha tier',
+            })).toBe('- "Product Alpha" (details: "Replaces legacy alpha tier")');
+        });
+    });
+    describe('compareItems', () => {
+        it('returns 0 for names equal ignoring case', () => {
+            expect(compareItems('Widget', 'widget')).toBe(0);
+        });
+        it('sorts by case-insensitive names', () => {
+            const items = [
+                'zeta',
+                { name: 'Bravo' },
+                'alpha',
+                { name: 'charlie' },
+            ];
+            const sortedNames = [...items].sort(compareItems).map(getItemName);
+            expect(sortedNames).toEqual(['alpha', 'Bravo', 'charlie', 'zeta']);
+        });
+        it('trims names before comparing', () => {
+            expect(compareItems('name', ' name')).toBe(0);
+        });
+        it('uses descriptions as case-insensitive tie-breaker when names are equal', () => {
+            expect(compareItems({ name: 'Georgia', description: 'zebra context' }, { name: 'Georgia', description: 'alpha context' })).toBeGreaterThan(0);
+        });
+        it('treats description case differences as equal in tie-break comparison', () => {
+            expect(compareItems({ name: 'Georgia', description: 'Country in caucasus' }, { name: 'Georgia', description: 'country in caucasus' })).toBe(0);
+        });
+    });
+    describe('areItemsEqual', () => {
+        it('is true for items with equal names ignoring case and whitespace', () => {
+            expect(areItemsEqual(' Catalog Item ', { name: 'catalog item' })).toBe(true);
+        });
+        it('is false for different names', () => {
+            expect(areItemsEqual('Catalog Item A', { name: 'Catalog Item B' })).toBe(false);
+        });
+        it('is false when names match but meaningful descriptions differ', () => {
+            expect(areItemsEqual({ name: 'Catalog Item', description: 'old' }, { name: 'catalog item', description: 'new' })).toBe(false);
+        });
+        it('treats name+description Georgia as equal to string Georgia', () => {
+            expect(areItemsEqual({
+                name: 'Georgia',
+                description: 'A sovereign country in the South Caucasus. Capital: Tbilisi.',
+            }, 'georgia')).toBe(true);
+        });
+    });
+    describe('removeItemFromList', () => {
+        it('removes matching string items case-insensitively', () => {
+            const original = ['Alpha', 'Bravo', 'alpha'];
+            const result = removeItemFromList(original, 'ALPHA');
+            expect(result).toEqual(['Bravo']);
+        });
+        it('removes object items when both name and description are equivalent', () => {
+            const original = [
+                { name: 'Catalog Item', description: 'legacy details' },
+                { name: 'Catalog Item', description: 'LEGACY DETAILS' },
+                { name: 'Other Item' },
+            ];
+            const result = removeItemFromList(original, {
+                name: 'catalog item',
+                description: '  legacy details  ',
+            });
+            expect(result).toEqual([{ name: 'Other Item' }]);
+        });
+        it('removes the item that does not have a description when name is ambiguous', () => {
+            const original = [
+                { name: 'Catalog Item', description: 'first copy' },
+                'catalog item',
+                { name: 'Other Item' },
+            ];
+            const result = removeItemFromList(original, {
+                name: 'CATALOG ITEM',
+                description: 'query description does not matter',
+            });
+            expect(result).toEqual([
+                { name: 'Catalog Item', description: 'first copy' },
+                { name: 'Other Item' },
+            ]);
+            expect(result).not.toBe(original);
+        });
+        it('does not remove items that only match by name when descriptions differ', () => {
+            const original = [
+                { name: 'Catalog Item', description: 'first copy' },
+                { name: 'catalog item', description: 'second copy' },
+                { name: 'Other Item' },
+            ];
+            const result = removeItemFromList(original, {
+                name: 'CATALOG ITEM',
+                description: 'query description does not matter',
+            });
+            expect(result).toEqual(original);
+            expect(result).not.toBe(original);
+        });
+        it('returns a new list and does not mutate the input array', () => {
+            const original = ['Alpha', 'Bravo'];
+            const result = removeItemFromList(original, 'alpha');
+            expect(result).toEqual(['Bravo']);
+            expect(original).toEqual(['Alpha', 'Bravo']);
+            expect(result).not.toBe(original);
+        });
+        it('returns unchanged items when there is no equivalent item', () => {
+            const original = ['Alpha', { name: 'Bravo' }];
+            const result = removeItemFromList(original, 'Charlie');
+            expect(result).toEqual(['Alpha', { name: 'Bravo' }]);
+        });
+    });
+});

package/dist/tests/subpathExports.test.js

@@ -5,16 +5,16 @@ import path from 'node:path';
 import { beforeAll, describe, expect, it } from 'vitest';
 const DIST_GPTAPI_INDEX = path.resolve('dist/src/gptApi/index.js');
 const DIST_JSON_SURGERY = path.resolve('dist/src/jsonSurgery/index.js');
-const DIST_COMPARISON_INDEX = path.resolve('dist/src/comparison/index.js');
+const DIST_SEMANTIC_MATCH_INDEX = path.resolve('dist/src/semanticMatch/index.js');
 beforeAll(() => {
     if (!existsSync(DIST_GPTAPI_INDEX) ||
         !existsSync(DIST_JSON_SURGERY) ||
-        !existsSync(DIST_COMPARISON_INDEX)) {
+        !existsSync(DIST_SEMANTIC_MATCH_INDEX)) {
         execSync('npm run build', { stdio: 'inherit' });
     }
 });
 describe('package subpath exports', () => {
-    it('declares gptApi, jsonSurgery, and comparison in package exports', async () => {
+    it('declares gptApi, jsonSurgery, and semanticMatch in package exports', async () => {
         const packageJsonPath = path.resolve('package.json');
         const packageJsonRaw = await readFile(packageJsonPath, 'utf8');
         const packageJson = JSON.parse(packageJsonRaw);
@@ -24,9 +24,9 @@ describe('package subpath exports', () => {
         expect(packageJson.exports?.['./jsonSurgery']).toBeDefined();
         expect(packageJson.exports?.['./jsonSurgery']?.types).toBe('./dist/src/jsonSurgery/index.d.ts');
         expect(packageJson.exports?.['./jsonSurgery']?.import).toBe('./dist/src/jsonSurgery/index.js');
-        expect(packageJson.exports?.['./comparison']).toBeDefined();
-        expect(packageJson.exports?.['./comparison']?.types).toBe('./dist/src/comparison/index.d.ts');
-        expect(packageJson.exports?.['./comparison']?.import).toBe('./dist/src/comparison/index.js');
+        expect(packageJson.exports?.['./semanticMatch']).toBeDefined();
+        expect(packageJson.exports?.['./semanticMatch']?.types).toBe('./dist/src/semanticMatch/index.d.ts');
+        expect(packageJson.exports?.['./semanticMatch']?.import).toBe('./dist/src/semanticMatch/index.js');
     });
     it('imports GPT API symbols from "mdi-llmkit/gptApi"', async () => {
         const mod = await import('mdi-llmkit/gptApi');
@@ -39,9 +39,13 @@ describe('package subpath exports', () => {
         expect(typeof mod.jsonSurgery).toBe('function');
         expect(typeof mod.JSONSurgeryError).toBe('function');
     });
-    it('imports comparison symbols from "mdi-llmkit/comparison"', async () => {
-        const mod = await import('mdi-llmkit/comparison');
+    it('imports semanticMatch symbols from "mdi-llmkit/semanticMatch"', async () => {
+        const mod = await import('mdi-llmkit/semanticMatch');
         expect(typeof mod.compareItemLists).toBe('function');
         expect(typeof mod.ItemComparisonResult).toBe('object');
+        expect(typeof mod.getItemName).toBe('function');
+        expect(typeof mod.itemToPromptString).toBe('function');
+        expect(typeof mod.compareItems).toBe('function');
+        expect(typeof mod.areItemsEqual).toBe('function');
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdi-llmkit",
-  "version": "1.1.0",
+  "version": "1.1.3",
   "description": "Utilities for managing multi-shot conversations and structured data handling in LLM applications",
   "author": "Mikhail Voloshin",
   "license": "MIT",
@@ -25,9 +25,9 @@
       "types": "./dist/src/jsonSurgery/index.d.ts",
       "import": "./dist/src/jsonSurgery/index.js"
     },
-    "./comparison": {
-      "types": "./dist/src/comparison/index.d.ts",
-      "import": "./dist/src/comparison/index.js"
+    "./semanticMatch": {
+      "types": "./dist/src/semanticMatch/index.d.ts",
+      "import": "./dist/src/semanticMatch/index.js"
     }
   },
   "files": [