@aeye/core 0.3.8 → 0.3.9
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/README.md +103 -2
- package/aeye-core-prompts.md +171 -0
- package/aeye-core-schema.md +117 -0
- package/aeye-core-tools.md +177 -0
- package/aeye-core-types.md +178 -0
- package/aeye-core.md +88 -0
- package/dist/common.d.ts +36 -0
- package/dist/common.d.ts.map +1 -1
- package/dist/common.js +101 -0
- package/dist/common.js.map +1 -1
- package/dist/prompt.d.ts +261 -16
- package/dist/prompt.d.ts.map +1 -1
- package/dist/prompt.js +653 -297
- package/dist/prompt.js.map +1 -1
- package/dist/schema.d.ts +432 -18
- package/dist/schema.d.ts.map +1 -1
- package/dist/schema.js +1403 -209
- package/dist/schema.js.map +1 -1
- package/dist/tool.d.ts +107 -17
- package/dist/tool.d.ts.map +1 -1
- package/dist/tool.js +128 -9
- package/dist/tool.js.map +1 -1
- package/dist/types.d.ts +50 -5
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -2
package/dist/schema.d.ts
CHANGED
|
@@ -1,17 +1,326 @@
|
|
|
1
1
|
import z from 'zod';
|
|
2
2
|
/**
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
|
|
8
|
-
|
|
3
|
+
* Provider family for a `FormatDescriptor`. The three known wire dialects
|
|
4
|
+
* (`'openai'`, `'anthropic'`, `'google'`) are autocomplete hints; any string
|
|
5
|
+
* is accepted so users can register custom descriptors via
|
|
6
|
+
* `registerDescriptor` and reference them by family name in
|
|
7
|
+
* `ModelInfo.strictFormat`. `'lenient'` is the no-rewrite catch-all and is
|
|
8
|
+
* not registerable as a custom family.
|
|
9
|
+
*
|
|
10
|
+
* Use this type wherever you need to talk about a descriptor family —
|
|
11
|
+
* registry functions, model declarations, etc.
|
|
12
|
+
*/
|
|
13
|
+
export type DescriptorFamily = 'openai' | 'anthropic' | 'google' | (string & {});
|
|
14
|
+
/**
|
|
15
|
+
* Format descriptor — describes the JSON Schema dialect of a target.
|
|
16
|
+
*
|
|
17
|
+
* Each provider/strict combination is represented by one descriptor. The
|
|
18
|
+
* descriptor controls both how `strictify` rewrites a Zod schema (preprocesses
|
|
19
|
+
* for record-as-array, tuple-as-object, etc.) and how `toJSONSchema` emits the
|
|
20
|
+
* matching JSON Schema. Every `if (strict)` decision in the conversion
|
|
21
|
+
* pipeline dispatches off a descriptor field, so adding a new dialect is a
|
|
22
|
+
* matter of declaring a new `FormatDescriptor` and registering it.
|
|
23
|
+
*/
|
|
24
|
+
export interface FormatDescriptor {
|
|
25
|
+
/** Stable id used as the cache key inside `strictify`. */
|
|
26
|
+
readonly id: string;
|
|
27
|
+
/**
|
|
28
|
+
* Provider family for this descriptor. The three built-in wire dialects
|
|
29
|
+
* are `'openai'` / `'anthropic'` / `'google'`; `'lenient'` is the
|
|
30
|
+
* no-rewrite catch-all. Custom descriptors registered via
|
|
31
|
+
* `registerDescriptor` may use any string here — the family is the
|
|
32
|
+
* lookup key used by `getDescriptor(family, strict)`.
|
|
33
|
+
*/
|
|
34
|
+
readonly family: DescriptorFamily | 'lenient';
|
|
35
|
+
/** True if this descriptor represents the strict variant for its family. */
|
|
36
|
+
readonly strict: boolean;
|
|
37
|
+
/** When true, every object field appears in `required[]` (OpenAI strict). */
|
|
38
|
+
readonly objectAllFieldsRequired: boolean;
|
|
39
|
+
/** When true, every object emits `additionalProperties: false`. */
|
|
40
|
+
readonly objectClosedByDefault: boolean;
|
|
41
|
+
/** How to encode `z.record(K, V)`. */
|
|
42
|
+
readonly recordEncoding: 'array-of-pairs' | 'open-record';
|
|
43
|
+
/**
|
|
44
|
+
* How to encode `z.tuple([...])`.
|
|
45
|
+
* - `object-numeric-keys`: OpenAI-strict workaround (`{ "0": A, "1": B, ... }`)
|
|
46
|
+
* - `prefix-items`: standard JSON Schema `prefixItems` (Anthropic / Google)
|
|
47
|
+
* - `items-union`: collapse to homogeneous `items: { anyOf: [...] }` (last-resort)
|
|
48
|
+
*/
|
|
49
|
+
readonly tupleEncoding: 'object-numeric-keys' | 'prefix-items' | 'items-union';
|
|
50
|
+
readonly allowAllOf: boolean;
|
|
51
|
+
readonly allowAnyOf: boolean;
|
|
52
|
+
readonly allowOneOf: boolean;
|
|
53
|
+
/** Whether `{ $ref: '#' }` self-reference is permitted. */
|
|
54
|
+
readonly allowRootRef: boolean;
|
|
55
|
+
readonly allowDefsRef: boolean;
|
|
56
|
+
/** Reserved: emit Google-style `propertyOrdering` hints. */
|
|
57
|
+
readonly emitPropertyOrdering: boolean;
|
|
58
|
+
/** Whitelist of `format:` values to emit, or `'all'` to pass through. */
|
|
59
|
+
readonly supportedStringFormats: ReadonlySet<string> | 'all';
|
|
60
|
+
readonly allowPattern: boolean;
|
|
61
|
+
readonly allowMultiplePatterns: boolean;
|
|
62
|
+
readonly allowMinMaxLength: boolean;
|
|
63
|
+
readonly allowMinMaxItems: boolean;
|
|
64
|
+
readonly allowMinimumMaximum: boolean;
|
|
65
|
+
/** When true, `optional` becomes `T|null` (because every prop must be required). */
|
|
66
|
+
readonly optionalAsNullable: boolean;
|
|
67
|
+
/**
|
|
68
|
+
* How `z.any()` / `z.unknown()` is encoded.
|
|
69
|
+
* - `recursive-strict`: self-referencing $defs/Any with array-of-pairs records
|
|
70
|
+
* (OpenAI strict has no open-object support)
|
|
71
|
+
* - `recursive-open`: $defs/Any with `additionalProperties: <self>` records
|
|
72
|
+
* - `flat`: a non-recursive `anyOf` over the JSON value types
|
|
73
|
+
* (`string`/`number`/`boolean`/`null`/`array`/open-`object`). Used by
|
|
74
|
+
* descriptors that reject recursive `$defs/Any` definitions (Anthropic
|
|
75
|
+
* strict). Equivalent to TypeScript `any` — accepts every JSON value
|
|
76
|
+
* without imposing any structural constraints.
|
|
77
|
+
*/
|
|
78
|
+
readonly anyEncoding: 'recursive-strict' | 'recursive-open' | 'flat';
|
|
79
|
+
/** Maximum number of tools that can carry `strict: true` in one request. */
|
|
80
|
+
readonly maxStrictTools?: number;
|
|
81
|
+
/** Maximum total optional parameters across all strict schemas in one request. */
|
|
82
|
+
readonly maxStrictOptionalParams?: number;
|
|
83
|
+
/** Maximum total union-type parameters across all strict schemas in one request. */
|
|
84
|
+
readonly maxStrictUnionTypes?: number;
|
|
85
|
+
/**
|
|
86
|
+
* Whether the descriptor can express recursive `$ref` schemas (`$ref: '#'`
|
|
87
|
+
* to root, or any `$ref: '#/$defs/X'` whose target transitively references
|
|
88
|
+
* itself). OpenAI / Google strict / Lenient: true. Anthropic strict: false
|
|
89
|
+
* — Anthropic's tool `input_schema` validator explicitly rejects circular
|
|
90
|
+
* `$defs` graphs.
|
|
91
|
+
*
|
|
92
|
+
* When `false`, the JSON-Schema emitter detects cycles in the source
|
|
93
|
+
* schema and replaces the offending back-edge with the descriptor's flat
|
|
94
|
+
* "any" shape (see `anyEncoding`) carrying a description that names the
|
|
95
|
+
* `$defs` entry it would otherwise have referenced. Non-cyclic shared
|
|
96
|
+
* `$ref` reuse is unaffected — those still emit as a `$ref` to a `$defs`
|
|
97
|
+
* entry.
|
|
98
|
+
*/
|
|
99
|
+
readonly supportsRecursion: boolean;
|
|
100
|
+
/**
|
|
101
|
+
* Instruction appended after the schema text when a Prompt's/Tool's schema
|
|
102
|
+
* can't be expressed as this descriptor's structured output and is instead
|
|
103
|
+
* delivered to the model as PROMPT TEXT (see `canExpress` and the ai-layer
|
|
104
|
+
* `applySchemaDeliveryFallback`). Steers the model to emit a single raw JSON
|
|
105
|
+
* object rather than echoing the schema or wrapping it in prose/fences.
|
|
106
|
+
*
|
|
107
|
+
* Optional — descriptors that omit it fall back to
|
|
108
|
+
* `DEFAULT_JSON_FALLBACK_INSTRUCTION` via `getJsonFallbackInstruction`.
|
|
109
|
+
*/
|
|
110
|
+
readonly jsonFallbackInstruction?: string;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* Default instruction used when a `FormatDescriptor` omits
|
|
114
|
+
* `jsonFallbackInstruction`. Appended after the schema text when a schema is
|
|
115
|
+
* delivered as prompt text instead of as structured output.
|
|
116
|
+
*/
|
|
117
|
+
export declare const DEFAULT_JSON_FALLBACK_INSTRUCTION = "Return ONLY a single raw JSON object conforming to the schema above \u2014 no markdown code fences, no prose, and do NOT echo the schema itself.";
|
|
118
|
+
/**
|
|
119
|
+
* Resolve the prompt-text fallback instruction for a descriptor, falling back
|
|
120
|
+
* to `DEFAULT_JSON_FALLBACK_INSTRUCTION` when the descriptor doesn't declare
|
|
121
|
+
* one of its own.
|
|
122
|
+
*/
|
|
123
|
+
export declare function getJsonFallbackInstruction(descriptor: FormatDescriptor): string;
|
|
124
|
+
/** Lenient descriptor — no rewrites, no closure, formats pass through. Default for unsupported models. */
|
|
125
|
+
export declare const LENIENT: FormatDescriptor;
|
|
126
|
+
/**
|
|
127
|
+
* OpenAI strict — current behavior verbatim. Records→pairs,
|
|
128
|
+
* tuples→numeric-keys, optional→nullable.
|
|
129
|
+
*
|
|
130
|
+
* No documented per-request slot limit (max strict tools / optional params /
|
|
131
|
+
* union types). The SchemaBudget treats those caps as `undefined` (no limit)
|
|
132
|
+
* for OpenAI; OpenAI's own ~5000-property and ~5-level-depth schema caps
|
|
133
|
+
* aren't enforced here either — they're rare in practice and produce a
|
|
134
|
+
* server-side rejection that the user can react to.
|
|
135
|
+
*/
|
|
136
|
+
export declare const OPENAI_STRICT: FormatDescriptor;
|
|
137
|
+
/** OpenAI non-strict — alias of LENIENT but tagged with the openai family. */
|
|
138
|
+
export declare const OPENAI_NON_STRICT: FormatDescriptor;
|
|
139
|
+
/**
|
|
140
|
+
* Anthropic strict — Claude 4.5+ only (Opus 4.7/4.6/4.5, Sonnet 4.6/4.5,
|
|
141
|
+
* Haiku 4.5). Per Anthropic's structured-outputs docs:
|
|
142
|
+
*
|
|
143
|
+
* - `additionalProperties` may **only** be `false` (no schema-valued open
|
|
144
|
+
* records), so `z.record(...)` falls back to the OpenAI-style
|
|
145
|
+
* array-of-pairs workaround.
|
|
146
|
+
* - Non-cyclic `$ref` / `$defs` reuse is supported and used freely — only
|
|
147
|
+
* *circular* `$defs` graphs are rejected by the API
|
|
148
|
+
* (`Circular reference detected in schema definitions: …`). The emitter
|
|
149
|
+
* sets `supportsRecursion: false` so the cycle-breaker replaces the
|
|
150
|
+
* offending back-edge with the flat "any" shape (see `anyEncoding`) and
|
|
151
|
+
* leaves shared non-cyclic `$ref`s alone. Root self-reference (`$ref: '#'`)
|
|
152
|
+
* is always cyclic by definition, so `allowRootRef` stays `false`.
|
|
153
|
+
* - Numerical (`minimum`/`maximum`/`multipleOf`) and string-length
|
|
154
|
+
* (`minLength`/`maxLength`) constraints are not supported and are dropped.
|
|
155
|
+
* - `prefixItems` and other positional tuple keywords are not in the
|
|
156
|
+
* supported list, so tuples collapse to a homogeneous `items: anyOf`.
|
|
157
|
+
* - Supported formats include `uri` (unlike OpenAI strict). We pass all
|
|
158
|
+
* formats through and let Anthropic ignore unknowns.
|
|
159
|
+
*/
|
|
160
|
+
export declare const ANTHROPIC_STRICT: FormatDescriptor;
|
|
161
|
+
export declare const ANTHROPIC_NON_STRICT: FormatDescriptor;
|
|
162
|
+
/**
|
|
163
|
+
* Google Gemini strict — per `ai.google.dev/gemini-api/docs/structured-output`:
|
|
164
|
+
*
|
|
165
|
+
* - Supported keywords: types, `properties`, `required`, `additionalProperties`,
|
|
166
|
+
* `enum`, `format` (date-time/date/time only), `minimum`, `maximum`, `items`,
|
|
167
|
+
* `prefixItems`, `minItems`, `maxItems`, `title`, `description`,
|
|
168
|
+
* `propertyOrdering`. Recursion via `$ref: "#"` (root self-ref).
|
|
169
|
+
* - Combinators (`allOf`, `anyOf`, `oneOf`) are NOT in the supported list;
|
|
170
|
+
* we conservatively flag them off so unions degrade to a representable form
|
|
171
|
+
* rather than emit something Gemini ignores.
|
|
172
|
+
* - String constraints (`minLength`, `maxLength`, `pattern` formats beyond the
|
|
173
|
+
* three documented) are not supported.
|
|
174
|
+
* - `propertyOrdering` is REQUIRED for Gemini 2.0 strict; we always emit it
|
|
175
|
+
* on object schemas under this descriptor.
|
|
176
|
+
*/
|
|
177
|
+
export declare const GOOGLE_STRICT: FormatDescriptor;
|
|
178
|
+
export declare const GOOGLE_NON_STRICT: FormatDescriptor;
|
|
179
|
+
/**
|
|
180
|
+
* Register a custom `FormatDescriptor` so it can be looked up by `id` or
|
|
181
|
+
* by `(family, strict)`. Useful for adding support for a new provider
|
|
182
|
+
* dialect or for registering a tweaked variant of an existing family.
|
|
183
|
+
*
|
|
184
|
+
* The descriptor's `id` and `family` become the lookup keys. If a
|
|
185
|
+
* descriptor with the same id is already registered, the new one
|
|
186
|
+
* replaces it. The family slot tracks one strict and one lenient
|
|
187
|
+
* variant; registering a third variant overwrites the matching slot.
|
|
188
|
+
*
|
|
189
|
+
* Built-in descriptors (`OPENAI_STRICT`, `LENIENT`, etc.) are seeded at
|
|
190
|
+
* module load — you don't need to register them manually. They CAN be
|
|
191
|
+
* overridden by registering a same-id descriptor afterwards, but doing
|
|
192
|
+
* so is generally a sign that you should pick a different id.
|
|
193
|
+
*
|
|
194
|
+
* @example
|
|
195
|
+
* ```ts
|
|
196
|
+
* import { registerDescriptor, OPENAI_STRICT } from '@aeye/core';
|
|
197
|
+
*
|
|
198
|
+
* // A tighter OpenAI-flavored descriptor: same wire shape but with
|
|
199
|
+
* // pattern support disabled (some downstream tools choke on regex).
|
|
200
|
+
* registerDescriptor({
|
|
201
|
+
* ...OPENAI_STRICT,
|
|
202
|
+
* id: 'openai-no-regex',
|
|
203
|
+
* family: 'openai-no-regex',
|
|
204
|
+
* allowPattern: false,
|
|
205
|
+
* allowMultiplePatterns: false,
|
|
206
|
+
* });
|
|
207
|
+
*
|
|
208
|
+
* // Now resolvable:
|
|
209
|
+
* getDescriptor('openai-no-regex', true); // → the registered descriptor
|
|
210
|
+
* getDescriptorById('openai-no-regex'); // → same
|
|
211
|
+
* ```
|
|
212
|
+
*/
|
|
213
|
+
export declare function registerDescriptor(descriptor: FormatDescriptor): void;
|
|
214
|
+
/**
|
|
215
|
+
* Resolve a descriptor by family + strictness.
|
|
216
|
+
*
|
|
217
|
+
* Built-in families (`'openai'`, `'anthropic'`, `'google'`) always
|
|
218
|
+
* resolve. Custom families registered via `registerDescriptor` resolve
|
|
219
|
+
* once they're registered. Unknown families fall back to `LENIENT`
|
|
220
|
+
* (safe default — strict mode silently degrades for unrecognized models).
|
|
221
|
+
*
|
|
222
|
+
* @param family - provider family (built-in or registered)
|
|
223
|
+
* @param strict - whether the strict variant is wanted
|
|
224
|
+
*/
|
|
225
|
+
export declare function getDescriptor(family: DescriptorFamily, strict: boolean): FormatDescriptor;
|
|
226
|
+
/**
|
|
227
|
+
* Look up a descriptor by id. Returns LENIENT for unknown ids (safe default).
|
|
228
|
+
* Custom descriptors registered via `registerDescriptor` are reachable here
|
|
229
|
+
* by their `id`.
|
|
230
|
+
*/
|
|
231
|
+
export declare function getDescriptorById(id: string | undefined): FormatDescriptor;
|
|
232
|
+
/**
|
|
233
|
+
* True if `family` has at least one registered descriptor (strict or
|
|
234
|
+
* lenient). Used by `@aeye/ai`'s `resolveStrictFormat` fallback chain to
|
|
235
|
+
* decide whether a model id prefix or provider name is a recognized
|
|
236
|
+
* dialect.
|
|
237
|
+
*/
|
|
238
|
+
export declare function hasDescriptorFamily(family: string | undefined): boolean;
|
|
239
|
+
/**
|
|
240
|
+
* Resolve descriptor from various input shapes (boolean, options object, or descriptor).
|
|
241
|
+
* Used by `toJSONSchema` to support its overloaded signature.
|
|
242
|
+
*/
|
|
243
|
+
export declare function resolveDescriptor(input: FormatDescriptor | ToJSONSchemaOptions | boolean | undefined): FormatDescriptor;
|
|
244
|
+
/**
|
|
245
|
+
* Decide whether `schema` can be expressed as structured output under
|
|
246
|
+
* `descriptor`'s JSON-Schema dialect. Returns `false` when the schema uses a
|
|
247
|
+
* construct the descriptor forbids, so the caller can DROP the wire schema and
|
|
248
|
+
* deliver it as prompt text instead (see the ai-layer
|
|
249
|
+
* `applySchemaDeliveryFallback`).
|
|
250
|
+
*
|
|
251
|
+
* Walks the Zod schema in the same style as `strictify`/`convert`, honoring:
|
|
252
|
+
* - **unions** (`z.union` / `z.discriminatedUnion` → `anyOf`) when
|
|
253
|
+
* `!descriptor.allowAnyOf` (e.g. Gemini strict rejects `anyOf`);
|
|
254
|
+
* - **intersections** (`z.intersection` → `allOf`) when `!descriptor.allowAllOf`;
|
|
255
|
+
* - **recursion** (a self-referential `z.lazy` cycle → `$ref`): a cycle back to
|
|
256
|
+
* the ROOT is fine when `descriptor.allowRootRef && descriptor.supportsRecursion`
|
|
257
|
+
* (Gemini supports `$ref: '#'`); a non-root cycle needs
|
|
258
|
+
* `descriptor.allowDefsRef && descriptor.supportsRecursion`.
|
|
259
|
+
*
|
|
260
|
+
* `ZodNullable` / `ZodOptional` are transparent wrappers here (nullability is
|
|
261
|
+
* NOT treated as a union), so only genuine `z.union(...)` trips `allowAnyOf`.
|
|
262
|
+
* Non-combinator, non-recursive schemas (plain objects, arrays, primitives)
|
|
263
|
+
* are always expressible. The structure mirrors the descriptor flags so more
|
|
264
|
+
* feasibility checks are easy to add.
|
|
265
|
+
*/
|
|
266
|
+
export declare function canExpress(schema: z.ZodType, descriptor: FormatDescriptor): boolean;
|
|
267
|
+
/**
|
|
268
|
+
* Recursively transforms a Zod schema to a target dialect.
|
|
269
|
+
*
|
|
270
|
+
* For LENIENT, returns the input schema unchanged (no rewrites). For strict
|
|
271
|
+
* descriptors, installs preprocesses that accept the dialect's wire shape
|
|
272
|
+
* (e.g. array-of-pairs records, numeric-key tuple objects) and normalize them
|
|
273
|
+
* back to the natural Zod shape before validation.
|
|
274
|
+
*
|
|
275
|
+
* Repeated calls with the same `(schema, descriptor)` return the cached
|
|
276
|
+
* transformed schema. Different descriptors share the same outer entry but
|
|
277
|
+
* map to different inner values — bounded by the small descriptor count.
|
|
278
|
+
*
|
|
279
|
+
* @param schema - input Zod schema
|
|
280
|
+
* @param descriptor - target dialect descriptor (defaults to OPENAI_STRICT)
|
|
281
|
+
*/
|
|
282
|
+
export declare function strictify<S extends z.ZodType>(schema: S, descriptor?: FormatDescriptor): S;
|
|
283
|
+
/**
|
|
284
|
+
* Produce a NON-FAILING variant of `schema` that keeps every transform
|
|
285
|
+
* (`preprocess`, `codec`, `pipe`, `transform`) but drops validation. Parsing
|
|
286
|
+
* a wire value through the result runs the decode preprocesses installed by
|
|
287
|
+
* `strictify` (array-of-pairs → record, numeric-key object → tuple, null →
|
|
288
|
+
* undefined) and yields the conceptual value, without ever rejecting.
|
|
289
|
+
*
|
|
290
|
+
* Recursion (`z.lazy` self-reference) is handled with a per-call memo map: an
|
|
291
|
+
* in-flight node is recorded as a thunk and re-encounters resolve to
|
|
292
|
+
* `z.lazy(thunk)`, so a self-referential schema relaxes in finite time and
|
|
293
|
+
* never infinite-loops.
|
|
294
|
+
*/
|
|
295
|
+
export declare function relaxValidation(schema: z.ZodType): z.ZodType;
|
|
296
|
+
/**
|
|
297
|
+
* DECODE a model's wire `value` back to the conceptual shape a custom parser
|
|
298
|
+
* expects — symmetric with how `strictify` ENCODEs the request for the wire.
|
|
299
|
+
*
|
|
300
|
+
* Runs the descriptor's decode transforms (via `relaxValidation(strictify(...))`)
|
|
301
|
+
* without imposing validation, so array-of-pairs records, numeric-key tuples,
|
|
302
|
+
* and null-for-optional fields are normalized before a provider-agnostic
|
|
303
|
+
* custom parser sees them. Best-effort: NEVER throws — if the relaxed decoder
|
|
304
|
+
* can't parse the value it is returned unchanged.
|
|
305
|
+
*
|
|
306
|
+
* @param schema - the PRE-strictify conceptual schema (strictify runs internally)
|
|
307
|
+
* @param value - the model's raw wire value (already `JSON.parse`d)
|
|
308
|
+
* @param descriptor - the wire dialect the request was encoded with
|
|
309
|
+
*/
|
|
310
|
+
export declare function decodeWire(schema: z.ZodType, value: unknown, descriptor: FormatDescriptor): unknown;
|
|
9
311
|
/**
|
|
10
312
|
* Format specification for JSON Schema generation
|
|
11
313
|
*/
|
|
12
|
-
export type JSONSchemaFormat = 'openai';
|
|
13
314
|
/**
|
|
14
|
-
*
|
|
315
|
+
* Family name for `ToJSONSchemaOptions.format`. Alias of `DescriptorFamily`
|
|
316
|
+
* — the three built-in dialects (`'openai'`, `'anthropic'`, `'google'`)
|
|
317
|
+
* plus any string registered via `registerDescriptor`.
|
|
318
|
+
*
|
|
319
|
+
* @deprecated Prefer `DescriptorFamily`. Both refer to the same widened type.
|
|
320
|
+
*/
|
|
321
|
+
export type JSONSchemaFormat = DescriptorFamily;
|
|
322
|
+
/**
|
|
323
|
+
* Options for toJSONSchema
|
|
15
324
|
*/
|
|
16
325
|
export interface ToJSONSchemaOptions {
|
|
17
326
|
/**
|
|
@@ -19,10 +328,11 @@ export interface ToJSONSchemaOptions {
|
|
|
19
328
|
*/
|
|
20
329
|
strict: boolean;
|
|
21
330
|
/**
|
|
22
|
-
* The target format for the JSON Schema.
|
|
23
|
-
*
|
|
331
|
+
* The target format for the JSON Schema. Resolves to a named FormatDescriptor.
|
|
332
|
+
* Built-in (`'openai'` / `'anthropic'` / `'google'`) or any string
|
|
333
|
+
* registered via `registerDescriptor`.
|
|
24
334
|
*/
|
|
25
|
-
format?:
|
|
335
|
+
format?: DescriptorFamily;
|
|
26
336
|
}
|
|
27
337
|
export type JSONSchemaType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'null' | 'integer';
|
|
28
338
|
/**
|
|
@@ -56,17 +366,19 @@ export interface JSONSchema {
|
|
|
56
366
|
const?: any;
|
|
57
367
|
title?: string;
|
|
58
368
|
$defs?: Record<string, JSONSchema>;
|
|
369
|
+
/** Gemini-specific: deterministic property emission order for strict mode. */
|
|
370
|
+
propertyOrdering?: string[];
|
|
59
371
|
[metadata: string]: unknown;
|
|
60
372
|
}
|
|
61
373
|
/**
|
|
62
|
-
* Converts a Zod schema to JSON Schema
|
|
374
|
+
* Converts a Zod schema to JSON Schema with support for different provider dialects.
|
|
63
375
|
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
376
|
+
* Accepts either a boolean (legacy: true = OPENAI_STRICT, false = LENIENT),
|
|
377
|
+
* an options object `{ strict, format? }`, or a `FormatDescriptor` directly.
|
|
66
378
|
*
|
|
67
379
|
* @param schema - The Zod schema to convert
|
|
68
380
|
* @param options - Configuration options for the conversion
|
|
69
|
-
* @returns JSON Schema object compatible with the
|
|
381
|
+
* @returns JSON Schema object compatible with the resolved dialect
|
|
70
382
|
*
|
|
71
383
|
* @example
|
|
72
384
|
* ```typescript
|
|
@@ -76,9 +388,111 @@ export interface JSONSchema {
|
|
|
76
388
|
* });
|
|
77
389
|
*
|
|
78
390
|
* // For OpenAI strict mode
|
|
79
|
-
* const
|
|
80
|
-
*
|
|
391
|
+
* const jsonSchema = toJSONSchema(schema, { strict: true, format: 'openai' });
|
|
392
|
+
*
|
|
393
|
+
* // For Anthropic strict mode
|
|
394
|
+
* const anthropic = toJSONSchema(schema, ANTHROPIC_STRICT);
|
|
81
395
|
* ```
|
|
82
396
|
*/
|
|
83
|
-
export declare function toJSONSchema(schema: z.ZodType, options: ToJSONSchemaOptions | boolean): JSONSchema;
|
|
397
|
+
export declare function toJSONSchema(schema: z.ZodType, options: ToJSONSchemaOptions | boolean | FormatDescriptor): JSONSchema;
|
|
398
|
+
/**
|
|
399
|
+
* Structural feature counts for a Zod schema, used by the SchemaBudget to
|
|
400
|
+
* decide whether an item fits a descriptor's per-request budget and whether
|
|
401
|
+
* the descriptor can express it at all.
|
|
402
|
+
*/
|
|
403
|
+
export interface SchemaFeatures {
|
|
404
|
+
/** True if the schema (or any subschema) uses `z.lazy` / self-recursion. */
|
|
405
|
+
hasRecursion: boolean;
|
|
406
|
+
/** Count of `z.optional()` leaves anywhere in the schema. */
|
|
407
|
+
optionalParameterCount: number;
|
|
408
|
+
/**
|
|
409
|
+
* Count of union-shaped nodes — `z.union`, `z.discriminatedUnion`, plus
|
|
410
|
+
* `z.nullable` (which on the wire under OpenAI strict becomes a type
|
|
411
|
+
* array `[T, "null"]`, also counts toward Anthropic's union-type budget).
|
|
412
|
+
*/
|
|
413
|
+
unionTypeCount: number;
|
|
414
|
+
/** Count of `z.record` nodes. */
|
|
415
|
+
recordCount: number;
|
|
416
|
+
/** Count of `z.tuple` nodes. */
|
|
417
|
+
tupleCount: number;
|
|
418
|
+
}
|
|
419
|
+
/**
|
|
420
|
+
* Walk a Zod schema once and count its structural features. Result is
|
|
421
|
+
* cached per schema in a WeakMap — second-and-subsequent calls are O(1) and
|
|
422
|
+
* the entry is GC'd with the schema (same OOM-safe pattern as `strictify`).
|
|
423
|
+
*/
|
|
424
|
+
export declare function analyzeSchema(schema: z.ZodType | z.core.$ZodType): SchemaFeatures;
|
|
425
|
+
/**
|
|
426
|
+
* Per-request strict-mode allocator.
|
|
427
|
+
*
|
|
428
|
+
* Constructed once per outgoing request with the chosen model's strictest
|
|
429
|
+
* descriptor. Tracks remaining slots (strict tools, optional parameters,
|
|
430
|
+
* union types) against the descriptor's documented per-request limits and
|
|
431
|
+
* decides per-tool / per-output whether to emit strict or fall back to
|
|
432
|
+
* LENIENT.
|
|
433
|
+
*
|
|
434
|
+
* Selection guarantees that any tool with `strict: true` (hard requirement)
|
|
435
|
+
* has a model that supports the family — `allocate` therefore always grants
|
|
436
|
+
* strict for `requested === true` (subject only to feasibility, not budget;
|
|
437
|
+
* if `true` items overflow the budget the API call will fail, which is the
|
|
438
|
+
* correct behavior for hard requirements).
|
|
439
|
+
*
|
|
440
|
+
* Numeric `strict: <priority>` items are allocated greedily after `true`
|
|
441
|
+
* items have consumed their share of the budget. Caller is expected to
|
|
442
|
+
* pre-sort by descending priority before iterating.
|
|
443
|
+
*/
|
|
444
|
+
export declare class SchemaBudget {
|
|
445
|
+
private readonly descriptor;
|
|
446
|
+
private remainingTools;
|
|
447
|
+
private remainingOptionalParams;
|
|
448
|
+
private remainingUnionTypes;
|
|
449
|
+
constructor(descriptor: FormatDescriptor);
|
|
450
|
+
/**
|
|
451
|
+
* Decide the effective descriptor for a tool's parameter schema given the
|
|
452
|
+
* dev's strict request, the schema's features, and the remaining budget.
|
|
453
|
+
*
|
|
454
|
+
* Returns `LENIENT` when:
|
|
455
|
+
* - `requested === false`
|
|
456
|
+
* - the schema uses a feature the descriptor can't represent
|
|
457
|
+
* - the descriptor has slot limits and the budget is exhausted (only
|
|
458
|
+
* applies to `requested` being a positive number; `true` always wins
|
|
459
|
+
* subject to feasibility)
|
|
460
|
+
*
|
|
461
|
+
* Returns the strict descriptor (and decrements the budget) otherwise.
|
|
462
|
+
*/
|
|
463
|
+
allocateTool(schema: z.ZodType | z.core.$ZodType, requested: boolean | number | undefined): FormatDescriptor;
|
|
464
|
+
/**
|
|
465
|
+
* Same as `allocateTool` but for the request's structured-output schema.
|
|
466
|
+
* The output schema doesn't consume a tool slot but it does count toward
|
|
467
|
+
* the optional-parameter and union-type budgets — descriptors document
|
|
468
|
+
* those limits as "across all strict schemas in one request".
|
|
469
|
+
*/
|
|
470
|
+
allocateOutput(schema: z.ZodType | z.core.$ZodType, requested: boolean | number | undefined): FormatDescriptor;
|
|
471
|
+
/** Snapshot of remaining budget. Useful for telemetry / debug logs. */
|
|
472
|
+
remaining(): {
|
|
473
|
+
strictTools: number;
|
|
474
|
+
optionalParams: number;
|
|
475
|
+
unionTypes: number;
|
|
476
|
+
};
|
|
477
|
+
private allocate;
|
|
478
|
+
}
|
|
479
|
+
/**
|
|
480
|
+
* Compare two descriptors and return the one with the tighter per-request
|
|
481
|
+
* budget. Used by providers to pick a single descriptor for a SchemaBudget
|
|
482
|
+
* shared between `convertTools` and `convertResponseFormat` — Anthropic's
|
|
483
|
+
* documented limits apply across the whole request, so the strictest
|
|
484
|
+
* descriptor wins.
|
|
485
|
+
*/
|
|
486
|
+
export declare function strictestOf(a: FormatDescriptor, b: FormatDescriptor): FormatDescriptor;
|
|
487
|
+
/**
|
|
488
|
+
* Convert a `boolean | number | undefined` strict request into a numeric
|
|
489
|
+
* priority for sorting. Used by providers to allocate strict slots in
|
|
490
|
+
* descending priority order.
|
|
491
|
+
*
|
|
492
|
+
* - `true` → `+Infinity` (hard requirement; always first in line)
|
|
493
|
+
* - `false` → `-Infinity` (always lenient; never wants strict)
|
|
494
|
+
* - `number > 0` → the number itself
|
|
495
|
+
* - `number <= 0` or `undefined` → `0` (no preference)
|
|
496
|
+
*/
|
|
497
|
+
export declare function strictPriority(requested: boolean | number | undefined): number;
|
|
84
498
|
//# sourceMappingURL=schema.d.ts.map
|
package/dist/schema.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;
|
|
1
|
+
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}
|