universal-llm-client 4.0.0 → 4.2.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.
- package/dist/ai-model.d.ts +20 -22
- package/dist/ai-model.d.ts.map +1 -1
- package/dist/ai-model.js +26 -23
- package/dist/ai-model.js.map +1 -1
- package/dist/client.d.ts +5 -5
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +17 -9
- package/dist/client.js.map +1 -1
- package/dist/http.d.ts +2 -0
- package/dist/http.d.ts.map +1 -1
- package/dist/http.js +1 -0
- package/dist/http.js.map +1 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -4
- package/dist/index.js.map +1 -1
- package/dist/interfaces.d.ts +49 -11
- package/dist/interfaces.d.ts.map +1 -1
- package/dist/interfaces.js +14 -0
- package/dist/interfaces.js.map +1 -1
- package/dist/providers/anthropic.d.ts +56 -0
- package/dist/providers/anthropic.d.ts.map +1 -0
- package/dist/providers/anthropic.js +524 -0
- package/dist/providers/anthropic.js.map +1 -0
- package/dist/providers/google.d.ts +5 -0
- package/dist/providers/google.d.ts.map +1 -1
- package/dist/providers/google.js +64 -8
- package/dist/providers/google.js.map +1 -1
- package/dist/providers/index.d.ts +1 -0
- package/dist/providers/index.d.ts.map +1 -1
- package/dist/providers/index.js +1 -0
- package/dist/providers/index.js.map +1 -1
- package/dist/providers/ollama.d.ts.map +1 -1
- package/dist/providers/ollama.js +38 -11
- package/dist/providers/ollama.js.map +1 -1
- package/dist/providers/openai.d.ts.map +1 -1
- package/dist/providers/openai.js +9 -7
- package/dist/providers/openai.js.map +1 -1
- package/dist/router.d.ts +13 -33
- package/dist/router.d.ts.map +1 -1
- package/dist/router.js +33 -57
- package/dist/router.js.map +1 -1
- package/dist/stream-decoder.d.ts +29 -2
- package/dist/stream-decoder.d.ts.map +1 -1
- package/dist/stream-decoder.js +39 -11
- package/dist/stream-decoder.js.map +1 -1
- package/dist/structured-output.d.ts +107 -181
- package/dist/structured-output.d.ts.map +1 -1
- package/dist/structured-output.js +137 -192
- package/dist/structured-output.js.map +1 -1
- package/dist/zod-adapter.d.ts +44 -0
- package/dist/zod-adapter.d.ts.map +1 -0
- package/dist/zod-adapter.js +61 -0
- package/dist/zod-adapter.js.map +1 -0
- package/package.json +9 -1
- package/src/ai-model.ts +350 -0
- package/src/auditor.ts +213 -0
- package/src/client.ts +402 -0
- package/src/debug/debug-google-streaming.ts +97 -0
- package/src/debug/debug-tool-execution.ts +86 -0
- package/src/debug/test-lmstudio-tools.ts +155 -0
- package/src/demos/README.md +47 -0
- package/src/demos/basic/universal-llm-examples.ts +161 -0
- package/src/demos/mcp/astrid-memory-demo.ts +295 -0
- package/src/demos/mcp/astrid-persona-memory.ts +357 -0
- package/src/demos/mcp/mcp-mongodb-demo.ts +275 -0
- package/src/demos/mcp/simple-astrid-memory.ts +148 -0
- package/src/demos/mcp/simple-mcp-demo.ts +68 -0
- package/src/demos/mcp/working-mcp-demo.ts +62 -0
- package/src/demos/model-alias-demo.ts +0 -0
- package/src/demos/tools/RAG_MEMORY_INTEGRATION.md +267 -0
- package/src/demos/tools/astrid-memory-demo.ts +270 -0
- package/src/demos/tools/astrid-production-memory-clean.ts +785 -0
- package/src/demos/tools/astrid-production-memory.ts +558 -0
- package/src/demos/tools/basic-translation-test.ts +66 -0
- package/src/demos/tools/chromadb-similarity-tuning.ts +390 -0
- package/src/demos/tools/clean-multilingual-conversation.ts +209 -0
- package/src/demos/tools/clean-translation-test.ts +119 -0
- package/src/demos/tools/clean-universal-multilingual-test.ts +131 -0
- package/src/demos/tools/complete-rag-demo.ts +369 -0
- package/src/demos/tools/complete-tool-demo.ts +132 -0
- package/src/demos/tools/demo-tool-calling.ts +124 -0
- package/src/demos/tools/dynamic-language-switching-test.ts +251 -0
- package/src/demos/tools/hybrid-thinking-test.ts +154 -0
- package/src/demos/tools/memory-integration-test.ts +420 -0
- package/src/demos/tools/multilingual-memory-system.ts +802 -0
- package/src/demos/tools/ondemand-translation-demo.ts +655 -0
- package/src/demos/tools/production-tool-demo.ts +245 -0
- package/src/demos/tools/revolutionary-multilingual-test.ts +151 -0
- package/src/demos/tools/rigorous-language-analysis.ts +218 -0
- package/src/demos/tools/test-universal-memory-system.ts +126 -0
- package/src/demos/tools/translation-integration-guide.ts +346 -0
- package/src/demos/tools/universal-memory-system.ts +560 -0
- package/src/http.ts +247 -0
- package/src/index.ts +161 -0
- package/src/interfaces.ts +657 -0
- package/src/mcp.ts +345 -0
- package/src/providers/anthropic.ts +762 -0
- package/src/providers/google.ts +620 -0
- package/src/providers/index.ts +8 -0
- package/src/providers/ollama.ts +469 -0
- package/src/providers/openai.ts +392 -0
- package/src/router.ts +780 -0
- package/src/stream-decoder.ts +361 -0
- package/src/structured-output.ts +759 -0
- package/src/test-scripts/test-advanced-tools.ts +310 -0
- package/src/test-scripts/test-google-streaming-enhanced.ts +147 -0
- package/src/test-scripts/test-google-streaming.ts +63 -0
- package/src/test-scripts/test-google-system-prompt-comprehensive.ts +189 -0
- package/src/test-scripts/test-mcp-config.ts +28 -0
- package/src/test-scripts/test-mcp-connection.ts +29 -0
- package/src/test-scripts/test-system-message-positions.ts +163 -0
- package/src/test-scripts/test-system-prompt-improvement-demo.ts +83 -0
- package/src/test-scripts/test-tool-calling.ts +231 -0
- package/src/tests/ai-model.test.ts +1614 -0
- package/src/tests/auditor.test.ts +224 -0
- package/src/tests/http.test.ts +200 -0
- package/src/tests/interfaces.test.ts +117 -0
- package/src/tests/providers/google.test.ts +660 -0
- package/src/tests/providers/ollama.test.ts +954 -0
- package/src/tests/providers/openai.test.ts +1122 -0
- package/src/tests/router.test.ts +254 -0
- package/src/tests/stream-decoder.test.ts +179 -0
- package/src/tests/structured-output.test.ts +1450 -0
- package/src/tests/tools.test.ts +175 -0
- package/src/tools.ts +246 -0
- package/src/zod-adapter.ts +72 -0
|
@@ -2,11 +2,12 @@
|
|
|
2
2
|
* Structured Output Core Types
|
|
3
3
|
*
|
|
4
4
|
* Core types for structured output support in universal-llm-client.
|
|
5
|
-
*
|
|
5
|
+
* Zero-dependency — works with raw JSON Schema and optional validate functions.
|
|
6
|
+
*
|
|
7
|
+
* For Zod integration, use the `universal-llm-client/zod` entrypoint.
|
|
6
8
|
*
|
|
7
9
|
* @module structured-output
|
|
8
10
|
*/
|
|
9
|
-
import { z } from 'zod';
|
|
10
11
|
/**
|
|
11
12
|
* JSON Schema definition for structured output.
|
|
12
13
|
* This is a subset of JSON Schema focused on what providers need.
|
|
@@ -14,9 +15,11 @@ import { z } from 'zod';
|
|
|
14
15
|
export interface JSONSchema {
|
|
15
16
|
type?: string | string[];
|
|
16
17
|
properties?: Record<string, JSONSchema>;
|
|
17
|
-
items?: JSONSchema | {
|
|
18
|
+
items?: JSONSchema | JSONSchema[] | {
|
|
18
19
|
type: string;
|
|
19
|
-
}
|
|
20
|
+
} | {
|
|
21
|
+
type: string;
|
|
22
|
+
}[];
|
|
20
23
|
required?: string[];
|
|
21
24
|
additionalProperties?: boolean | JSONSchema;
|
|
22
25
|
enum?: (string | number | boolean | null)[];
|
|
@@ -48,6 +51,49 @@ export interface JSONSchema {
|
|
|
48
51
|
definitions?: Record<string, JSONSchema>;
|
|
49
52
|
$defs?: Record<string, JSONSchema>;
|
|
50
53
|
}
|
|
54
|
+
/**
|
|
55
|
+
* Universal schema configuration for structured output.
|
|
56
|
+
*
|
|
57
|
+
* This is the Bring-Your-Own-Validator interface. The core library never
|
|
58
|
+
* imports Zod — instead it accepts a JSON Schema + optional validate function.
|
|
59
|
+
*
|
|
60
|
+
* Use `universal-llm-client/zod` → `fromZod()` to create this from Zod schemas.
|
|
61
|
+
*
|
|
62
|
+
* @template T The expected output type
|
|
63
|
+
*
|
|
64
|
+
* @example
|
|
65
|
+
* ```typescript
|
|
66
|
+
* // Zero-dep usage (no Zod):
|
|
67
|
+
* const config: SchemaConfig<{ name: string; age: number }> = {
|
|
68
|
+
* jsonSchema: {
|
|
69
|
+
* type: 'object',
|
|
70
|
+
* properties: {
|
|
71
|
+
* name: { type: 'string' },
|
|
72
|
+
* age: { type: 'number' },
|
|
73
|
+
* },
|
|
74
|
+
* required: ['name', 'age'],
|
|
75
|
+
* },
|
|
76
|
+
* validate: (data) => data as { name: string; age: number },
|
|
77
|
+
* };
|
|
78
|
+
*
|
|
79
|
+
* // With Zod (via adapter):
|
|
80
|
+
* import { fromZod } from 'universal-llm-client/zod';
|
|
81
|
+
* const config = fromZod(z.object({ name: z.string(), age: z.number() }));
|
|
82
|
+
* ```
|
|
83
|
+
*/
|
|
84
|
+
export interface SchemaConfig<T = unknown> {
|
|
85
|
+
/** JSON Schema sent to the LLM provider */
|
|
86
|
+
readonly jsonSchema: JSONSchema;
|
|
87
|
+
/**
|
|
88
|
+
* Optional validator: parse unknown → T or throw.
|
|
89
|
+
* If omitted, JSON.parse() result is returned as-is (unsafe cast).
|
|
90
|
+
*/
|
|
91
|
+
readonly validate?: (data: unknown) => T;
|
|
92
|
+
/** Schema name (for provider guidance, e.g. OpenAI strict mode) */
|
|
93
|
+
readonly name?: string;
|
|
94
|
+
/** Schema description (for provider guidance) */
|
|
95
|
+
readonly description?: string;
|
|
96
|
+
}
|
|
51
97
|
/**
|
|
52
98
|
* Provider identifier for schema conversion.
|
|
53
99
|
*/
|
|
@@ -69,7 +115,7 @@ export interface ProviderSchema {
|
|
|
69
115
|
export interface StructuredOutputErrorOptions {
|
|
70
116
|
/** The raw output from the LLM that failed validation */
|
|
71
117
|
rawOutput: string;
|
|
72
|
-
/** The underlying cause (e.g.,
|
|
118
|
+
/** The underlying cause (e.g., validation error) */
|
|
73
119
|
cause?: Error;
|
|
74
120
|
}
|
|
75
121
|
/**
|
|
@@ -77,22 +123,20 @@ export interface StructuredOutputErrorOptions {
|
|
|
77
123
|
*
|
|
78
124
|
* Thrown when:
|
|
79
125
|
* - JSON parsing of LLM response fails
|
|
80
|
-
* -
|
|
126
|
+
* - Schema validation fails
|
|
81
127
|
*
|
|
82
128
|
* Features:
|
|
83
129
|
* - `rawOutput` property containing the original LLM response
|
|
84
|
-
* - `cause` property for the underlying error
|
|
130
|
+
* - `cause` property for the underlying error
|
|
85
131
|
*
|
|
86
132
|
* @example
|
|
87
133
|
* ```typescript
|
|
88
134
|
* try {
|
|
89
|
-
* const result = await model.generateStructured(
|
|
135
|
+
* const result = await model.generateStructured(schema, messages);
|
|
90
136
|
* } catch (error) {
|
|
91
137
|
* if (error instanceof StructuredOutputError) {
|
|
92
138
|
* console.log('Raw LLM output:', error.rawOutput);
|
|
93
|
-
*
|
|
94
|
-
* console.log('Validation issues:', error.cause.issues);
|
|
95
|
-
* }
|
|
139
|
+
* console.log('Cause:', error.cause);
|
|
96
140
|
* }
|
|
97
141
|
* }
|
|
98
142
|
* ```
|
|
@@ -100,7 +144,7 @@ export interface StructuredOutputErrorOptions {
|
|
|
100
144
|
export declare class StructuredOutputError extends Error {
|
|
101
145
|
/** The raw output from the LLM that failed validation */
|
|
102
146
|
readonly rawOutput: string;
|
|
103
|
-
/** The underlying cause (e.g.,
|
|
147
|
+
/** The underlying cause (e.g., validation error) */
|
|
104
148
|
readonly cause?: Error;
|
|
105
149
|
constructor(message: string, options: StructuredOutputErrorOptions);
|
|
106
150
|
}
|
|
@@ -108,26 +152,16 @@ export declare class StructuredOutputError extends Error {
|
|
|
108
152
|
* Options for structured output generation.
|
|
109
153
|
*
|
|
110
154
|
* Accepts either:
|
|
111
|
-
* - A
|
|
112
|
-
* - A raw JSON Schema object
|
|
113
|
-
*
|
|
114
|
-
* Optional `name` and `description` can be provided for LLM guidance
|
|
115
|
-
* (used by providers like OpenAI that support schema names).
|
|
155
|
+
* - A SchemaConfig (recommended)
|
|
156
|
+
* - A raw JSON Schema object for flexibility
|
|
116
157
|
*
|
|
117
|
-
* @template T The expected output type
|
|
158
|
+
* @template T The expected output type
|
|
118
159
|
*
|
|
119
160
|
* @example
|
|
120
161
|
* ```typescript
|
|
121
|
-
* // Using
|
|
122
|
-
* const UserSchema = z.object({
|
|
123
|
-
* name: z.string(),
|
|
124
|
-
* age: z.number(),
|
|
125
|
-
* });
|
|
126
|
-
*
|
|
162
|
+
* // Using SchemaConfig
|
|
127
163
|
* const options: StructuredOutputOptions<User> = {
|
|
128
|
-
*
|
|
129
|
-
* name: 'User',
|
|
130
|
-
* description: 'A user object',
|
|
164
|
+
* schemaConfig: mySchemaConfig,
|
|
131
165
|
* };
|
|
132
166
|
* ```
|
|
133
167
|
*
|
|
@@ -148,13 +182,13 @@ export declare class StructuredOutputError extends Error {
|
|
|
148
182
|
*/
|
|
149
183
|
export interface StructuredOutputOptions<T> {
|
|
150
184
|
/**
|
|
151
|
-
*
|
|
152
|
-
*
|
|
185
|
+
* Schema configuration for structured output.
|
|
186
|
+
* Contains JSON Schema + optional validator.
|
|
153
187
|
*/
|
|
154
|
-
|
|
188
|
+
schemaConfig?: SchemaConfig<T>;
|
|
155
189
|
/**
|
|
156
190
|
* Raw JSON Schema for structured output.
|
|
157
|
-
* Use this when you have a pre-defined schema without
|
|
191
|
+
* Use this when you have a pre-defined schema without validation.
|
|
158
192
|
*/
|
|
159
193
|
jsonSchema?: JSONSchema;
|
|
160
194
|
/**
|
|
@@ -200,78 +234,16 @@ export interface StructuredOutputFailure<_T> {
|
|
|
200
234
|
* - `ok: false` → `{ error: StructuredOutputError, rawOutput: string }`
|
|
201
235
|
*
|
|
202
236
|
* @template T The output type
|
|
203
|
-
*
|
|
204
|
-
* @example
|
|
205
|
-
* ```typescript
|
|
206
|
-
* const result = await model.tryParseStructured(UserSchema, messages);
|
|
207
|
-
*
|
|
208
|
-
* if (result.ok) {
|
|
209
|
-
* // TypeScript knows result.value is User
|
|
210
|
-
* console.log('User:', result.value.name);
|
|
211
|
-
* } else {
|
|
212
|
-
* // TypeScript knows result.error is StructuredOutputError
|
|
213
|
-
* console.log('Error:', result.error.message);
|
|
214
|
-
* console.log('Raw output:', result.rawOutput);
|
|
215
|
-
* }
|
|
216
|
-
* ```
|
|
217
237
|
*/
|
|
218
238
|
export type StructuredOutputResult<T> = StructuredOutputSuccess<T> | StructuredOutputFailure<T>;
|
|
219
239
|
/**
|
|
220
240
|
* Type guard to check if a structured output result is successful.
|
|
221
|
-
*
|
|
222
|
-
* @param result The result to check
|
|
223
|
-
* @returns true if the result is successful
|
|
224
|
-
*
|
|
225
|
-
* @example
|
|
226
|
-
* ```typescript
|
|
227
|
-
* const result = await model.tryParseStructured(UserSchema, messages);
|
|
228
|
-
*
|
|
229
|
-
* if (isStructuredOutputSuccess(result)) {
|
|
230
|
-
* console.log('User:', result.value.name);
|
|
231
|
-
* } else {
|
|
232
|
-
* console.log('Error:', result.error.message);
|
|
233
|
-
* }
|
|
234
|
-
* ```
|
|
235
241
|
*/
|
|
236
242
|
export declare function isStructuredOutputSuccess<T>(result: StructuredOutputResult<T>): result is StructuredOutputSuccess<T>;
|
|
237
243
|
/**
|
|
238
244
|
* Type guard to check if a structured output result is a failure.
|
|
239
|
-
*
|
|
240
|
-
* @param result The result to check
|
|
241
|
-
* @returns true if the result is a failure
|
|
242
|
-
*
|
|
243
|
-
* @example
|
|
244
|
-
* ```typescript
|
|
245
|
-
* const result = await model.tryParseStructured(UserSchema, messages);
|
|
246
|
-
*
|
|
247
|
-
* if (isStructuredOutputFailure(result)) {
|
|
248
|
-
* console.log('Error:', result.error.message);
|
|
249
|
-
* console.log('Raw:', result.rawOutput);
|
|
250
|
-
* }
|
|
251
|
-
* ```
|
|
252
245
|
*/
|
|
253
246
|
export declare function isStructuredOutputFailure<T>(result: StructuredOutputResult<T>): result is StructuredOutputFailure<T>;
|
|
254
|
-
/**
|
|
255
|
-
* Convert a Zod schema to JSON Schema.
|
|
256
|
-
*
|
|
257
|
-
* Uses Zod 4's native `z.toJSONSchema()` for conversion.
|
|
258
|
-
* Handles all Zod types including objects, arrays, primitives, enums, and nested structures.
|
|
259
|
-
*
|
|
260
|
-
* @param schema The Zod schema to convert
|
|
261
|
-
* @returns JSON Schema representation
|
|
262
|
-
*
|
|
263
|
-
* @example
|
|
264
|
-
* ```typescript
|
|
265
|
-
* const UserSchema = z.object({
|
|
266
|
-
* name: z.string(),
|
|
267
|
-
* age: z.number(),
|
|
268
|
-
* });
|
|
269
|
-
*
|
|
270
|
-
* const jsonSchema = zodToJsonSchema(UserSchema);
|
|
271
|
-
* // { type: 'object', properties: { name: { type: 'string' }, ... }, required: ['name', 'age'] }
|
|
272
|
-
* ```
|
|
273
|
-
*/
|
|
274
|
-
export declare function zodToJsonSchema<T>(schema: z.ZodType<T>): JSONSchema;
|
|
275
247
|
/**
|
|
276
248
|
* Normalize a raw JSON Schema.
|
|
277
249
|
*
|
|
@@ -283,14 +255,16 @@ export declare function zodToJsonSchema<T>(schema: z.ZodType<T>): JSONSchema;
|
|
|
283
255
|
*/
|
|
284
256
|
export declare function normalizeJsonSchema(schema: JSONSchema): JSONSchema;
|
|
285
257
|
/**
|
|
286
|
-
* Get the JSON Schema from
|
|
287
|
-
*
|
|
288
|
-
* Converts Zod schema to JSON Schema if necessary, or normalizes raw JSON Schema.
|
|
258
|
+
* Get the JSON Schema from a SchemaConfig or StructuredOutputOptions.
|
|
289
259
|
*
|
|
290
260
|
* @param options The structured output options
|
|
291
261
|
* @returns JSON Schema
|
|
292
262
|
*/
|
|
293
263
|
export declare function getJsonSchema<T>(options: StructuredOutputOptions<T>): JSONSchema;
|
|
264
|
+
/**
|
|
265
|
+
* Get the JSON Schema from a SchemaConfig directly.
|
|
266
|
+
*/
|
|
267
|
+
export declare function getJsonSchemaFromConfig<T>(config: SchemaConfig<T>): JSONSchema;
|
|
294
268
|
/**
|
|
295
269
|
* Strip unsupported features from a JSON Schema for a specific provider.
|
|
296
270
|
*
|
|
@@ -300,18 +274,6 @@ export declare function getJsonSchema<T>(options: StructuredOutputOptions<T>): J
|
|
|
300
274
|
* @param schema The JSON Schema to transform
|
|
301
275
|
* @param provider The target provider
|
|
302
276
|
* @returns Cleaned JSON Schema
|
|
303
|
-
*
|
|
304
|
-
* @example
|
|
305
|
-
* ```typescript
|
|
306
|
-
* const schema = {
|
|
307
|
-
* type: 'string',
|
|
308
|
-
* pattern: '^[a-z]+$',
|
|
309
|
-
* minLength: 1,
|
|
310
|
-
* };
|
|
311
|
-
*
|
|
312
|
-
* const cleaned = stripUnsupportedFeatures(schema, 'google');
|
|
313
|
-
* // { type: 'string' } - pattern and minLength removed
|
|
314
|
-
* ```
|
|
315
277
|
*/
|
|
316
278
|
export declare function stripUnsupportedFeatures(schema: JSONSchema, provider: SchemaProvider): JSONSchema;
|
|
317
279
|
/**
|
|
@@ -321,46 +283,45 @@ export declare function stripUnsupportedFeatures(schema: JSONSchema, provider: S
|
|
|
321
283
|
* 1. Extracts/converts the JSON Schema from options
|
|
322
284
|
* 2. Applies provider-specific transformations (e.g., removing unsupported features for Google)
|
|
323
285
|
* 3. Adds name/description for LLM guidance
|
|
286
|
+
*/
|
|
287
|
+
export declare function convertToProviderSchema<T>(provider: SchemaProvider, options: StructuredOutputOptions<T>): ProviderSchema;
|
|
288
|
+
/**
|
|
289
|
+
* Strip markdown code fences from raw LLM output.
|
|
324
290
|
*
|
|
325
|
-
*
|
|
326
|
-
*
|
|
327
|
-
*
|
|
291
|
+
* Some providers/models — notably Gemma variants via Ollama — wrap
|
|
292
|
+
* structured JSON output in ` ```json ... ``` ` fences even when a JSON
|
|
293
|
+
* schema is passed via the `format` field. This helper extracts the
|
|
294
|
+
* inner payload so it can be fed to `JSON.parse`.
|
|
328
295
|
*
|
|
329
|
-
*
|
|
330
|
-
*
|
|
331
|
-
*
|
|
332
|
-
*
|
|
333
|
-
*
|
|
334
|
-
*
|
|
335
|
-
*
|
|
336
|
-
*
|
|
337
|
-
*
|
|
338
|
-
*
|
|
339
|
-
*
|
|
340
|
-
*
|
|
296
|
+
* Behavior:
|
|
297
|
+
* - If the input contains no triple-backtick fences, the input is
|
|
298
|
+
* returned unchanged (zero risk of disturbing well-formed output).
|
|
299
|
+
* - Otherwise, the first fenced block is extracted and returned trimmed.
|
|
300
|
+
* Language tags (` ```json `, ` ```JSON `, etc.) are handled.
|
|
301
|
+
* - Callers should still treat the return value as untrusted — it may
|
|
302
|
+
* not be valid JSON (e.g. the model emitted prose, not JSON).
|
|
303
|
+
*
|
|
304
|
+
* This helper is idempotent: `stripJsonFences(stripJsonFences(x)) === stripJsonFences(x)`.
|
|
305
|
+
*
|
|
306
|
+
* @param rawOutput The raw LLM response text
|
|
307
|
+
* @returns Fence-stripped content if fences were present, otherwise `rawOutput` unchanged
|
|
341
308
|
*/
|
|
342
|
-
export declare function
|
|
309
|
+
export declare function stripJsonFences(rawOutput: string): string;
|
|
343
310
|
/**
|
|
344
311
|
* Parse and validate structured output from raw LLM response text.
|
|
345
312
|
*
|
|
346
313
|
* This function:
|
|
347
|
-
* 1. Parses JSON from the raw output string
|
|
348
|
-
*
|
|
314
|
+
* 1. Parses JSON from the raw output string (with fallback fence stripping
|
|
315
|
+
* for models that wrap structured output in ` ```json ... ``` `)
|
|
316
|
+
* 2. Validates using the SchemaConfig's validate function (if provided)
|
|
349
317
|
* 3. Throws StructuredOutputError on failure
|
|
350
318
|
*
|
|
351
|
-
* @param
|
|
319
|
+
* @param config The schema configuration with optional validator
|
|
352
320
|
* @param rawOutput The raw string output from the LLM
|
|
353
321
|
* @returns The validated and typed data
|
|
354
|
-
* @throws StructuredOutputError if JSON parsing fails or
|
|
355
|
-
*
|
|
356
|
-
* @example
|
|
357
|
-
* ```typescript
|
|
358
|
-
* const schema = z.object({ name: z.string(), age: z.number() });
|
|
359
|
-
* const rawOutput = '{"name": "Alice", "age": 30}';
|
|
360
|
-
* const result = parseStructured(schema, rawOutput); // { name: "Alice", age: 30 }
|
|
361
|
-
* ```
|
|
322
|
+
* @throws StructuredOutputError if JSON parsing fails or validation fails
|
|
362
323
|
*/
|
|
363
|
-
export declare function parseStructured<T>(
|
|
324
|
+
export declare function parseStructured<T>(config: SchemaConfig<T>, rawOutput: string): T;
|
|
364
325
|
/**
|
|
365
326
|
* Try to parse and validate structured output, returning a result object.
|
|
366
327
|
*
|
|
@@ -368,49 +329,23 @@ export declare function parseStructured<T>(schema: z.ZodType<T>, rawOutput: stri
|
|
|
368
329
|
* on validation failure, it returns a result object with `ok: false` and
|
|
369
330
|
* the error details.
|
|
370
331
|
*
|
|
371
|
-
* @param
|
|
332
|
+
* @param config The schema configuration with optional validator
|
|
372
333
|
* @param rawOutput The raw string output from the LLM
|
|
373
334
|
* @returns A result object: `{ ok: true, value }` on success, `{ ok: false, error, rawOutput }` on failure
|
|
374
|
-
*
|
|
375
|
-
* @example
|
|
376
|
-
* ```typescript
|
|
377
|
-
* const schema = z.object({ name: z.string(), age: z.number() });
|
|
378
|
-
*
|
|
379
|
-
* // Success case
|
|
380
|
-
* const result1 = tryParseStructured(schema, '{"name": "Alice", "age": 30}');
|
|
381
|
-
* if (result1.ok) {
|
|
382
|
-
* console.log(result1.value.name); // "Alice"
|
|
383
|
-
* }
|
|
384
|
-
*
|
|
385
|
-
* // Failure case
|
|
386
|
-
* const result2 = tryParseStructured(schema, 'invalid json');
|
|
387
|
-
* if (!result2.ok) {
|
|
388
|
-
* console.log(result2.error.message); // Error message
|
|
389
|
-
* console.log(result2.rawOutput); // Original output
|
|
390
|
-
* }
|
|
391
|
-
* ```
|
|
392
335
|
*/
|
|
393
|
-
export declare function tryParseStructured<T>(
|
|
336
|
+
export declare function tryParseStructured<T>(config: SchemaConfig<T>, rawOutput: string): StructuredOutputResult<T>;
|
|
394
337
|
/**
|
|
395
|
-
* Validate already-parsed data
|
|
338
|
+
* Validate already-parsed data using a SchemaConfig's validator.
|
|
396
339
|
*
|
|
397
|
-
* This is useful when you have already parsed JSON and need to validate
|
|
398
|
-
* it against a schema, with optional raw output for error messages.
|
|
340
|
+
* This is useful when you have already parsed JSON and need to validate it.
|
|
399
341
|
*
|
|
400
|
-
* @param
|
|
342
|
+
* @param config The schema configuration with optional validator
|
|
401
343
|
* @param data The parsed data to validate
|
|
402
344
|
* @param rawOutput Optional raw output string for error messages
|
|
403
345
|
* @returns The validated and typed data
|
|
404
|
-
* @throws StructuredOutputError if
|
|
405
|
-
*
|
|
406
|
-
* @example
|
|
407
|
-
* ```typescript
|
|
408
|
-
* const schema = z.object({ name: z.string(), age: z.number() });
|
|
409
|
-
* const data = JSON.parse('{"name": "Alice", "age": 30}');
|
|
410
|
-
* const result = validateStructuredOutput(schema, data); // { name: "Alice", age: 30 }
|
|
411
|
-
* ```
|
|
346
|
+
* @throws StructuredOutputError if validation fails
|
|
412
347
|
*/
|
|
413
|
-
export declare function validateStructuredOutput<T>(
|
|
348
|
+
export declare function validateStructuredOutput<T>(config: SchemaConfig<T>, data: unknown, rawOutput?: string): T;
|
|
414
349
|
/**
|
|
415
350
|
* Incremental JSON parser for streaming structured output.
|
|
416
351
|
*
|
|
@@ -420,20 +355,12 @@ export declare function validateStructuredOutput<T>(schema: z.ZodType<T>, data:
|
|
|
420
355
|
*/
|
|
421
356
|
export declare class StreamingJsonParser<T> {
|
|
422
357
|
private buffer;
|
|
423
|
-
private
|
|
424
|
-
constructor(
|
|
358
|
+
private readonly validateFn?;
|
|
359
|
+
constructor(config: SchemaConfig<T>);
|
|
425
360
|
/**
|
|
426
361
|
* Feed a chunk of JSON text to the parser.
|
|
427
362
|
* Returns a validated partial object if the current buffer can be parsed
|
|
428
|
-
* as valid JSON that passes
|
|
429
|
-
*
|
|
430
|
-
* For partial objects, this attempts to:
|
|
431
|
-
* 1. Add closing braces/brackets to make valid JSON
|
|
432
|
-
* 2. Fill in missing required fields with null/empty values
|
|
433
|
-
* 3. Validate against schema
|
|
434
|
-
*
|
|
435
|
-
* @param chunk Text chunk from the stream
|
|
436
|
-
* @returns Validated partial object or undefined
|
|
363
|
+
* as valid JSON that passes validation, or undefined if not yet valid.
|
|
437
364
|
*/
|
|
438
365
|
feed(chunk: string): {
|
|
439
366
|
partial: T | undefined;
|
|
@@ -463,5 +390,4 @@ export interface StreamingStructuredResult<T> {
|
|
|
463
390
|
/** The validated partial or complete object */
|
|
464
391
|
value: T;
|
|
465
392
|
}
|
|
466
|
-
export { z } from 'zod';
|
|
467
393
|
//# sourceMappingURL=structured-output.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"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"}
|