@terreno/ai 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,180 @@
1
+ "use strict";
2
+ /**
3
+ * Bulletproof-ish extraction of JSON from LLM output.
4
+ *
5
+ * Handles common "return only JSON" violations:
6
+ * - markdown code fences (full ```json … ``` wrappers or partial ``` lines)
7
+ * - preamble / trailing prose around a JSON value
8
+ * - JSON buried mid-string (first balanced `{`/`[` … `}`/`]` slice)
9
+ * - trailing commas before `}` or `]`
10
+ * - smart quotes outside string literals (conservative repair)
11
+ *
12
+ * Strategy: try the cheapest parse first, escalate only when it fails.
13
+ */
14
+ Object.defineProperty(exports, "__esModule", { value: true });
15
+ exports.normalizeLlmJsonTextForStructuredOutput = exports.parseAiJson = void 0;
16
+ /**
17
+ * Strip leading/trailing markdown code fences when the whole payload is fenced,
18
+ * otherwise strip a common opening ```lang line and trailing ``` block.
19
+ */
20
+ var stripFences = function (input) {
21
+ var trimmed = input.trim();
22
+ var fullyFenced = /^```(?:json|javascript|js|typescript|ts)?\s*\n?([\s\S]*?)\n?```$/i.exec(trimmed);
23
+ if (fullyFenced) {
24
+ return fullyFenced[1].trim();
25
+ }
26
+ var t = trimmed;
27
+ t = t.replace(/^```[a-zA-Z0-9_-]*\s*:?\s*\n?/, "");
28
+ t = t.replace(/\n?```\s*$/m, "").trim();
29
+ return t;
30
+ };
31
+ /**
32
+ * Returns the first balanced JSON object or array substring, respecting string literals
33
+ * and escapes. Uses a bracket stack so nested `{}` / `[]` mix correctly.
34
+ */
35
+ var extractBalancedJson = function (input) {
36
+ var start = input.search(/[{[]/);
37
+ if (start === -1) {
38
+ return null;
39
+ }
40
+ var stack = [];
41
+ var inString = false;
42
+ var escaped = false;
43
+ for (var i = start; i < input.length; i++) {
44
+ var char = input[i];
45
+ if (escaped) {
46
+ escaped = false;
47
+ continue;
48
+ }
49
+ if (char === "\\") {
50
+ escaped = true;
51
+ continue;
52
+ }
53
+ if (char === '"') {
54
+ inString = !inString;
55
+ continue;
56
+ }
57
+ if (inString) {
58
+ continue;
59
+ }
60
+ if (char === "{") {
61
+ stack.push("}");
62
+ continue;
63
+ }
64
+ if (char === "[") {
65
+ stack.push("]");
66
+ continue;
67
+ }
68
+ if (char === "}" || char === "]") {
69
+ var expected = stack.pop();
70
+ if (expected !== char) {
71
+ return null;
72
+ }
73
+ if (stack.length === 0) {
74
+ return input.slice(start, i + 1);
75
+ }
76
+ }
77
+ }
78
+ return null;
79
+ };
80
+ /**
81
+ * Light-touch repairs for common malformations. Only changes characters outside
82
+ * string literals so legitimate string content is preserved.
83
+ */
84
+ var repairJsonishOutsideStrings = function (input) {
85
+ var result = "";
86
+ var inString = false;
87
+ var escaped = false;
88
+ for (var i = 0; i < input.length; i++) {
89
+ var char = input[i];
90
+ if (escaped) {
91
+ result += char;
92
+ escaped = false;
93
+ continue;
94
+ }
95
+ if (char === "\\") {
96
+ result += char;
97
+ escaped = true;
98
+ continue;
99
+ }
100
+ if (char === '"') {
101
+ inString = !inString;
102
+ result += char;
103
+ continue;
104
+ }
105
+ if (!inString) {
106
+ if (char === "\u201C" || char === "\u201D") {
107
+ result += '"';
108
+ continue;
109
+ }
110
+ if (char === ",") {
111
+ var rest = input.slice(i + 1);
112
+ var next = rest.match(/^\s*([}\]])/);
113
+ if (next) {
114
+ continue;
115
+ }
116
+ }
117
+ }
118
+ result += char;
119
+ }
120
+ return result;
121
+ };
122
+ var tryParse = function (candidate) {
123
+ try {
124
+ return JSON.parse(candidate);
125
+ }
126
+ catch (_a) {
127
+ return undefined;
128
+ }
129
+ };
130
+ /**
131
+ * Extract and parse JSON from arbitrary LLM output.
132
+ */
133
+ var parseAiJson = function (input) {
134
+ if (typeof input !== "string" || input.trim().length === 0) {
135
+ return { error: "Empty or non-string input", raw: input, success: false };
136
+ }
137
+ var cleaned = stripFences(input);
138
+ var direct = tryParse(cleaned);
139
+ if (direct !== undefined) {
140
+ return { data: direct, repaired: false, success: true };
141
+ }
142
+ var balanced = extractBalancedJson(cleaned);
143
+ if (balanced !== null) {
144
+ var extracted = tryParse(balanced);
145
+ if (extracted !== undefined) {
146
+ return { data: extracted, repaired: true, success: true };
147
+ }
148
+ var repairedSlice = tryParse(repairJsonishOutsideStrings(balanced));
149
+ if (repairedSlice !== undefined) {
150
+ return { data: repairedSlice, repaired: true, success: true };
151
+ }
152
+ }
153
+ var repairedWhole = tryParse(repairJsonishOutsideStrings(cleaned));
154
+ if (repairedWhole !== undefined) {
155
+ return { data: repairedWhole, repaired: true, success: true };
156
+ }
157
+ var aggressiveQuotes = tryParse(cleaned.replace(/[\u201C\u201D]/g, '"'));
158
+ if (aggressiveQuotes !== undefined) {
159
+ return { data: aggressiveQuotes, repaired: true, success: true };
160
+ }
161
+ return {
162
+ error: "No valid JSON could be extracted",
163
+ raw: input,
164
+ success: false,
165
+ };
166
+ };
167
+ exports.parseAiJson = parseAiJson;
168
+ /**
169
+ * Normalizes raw LLM text into a single JSON text payload for Vercel `Output.*` parsers.
170
+ * On success returns `JSON.stringify` of the parsed value; on failure returns `cleaned`
171
+ * (fence-stripped) text so the SDK can still attempt its own error path.
172
+ */
173
+ var normalizeLlmJsonTextForStructuredOutput = function (raw) {
174
+ var parsed = (0, exports.parseAiJson)(raw);
175
+ if (parsed.success) {
176
+ return JSON.stringify(parsed.data);
177
+ }
178
+ return stripFences(raw);
179
+ };
180
+ exports.normalizeLlmJsonTextForStructuredOutput = normalizeLlmJsonTextForStructuredOutput;
@@ -3,3 +3,5 @@ export declare const REMIX_PROMPT: string;
3
3
  export declare const CONTENT_SUMMARY_PROMPT: string;
