@hardlydifficult/ai-msg 1.0.1 → 1.0.2

package/README.md

@@ -1,8 +1,6 @@
 # @hardlydifficult/ai-msg
 
-Opinionated utilities for extracting structured output from AI text responses.
-
-LLM responses often wrap structured data in markdown code blocks, preamble text, or trailing commentary. This package reliably extracts JSON and code blocks from messy AI output.
+Extract structured data from AI model responses: JSON, typed schemas, code blocks, and multimodal content.
 
 ## Installation
 
@@ -10,60 +8,51 @@ LLM responses often wrap structured data in markdown code blocks, preamble text,
 npm install @hardlydifficult/ai-msg
 ```
 
-For typed extraction with Zod validation:
-
-```bash
-npm install @hardlydifficult/ai-msg zod
-```
-
-## Usage
+## API
 
-### `extractJson(text, sentinel?): unknown[]`
+### `extractJson(text: string, sentinel?: string): unknown[]`
 
-Extracts all valid JSON values from text using a three-pass strategy:
+Extract JSON objects/arrays from AI response text. Uses a three-pass strategy:
 
-1. Direct `JSON.parse` of the trimmed text
-2. Search markdown code blocks (json-tagged first, then any)
-3. Find all balanced `{}` or `[]` substrings in prose
+1. Parse the entire text as JSON
+2. Extract from fenced code blocks (json-tagged first, then any)
+3. Find balanced `{}`/`[]` in prose
 
-Always returns an array. Returns `[]` when no JSON is found.
+Pass a `sentinel` string to return `[]` when the response contains it (useful for "no results" markers).
 
 ````typescript
 import { extractJson } from "@hardlydifficult/ai-msg";
 
-extractJson('{"key": "value"}');
-// [{ key: "value" }]
-
 extractJson('Here is the result:\n```json\n{"key": "value"}\n```\nDone.');
 // [{ key: "value" }]
 
-extractJson('The answer is {"key": "value"} as shown.');
-// [{ key: "value" }]
+extractJson('First {"a": 1} then {"b": 2} done.');
+// [{ a: 1 }, { b: 2 }]
 
-extractJson("no json here");
+extractJson("NO_FINDINGS: scan completed.", "NO_FINDINGS");
 // []
 ````
 
-Multiple JSON values are returned when present:
+### `extractTyped<T>(text: string, schema: SchemaLike<T>, sentinel?: string): T[]`
+
+Extract and validate JSON against a schema. Works with Zod 3, Zod 4, or any object with a `safeParse` method. Only returns entries that pass validation.
 
 ```typescript
-extractJson('First {"a": 1} then {"b": 2} done.');
-// [{ a: 1 }, { b: 2 }]
-```
+import { extractTyped } from "@hardlydifficult/ai-msg";
+import { z } from "zod";
 
-The optional `sentinel` parameter short-circuits extraction — if the text contains the sentinel string, an empty array is returned immediately:
+const Person = z.object({ name: z.string(), age: z.number() });
 
-```typescript
-extractJson("NO_FINDINGS: the scan completed with no issues.", "NO_FINDINGS");
-// []
+extractTyped('{"name": "Alice", "age": 30}', Person);
+// [{ name: "Alice", age: 30 }]
 
-extractJson('{"result": "found"}', "NO_FINDINGS");
-// [{ result: "found" }]
+extractTyped('{"name": "Alice", "age": "thirty"}', Person);
+// [] — fails validation
 ```
 
-### `extractCodeBlock(text, lang?): string[]`
+### `extractCodeBlock(text: string, lang?: string): string[]`
 
-Extracts all markdown code blocks from text. Optionally filters by language tag.
+Extract fenced code block contents. Optionally filter by language tag.
 
 ````typescript
 import { extractCodeBlock } from "@hardlydifficult/ai-msg";
@@ -73,27 +62,22 @@ extractCodeBlock("```ts\nconst x = 1;\n```");
 
 extractCodeBlock("```json\n{}\n```\n```ts\nconst x = 1;\n```", "json");
 // ["{}"]
-
-extractCodeBlock("no code blocks");
-// []
 ````
 
-### `extractTyped<T>(text, schema, sentinel?): T[]`
+### `extractTextContent(content: string | { type: string; text?: string }[]): string`
 
-Extracts all JSON values from text and validates each against a Zod schema. Only values that pass validation are included. Requires `zod` as a peer dependency.
+Extract plain text from a message content field. Handles both plain strings and multimodal content arrays (AI SDK format).
 
 ```typescript
