Dashboard

Cookbook Recipe

Documents

Extract structured data from a PDF

Send a PDF of your own to a chat model and get back invoice fields as JSON that matches a strict schema, checked locally before you use it.

POSThttps://api.devupai.com/v1/chat/completions

What you'll build

A command-line program that reads the path of a PDF from its first argument, sends the file to a model that accepts PDF input, and asks for a reply in a json_schema with strict: true. It validates the reply against the same schema and prints the invoice fields as JSON.

The model is chosen at run time from GET /v1/models, so no model ID is written in the code.

Before you start

  • A DEVUP AI account and an API key (sk-devup-...) in the DEVUP_API_KEY environment variable. The program stops when it is not set. See Authentication.
  • Python 3.10 or later, or Node.js 22.12 or later.
  • The packages for your language: openai and jsonschema for Python, the official devupai SDK and ajv for Node.js.
  • A PDF of your own, such as an invoice.
pip install openai jsonschema

The complete program

Save it as extract_invoice.py or extract-invoice.mjs. The Node.js program uses the official devupai SDK, and the Python program uses the openai package with the DEVUP AI base URL.

"""Extract invoice fields from a PDF into JSON that matches a strict schema.

Usage: python extract_invoice.py path/to/invoice.pdf
"""
import base64
import json
import os
import sys
from pathlib import Path

import jsonschema
import openai
from openai import OpenAI

MAX_BODY_BYTES = 10_485_760  # 10 MiB, Base64 file data included
PDF_MAGIC = b"%PDF-"
NEXT_CANDIDATE_CODES = {
    "response_format_not_supported",
    "unsupported_content",
    "use_responses_api",
    "wrong_endpoint",
}
ATTEMPTS_PER_MODEL = 2  # the first try and one retry

INSTRUCTION = (
    "Extract the invoice fields from the attached PDF. "
    "Use the document's own values, exactly as written."
)

INVOICE_SCHEMA = {
    "type": "object",
    "properties": {
        "vendor": {"type": "string"},
        "invoice_number": {"type": "string"},
        "issue_date": {"type": "string"},
        "currency": {"type": "string"},
        "line_items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string"},
                    "quantity": {"type": "number"},
                    "unit_price": {"type": "number"},
                },
                "required": ["description", "quantity", "unit_price"],
                "additionalProperties": False,
            },
        },
        "total": {"type": "number"},
    },
    "required": ["vendor", "invoice_number", "issue_date", "currency", "line_items", "total"],
    "additionalProperties": False,
}


class ExtractionError(Exception):
    """The PDF could not be turned into JSON that matches the schema."""


def read_pdf(pdf_path: Path) -> bytes:
    """The bytes of the file, or an ExtractionError that names the path."""
    try:
        return pdf_path.read_bytes()
    except OSError as e:
        raise ExtractionError(f"Cannot read {pdf_path}: {e.strerror or e}.") from e


def check_pdf(pdf_bytes: bytes) -> None:
    """Raise unless the file starts with the PDF signature."""
    if not pdf_bytes.startswith(PDF_MAGIC):
        raise ExtractionError("The file is not a PDF: it does not start with %PDF-.")


def pick_candidates(models) -> list[str]:
    """IDs of the models that take a PDF and a strict json_schema, in catalog order."""
    candidates = []
    for model in models:
        supports = getattr(model, "supports", None) or {}
        if (
            getattr(model, "type", None) == "text-generation"
            and getattr(model, "is_replaced", None) is not True
            and supports.get("pdf_input") is True
            and supports.get("structured_output") is True
        ):
            candidates.append(model.id)
    return candidates


def build_request(model: str, pdf_bytes: bytes, filename: str) -> dict:
    """One user message with the instruction and the PDF, and a strict json_schema."""
    file_data = "data:application/pdf;base64," + base64.b64encode(pdf_bytes).decode("ascii")
    return {
        "model": model,
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": INSTRUCTION},
                    {"type": "file", "file": {"filename": filename, "file_data": file_data}},
                ],
            }
        ],
        "response_format": {
            "type": "json_schema",
            "json_schema": {"name": "invoice", "strict": True, "schema": INVOICE_SCHEMA},
        },
    }


def check_body_size(body: dict) -> None:
    """Raise when the serialized request is over the 10 MiB body limit."""
    size = len(json.dumps(body, separators=(",", ":")).encode("utf-8"))
    if size > MAX_BODY_BYTES:
        raise ExtractionError(
            f"The request is {size:,} bytes and the limit is {MAX_BODY_BYTES:,} bytes (10 MiB). "
            "Split the PDF into smaller page ranges or compress it."
        )


def parse_invoice(content, validator) -> dict | None:
    """The reply as a dict when it is JSON that matches the schema, else None."""
    if not isinstance(content, str):
        return None
    try:
        data = json.loads(content)
    except json.JSONDecodeError:
        return None  # not JSON: the caller retries or raises
    return data if validator.is_valid(data) else None


