Chapter 20 · Hands-on: more projects
Pull structured data out of documents
Ask a model for answers in a fixed format (like JSON) to turn messy text into tidy fields you can use.
Chapter 20 · Hands-on: more projects
Ask a model for answers in a fixed format (like JSON) to turn messy text into tidy fields you can use.
The model reads the text and fills one labelled field at a time…
A short script that reads a messy text file, asks your local model to fill in a fixed set of fields, checks the answer’s shape and shows you tidy JSON.
As in the structured output lesson, a model can answer in a fixed format such as JSON. Here you use that to turn messy text, such as an invoice, into fields a program can sort, add up or save to a spreadsheet.
You need a local model running (see Run an open model on your computer), the project setup from Call your local model from code, and Python with a virtual environment. Windows, macOS and Linux desktops work. The text stays on your computer.
requests talks to your local model. pydantic describes the shape of the data you expect and checks answers against it. Activate the virtual environment first, as in the Python lesson.
mkdir extract-data
cd extract-data
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install requests pydantic Check: Your prompt starts with (.venv), and your model runner is running with a small model downloaded.
Create a plain text file called invoice.txt in the folder and paste in this made-up invoice. Later you can use your own text.
Sunrise Stationers
Invoice no: SS-2041
Date: 12 March 2025
2 x Notebook (A5) Rs 120.00
10 x Blue pen Rs 150.00
1 x Desk lamp Rs 899.00
Total due: Rs 1,169.00
Thank you for your business! Check: The file is saved as invoice.txt in extract-data.
In the next step’s script you will see two small classes, Item and Invoice. Each line is a field name and its type: str is text, int a whole number, float a number with decimals, and list[Item] a list of items. This class does two jobs: it tells the runner the exact shape to answer in, and it checks the reply afterwards. Use the field helper below to practise writing your own.
Check: You can say what total: float means.
Create extract.py and paste this in. It sends your text to the model with the shape attached (format), turns the answer into an Invoice object, and if the answer does not fit, tells the model what was wrong and asks once more. Finally it adds up the items and compares them with the total.
import sys
from pathlib import Path
import requests
from pydantic import BaseModel, ValidationError
MODEL_NAME = "llama3.2" # any small model your runner lists
URL = "http://localhost:11434/api/chat"
class Item(BaseModel):
description: str
quantity: int
amount: float # the line total for that item
class Invoice(BaseModel):
vendor: str
invoice_number: str
date: str
total: float
items: list[Item]
def ask_model(messages):
reply = requests.post(
URL,
json={
"model": MODEL_NAME,
"messages": messages,
"stream": False,
"format": Invoice.model_json_schema(), # asks the runner to answer in this shape
"options": {"temperature": 0}, # 0 = as steady as possible
},
timeout=300,
)
reply.raise_for_status()
return reply.json()["message"]["content"]
def extract(text):
messages = [{
"role": "user",
"content": "Extract the invoice fields from the text below. Use only what the text says. "
"Write amounts as plain numbers without currency symbols.\n\n" + text,
}]
answer = ask_model(messages)
for attempt in range(2):
try:
return Invoice.model_validate_json(answer)
except ValidationError as problem:
if attempt == 1:
raise
messages += [
{"role": "assistant", "content": answer},
{"role": "user", "content": f"That did not match the format. Fix it. Problems:\n{problem}"},
]
answer = ask_model(messages)
def main():
if len(sys.argv) < 2:
sys.exit("Give a text file, for example: python extract.py invoice.txt")
text = Path(sys.argv[1]).read_text(encoding="utf-8")
invoice = extract(text)
print(invoice.model_dump_json(indent=2))
added_up = round(sum(item.amount for item in invoice.items), 2)
if abs(added_up - invoice.total) > 0.01:
print(f"\nWARNING: the items add up to {added_up} but the total says {invoice.total}. Check by hand.")
else:
print("\nCheck passed: the items add up to the total.")
if __name__ == "__main__":
main() Check: The file is saved as extract.py next to invoice.txt.
Give the script your text file. A small model on a CPU may take a little while.
python extract.py invoice.txt Check: You see neat JSON with vendor, invoice_number, date, total and a list of items, then Check passed: the items add up to the total.
Edit invoice.txt: change one item price so the items no longer add up to the total, then run again. The warning shows why a cheap check on your own data is valuable. Then try a messier text: a forwarded email, notes typed in a hurry, text copied from a PDF as in Turn PDFs into searchable chunks.
Check: You see the WARNING line when numbers disagree.
If a field may be missing, a model under pressure may invent a value. Make it optional so the honest answer is allowed: write due_date: str | None = None and add “If a field is not in the text, use null” to the instruction. Then missing information shows up as null instead of a guess.
Check: A document without a due date gives null for it rather than a made-up date.
Edit the field list and see the Python class. Then paste a model answer and see whether it fits. This runs only in your browser and does not call a model.
from pydantic import BaseModel
class Record(BaseModel):
vendor: str
invoice_number: str
total: floatThis is a simplified browser check of the same idea the script uses; nothing is sent anywhere. In the script, the retry step sends problems like these back to the model.
What do you see?
What does the Pydantic class do in this tutorial?
The answer has the right shape but the items do not add up to the total. What does that tell you?
Why make a field optional when the document may not contain it?