-import { extractTyped } from "@hardlydifficult/ai-msg";
-import { z } from "zod";
+import { extractTextContent } from "@hardlydifficult/ai-msg";
 
-const Person = z.object({ name: z.string(), age: z.number() });
-
-extractTyped('{"name": "Alice", "age": 30}', Person);
-// [{ name: "Alice", age: 30 }]
+extractTextContent("hello"); // "hello"
+extractTextContent([
+  { type: "text", text: "hello" },
+  { type: "image_url", url: "..." },
+]); // "hello"
+```
 
-extractTyped('{"name": "Alice", "age": "thirty"}', Person);
-// []
+### `toPlainTextMessages(messages: MultimodalMessage[]): { role, content }[]`
 
-extractTyped("NO_FINDINGS", Person, "NO_FINDINGS");
-// []
-```
+Convert multimodal messages to plain text messages by flattening content arrays.

package/dist/extractTyped.d.ts

@@ -1,3 +1,15 @@
-import { type ZodType } from "zod";
-export declare function extractTyped<T>(text: string, schema: ZodType<T>, sentinel?: string): T[];
+/**
+ * Any schema with a safeParse method (e.g. Zod 3, Zod 4, or custom).
+ * Using a structural type avoids coupling to a specific Zod version.
+ */
+export interface SchemaLike<T> {
+    safeParse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error?: unknown;
+    };
+}
+export declare function extractTyped<T>(text: string, schema: SchemaLike<T>, sentinel?: string): T[];
 //# sourceMappingURL=extractTyped.d.ts.map