def extract_with_model(client, body: dict, validator) -> tuple[dict, str] | None:
    """(invoice, raw reply) from one model, or None when the next candidate should take over."""
    for attempt in range(1, ATTEMPTS_PER_MODEL + 1):
        last = attempt == ATTEMPTS_PER_MODEL
        try:
            completion = client.chat.completions.create(**body)
        except openai.APIStatusError as e:
            if e.code in NEXT_CANDIDATE_CODES:
                return None
            if e.code == "structured_output_mismatch" and not last:
                continue
            if e.code == "structured_output_mismatch":
                request_id = e.response.headers.get("x-request-id") or "none"
                raise ExtractionError(
                    f"The reply of {body['model']} did not match the schema after a retry "
                    f"(x-request-id {request_id}). Simplify the schema and try again."
                ) from e
            raise
        raw = completion.choices[0].message.content if completion.choices else None
        invoice = parse_invoice(raw, validator)
        if invoice is not None:
            return invoice, raw
        if last:
            raise ExtractionError(
                f"The reply of {body['model']} did not pass local validation after a retry. "
                "Simplify the schema or the instruction and try again."
            )


def extract_invoice(client, pdf_bytes: bytes, filename: str, candidates: list[str], validator):
    """(model id, invoice, raw reply) from the first candidate that answers."""
    for model in candidates:
        body = build_request(model, pdf_bytes, filename)
        check_body_size(body)
        result = extract_with_model(client, body, validator)
        if result is not None:
            invoice, raw = result
            return model, invoice, raw
    raise ExtractionError(
        "No candidate model accepted this request. "
        "Check supports.pdf_input and supports.structured_output in the model list."
    )


def main() -> int:
    if len(sys.argv) != 2:
        print("Usage: python extract_invoice.py path/to/invoice.pdf", file=sys.stderr)
        return 2
    api_key = os.environ.get("DEVUP_API_KEY")
    if not api_key:
        print("Set DEVUP_API_KEY.", file=sys.stderr)
        return 1
    pdf_path = Path(sys.argv[1])
    client = OpenAI(api_key=api_key, base_url="https://api.devupai.com/v1", max_retries=0)
    validator = jsonschema.Draft202012Validator(INVOICE_SCHEMA)
    try:
        pdf_bytes = read_pdf(pdf_path)
        check_pdf(pdf_bytes)
        candidates = pick_candidates(client.models.list())
        if not candidates:
            raise ExtractionError("No model in the catalog takes PDF input with structured output at the moment.")
        model, invoice, _raw = extract_invoice(client, pdf_bytes, pdf_path.name, candidates, validator)
    except (ExtractionError, openai.APIConnectionError) as e:
        print(e, file=sys.stderr)
        return 1
    except openai.APIStatusError as e:
        body = e.body if isinstance(e.body, dict) else {}
        message = body.get("message") or e.message
        request_id = e.response.headers.get("x-request-id") or "none"
        print(f"HTTP {e.status_code} {e.code or 'no code'}: {message} (x-request-id {request_id})", file=sys.stderr)
        return 1
    print(f"Model: {model}", file=sys.stderr)
    print(json.dumps(invoice, indent=2, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    sys.exit(main())

Run it with the path of your PDF:

export DEVUP_API_KEY=sk-devup-your-api-key
python extract_invoice.py path/to/invoice.pdf

The program prints the chosen model ID on stderr (Model: <model ID>) and the invoice on stdout. Every value below is a placeholder:

Output shape
{
  "vendor": "<vendor>",
  "invoice_number": "<invoice_number>",
  "issue_date": "<issue_date>",
  "currency": "<currency>",
  "line_items": [
    {
      "description": "<description>",
      "quantity": <quantity>,
      "unit_price": <unit_price>
    }
  ],
  "total": <total>
}

quantity, unit_price and total are numbers. The other fields are strings, as written in the document.

How it works

1Pick a model at run time

The program keeps the models whose type is text-generation, whose is_replaced is not true, and whose supports.pdf_input and supports.structured_output are both true. It keeps the catalog order and tries the candidates one after another. The capability values can change when models are added or updated, so they are read on every run. In Node.js, client.models.list() resolves to the whole list at once, and the program reads its data array. Pick the right model at runtime shows the full selection.

def pick_candidates(models) -> list[str]:
    """IDs of the models that take a PDF and a strict json_schema, in catalog order."""
    candidates = []
    for model in models:
        supports = getattr(model, "supports", None) or {}
        if (
            getattr(model, "type", None) == "text-generation"
            and getattr(model, "is_replaced", None) is not True
            and supports.get("pdf_input") is True
            and supports.get("structured_output") is True
        ):
            candidates.append(model.id)
    return candidates

2Define a strict schema

Every property is listed in required, and every object sets additionalProperties: false, the form a schema sent with strict: true takes. The same object is sent to the model and used for local validation, so the two cannot drift apart.

INVOICE_SCHEMA = {
    "type": "object",
    "properties": {
        "vendor": {"type": "string"},
        "invoice_number": {"type": "string"},
        "issue_date": {"type": "string"},
        "currency": {"type": "string"},
        "line_items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string"},
                    "quantity": {"type": "number"},
                    "unit_price": {"type": "number"},
                },
                "required": ["description", "quantity", "unit_price"],
                "additionalProperties": False,
            },
        },
        "total": {"type": "number"},
    },
    "required": ["vendor", "invoice_number", "issue_date", "currency", "line_items", "total"],
    "additionalProperties": False,
}

