landrecords-card-reader 0.3.0

Extract structured property data from assessment card PDFs using LLM-powered text extraction

landrecords-card-reader

Extract structured property data from assessment card PDFs using LLM-powered text extraction.

Property cards (also called land cards or assessment cards) are PDF documents produced by county tax assessors.

Installation

pip install landrecords-card-reader

With optional extras:

# Tesseract OCR for image-encoded text regions
pip install landrecords-card-reader[ocr]

# Everything
pip install landrecords-card-reader[all]

System dependencies

• Ollama running locally or on a remote host with a text model loaded (e.g. gemma4:26b-a4b-it-q8_0)
• Tesseract (optional, for the [ocr] extra):

  sudo apt-get install tesseract-ocr
  

Quick start

from landrecords_card_reader import read_property_card

data, photo = read_property_card("https://example.com/card.pdf")

print(data["ownername"])    # "SMITH, JOHN A"
print(data["totalvalue"])   # 285000
print(data["parceladdr"])   # "123 MAIN ST"

# photo is raw image bytes of the first property photo, or None
if photo:
    with open("photo.jpg", "wb") as f:
        f.write(photo)

Use analyze_photo=True to send the property photo (if it exists) to the vision model, filling in missing building details (exterior walls, roof style, number of floors, etc.):

data, photo = read_property_card(url, analyze_photo=True)

If you already have the PDF bytes, pass them directly to skip the download:

data, photo = read_property_card(url, pdf_bytes=raw_bytes)

For URLs that might be HTML property report pages (e.g. Beacon, Tyler, or other county assessment sites), use read_property_card_from_url. It fetches the URL, detects whether the response is a PDF or HTML, and converts HTML pages to PDF via pdfkit (wkhtmltopdf) automatically:

from landrecords_card_reader import read_property_card_from_url

data, photo = read_property_card_from_url(
    "https://www.webgis.net/LinkedFiles/va/pulaski/pc/cards/PC17759.htm"
)

CLI

landrecords-card-reader https://example.com/card.pdf --dry-run -v

Configuration

Set via environment variables or a .env file:

Variable	Default	Description
CARD_READER_OLLAMA_HOST	http://localhost:11434	Ollama server URL
CARD_READER_EXTRACTION_MODEL	gemma4:26b-a4b-it-q8_0	Model for structured extraction
CARD_READER_PHOTO_CLASSIFICATION_MODEL	gemma4:e2b	Lightweight vision model for photo classification

Extracted fields

The extraction prompt maps over 80 property card fields including:

• Identity: parcelid, taxacctnum, taxyear
• Owner: ownername, owneraddr, ownercity, ownerstate, ownerzip
• Location: parceladdr, parcelcity, parcelstate, parcelzip, legaldesc
• Valuation: landvalue, imprvalue, totalvalue, assessedvalue, appraisedvalue
• Building: yearbuilt, bldgsqft, bedrooms, fullbaths, halfbaths, bldgtype
• Construction: foundation, roofcover, extwall, heating, heatfuel, cooling
• Sale: saleamt, saledate
• Zoning: zoningcode, zoningdesc, zoningtype

How it works

1. Download the PDF (or accept pre-downloaded bytes)
2. In parallel:
   • OCR every page via Tesseract — each page is rendered at 300 DPI (configurable via CARD_READER_OCR_DPI) and OCR'd as a single bitmap; pages run in parallel via a thread pool
   • Extract & classify property photos — candidate images are filtered by size/aspect ratio, then sent to a vision model to keep only actual photographs (discarding sketches, floorplans, maps, etc.)
3. Extract structured data by sending the raw OCR text to an Ollama LLM
4. Reconcile values — verifies landvalue + imprvalue == totalvalue and computes any single missing value arithmetically
5. Targeted retries — if parcelid is too short, re-asks; if a heat-fuel label is present but heatfuel is empty, runs a deterministic regex fallback then a focused LLM retry; if any registered field's label is in the OCR text but the value is empty, batches them into one LLM retry

License

MIT