Core client and retry engine

Zodstructor

createZodstructor(provider, config) returns a client with one main method:

const value = await client.completion({
  schema,
  messages,
  model,
  mode: 'json_schema',
})

value is typed as z.infer<typeof schema>. The method either returns schema-valid data or throws after the configured retries.

Output mode resolution

structured is kept for backward compatibility. Prefer mode.

InputResolved mode
mode setused as-is
structured: truejson_schema
structured: falseprompt
neitherauto

Validation retries always downgrade to prompt after the first attempt, so a broken native structured-output response does not keep failing in the same mode.

Retry layers

Validation retry

completionWithRetry performs this loop:

  1. Convert Zod to JSON Schema.
  2. Inject a compact schema prompt into the system message.
  3. Call the provider.
  4. extractJson → JSON.parse → schema.safeParse.
  5. On failure, append the invalid assistant output and a user message containing Zod issues plus the required schema.

maxRetries controls only this layer.

Transport retry

Provider exceptions are retried independently with exponential backoff:

  • transportRetries default 2
  • retryDelayMs default 250
  • delay: retryDelayMs * 2 ** attempt
  • abort signals and AbortError are never retried

Use onRetry for validation repair and onTransportRetry for network/HTTP failures.

Errors

  • ValidationError: JSON parsing or Zod validation failed. Carries issues, rawOutput, and attempt.
  • AbortError: the caller aborted the operation.

Provider SDK errors are otherwise allowed to propagate so callers keep the original HTTP/network details.