4
4
  export declare const TRANSLATION_PROMPT: string;
5
5
  export declare const TITLE_GENERATION_PROMPT: string;
6
+ /** When callers omit systemPrompt for JSON helpers, steer the model away from prose and markdown fences. */
7
+ export declare const JSON_VALUE_SYSTEM_PROMPT: string;
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.TITLE_GENERATION_PROMPT = exports.TRANSLATION_PROMPT = exports.CONTENT_SUMMARY_PROMPT = exports.REMIX_PROMPT = exports.DEFAULT_GPT_MEMORY = void 0;
3
+ exports.JSON_VALUE_SYSTEM_PROMPT = exports.TITLE_GENERATION_PROMPT = exports.TRANSLATION_PROMPT = exports.CONTENT_SUMMARY_PROMPT = exports.REMIX_PROMPT = exports.DEFAULT_GPT_MEMORY = void 0;
4
4
  exports.DEFAULT_GPT_MEMORY = "You are a helpful, friendly AI assistant. Provide clear, accurate, and concise responses. " +
5
5
  "When you don't know something, say so honestly rather than guessing.";
6
6
  exports.REMIX_PROMPT = "Reword the following text to sound more natural and polished while preserving the original " +
@@ -14,3 +14,6 @@ exports.TRANSLATION_PROMPT = "Translate the following text from {sourceLanguage}
14
14
  "Return only the translated text with no additional commentary.";
