@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/dist/schema.d.ts CHANGED
@@ -1,17 +1,326 @@
1
1
  import z from 'zod';
2
2
  /**
3
- * Recursively transforms a Zod schema to support strict mode.
4
- *
5
- * @param schema - input Zod schema
6
- * @returns transformed Zod schema
7
- */
8
- export declare function strictify<S extends z.ZodType>(schema: S): S;
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
- * Options for toJSONSchemaV2
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. Currently only 'openai' is supported.
23
- * Different formats may have different constraints and supported features.
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?: JSONSchemaFormat;
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 V2 with support for different provider formats.
374
+ * Converts a Zod schema to JSON Schema with support for different provider dialects.
63
375
  *
64
- * This is a custom implementation that recursively inspects Zod schemas and converts them
65
- * to JSON Schema following the pattern of strictify/strictifySimple.
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 specified format
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 strictSchema = strictify(schema);
80
- * const jsonSchema = toJSONSchemaV2(strictSchema, { strict: true, format: 'openai' });
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
@@ -1 +1 @@
1
- {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,KAAK,CAAC;AAKpB;;;;;EAKE;AACF,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAoB3D;AAmND;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAEvG;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACb,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,eAAe,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACvC,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACnC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7B;AAeD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,CAAC,CAAC,OAAO,EACjB,OAAO,EAAE,mBAAmB,GAAG,OAAO,GACrC,UAAU,CA2BZ"}
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}