Skip to main content

​
Overview

Use session.prompt(..., { schema }) to extract typed structured data from a document.

​
Basic example

import { createOkra } from '@okrapdf/runtime';
import { z } from 'zod';

const okra = createOkra({ apiKey: process.env.OKRA_API_KEY });
const session = okra.sessions.from('ocr_doc_id');

const InvoiceSchema = z.object({
  vendor: z.string(),
  invoiceNumber: z.string(),
  date: z.string(),
  total: z.number(),
  lineItems: z.array(z.object({
    description: z.string(),
    quantity: z.number().optional(),
    amount: z.number(),
  })),
});

const { data, meta } = await session.prompt(
  'Extract all invoice fields including line items',
  { schema: InvoiceSchema },
);

console.log(data?.vendor, data?.total, meta?.confidence);

​
JSON Schema example

const result = await session.prompt('Extract invoice fields', {
  schema: {
    type: 'object',
    properties: {
      vendor: { type: 'string' },
      total: { type: 'number' },
    },
    required: ['vendor', 'total'],
  },
});

​
Multi-document pattern

Run extraction across many docs by attaching sessions and using Promise.all: 
const sessions = ['ocr_a', 'ocr_b', 'ocr_c'].map((id) => okra.sessions.from(id));

const results = await Promise.all(
  sessions.map((s) => s.prompt('Extract invoice fields', { schema: InvoiceSchema })),
);

​
Error handling

import { StructuredOutputError } from '@okrapdf/runtime';

try {
  await session.prompt('Extract invoice fields', { schema: InvoiceSchema });
} catch (err) {
  if (err instanceof StructuredOutputError) {
    console.error(err.code, err.message, err.details);
  }
}