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.
Files changed (127) hide show
  1. package/dist/ai-model.d.ts +20 -22
  2. package/dist/ai-model.d.ts.map +1 -1
  3. package/dist/ai-model.js +26 -23
  4. package/dist/ai-model.js.map +1 -1
  5. package/dist/client.d.ts +5 -5
  6. package/dist/client.d.ts.map +1 -1
  7. package/dist/client.js +17 -9
  8. package/dist/client.js.map +1 -1
  9. package/dist/http.d.ts +2 -0
  10. package/dist/http.d.ts.map +1 -1
  11. package/dist/http.js +1 -0
  12. package/dist/http.js.map +1 -1
  13. package/dist/index.d.ts +3 -3
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +4 -4
  16. package/dist/index.js.map +1 -1
  17. package/dist/interfaces.d.ts +49 -11
  18. package/dist/interfaces.d.ts.map +1 -1
  19. package/dist/interfaces.js +14 -0
  20. package/dist/interfaces.js.map +1 -1
  21. package/dist/providers/anthropic.d.ts +56 -0
  22. package/dist/providers/anthropic.d.ts.map +1 -0
  23. package/dist/providers/anthropic.js +524 -0
  24. package/dist/providers/anthropic.js.map +1 -0
  25. package/dist/providers/google.d.ts +5 -0
  26. package/dist/providers/google.d.ts.map +1 -1
  27. package/dist/providers/google.js +64 -8
  28. package/dist/providers/google.js.map +1 -1
  29. package/dist/providers/index.d.ts +1 -0
  30. package/dist/providers/index.d.ts.map +1 -1
  31. package/dist/providers/index.js +1 -0
  32. package/dist/providers/index.js.map +1 -1
  33. package/dist/providers/ollama.d.ts.map +1 -1
  34. package/dist/providers/ollama.js +38 -11
  35. package/dist/providers/ollama.js.map +1 -1
  36. package/dist/providers/openai.d.ts.map +1 -1
  37. package/dist/providers/openai.js +9 -7
  38. package/dist/providers/openai.js.map +1 -1
  39. package/dist/router.d.ts +13 -33
  40. package/dist/router.d.ts.map +1 -1
  41. package/dist/router.js +33 -57
  42. package/dist/router.js.map +1 -1
  43. package/dist/stream-decoder.d.ts +29 -2
  44. package/dist/stream-decoder.d.ts.map +1 -1
  45. package/dist/stream-decoder.js +39 -11
  46. package/dist/stream-decoder.js.map +1 -1
  47. package/dist/structured-output.d.ts +107 -181
  48. package/dist/structured-output.d.ts.map +1 -1
  49. package/dist/structured-output.js +137 -192
  50. package/dist/structured-output.js.map +1 -1
  51. package/dist/zod-adapter.d.ts +44 -0
  52. package/dist/zod-adapter.d.ts.map +1 -0
  53. package/dist/zod-adapter.js +61 -0
  54. package/dist/zod-adapter.js.map +1 -0
  55. package/package.json +9 -1
  56. package/src/ai-model.ts +350 -0
  57. package/src/auditor.ts +213 -0
  58. package/src/client.ts +402 -0
  59. package/src/debug/debug-google-streaming.ts +97 -0
  60. package/src/debug/debug-tool-execution.ts +86 -0
  61. package/src/debug/test-lmstudio-tools.ts +155 -0
  62. package/src/demos/README.md +47 -0
  63. package/src/demos/basic/universal-llm-examples.ts +161 -0
  64. package/src/demos/mcp/astrid-memory-demo.ts +295 -0
  65. package/src/demos/mcp/astrid-persona-memory.ts +357 -0
  66. package/src/demos/mcp/mcp-mongodb-demo.ts +275 -0
  67. package/src/demos/mcp/simple-astrid-memory.ts +148 -0
  68. package/src/demos/mcp/simple-mcp-demo.ts +68 -0
  69. package/src/demos/mcp/working-mcp-demo.ts +62 -0
  70. package/src/demos/model-alias-demo.ts +0 -0
  71. package/src/demos/tools/RAG_MEMORY_INTEGRATION.md +267 -0
  72. package/src/demos/tools/astrid-memory-demo.ts +270 -0
  73. package/src/demos/tools/astrid-production-memory-clean.ts +785 -0
  74. package/src/demos/tools/astrid-production-memory.ts +558 -0
  75. package/src/demos/tools/basic-translation-test.ts +66 -0
  76. package/src/demos/tools/chromadb-similarity-tuning.ts +390 -0
  77. package/src/demos/tools/clean-multilingual-conversation.ts +209 -0
  78. package/src/demos/tools/clean-translation-test.ts +119 -0
  79. package/src/demos/tools/clean-universal-multilingual-test.ts +131 -0
  80. package/src/demos/tools/complete-rag-demo.ts +369 -0
  81. package/src/demos/tools/complete-tool-demo.ts +132 -0
  82. package/src/demos/tools/demo-tool-calling.ts +124 -0
  83. package/src/demos/tools/dynamic-language-switching-test.ts +251 -0
  84. package/src/demos/tools/hybrid-thinking-test.ts +154 -0
  85. package/src/demos/tools/memory-integration-test.ts +420 -0
  86. package/src/demos/tools/multilingual-memory-system.ts +802 -0
  87. package/src/demos/tools/ondemand-translation-demo.ts +655 -0
  88. package/src/demos/tools/production-tool-demo.ts +245 -0
  89. package/src/demos/tools/revolutionary-multilingual-test.ts +151 -0
  90. package/src/demos/tools/rigorous-language-analysis.ts +218 -0
  91. package/src/demos/tools/test-universal-memory-system.ts +126 -0
  92. package/src/demos/tools/translation-integration-guide.ts +346 -0
  93. package/src/demos/tools/universal-memory-system.ts +560 -0
  94. package/src/http.ts +247 -0
  95. package/src/index.ts +161 -0
  96. package/src/interfaces.ts +657 -0
  97. package/src/mcp.ts +345 -0
  98. package/src/providers/anthropic.ts +762 -0
  99. package/src/providers/google.ts +620 -0
  100. package/src/providers/index.ts +8 -0
  101. package/src/providers/ollama.ts +469 -0
  102. package/src/providers/openai.ts +392 -0
  103. package/src/router.ts +780 -0
  104. package/src/stream-decoder.ts +361 -0
  105. package/src/structured-output.ts +759 -0
  106. package/src/test-scripts/test-advanced-tools.ts +310 -0
  107. package/src/test-scripts/test-google-streaming-enhanced.ts +147 -0
  108. package/src/test-scripts/test-google-streaming.ts +63 -0
  109. package/src/test-scripts/test-google-system-prompt-comprehensive.ts +189 -0
  110. package/src/test-scripts/test-mcp-config.ts +28 -0
  111. package/src/test-scripts/test-mcp-connection.ts +29 -0
  112. package/src/test-scripts/test-system-message-positions.ts +163 -0
  113. package/src/test-scripts/test-system-prompt-improvement-demo.ts +83 -0
  114. package/src/test-scripts/test-tool-calling.ts +231 -0
  115. package/src/tests/ai-model.test.ts +1614 -0
  116. package/src/tests/auditor.test.ts +224 -0
  117. package/src/tests/http.test.ts +200 -0
  118. package/src/tests/interfaces.test.ts +117 -0
  119. package/src/tests/providers/google.test.ts +660 -0
  120. package/src/tests/providers/ollama.test.ts +954 -0
  121. package/src/tests/providers/openai.test.ts +1122 -0
  122. package/src/tests/router.test.ts +254 -0
  123. package/src/tests/stream-decoder.test.ts +179 -0
  124. package/src/tests/structured-output.test.ts +1450 -0
  125. package/src/tests/tools.test.ts +175 -0
  126. package/src/tools.ts +246 -0
  127. 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