15
15
  exports.TITLE_GENERATION_PROMPT = "Generate a short title (3-6 words) that summarizes this conversation for a sidebar label. " +
16
16
  "Return only the title text with no quotes, punctuation, or additional commentary.";
17
+ /** When callers omit systemPrompt for JSON helpers, steer the model away from prose and markdown fences. */
18
+ exports.JSON_VALUE_SYSTEM_PROMPT = "You respond with a single JSON value (object, array, string, number, boolean, or null) only. " +
19
+ "No markdown code fences, no commentary before or after the JSON.";
@@ -1,7 +1,7 @@
1
1
  import type { FindExactlyOnePlugin, FindOneOrNonePlugin } from "@terreno/api";
2
2
  import type { LanguageModel } from "ai";
3
3
  import type mongoose from "mongoose";
4
- export declare const DEFAULT_AI_REQUEST_TYPES: readonly ["general", "remix", "summarization", "translation"];
4
+ export declare const DEFAULT_AI_REQUEST_TYPES: readonly ["general", "json_array", "json_object", "json_value", "remix", "summarization", "translation"];
5
5
  export type DefaultAIRequestType = (typeof DEFAULT_AI_REQUEST_TYPES)[number];
6
6
  export type AIRequestType = DefaultAIRequestType | (string & {});
