LlamaIndex Tutorial (TypeScript): parsing structured output for beginners

This tutorial shows you how to take free-form model output and turn it into a typed JSON object with LlamaIndex in TypeScript. You need this when your app expects consistent fields like name, amount, or riskLevel instead of brittle text that changes every run.

What You'll Need

• •Node.js 18+
• •A TypeScript project with ts-node or a build step
• •An OpenAI API key
• •These packages:
  • •llamaindex
  • •zod
  • •dotenv

Install them like this:

npm install llamaindex zod dotenv
npm install -D typescript ts-node @types/node

Set your API key in .env:

OPENAI_API_KEY=your_api_key_here

Step-by-Step

1. •Start by defining the shape you want back from the model. Use Zod so the schema is both a runtime validator and a TypeScript type source.

import { z } from "zod";

export const ClaimSchema = z.object({
  claimantName: z.string(),
  policyNumber: z.string(),
  incidentDate: z.string(),
  estimatedLossUSD: z.number(),
});

export type Claim = z.infer<typeof ClaimSchema>;

2. •Load your environment variables and create an LLM instance. This keeps your API key out of code and gives LlamaIndex access to the model.

import "dotenv/config";
import { OpenAI } from "llamaindex";

const llm = new OpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
});

3. •Ask for structured output using asStructuredLLM. This wraps the base model so it returns data that matches your Zod schema instead of plain text.

import { ClaimSchema } from "./schema";
import { OpenAI } from "llamaindex";

const llm = new OpenAI({
  model: "gpt-4o-mini",
});

const structuredLLM = llm.asStructuredLLM(ClaimSchema);

async function main() {
  const result = await structuredLLM.complete({
    prompt:
      "Extract claim details from this note: 'John Doe, policy PN-88321, incident on 2024-11-03, estimated loss $4200.'",
  });

  console.log(result.raw);
}

main();

4. •Parse the response and use it as typed data in your app. The returned object is validated against the schema, which means bad shapes fail early instead of leaking into downstream logic.

import "dotenv/config";
import { OpenAI } from "llamaindex";
import { ClaimSchema, type Claim } from "./schema";

const llm = new OpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
});

const structuredLLM = llm.asStructuredLLM(ClaimSchema);

async function extractClaim(): Promise<Claim> {
  const result = await structuredLLM.complete({
    prompt:
      "Extract claim details from this note: 'John Doe, policy PN-88321, incident on 2024-11-03, estimated loss $4200.'",
  });

  return result.raw;
}

extractClaim().then((claim) => {
  console.log(claim.claimantName);
});

5. •Add a small guardrail for invalid input. In production, you should assume some prompts will be incomplete or messy, so validate before trusting the result.

import { ClaimSchema } from "./schema";

const maybeClaim = {
  claimantName: "John Doe",
  policyNumber: "PN-88321",
  incidentDate: "2024-11-03",
  estimatedLossUSD: 4200,
};

const parsed = ClaimSchema.safeParse(maybeClaim);

if (!parsed.success) {
  console.error(parsed.error.flatten());
} else {
    console.log("Valid claim:", parsed.data);
}

Testing It

Run the script with npx ts-node or compile it with tsc and execute the output with Node. If everything is wired correctly, you should see a JavaScript object with the exact fields from your schema, not a blob of markdown or prose.

Test one bad prompt too. For example, ask for an amount without a number or omit a required field, then confirm your validation path catches it before the data reaches business logic.

If you are integrating this into an API endpoint, log both the raw model response and the parsed object during development. That makes it much easier to debug schema mismatches and prompt drift.

Next Steps

• •Learn how to use structuredLLM.chat() for multi-turn extraction flows.
• •Add enums and nested objects to your Zod schemas for richer business documents.
• •Combine structured output with LlamaIndex tools so agents can extract, validate, and route data in one pass.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.