SDK helpers for structured output

⚠️

Preview — this feature is being built; the design below is the spec.

The official Python and TypeScript SDKs let you declare the schema as a type in your own code and receive a parsed, typed object back. The SDK turns the type into a JSON schema, sends it as response_format, validates the reply and raises a typed error if parsing fails.

Python with Pydantic

from typing import Literal, Optional
from pydantic import BaseModel, Field
from syntic import Syntic
 
class Ticket(BaseModel):
    reason: str
    category: Literal["billing", "technical", "account", "other"]
    order_number: Optional[str] = Field(description="Order number if present, else null")
 
client = Syntic()
result = client.chat.completions.parse(
    model="Amara Quick",
    messages=[{"role": "user", "content": email_body}],
    response_format=Ticket,
)
ticket: Ticket = result.choices[0].message.parsed

TypeScript with Zod

import Syntic from '@syntic/sdk'
import { z } from 'zod'
import { zodResponseFormat } from '@syntic/sdk/helpers/zod'
 
const Ticket = z.object({
  reason: z.string(),
  category: z.enum(['billing', 'technical', 'account', 'other']),
  order_number: z.string().nullable(),
})
 
const client = new Syntic()
const result = await client.chat.completions.parse({
  model: 'Amara Quick',
  messages: [{ role: 'user', content: emailBody }],
  response_format: zodResponseFormat(Ticket, 'ticket'),
})
const ticket = result.choices[0].message.parsed // typed as z.infer<typeof Ticket>

How the conversion works

Your type	Sent as
`Optional[str]` / `.nullable()`	`{"type": ["string", "null"]}`, still listed in `required`
`Literal[...]` / `z.enum`	`enum`
Field description	`description`
Nested model	Nested object with `additionalProperties: false`
`list[...]` with `max_length` / `.max()`	`array` with `maxItems`

Defaults in your type are not sent; the model is asked for every field and your type applies defaults only if you parse loosely.

Errors

Exception	When
`LengthFinishReasonError`	The reply was cut off by `max_tokens` before the object closed.
`ContentRefusalError`	The model declined; `message.refusal` holds its reason.
`ValidationError` (Pydantic) / `ZodError`	Should not happen with `strict: true`; indicates a schema feature the server ignored. Report it with the request id.

The same helpers work for strict tools: client.tools.function(Ticket) builds a strict tool definition from the type.

Design schemas Stream structured output

Was this page helpful?