7
7
  export interface AIRequestDocument extends mongoose.Document<mongoose.Types.ObjectId> {
@@ -154,6 +154,41 @@ export interface TranslateOptions {
154
154
  text: string;
155
155
  userId?: mongoose.Types.ObjectId;
156
156
  }
157
+ export interface GenerateJsonValueOptions {
158
+ maxOutputTokens?: number;
159
+ /** Optional name passed to the provider for structured-output guidance. */
160
+ outputName?: string;
161
+ /** Optional description passed to the provider for structured-output guidance. */
162
+ outputDescription?: string;
163
+ prompt: string;
164
+ systemPrompt?: string;
165
+ temperature?: number;
166
+ userId?: mongoose.Types.ObjectId;
167
+ }
168
+ export interface GenerateJsonObjectOptions<OBJECT> {
169
+ maxOutputTokens?: number;
170
+ prompt: string;
171
+ /** Zod schema, `jsonSchema(...)`, or other `FlexibleSchema` accepted by the AI SDK. */
172
+ schema: import("ai").FlexibleSchema<OBJECT>;
173
+ schemaDescription?: string;
174
+ schemaName?: string;
175
+ systemPrompt?: string;
176
+ temperature?: number;
177
+ userId?: mongoose.Types.ObjectId;
178
+ }
179
+ export interface GenerateJsonArrayOptions<ELEMENT> {
180
+ /** Schema for each array element. */
181
+ element: import("ai").FlexibleSchema<ELEMENT>;
182
+ /** Optional description for the array output (provider guidance). */
183
+ outputDescription?: string;
184
+ /** Optional name for the array output (provider guidance). */
185
+ outputName?: string;
186
+ maxOutputTokens?: number;
187
+ prompt: string;
188
+ systemPrompt?: string;
189
+ temperature?: number;
190
+ userId?: mongoose.Types.ObjectId;
191
+ }
157
192
  export interface GptRouteOptions {
158
193
  /** Pre-configured AIService. Optional when using per-request keys or demo mode. */
159
194
  aiService?: import("../service/aiService").AIService;
@@ -6,6 +6,9 @@ exports.DEFAULT_AI_REQUEST_TYPES = void 0;
6
6
  // ============================================================
7
7
  exports.DEFAULT_AI_REQUEST_TYPES = [
8
8
  "general",
9
+ "json_array",
10
+ "json_object",
11
+ "json_value",
9
12
  "remix",
10
13
  "summarization",
11
14
  "translation",
package/package.json CHANGED
@@ -24,7 +24,7 @@
24
24
  "@types/multer": "^1.4.12",
25
25
  "@types/passport-local-mongoose": "^6.1.5",
26
26
  "@types/supertest": "^6.0.2",
27
- "@terreno/api": "0.18.0",
27
+ "@terreno/api": "0.20.0",
28
28
  "mongoose": "8.23.0",
29
29
  "passport-local-mongoose": "^9.0.1",
30
30
  "supertest": "^7.0.0",
@@ -65,7 +65,7 @@
65
65
  "access": "public"
66
66
  },
67
67
  "peerDependencies": {
68
- "@terreno/api": "0.18.0",
68
+ "@terreno/api": "0.20.0",
69
69
  "mongoose": "^8.0.0"
70
70
  },
71
71
  "repository": {
@@ -84,5 +84,5 @@
84
84
  "test:coverage": "bun run ../scripts/check-coverage.ts"
85
85
  },
86
86
  "types": "dist/index.d.ts",
87
- "version": "0.18.0"
87
+ "version": "0.20.0"
88
88
  }
@@ -1,5 +1,5 @@
1
1
  import {afterEach, beforeEach, describe, expect, it, mock} from "bun:test";
2
- import type {LanguageModel} from "ai";
2
+ import {jsonSchema, type LanguageModel} from "ai";
3
3
  import mongoose from "mongoose";
4
4
 
5
5
  import {AIRequest} from "../models/aiRequest";
@@ -99,6 +99,147 @@ describe("AIService", () => {
99
99
  });
100
100
  });
101
101
 