package/dist/extractTyped.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractTyped.d.ts","sourceRoot":"","sources":["../src/extractTyped.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,QAAQ,CAAC,EAAE,MAAM,GAChB,CAAC,EAAE,CAUL"}
+{"version":3,"file":"extractTyped.d.ts","sourceRoot":"","sources":["../src/extractTyped.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,SAAS,CACP,IAAI,EAAE,OAAO,GACZ;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACrE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,QAAQ,CAAC,EAAE,MAAM,GAChB,CAAC,EAAE,CAUL"}

package/dist/extractTyped.js.map

@@ -1 +1 @@
-{"version":3,"file":"extractTyped.js","sourceRoot":"","sources":["../src/extractTyped.ts"],"names":[],"mappings":";;AAIA,oCAcC;AAhBD,qDAA+C;AAE/C,SAAgB,YAAY,CAC1B,IAAY,EACZ,MAAkB,EAClB,QAAiB;IAEjB,MAAM,OAAO,GAAG,IAAA,4BAAW,EAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAQ,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"extractTyped.js","sourceRoot":"","sources":["../src/extractTyped.ts"],"names":[],"mappings":";;AAYA,oCAcC;AA1BD,qDAA+C;AAY/C,SAAgB,YAAY,CAC1B,IAAY,EACZ,MAAqB,EACrB,QAAiB;IAEjB,MAAM,OAAO,GAAG,IAAA,4BAAW,EAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAQ,EAAE,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { extractCodeBlock } from "./extractCodeBlock.js";
 export { extractJson } from "./extractJson.js";
-export { extractTyped } from "./extractTyped.js";
+export { extractTyped, type SchemaLike } from "./extractTyped.js";
+export { extractTextContent, toPlainTextMessages, type MultimodalMessage, } from "./multimodal.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractTyped = exports.extractJson = exports.extractCodeBlock = void 0;
+exports.toPlainTextMessages = exports.extractTextContent = exports.extractTyped = exports.extractJson = exports.extractCodeBlock = void 0;
 var extractCodeBlock_js_1 = require("./extractCodeBlock.js");
 Object.defineProperty(exports, "extractCodeBlock", { enumerable: true, get: function () { return extractCodeBlock_js_1.extractCodeBlock; } });
 var extractJson_js_1 = require("./extractJson.js");
 Object.defineProperty(exports, "extractJson", { enumerable: true, get: function () { return extractJson_js_1.extractJson; } });
 var extractTyped_js_1 = require("./extractTyped.js");
 Object.defineProperty(exports, "extractTyped", { enumerable: true, get: function () { return extractTyped_js_1.extractTyped; } });
+var multimodal_js_1 = require("./multimodal.js");
+Object.defineProperty(exports, "extractTextContent", { enumerable: true, get: function () { return multimodal_js_1.extractTextContent; } });
+Object.defineProperty(exports, "toPlainTextMessages", { enumerable: true, get: function () { return multimodal_js_1.toPlainTextMessages; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AACzB,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AACpB,qDAAiD;AAAxC,+GAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,6DAAyD;AAAhD,uHAAA,gBAAgB,OAAA;AACzB,mDAA+C;AAAtC,6GAAA,WAAW,OAAA;AACpB,qDAAkE;AAAzD,+GAAA,YAAY,OAAA;AACrB,iDAIyB;AAHvB,mHAAA,kBAAkB,OAAA;AAClB,oHAAA,mBAAmB,OAAA"}

package/dist/multimodal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Structural type for messages that may contain multimodal content.
+ * Compatible with AI SDK message formats and ChatMessage from @ai/shared.
+ */
+export interface MultimodalMessage {
+    role: "system" | "user" | "assistant";
+    content: string | {
+        type: string;
+        text?: string;
+    }[];
+}
+/**
+ * Extract text content from a message content field.
+ * Handles both plain string and multimodal content arrays.
+ */
+export declare function extractTextContent(content: MultimodalMessage["content"]): string;
+/**
+ * Convert multimodal messages to plain text messages.
+ * Flattens any multimodal content arrays to plain text strings.
+ */
+export declare function toPlainTextMessages(messages: MultimodalMessage[]): {
+    role: "system" | "user" | "assistant";
+    content: string;
+}[];
+//# sourceMappingURL=multimodal.d.ts.map

package/dist/multimodal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multimodal.d.ts","sourceRoot":"","sources":["../src/multimodal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACrD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,GACpC,MAAM,CAWR;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAAE,GAC5B;IAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAK9D"}

package/dist/multimodal.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractTextContent = extractTextContent;
+exports.toPlainTextMessages = toPlainTextMessages;
+/**
+ * Extract text content from a message content field.
+ * Handles both plain string and multimodal content arrays.
+ */
+function extractTextContent(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    return content
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("\n");
+}
+/**
+ * Convert multimodal messages to plain text messages.
+ * Flattens any multimodal content arrays to plain text strings.
+ */
+function toPlainTextMessages(messages) {
+    return messages.map((m) => ({
+        role: m.role,
+        content: extractTextContent(m.content),
+    }));
+}
+//# sourceMappingURL=multimodal.js.map

package/dist/multimodal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multimodal.js","sourceRoot":"","sources":["../src/multimodal.ts"],"names":[],"mappings":";;AAaA,gDAaC;AAMD,kDAOC;AA9BD;;;GAGG;AACH,SAAgB,kBAAkB,CAChC,OAAqC;IAErC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,OAAO;SACX,MAAM,CACL,CAAC,CAAC,EAAuC,EAAE,CACzC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAClD;SACA,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CACjC,QAA6B;IAE7B,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC;KACvC,CAAC,CAAC,CAAC;AACN,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/ai-msg",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -14,14 +14,6 @@
     "lint": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
-  "peerDependencies": {
-    "zod": ">=3.0.0"
-  },
-  "peerDependenciesMeta": {
-    "zod": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "typescript": "5.8.3",
     "vitest": "1.6.1",