3Send the PDF as a data URL

One user message carries a text part with the instruction and a file part with the PDF. The file_data value starts with exactly data:application/pdf;base64,. The request is not streamed, so the whole reply can be parsed at once.

    file_data = "data:application/pdf;base64," + base64.b64encode(pdf_bytes).decode("ascii")
    return {
        "model": model,
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": INSTRUCTION},
                    {"type": "file", "file": {"filename": filename, "file_data": file_data}},
                ],
            }
        ],
        "response_format": {
            "type": "json_schema",
            "json_schema": {"name": "invoice", "strict": True, "schema": INVOICE_SCHEMA},
        },
    }

4Check the file and the size before sending

Every PDF starts with the bytes %PDF-. Checking them first gives a clear message for a file of another type.

    if not pdf_bytes.startswith(PDF_MAGIC):
        raise ExtractionError("The file is not a PDF: it does not start with %PDF-.")

The request body can be up to 10,485,760 bytes (10 MiB), and the Base64 file data counts toward it. Base64 adds about one third to the size of the file. The program measures the serialized request and stops before sending one that is over the limit.

    size = len(json.dumps(body, separators=(",", ":")).encode("utf-8"))
    if size > MAX_BODY_BYTES:

5Validate every reply locally

Validating the parsed reply against the schema before using it is good practice. A reply that is not JSON, or does not match, counts as invalid. The Python program uses jsonschema and the Node.js program uses ajv, both with the same INVOICE_SCHEMA.

def parse_invoice(content, validator) -> dict | None:
    """The reply as a dict when it is JSON that matches the schema, else None."""
    if not isinstance(content, str):
        return None
    try:
        data = json.loads(content)
    except json.JSONDecodeError:
        return None  # not JSON: the caller retries or raises
    return data if validator.is_valid(data) else None

6Retry once, then move on

Each model gets two attempts. A structured_output_mismatch or a reply that does not pass local validation is retried once with the same model, and the program stops with advice after the second one. A response_format_not_supported, unsupported_content, use_responses_api or wrong_endpoint from a model sends the request to the next candidate, whatever the HTTP status. Any other error is raised to the caller.

A model removed from the catalog between the listing and the call returns 404 model_not_found, and the program stops with that error. Run it again to read a fresh model list.

        except openai.APIStatusError as e:
            if e.code in NEXT_CANDIDATE_CODES:
                return None
            if e.code == "structured_output_mismatch" and not last:
                continue

The program handles only the codes above. In Node.js, the SDK keeps its own retries at their default: the SDK retries 408, 429, 502, 503 and 504 responses up to twice, waiting what the response asks for within the client timeout; it never retries 409 or 500. The client sets an explicit timeout of five minutes. In Python, max_retries=0 turns off the client's automatic retries, which would also repeat a 409, so the client sends each request once; the retry after a structured_output_mismatch and the move to the next candidate are the program's own. For a full retry policy, see Handle every API error in production.

client = OpenAI(api_key=api_key, base_url="https://api.devupai.com/v1", max_retries=0)

In production

  • Validate every result locally against the schema you sent, as the program does, before you store or use it.
  • Keep each request under 10 MiB. Split large documents by page range on your side and send each part in its own request.
  • Log the x-request-id of every request that returns an error. Every response carries it.
  • Store the raw model output next to the parsed JSON. extract_invoice and extractInvoice return it as raw, so you can check a result again later.
  • Add a full retry policy for rate limits, timeouts and server errors. See Production error handling.

Errors this recipe handles

CodeStatusWhat the program does
unsupported_content400Checks for %PDF- and sends the file as a data URL that starts with data:application/pdf;base64,, only to models whose supports.pdf_input is true. When a model returns this code, it moves on to the next candidate.
payload_too_large413Measures the serialized request before sending. Over 10 MiB, it stops and asks you to split the PDF into smaller page ranges or compress it.
structured_output_mismatch400Retries once with the same model, then stops with the x-request-id and the advice to simplify the schema.
response_format_not_supported400Moves on to the next candidate.
use_responses_api400Moves on to the next candidate.
wrong_endpoint400Moves on to the next candidate.

Next steps