universal-llm-client 4.0.0 → 4.1.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 +3 -3
- 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 +84 -181
- package/dist/structured-output.d.ts.map +1 -1
- package/dist/structured-output.js +79 -187
- 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 +160 -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 +702 -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 +1340 -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
|
|
155
|
+
* - A SchemaConfig (recommended)
|
|
156
|
+
* - A raw JSON Schema object for flexibility
|
|
113
157
|
*
|
|
114
|
-
*
|
|
115
|
-
* (used by providers like OpenAI that support schema names).
|
|
116
|
-
*
|
|
117
|
-
* @template T The expected output type (inferred from Zod schema)
|
|
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,23 +283,6 @@ 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
|
|
324
|
-
*
|
|
325
|
-
* @param provider The target provider
|
|
326
|
-
* @param options The structured output options
|
|
327
|
-
* @returns Provider-ready schema with name and description
|
|
328
|
-
*
|
|
329
|
-
* @example
|
|
330
|
-
* ```typescript
|
|
331
|
-
* const result = convertToProviderSchema('openai', {
|
|
332
|
-
* schema: z.object({ name: z.string() }),
|
|
333
|
-
* name: 'User',
|
|
334
|
-
* description: 'A user object',
|
|
335
|
-
* });
|
|
336
|
-
*
|
|
337
|
-
* // result.schema - JSON Schema
|
|
338
|
-
* // result.name - 'User'
|
|
339
|
-
* // result.description - 'A user object'
|
|
340
|
-
* ```
|
|
341
286
|
*/
|
|
342
287
|
export declare function convertToProviderSchema<T>(provider: SchemaProvider, options: StructuredOutputOptions<T>): ProviderSchema;
|
|
343
288
|
/**
|
|
@@ -345,22 +290,15 @@ export declare function convertToProviderSchema<T>(provider: SchemaProvider, opt
|
|
|
345
290
|
*
|
|
346
291
|
* This function:
|
|
347
292
|
* 1. Parses JSON from the raw output string
|
|
348
|
-
* 2. Validates the
|
|
293
|
+
* 2. Validates using the SchemaConfig's validate function (if provided)
|
|
349
294
|
* 3. Throws StructuredOutputError on failure
|
|
350
295
|
*
|
|
351
|
-
* @param
|
|
296
|
+
* @param config The schema configuration with optional validator
|
|
352
297
|
* @param rawOutput The raw string output from the LLM
|
|
353
298
|
* @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
|
-
* ```
|
|
299
|
+
* @throws StructuredOutputError if JSON parsing fails or validation fails
|
|
362
300
|
*/
|
|
363
|
-
export declare function parseStructured<T>(
|
|
301
|
+
export declare function parseStructured<T>(config: SchemaConfig<T>, rawOutput: string): T;
|
|
364
302
|
/**
|
|
365
303
|
* Try to parse and validate structured output, returning a result object.
|
|
366
304
|
*
|
|
@@ -368,49 +306,23 @@ export declare function parseStructured<T>(schema: z.ZodType<T>, rawOutput: stri
|
|
|
368
306
|
* on validation failure, it returns a result object with `ok: false` and
|
|
369
307
|
* the error details.
|
|
370
308
|
*
|
|
371
|
-
* @param
|
|
309
|
+
* @param config The schema configuration with optional validator
|
|
372
310
|
* @param rawOutput The raw string output from the LLM
|
|
373
311
|
* @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
312
|
*/
|
|
393
|
-
export declare function tryParseStructured<T>(
|
|
313
|
+
export declare function tryParseStructured<T>(config: SchemaConfig<T>, rawOutput: string): StructuredOutputResult<T>;
|
|
394
314
|
/**
|
|
395
|
-
* Validate already-parsed data
|
|
315
|
+
* Validate already-parsed data using a SchemaConfig's validator.
|
|
396
316
|
*
|
|
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.
|
|
317
|
+
* This is useful when you have already parsed JSON and need to validate it.
|
|
399
318
|
*
|
|
400
|
-
* @param
|
|
319
|
+
* @param config The schema configuration with optional validator
|
|
401
320
|
* @param data The parsed data to validate
|
|
402
321
|
* @param rawOutput Optional raw output string for error messages
|
|
403
322
|
* @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
|
-
* ```
|
|
323
|
+
* @throws StructuredOutputError if validation fails
|
|
412
324
|
*/
|
|
413
|
-
export declare function validateStructuredOutput<T>(
|
|
325
|
+
export declare function validateStructuredOutput<T>(config: SchemaConfig<T>, data: unknown, rawOutput?: string): T;
|
|
414
326
|
/**
|
|
415
327
|
* Incremental JSON parser for streaming structured output.
|
|
416
328
|
*
|
|
@@ -420,20 +332,12 @@ export declare function validateStructuredOutput<T>(schema: z.ZodType<T>, data:
|
|
|
420
332
|
*/
|
|
421
333
|
export declare class StreamingJsonParser<T> {
|
|
422
334
|
private buffer;
|
|
423
|
-
private
|
|
424
|
-
constructor(
|
|
335
|
+
private readonly validateFn?;
|
|
336
|
+
constructor(config: SchemaConfig<T>);
|
|
425
337
|
/**
|
|
426
338
|
* Feed a chunk of JSON text to the parser.
|
|
427
339
|
* 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
|
|
340
|
+
* as valid JSON that passes validation, or undefined if not yet valid.
|
|
437
341
|
*/
|
|
438
342
|
feed(chunk: string): {
|
|
439
343
|
partial: T | undefined;
|
|
@@ -463,5 +367,4 @@ export interface StreamingStructuredResult<T> {
|
|
|
463
367
|
/** The validated partial or complete object */
|
|
464
368
|
value: T;
|
|
465
369
|
}
|
|
466
|
-
export { z } from 'zod';
|
|
467
370
|
//# 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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"}
|