mdi-llmkit 0.1.0 → 1.0.5

package/README.md

@@ -1,108 +1,190 @@
-# mdi-llmkit (TypeScript)
-
-Utilities for managing LLM chat conversations and structured JSON responses with OpenAI's Responses API.
-
-## Installation
-
-```bash
-npm install mdi-llmkit openai
-```
-
-## Quick Start
-
-### `gptSubmit`
-
-```ts
-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,
-);
-
-console.log(reply);
-```
-
-### `GptConversation`
-
-```ts
-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.");
-console.log(reply);
-```
-
-### `JSONSchemaFormat`
-
-```ts
-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",
-	},
-);
-
-const result = await gptSubmit(
-	[{ role: "user", content: "Return answer as structured JSON." }],
-	client,
-	{ jsonResponse: responseFormat },
-);
-```
-
-## JSON Response Mode
-
-```ts
-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 },
-);
-
-console.log(result);
-```
-
-## Notes
-
-- Current TypeScript parity slices include `gptSubmit`, `GptConversation`, and `JSONSchemaFormat`.
-- Integer schemas can be expressed with `JSON_INTEGER`; numeric (float-capable) schemas can use `JSON_NUMBER`.
-
-## Migration from Python
-
-- Function naming: Python `gpt_submit(...)` maps to TypeScript `gptSubmit(...)`.
-- 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]`
-- JSON schema type markers in TypeScript:
-	- `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`.
-- 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`.
+# mdi-llmkit (TypeScript)
+
+Utilities for managing LLM chat conversations and structured JSON responses with OpenAI's Responses API.
+
+## Installation
+
+```bash
+npm install mdi-llmkit openai
+```
+
+## Quick Start
+
+### `gptSubmit`
+
+```ts
+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
+);
+
+console.log(reply);
+```
+
+### `GptConversation`
+
+```ts
+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.'
+);
+console.log(reply);
+```
+
+### `JSONSchemaFormat`
+
+```ts
+import { JSONSchemaFormat, JSON_INTEGER, gptSubmit } from 'mdi-llmkit';
+
+const responseFormat = JSONSchemaFormat(
+  '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 }
+);
+```
+
+## `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';
+
+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 }
+);
+
+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
+
+- Function naming: Python `gpt_submit(...)` maps to TypeScript `gptSubmit(...)`.
+- 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]`
+- JSON schema type markers in TypeScript:
+  - `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`.
+- Release workflow: `.github/workflows/typescript-release.yml`
+  - 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[];
+}>;