Repository Public
1<!-- source: https://docs.x.ai/developers/model-capabilities/text/structured-outputs (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Model Capabilities34# Structured Outputs56Structured Outputs lets the API return responses in a specific format,7for example, a JSON object matching a schema you define instead of free-form8text. This feature is especially useful for tasks like document parsing, entity9extraction, and report generation.1011> [!TIP]12>13> When using supported schema features, the response is guaranteed to match your schema.1415There are two ways to request structured outputs from the model.1617The primary and most flexible method is to use the `response_format` parameter. By setting `response_format.type` to `"json_schema"` and providing your schema under `response_format.json_schema`, you can define exactly what structured output the model should return. The parameter also accepts `"json_object"` for any well-formed JSON when you don't need a specific structure, or `"text"` (the default) for free-form text.1819The second way is through tool calling. When you define tools, xAI models will always generate tool call arguments that strictly conform to the tool’s input JSON Schema (the `strict` flag is implicitly always `true`).2021> [!NOTE]22>23> Tool schemas follow the same JSON Schema support rules described on this page. See the [Function Calling](/developers/tools/function-calling) documentation for full details.2425You can define schemas using libraries like26[Pydantic](https://pydantic.dev/) or [Zod](https://zod.dev/).2728## JSON Schema support2930We support a practical subset of JSON Schema. Schemas authored against Draft 2020-12 work best; Draft-07 schemas are also accepted.3132### Supported types3334* `string`35* `number`36* `integer`37* `boolean`38* `null`39* `enum`40* `const`41* `array`42* `object`43* `anyOf`44* `oneOf` (behaves identically to `anyOf`)45* `allOf` (single subschema only; see [Best-effort keywords](#best-effort-keywords) for multiple)46* `$ref` / `$defs` (non-circular references only)4748> [!NOTE]49>50> `additionalProperties` defaults to `false` and must be set to `true` explicitly.5152To make a field nullable, use a type array (`{"type": ["string", "null"]}`) or an `anyOf` variant that includes `null`. Fields not listed in `required` are treated as optional.5354### String formats5556The `format` keyword is enforced for these values:5758`date` · `time` · `date-time` · `email` · `uuid` · `ipv4` · `ipv6` · `uri`5960Other `format` values are accepted but not enforced (see [Best-effort keywords](#best-effort-keywords)).6162### Constraint limits6364The following constraints are enforced by the output engine up to65the thresholds below. Schemas exceeding these limits are still accepted,66but conformance relies on model behavior.6768| Keyword | Guaranteed up to |69|---|---|70| `minimum` / `maximum` / `exclusiveMinimum` / `exclusiveMaximum` | No limit |71| `minLength` / `maxLength` | 2,048 |72| `minItems` / `maxItems` | 256 |73| `minProperties` / `maxProperties` | 64 |7475### Best-effort keywords7677These keywords are accepted but not structurally enforced; the model78handles them and does so reliably in practice, but outputs are not79guaranteed to satisfy these constraints. We recommend validating80if strict conformance is required.8182* `not`83* `if` / `then` / `else`84* `allOf` with more than one subschema85* `format` values not listed under [String formats](#string-formats)86* Constraints exceeding the limits above8788### Rejected schemas8990The following will return a `400` error:9192* `enum` or `anyOf` with zero variants93* Properties with a schema of `true` or `false`94* `maxContains` / `minContains`95* `items` as an array (use `prefixItems` for tuple validation)9697### Regex support (`pattern`)9899When using the `pattern` keyword on a string field, we support a practical subset of ECMAScript Regular Expressions (ECMA-262).100101**Supported:**102103* Literals and character classes (`[abc]`, `[a-z]`, `[^abc]`)104* `.` (matches any Unicode codepoint, including newlines)105* Alternation `|`, grouping `(...)`, and non-capturing groups `(?:...)`106* Quantifiers `*`, `+`, `?` and repetition ranges `{n}`, `{n,}`, `{n,m}`107* Shorthand classes `\d`, `\w`, `\s` (and their negations `\D`, `\W`, `\S`)108* Common escapes: `\n`, `\t`, `\r`, `\f`, `\xHH`, `\uHHHH`, `\u{HHHHHH}`109110**Not supported:**111112* Backreferences (`\1`, `\k<name>`, etc.)113* Unicode property escapes (`\p{L}`, `\P{Letter}`)114* Word boundaries (`\b`, `\B`)115* Lookahead and lookbehind (`(?=...)`, `(?<=...)`, etc.)116* Inline modifiers (`(?i)`, `(?m)`, etc.)117* Conditional expressions and other advanced constructs118119**Semantic differences from standard JavaScript RegExp:**120121* `.` matches newlines122* `^` and `$` are *implicit*—the pattern always matches the *entire string* (no need to add them)123* Capturing groups `(...)` have no semantic effect (they behave like non-capturing groups)124* The regex is evaluated with Unicode support125126## Example: Invoice Parsing127128A common use case for Structured Outputs is parsing raw documents. For example, invoices contain structured data like vendor details, amounts, and dates, but extracting this data from raw text can be error-prone. Structured Outputs ensures the extracted data matches a predefined schema.129130Let's say you want to extract the following data from an invoice:131132* Vendor name and address133* Invoice number and date134* Line items (description, quantity, price)135* Total amount and currency136137We'll use structured outputs to have Grok generate a strongly typed JSON for this.138139### Step 1: Defining the Schema140141You can use [Pydantic](https://pydantic.dev/) or [Zod](https://zod.dev/) to define your schema.142143```pythonWithoutSDK144from datetime import date145from enum import Enum146147from pydantic import BaseModel, Field148149class Currency(str, Enum):150 USD = "USD"151 EUR = "EUR"152 GBP = "GBP"153154class LineItem(BaseModel):155 description: str = Field(description="Description of the item or service")156 quantity: int = Field(description="Number of units", ge=1)157 unit_price: float = Field(description="Price per unit", ge=0)158159class Address(BaseModel):160 street: str = Field(description="Street address")161 city: str = Field(description="City")162 postal_code: str = Field(description="Postal/ZIP code")163 country: str = Field(description="Country")164165class Invoice(BaseModel):166 vendor_name: str = Field(description="Name of the vendor")167 vendor_address: Address = Field(description="Vendor's address")168 invoice_number: str = Field(description="Unique invoice identifier")169 invoice_date: date = Field(description="Date the invoice was issued")170 line_items: list[LineItem] = Field(description="List of purchased items/services")171 total_amount: float = Field(description="Total amount due", ge=0)172 currency: Currency = Field(description="Currency of the invoice")173```174175```javascriptWithoutSDK176import { z } from "zod";177178const CurrencyEnum = z.enum(["USD", "EUR", "GBP"]);179180const LineItemSchema = z.object({181 description: z.string().describe("Description of the item or service"),182 quantity: z.number().int().min(1).describe("Number of units"),183 unit_price: z.number().min(0).describe("Price per unit"),184});185186const AddressSchema = z.object({187 street: z.string().describe("Street address"),188 city: z.string().describe("City"),189 postal_code: z.string().describe("Postal/ZIP code"),190 country: z.string().describe("Country"),191});192193const InvoiceSchema = z.object({194 vendor_name: z.string().describe("Name of the vendor"),195 vendor_address: AddressSchema.describe("Vendor's address"),196 invoice_number: z.string().describe("Unique invoice identifier"),197 invoice_date: z.string().date().describe("Date the invoice was issued"),198 line_items: z.array(LineItemSchema).describe("List of purchased items/services"),199 total_amount: z.number().min(0).describe("Total amount due"),200 currency: CurrencyEnum.describe("Currency of the invoice"),201});202```203204### Step 2: Prepare The Prompts205206### System Prompt207208The system prompt instructs the model to extract invoice data from text. Since the schema is defined separately, the prompt can focus on the task without explicitly specifying the required fields in the output JSON.209210```text211Given a raw invoice, carefully analyze the text and extract the relevant invoice data into JSON format.212```213214### Example Invoice Text215216```text217Vendor: Acme Corp, 123 Main St, Springfield, IL 62704218Invoice Number: INV-2025-001219Date: 2025-02-10220Items:221- Widget A, 5 units, $10.00 each222- Widget B, 2 units, $15.00 each223Total: $80.00 USD224```225226### Step 3: The Final Code227228Use the structured outputs feature of the SDK to parse the invoice.229230```pythonXAI231import os232from datetime import date233from enum import Enum234235from pydantic import BaseModel, Field236237from xai_sdk import Client238from xai_sdk.chat import system, user239240# Pydantic Schemas241242class Currency(str, Enum):243 USD = "USD"244 EUR = "EUR"245 GBP = "GBP"246247class LineItem(BaseModel):248 description: str = Field(description="Description of the item or service")249 quantity: int = Field(description="Number of units", ge=1)250 unit_price: float = Field(description="Price per unit", ge=0)251252class Address(BaseModel):253 street: str = Field(description="Street address")254 city: str = Field(description="City")255 postal_code: str = Field(description="Postal/ZIP code")256 country: str = Field(description="Country")257258class Invoice(BaseModel):259 vendor_name: str = Field(description="Name of the vendor")260 vendor_address: Address = Field(description="Vendor's address")261 invoice_number: str = Field(description="Unique invoice identifier")262 invoice_date: date = Field(description="Date the invoice was issued")263 line_items: list[LineItem] = Field(description="List of purchased items/services")264 total_amount: float = Field(description="Total amount due", ge=0)265 currency: Currency = Field(description="Currency of the invoice")266267client = Client(api_key=os.getenv("XAI_API_KEY"))268chat = client.chat.create(model="grok-4.6")269270chat.append(system("Given a raw invoice, carefully analyze the text and extract the invoice data into JSON format."))271chat.append(272user("""273Vendor: Acme Corp, 123 Main St, Springfield, IL 62704274Invoice Number: INV-2025-001275Date: 2025-02-10276Items: - Widget A, 5 units, $10.00 each - Widget B, 2 units, $15.00 each277Total: $80.00 USD278""")279)280281# The parse method returns a tuple of the full response object as well as the parsed pydantic object.282283response, invoice = chat.parse(Invoice)284assert isinstance(invoice, Invoice)285286# Can access fields of the parsed invoice object directly287288print(invoice.vendor_name)289print(invoice.invoice_number)290print(invoice.invoice_date)291print(invoice.line_items)292print(invoice.total_amount)293print(invoice.currency)294295# Can also access fields from the raw response object such as the content.296297# In this case, the content is the JSON schema representation of the parsed invoice object298299print(response.content)300```301302```pythonOpenAISDK303from openai import OpenAI304305from pydantic import BaseModel, Field306from datetime import date307from enum import Enum308309# Pydantic Schemas310311class Currency(str, Enum):312 USD = "USD"313 EUR = "EUR"314 GBP = "GBP"315316class LineItem(BaseModel):317 description: str = Field(description="Description of the item or service")318 quantity: int = Field(description="Number of units", ge=1)319 unit_price: float = Field(description="Price per unit", ge=0)320321class Address(BaseModel):322 street: str = Field(description="Street address")323 city: str = Field(description="City")324 postal_code: str = Field(description="Postal/ZIP code")325 country: str = Field(description="Country")326327class Invoice(BaseModel):328 vendor_name: str = Field(description="Name of the vendor")329 vendor_address: Address = Field(description="Vendor's address")330 invoice_number: str = Field(description="Unique invoice identifier")331 invoice_date: date = Field(description="Date the invoice was issued")332 line_items: list[LineItem] = Field(description="List of purchased items/services")333 total_amount: float = Field(description="Total amount due", ge=0)334 currency: Currency = Field(description="Currency of the invoice")335336client = OpenAI(337 api_key="<YOUR_XAI_API_KEY_HERE>",338 base_url="https://api.x.ai/v1",339)340341completion = client.beta.chat.completions.parse(342 model="grok-4.6",343 messages=[344 {"role": "system", "content": "Given a raw invoice, carefully analyze the text and extract the invoice data into JSON format."},345 {"role": "user", "content": """346 Vendor: Acme Corp, 123 Main St, Springfield, IL 62704347 Invoice Number: INV-2025-001348 Date: 2025-02-10349 Items:350351 - Widget A, 5 units, $10.00 each352 - Widget B, 2 units, $15.00 each353 Total: $80.00 USD354 """}355 ],356 response_format=Invoice,357 )358359invoice = completion.choices[0].message.parsed360print(invoice)361```362363```javascriptOpenAISDK364import OpenAI from "openai";365import { zodResponseFormat } from "openai/helpers/zod";366import { z } from "zod";367368const CurrencyEnum = z.enum(["USD", "EUR", "GBP"]);369370const LineItemSchema = z.object({371 description: z.string().describe("Description of the item or service"),372 quantity: z.number().int().min(1).describe("Number of units"),373 unit_price: z.number().min(0).describe("Price per unit"),374});375376const AddressSchema = z.object({377 street: z.string().describe("Street address"),378 city: z.string().describe("City"),379 postal_code: z.string().describe("Postal/ZIP code"),380 country: z.string().describe("Country"),381});382383const InvoiceSchema = z.object({384 vendor_name: z.string().describe("Name of the vendor"),385 vendor_address: AddressSchema.describe("Vendor's address"),386 invoice_number: z.string().describe("Unique invoice identifier"),387 invoice_date: z.string().date().describe("Date the invoice was issued"),388 line_items: z.array(LineItemSchema).describe("List of purchased items/services"),389 total_amount: z.number().min(0).describe("Total amount due"),390 currency: CurrencyEnum.describe("Currency of the invoice"),391});392393const client = new OpenAI({394 apiKey: "<api key>",395 baseURL: "https://api.x.ai/v1",396});397398const completion = await client.chat.completions.parse({399 model: "grok-4.6",400 messages: [401 { role: "system", content: "Given a raw invoice, carefully analyze the text and extract the invoice data into JSON format." },402 { role: "user", content: \`403 Vendor: Acme Corp, 123 Main St, Springfield, IL 62704404 Invoice Number: INV-2025-001405 Date: 2025-02-10406 Items:407408 - Widget A, 5 units, $10.00 each409 - Widget B, 2 units, $15.00 each410 Total: $80.00 USD411 \` },412 ],413 response_format: zodResponseFormat(InvoiceSchema, "invoice"),414});415416const invoice = completion.choices[0].message.parsed;417console.log(invoice);418```419420```javascriptAISDK421import { xai } from '@ai-sdk/xai';422import { generateText, Output } from 'ai';423import { z } from 'zod';424425const CurrencyEnum = z.enum(['USD', 'EUR', 'GBP']);426427const LineItemSchema = z.object({428 description: z.string().describe('Description of the item or service'),429 quantity: z.number().int().min(1).describe('Number of units'),430 unit_price: z.number().min(0).describe('Price per unit'),431});432433const AddressSchema = z.object({434 street: z.string().describe('Street address'),435 city: z.string().describe('City'),436 postal_code: z.string().describe('Postal/ZIP code'),437 country: z.string().describe('Country'),438});439440const InvoiceSchema = z.object({441 vendor_name: z.string().describe('Name of the vendor'),442 vendor_address: AddressSchema.describe("Vendor's address"),443 invoice_number: z.string().describe('Unique invoice identifier'),444 invoice_date: z.string().date().describe('Date the invoice was issued'),445 line_items: z446 .array(LineItemSchema)447 .describe('List of purchased items/services'),448 total_amount: z.number().min(0).describe('Total amount due'),449 currency: CurrencyEnum.describe('Currency of the invoice'),450});451452const result = await generateText({453 model: xai.responses('grok-4.6'),454 output: Output.object({ schema: InvoiceSchema }),455 system:456 'Given a raw invoice, carefully analyze the text and extract the invoice data into JSON format.',457 prompt: \`458 Vendor: Acme Corp, 123 Main St, Springfield, IL 62704459 Invoice Number: INV-2025-001460 Date: 2025-02-10461 Items:462463 - Widget A, 5 units, $10.00 each464 - Widget B, 2 units, $15.00 each465 Total: $80.00 USD466 \`,467});468469console.log(result._output);470```471472### Step 4: Type-safe Output473474When using supported schema features, the output will be type-safe and respect the input schema.475476```json477{478 "vendor_name": "Acme Corp",479 "vendor_address": {480 "street": "123 Main St",481 "city": "Springfield",482 "postal_code": "62704",483 "country": "IL"484 },485 "invoice_number": "INV-2025-001",486 "invoice_date": "2025-02-10",487 "line_items": [488 { "description": "Widget A", "quantity": 5, "unit_price": 10.0 },489 { "description": "Widget B", "quantity": 2, "unit_price": 15.0 }490 ],491 "total_amount": 80.0,492 "currency": "USD"493}494```495496## Structured Outputs with Tools497498> [!NOTE]499>500> Structured outputs with tools is only available for supported Grok 4 family models.501502You can combine structured outputs with tool calling to get type-safe responses from tool-augmented queries. This works with both:503504* **[Agentic tool calling](/developers/tools/overview)**: Server-side tools like web search, X search, and code execution that the model orchestrates autonomously.505* **[Function calling](/developers/tools/function-calling)**: User-supplied tools where you define custom functions and handle tool execution yourself.506507This combination enables workflows where the model can use tools to gather information and return results in a predictable, strongly typed format.508509### Example: Agentic Tools with Structured Output510511This example uses web search to find the latest research on a topic and extracts structured data into a schema:512513```python customLanguage="pythonWithoutSDK"514from pydantic import BaseModel, Field515516class ProofInfo(BaseModel):517 name: str = Field(description="Name of the proof or paper")518 authors: str = Field(description="Authors of the proof")519 year: str = Field(description="Year published")520 summary: str = Field(description="Brief summary of the approach")521```522523```javascript customLanguage="javascriptWithoutSDK"524import { z } from "zod";525526const ProofInfoSchema = z.object({527 name: z.string().describe("Name of the proof or paper"),528 authors: z.string().describe("Authors of the proof"),529 year: z.string().describe("Year published"),530 summary: z.string().describe("Brief summary of the approach"),531});532```533534```python customLanguage="pythonXAI"535import os536from pydantic import BaseModel, Field537538from xai_sdk import Client539from xai_sdk.chat import user540from xai_sdk.tools import web_search541542# ProofInfo schema defined above543544client = Client(api_key=os.getenv("XAI_API_KEY"))545chat = client.chat.create(546 model="grok-4.6",547 tools=[web_search()],548)549550chat.append(user("Find the latest machine-checked proof of the four color theorem."))551552response, proof = chat.parse(ProofInfo)553554print(f"Name: {proof.name}")555print(f"Authors: {proof.authors}")556print(f"Year: {proof.year}")557print(f"Summary: {proof.summary}")558```559560```python customLanguage="pythonOpenAISDK"561import os562from openai import OpenAI563from pydantic import BaseModel, Field564565# ProofInfo schema defined above566567client = OpenAI(568 api_key=os.getenv("XAI_API_KEY"),569 base_url="https://api.x.ai/v1",570)571572response = client.responses.parse(573 model="grok-4.6",574 input="Find the latest machine-checked proof of the four color theorem.",575 tools=[576 {"type": "web_search"}577 ],578 text_format=ProofInfo,579)580581proof = response.output_parsed582print(f"Name: {proof.name}")583print(f"Authors: {proof.authors}")584print(f"Year: {proof.year}")585print(f"Summary: {proof.summary}")586```587588```javascript customLanguage="javascriptOpenAISDK"589import OpenAI from "openai";590import { zodResponseFormat } from "openai/helpers/zod";591import { z } from "zod";592593// ProofInfoSchema defined above594595const client = new OpenAI({596 apiKey: process.env.XAI_API_KEY,597 baseURL: "https://api.x.ai/v1",598});599600// Convert Zod schema to JSON schema format601const format = zodResponseFormat(ProofInfoSchema, "proof_info");602603const response = await client.responses.create({604 model: "grok-4.6",605 input: "Find the latest machine-checked proof of the four color theorem.",606 tools: [607 { type: "web_search" }608 ],609 text: {610 format: {611 type: "json_schema",612 name: format.json_schema.name,613 schema: format.json_schema.schema,614 strict: true,615 }616 }617});618619// Find the message in the output array620const message = response.output.find((item) => item.type === "message");621const textContent = message?.content?.find((c) => c.type === "output_text");622623if (textContent) {624 const proof = JSON.parse(textContent.text);625 console.log(`Name: ${proof.name}`);626 console.log(`Authors: ${proof.authors}`);627 console.log(`Year: ${proof.year}`);628 console.log(`Summary: ${proof.summary}`);629}630```631632### Example: Client-side Tools with Structured Output633634This example uses a client-side function tool to compute Collatz sequence steps and returns the result in a structured format:635636```python customLanguage="pythonWithoutSDK"637from pydantic import BaseModel, Field638639class CollatzResult(BaseModel):640 starting_number: int = Field(description="The input number")641 steps: int = Field(description="Number of steps to reach 1")642```643644```javascript customLanguage="javascriptWithoutSDK"645const CollatzResultSchema = {646 type: "object",647 properties: {648 starting_number: { type: "integer", description: "The input number" },649 steps: { type: "integer", description: "Number of steps to reach 1" },650 },651 required: ["starting_number", "steps"],652 additionalProperties: false,653};654```655656```python customLanguage="pythonXAI"657import os658import json659from pydantic import BaseModel, Field660661from xai_sdk import Client662from xai_sdk.chat import tool, tool_result, user663664# CollatzResult schema defined above665666def collatz_steps(n: int) -> int:667 """Returns the number of steps for n to reach 1 in the Collatz sequence."""668 steps = 0669 while n != 1:670 n = n // 2 if n % 2 == 0 else 3 * n + 1671 steps += 1672 return steps673674collatz_tool = tool(675 name="collatz_steps",676 description="Compute the number of steps for a number to reach 1 in the Collatz sequence",677 parameters={678 "type": "object",679 "properties": {680 "n": {"type": "integer", "description": "The starting number"},681 },682 "required": ["n"],683 },684)685686client = Client(api_key=os.getenv("XAI_API_KEY"))687chat = client.chat.create(688 model="grok-4.6",689 tools=[collatz_tool],690)691692chat.append(user("Use the collatz_steps tool to find how many steps it takes for 20250709 to reach 1."))693694# Handle tool calls until we get a final response695while True:696 response = chat.sample()697 698 if not response.tool_calls:699 break700 701 chat.append(response)702 for tc in response.tool_calls:703 args = json.loads(tc.function.arguments)704 result = collatz_steps(args["n"])705 chat.append(tool_result(str(result)))706707# Parse the final response into structured output708response, result = chat.parse(CollatzResult)709710print(f"Starting number: {result.starting_number}")711print(f"Steps to reach 1: {result.steps}")712```713714```python customLanguage="pythonOpenAISDK"715import os716import json717from openai import OpenAI718from pydantic import BaseModel, Field719720# CollatzResult schema defined above721722def collatz_steps(n: int) -> int:723 """Returns the number of steps for n to reach 1 in the Collatz sequence."""724 steps = 0725 while n != 1:726 n = n // 2 if n % 2 == 0 else 3 * n + 1727 steps += 1728 return steps729730client = OpenAI(731 api_key=os.getenv("XAI_API_KEY"),732 base_url="https://api.x.ai/v1",733)734735tools = [736 {737 "type": "function",738 "function": {739 "name": "collatz_steps",740 "description": "Compute the number of steps for a number to reach 1 in the Collatz sequence",741 "parameters": {742 "type": "object",743 "properties": {744 "n": {"type": "integer", "description": "The starting number"},745 },746 "required": ["n"],747 },748 },749 }750]751752messages = [753 {"role": "user", "content": "Use the collatz_steps tool to find how many steps it takes for 20250709 to reach 1."}754]755756# Handle tool calls until we get a final response757while True:758 completion = client.chat.completions.create(759 model="grok-4.6",760 messages=messages,761 tools=tools,762 )763 764 message = completion.choices[0].message765 766 if not message.tool_calls:767 break768 769 messages.append(message)770 for tc in message.tool_calls:771 args = json.loads(tc.function.arguments)772 result = collatz_steps(args["n"])773 messages.append({774 "role": "tool",775 "tool_call_id": tc.id,776 "content": str(result),777 })778779# Final call with structured output780completion = client.beta.chat.completions.parse(781 model="grok-4.6",782 messages=messages,783 response_format=CollatzResult,784)785786result = completion.choices[0].message.parsed787print(f"Starting number: {result.starting_number}")788print(f"Steps to reach 1: {result.steps}")789```790791```javascript customLanguage="javascriptOpenAISDK"792import OpenAI from "openai";793794// CollatzResultSchema defined above795796function collatzSteps(n) {797 let steps = 0;798 while (n !== 1) {799 n = n % 2 === 0 ? n / 2 : 3 * n + 1;800 steps++;801 }802 return steps;803}804805const client = new OpenAI({806 apiKey: process.env.XAI_API_KEY,807 baseURL: "https://api.x.ai/v1",808});809810const tools = [811 {812 type: "function",813 function: {814 name: "collatz_steps",815 description: "Compute the number of steps for a number to reach 1 in the Collatz sequence",816 parameters: {817 type: "object",818 properties: {819 n: { type: "integer", description: "The starting number" },820 },821 required: ["n"],822 },823 },824 },825];826827let messages = [828 { role: "user", content: "Use the collatz_steps tool to find how many steps it takes for 20250709 to reach 1." }829];830831// Handle tool calls until we get a final response832while (true) {833 const completion = await client.chat.completions.create({834 model: "grok-4.6",835 messages,836 tools,837 });838839 const message = completion.choices[0].message;840841 if (!message.tool_calls) {842 break;843 }844845 messages.push(message);846 for (const tc of message.tool_calls) {847 const args = JSON.parse(tc.function.arguments);848 const result = collatzSteps(args.n);849 messages.push({850 role: "tool",851 tool_call_id: tc.id,852 content: String(result),853 });854 }855}856857// Final call with structured output858const completion = await client.chat.completions.create({859 model: "grok-4.6",860 messages,861 response_format: {862 type: "json_schema",863 json_schema: {864 name: "collatz_result",865 schema: CollatzResultSchema,866 strict: true,867 },868 },869});870871const result = JSON.parse(completion.choices[0].message.content);872console.log("Starting number:", result.starting_number);873console.log("Steps to reach 1:", result.steps);874```875876## Alternative: Using `response_format` with `sample()` or `stream()`877878When using the xAI Python SDK, there's an alternative way to retrieve structured outputs. Instead of using the `parse()` method, you can pass your Pydantic model directly to the `response_format` parameter when creating a chat, and then use `sample()` or `stream()` to get the response.879880### How It Works881882When you pass a Pydantic model to `response_format`, the SDK automatically:8838841. Converts your Pydantic model to a JSON schema8852. Constrains the model's output to conform to that schema8863. Returns the response as a JSON string, that is conforming to the Pydantic model, in `response.content`887888You then manually parse the JSON string into your Pydantic model instance.889890### Key Differences891892| Approach | Method | Returns | Parsing |893|----------|--------|---------|---------|894| **Using `parse()`** | `chat.parse(Model)` | Tuple of `(Response, Model)` | Automatic - SDK parses for you |895| **Using `response_format`** | `chat.sample()` or `chat.stream()` | `Response` with JSON string | Manual - You parse `response.content` |896897### When to Use Each Approach898899* **Use `parse()`** when you want the simplest, most convenient experience with automatic parsing900* **Use `response_format` + `sample()` or `stream()`** when you:901 * Want more control over the parsing process902 * Need to handle the raw JSON string before parsing903 * Want to use streaming with structured outputs904 * Are integrating with existing code that expects to work with `sample()` or `stream()`905906### Example Using `response_format`907908```pythonXAI909import os910from datetime import date911from enum import Enum912913from pydantic import BaseModel, Field914from xai_sdk import Client915from xai_sdk.chat import system, user916917# Pydantic Schemas918class Currency(str, Enum):919 USD = "USD"920 EUR = "EUR"921 GBP = "GBP"922923924class LineItem(BaseModel):925 description: str = Field(description="Description of the item or service")926 quantity: int = Field(description="Number of units", ge=1)927 unit_price: float = Field(description="Price per unit", ge=0)928929930class Address(BaseModel):931 street: str = Field(description="Street address")932 city: str = Field(description="City")933 postal_code: str = Field(description="Postal/ZIP code")934 country: str = Field(description="Country")935936937class Invoice(BaseModel):938 vendor_name: str = Field(description="Name of the vendor")939 vendor_address: Address = Field(description="Vendor's address")940 invoice_number: str = Field(description="Unique invoice identifier")941 invoice_date: date = Field(description="Date the invoice was issued")942 line_items: list[LineItem] = Field(description="List of purchased items/services")943 total_amount: float = Field(description="Total amount due", ge=0)944 currency: Currency = Field(description="Currency of the invoice")945946947client = Client(api_key=os.getenv("XAI_API_KEY"))948949# Pass the Pydantic model to response_format instead of using parse()950chat = client.chat.create(951 model="grok-4.6",952 response_format=Invoice, # Pass the Pydantic model here953)954955chat.append(system("Given a raw invoice, carefully analyze the text and extract the invoice data into JSON format."))956chat.append(957 user("""958Vendor: Acme Corp, 123 Main St, Springfield, IL 62704959Invoice Number: INV-2025-001960Date: 2025-02-10961Items: - Widget A, 5 units, $10.00 each - Widget B, 2 units, $15.00 each962Total: $80.00 USD963""")964)965966# Use sample() instead of parse() - returns Response object967response = chat.sample()968969# The response.content is a valid JSON string conforming to your schema970print(response.content)971# Output: {"vendor_name": "Acme Corp", "vendor_address": {...}, ...}972973# Manually parse the JSON string into your Pydantic model974invoice = Invoice.model_validate_json(response.content)975assert isinstance(invoice, Invoice)976977# Access fields of the parsed invoice object978print(invoice.vendor_name)979print(invoice.invoice_number)980print(invoice.total_amount)981```982983### Streaming with Structured Outputs984985You can also use `stream()` with `response_format` to get streaming structured output. The chunks will progressively build up the JSON string:986987```pythonXAI988import os989990from pydantic import BaseModel, Field991from xai_sdk import Client992from xai_sdk.chat import system, user993994995class Summary(BaseModel):996 title: str = Field(description="A brief title")997 key_points: list[str] = Field(description="Main points from the text")998 sentiment: str = Field(description="Overall sentiment: positive, negative, or neutral")99910001001client = Client(api_key=os.getenv("XAI_API_KEY"))10021003chat = client.chat.create(1004 model="grok-4.6",1005 response_format=Summary, # Pass the Pydantic model here1006)10071008chat.append(system("Analyze the following text and provide a structured summary."))1009chat.append(user("The new product launch exceeded expectations with record sales..."))101010111012# Stream the response - chunks contain partial JSON1013for response, chunk in chat.stream():1014 print(chunk.content, end="", flush=True)101510161017# Parse the complete JSON string into your model1018summary = Summary.model_validate_json(response.content)1019print(f"Title: {summary.title}")1020print(f"Sentiment: {summary.sentiment}")1021```1022