Anvia

Parsed completion ​

Use generateCompletion() when one direct model request should return a schema-validated value.

1. Return typed data ​

Pass the prompt or messages together with the model, schema, and request options:

ts
import { generateCompletion } from '@anvia/core'
import { z } from 'zod'

const ticketSchema = z.object({
  customer: z.string(),
  priority: z.enum(['low', 'normal', 'high']),
  summary: z.string().min(1),
})

const result = await generateCompletion({
    prompt: 'Acme Co. reports checkout failures. Priority is high.',
    model,
    outputSchema: ticketSchema,
    instructions: 'Classify the support message.'
})

console.log(result.output.customer)
console.log(result.output.priority)

result.output is inferred from the schema. The result also includes text, structured assistant content, token usage, and the original provider rawResponse. The schema need not be Zod: any Standard Schema works here (see Schema design).

2. Understand the validation path ​

Anvia performs four steps:

  1. Converts the schema to provider JSON Schema (Zod natively, Valibot via @valibot/to-json-schema, others via ~standard.jsonSchema).
  2. Verifies that the model supports output schemas.
  3. Sends one completion request.
  4. Parses the returned text as JSON and validates it against the same schema.

The promise rejects if the provider returns invalid JSON or a value that fails the schema. Never fall back to using result.text as trusted product data after validation fails.

3. Pass normal completion controls ​

Parsed completions accept the same direct-request options, including documents, temperature, token limits, typed controls, additional provider parameters, cancellation, and transport retries:

ts
const result = await generateCompletion({
    prompt: message,
    model,
    outputSchema: ticketSchema,
    instructions: 'Classify only from the supplied message.',
    temperature: 0,
    maxTokens: 300,
    retries: { maxAttempts: 3 }
})

Transport retries cover retryable model-call failures. JSON parsing and schema validation happen after the call completes and are not automatically regenerated by generateCompletion().

4. Stream a parsed completion ​

streamCompletion() accepts outputSchema and streams text_delta events while the terminal final event carries the validated, typed result:

ts
import { streamCompletion } from '@anvia/core'

for await (const event of streamCompletion({
    prompt: message,
    model,
    outputSchema: ticketSchema
})) {
  if (event.type === 'text_delta') {
    renderDelta(event.delta)
  }

  if (event.type === 'final') {
    console.log(event.result.output.priority)
  }
}

event.result.output is parsed and validated against the schema before the final event. Invalid output raises CompletionStructuredOutputError with the same phase union as generateCompletion() and arrives as a terminal error event. The default completion retry policy does not retry structured-output validation failures. A custom retries.shouldRetry can opt in, but a stream can retry only before provider progress has been exposed. Direct completion retries do not add an agent-style correction prompt. The model must support both streaming and output schemas.

Use agent output when the run needs tools, memory, retrieval, approvals, or several turns. Use an extractor when fields already exist in document-like text.

Built for Anvia.