102
+ describe("generateJsonValue", () => {
103
+ it("parses JSON, returns the value, and logs json_value", async () => {
104
+ const model = createMockModel('{"ok":true,"n":3}');
105
+ const service = new AIService({model: model as unknown as LanguageModel});
106
+ const userId = new mongoose.Types.ObjectId();
107
+
108
+ const result = await service.generateJsonValue({
109
+ prompt: "Return a small object",
110
+ userId,
111
+ });
112
+
113
+ expect(result).toEqual({n: 3, ok: true});
114
+
115
+ const logs = await AIRequest.find({userId});
116
+ expect(logs.length).toBe(1);
117
+ expect(logs[0].requestType).toBe("json_value");
118
+ expect(JSON.parse(logs[0].response ?? "{}")).toEqual({n: 3, ok: true});
119
+ });
120
+
121
+ it("parses JSON wrapped in markdown fences (including ```json:)", async () => {
122
+ const model = createMockModel('```json:\n{"colon":true}\n```');
123
+ const service = new AIService({model: model as unknown as LanguageModel});
124
+
125
+ const result = await service.generateJsonValue({
126
+ prompt: "Return JSON",
127
+ });
128
+
129
+ expect(result).toEqual({colon: true});
130
+ });
131
+
132
+ it("parses JSON wrapped in a generic ```lang fence", async () => {
133
+ const model = createMockModel("```typescript\n[1,2]\n```");
134
+ const service = new AIService({model: model as unknown as LanguageModel});
135
+
136
+ const result = await service.generateJsonValue({
137
+ prompt: "Return JSON",
138
+ });
139
+
140
+ expect(result).toEqual([1, 2]);
141
+ });
142
+
143
+ it("logs errors when JSON output cannot be produced", async () => {
144
+ const model = createMockModel("not-json");
145
+ const service = new AIService({model: model as unknown as LanguageModel});
146
+
147
+ await expect(service.generateJsonValue({prompt: "bad"})).rejects.toThrow();
148
+
149
+ const logs = await AIRequest.find({prompt: "bad"});
150
+ expect(logs.length).toBe(1);
151
+ expect(logs[0].error).toBeTruthy();
152
+ expect(logs[0].requestType).toBe("json_value");
153
+ expect(logs[0].response).toBe("not-json");
154
+ expect(logs[0].metadata?.rawModelTextCaptured).toBe(true);
155
+ });
156
+ });
157
+
158
+ describe("generateJsonObject", () => {
159
+ it("parses against a schema and logs json_object", async () => {
160
+ const model = createMockModel('{"id":"item-1","count":2}');
161
+ const service = new AIService({model: model as unknown as LanguageModel});
162
+ const userId = new mongoose.Types.ObjectId();
163
+
164
+ const schema = jsonSchema<{count: number; id: string}>({
165
+ additionalProperties: false,
166
+ properties: {
167
+ count: {type: "number"},
168
+ id: {type: "string"},
169
+ },
170
+ required: ["id", "count"],
171
+ type: "object",
172
+ });
173
+
174
+ const result = await service.generateJsonObject({
175
+ prompt: "Extract fields",
176
+ schema,
177
+ userId,
178
+ });
179
+
180
+ expect(result).toEqual({count: 2, id: "item-1"});
181
+
182
+ const logs = await AIRequest.find({userId});
183
+ expect(logs[0].requestType).toBe("json_object");
184
+ });
185
+
186
+ it("parses object output wrapped in markdown fences", async () => {
187
+ const model = createMockModel('```json\n{"id":"fenced","count":9}\n```');
188
+ const service = new AIService({model: model as unknown as LanguageModel});
189
+
190
+ const schema = jsonSchema<{count: number; id: string}>({
191
+ additionalProperties: false,
192
+ properties: {
193
+ count: {type: "number"},
194
+ id: {type: "string"},
195
+ },
196
+ required: ["id", "count"],
197
+ type: "object",
198
+ });
199
+
200
+ const result = await service.generateJsonObject({
201
+ prompt: "Extract fields",
202
+ schema,
203
+ });
204
+
205
+ expect(result).toEqual({count: 9, id: "fenced"});
206
+ });
207
+ });
208
+
209
+ describe("generateJsonArray", () => {
210
+ it("parses an array against an element schema and logs json_array", async () => {
211
+ const model = createMockModel('{"elements":[10,20,30]}');
212
+ const service = new AIService({model: model as unknown as LanguageModel});
213
+ const userId = new mongoose.Types.ObjectId();
214
+
215
+ const element = jsonSchema<number>({type: "number"});
216
+
217
+ const result = await service.generateJsonArray({
218
+ element,
219
+ prompt: "List numbers",
220
+ userId,
221
+ });
222
+
223
+ expect(result).toEqual([10, 20, 30]);
224
+
225
+ const logs = await AIRequest.find({userId});
226
+ expect(logs[0].requestType).toBe("json_array");
227
+ });
228
+
229
+ it("parses array payload when model wraps elements in markdown fences", async () => {
230
+ const model = createMockModel('```json\n{"elements":[1,2]}\n```');
231
+ const service = new AIService({model: model as unknown as LanguageModel});
232
+ const element = jsonSchema<number>({type: "number"});
233
+
234
+ const result = await service.generateJsonArray({
235
+ element,
236
+ prompt: "List numbers",
237
+ });
238
+
239
+ expect(result).toEqual([1, 2]);
240
+ });
241
+ });
242
+
102
243
  describe("generateTextStream", () => {
103
244
  it("should stream text chunks", async () => {
104
245
  const model = createMockModel();