- * Provides type-safe Zod schema integration and JSON Schema support.
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., ZodError) */
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
- * - Zod schema validation fails
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 (ZodError, SyntaxError, etc.)
130
+ * - `cause` property for the underlying error
85
131
  *
86
132
  * @example
87
133
  * ```typescript
88
134
  * try {
89
- * const result = await model.generateStructured(UserSchema, messages);
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
- * if (error.cause instanceof z.ZodError) {
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., ZodError for schema validation failures) */
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 Zod schema (`schema`) for type-safe validation
112
- * - A raw JSON Schema object (`jsonSchema`) for flexibility
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 (inferred from Zod schema)
158
+ * @template T The expected output type
118
159
  *
119
160
  * @example
120
161
  * ```typescript
121
- * // Using Zod schema (recommended)
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
- * schema: UserSchema,
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
- * Zod schema for structured output.
152
- * Use this for type-safe validation with automatic type inference.
185
+ * Schema configuration for structured output.
186
+ * Contains JSON Schema + optional validator.
153
187
  */
154
- schema?: z.ZodType<T>;
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 Zod.
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 options.
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
- * @param provider The target provider
326
- * @param options The structured output options
327
- * @returns Provider-ready schema with name and description
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
- * @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
- * ```
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 convertToProviderSchema<T>(provider: SchemaProvider, options: StructuredOutputOptions<T>): ProviderSchema;
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
- * 2. Validates the parsed data against the Zod schema
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 schema The Zod schema to validate against
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 schema validation fails
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>(schema: z.ZodType<T>, rawOutput: string): 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 schema The Zod schema to validate against
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>(schema: z.ZodType<T>, rawOutput: string): StructuredOutputResult<T>;
336
+ export declare function tryParseStructured<T>(config: SchemaConfig<T>, rawOutput: string): StructuredOutputResult<T>;
394
337
  /**
395
- * Validate already-parsed data against a Zod schema.
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 schema The Zod schema to validate against
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 schema validation fails
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>(schema: z.ZodType<T>, data: unknown, rawOutput?: string): 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 schema;
424
- constructor(schema: z.ZodType<T>);
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 the schema, or undefined if not yet valid.
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;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACtC;AAMD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,uCAAuC;IACvC,MAAM,EAAE,UAAU,CAAC;IACnB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;GAEG;AACH,MAAM,WAAW,4BAA4B;IACzC,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,KAAK,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC5C,yDAAyD;IACzD,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC,2EAA2E;IAC3E,SAAyB,KAAK,CAAC,EAAE,KAAK,CAAC;gBAE3B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B;CAUrE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACtC;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAEtB;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACtC,wBAAwB;IACxB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB,CAAC,EAAE;IACvC,wBAAwB;IACxB,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAC9B,uBAAuB,CAAC,CAAC,CAAC,GAC1B,uBAAuB,CAAC,CAAC,CAAC,CAAC;AAMjC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EACvC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAClC,MAAM,IAAI,uBAAuB,CAAC,CAAC,CAAC,CAEtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EACvC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAClC,MAAM,IAAI,uBAAuB,CAAC,CAAC,CAAC,CAEtC;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,UAAU,CAWnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAGlE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,UAAU,CAQhF;AAkBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CACpC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,cAAc,GACzB,UAAU,CAwCZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACrC,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GACpC,cAAc,CAehB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC7B,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,MAAM,GAClB,CAAC,CA2BH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAChC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,MAAM,GAClB,sBAAsB,CAAC,CAAC,CAAC,CAe3B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EACtC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,EAAE,OAAO,EACb,SAAS,CAAC,EAAE,MAAM,GACnB,CAAC,CAUH;AAMD;;;;;;GAMG;AACH,qBAAa,mBAAmB,CAAC,CAAC;IAC9B,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAIhC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,CAAC,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE;IAmBlE;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,OAAO,CAAC,eAAe;CA0D1B;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IACxC,gDAAgD;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,KAAK,EAAE,CAAC,CAAC;CACZ;AAOD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC"}
1
+ {"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"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"}