README.md

---
title: Document Intelligence - OCR Data Extractor
emoji: 📄
colorFrom: blue
colorTo: gray
sdk: gradio
sdk_version: 6.19.0
app_file: app.py
pinned: false
license: mit
---

# Turn Documents Into Structured Business Data

The real value isn't converting images into text — it's turning
unstructured documents into reliable, actionable data. This tool takes
scanned PDFs or images, runs them through OCR, and uses an AI-assisted
extraction step (configured by describing what you need in plain
language) to produce clean, audit-ready structured data. Built for:

- **Construction / SAP data support** — change orders, delay notices,
  punch list items, RFIs, PO numbers, SAP document numbers, quantities.
- **Compliance** — non-conformances, violations, expirations, corrective
  actions, certification codes (ISO, OSHA, ASTM, ANSI).
- **Business finance** — past-due invoices, payment rejections, credit
  holds, invoice numbers, dollar amounts, due dates.

## Notifications vs. fields

The tool treats two kinds of requests differently, rather than running
one blanket extraction pass over every document:

- **Notifications** — keyword/phrase hits that flag an event (a boolean
  "this happened on this page"), e.g. "past due", "non-compliant",
  "change order". Each category (construction/compliance/finance/general)
  has its own built-in phrase list; you can add your own custom
  notification keywords too.
- **Fields** — labeled values extracted as data, not just flagged.
  Standard fields are *scoped to the categories you select* (see
  `CATEGORY_FIELD_MAP` in `extractors.py`) so a compliance document
  doesn't generate empty invoice-number columns: construction gets PO/SAP
  numbers, compliance gets certification codes, finance gets invoice
  numbers/percentages, and dates/amounts apply where relevant. On top of
  that, you can name your own **custom fields** — any label that appears
  in the document followed by a value (e.g. "reference number", "gross
  weight", "delivery date") — and the app finds the label and captures
  what follows it.

## How it works

The app is a single guided flow: describe what you need, upload your
documents, run and review.

1. **Step 1 - describe what you need** — in plain language (e.g. *"flag
   overdue invoices over $10k and non-compliance notices, and pull the
   reference number and gross weight"*), or tap one of the
   construction/compliance/finance starting-point buttons. A Hugging
   Face-hosted chat model turns that into extraction settings
   (categories, notification keywords, custom fields, export filter),
   shown live in the "Extraction plan" panel. You can also skip the chat
   and set everything by hand in the "Advanced" accordion in Step 2.
2. **Step 2 - upload your documents** — one or more PDFs or images.
3. Each page's text is pulled directly from the PDF when it has a text
   layer; scanned/image-only pages are rendered and run through
   Tesseract OCR.
4. The text is scanned for notification keywords and both standard and
   custom fields, per the scoping above.
5. Results are shown as two tidy (one-fact-per-row) tables — extracted
   fields and notification hits — and exported as three CSVs:
   - `ocr_fields_*.csv` — file, page, field_type (standard/custom),
     field_name, field_value, OCR source/confidence.
   - `ocr_notifications_*.csv` — file, page, category, keyword, context,
     OCR source/confidence.
   - `ocr_run_metadata_*.csv` — an audit record of exactly what produced
     the run: categories, notification keywords, custom fields, the
     match filter, the chat model used, and the full chat transcript.
     This is the lineage trail for anyone auditing why a given row was
     (or wasn't) extracted.

   Long/tidy tables were chosen over one wide fixed-schema table so that
   irrelevant fields never show up as blank columns, and so the output
   loads cleanly into a database, pivot table, or BI tool without
   reshaping — consistent with standard data-quality practice (e.g. DAMA
   DMBOK's completeness, validity, and lineage dimensions).

## Chat assistant setup

The Step 1 assistant calls the Hugging Face Inference API, so it needs a token:

- **On a Space:** add a repo secret named `HF_TOKEN` (Settings ->
  Variables and secrets) with a token that has Inference API access.
- **Locally / as a fallback:** paste a token into the "Use your own
  Hugging Face token" accordion in Step 1; it's only used for that session.

The token needs **Inference Providers** permission: use the simple
"Read" token type, or on a fine-grained token check "Make calls to
Inference Providers".

The assistant tries `Qwen/Qwen2.5-7B-Instruct` first, then falls back to
`mistralai/Mistral-7B-Instruct-v0.3` and `Qwen/Qwen2.5-72B-Instruct` if
a provider doesn't carry it. Set an `HF_CHAT_MODEL` env var/Space
variable to force a specific model instead.

If the chat call fails or no token is available, the rest of the app
still works fully via the "Advanced: edit settings manually" accordion
in Step 2 — the chat is a convenience layer on top, not a dependency.

## Sample documents

Three fictitious, clearly watermarked demo PDFs are generated on first
launch (by `sample_docs/generate_samples.py` — they aren't committed,
since the Hub requires LFS for binaries) and are loadable with one click
from Step 2 (each button also presets the matching extraction settings,
so Run works immediately):

- **Construction change order** — PO/SAP numbers, cost overrun amounts,
  a safety-violation field note, OSHA cert reference (native text layer).
- **Accounting / tax invoice** — invoice number, line items, tax rate,
  past-due/credit-hold language (native text layer).
- **Bill of lading** — saved as an image-only "scanned" page, so it
  exercises the full Tesseract OCR path with confidence scores; custom
  fields pull BOL/reference numbers, weights, and delivery date.

Every sample carries a "FICTITIOUS DATA - NOT REAL DATA" banner,
watermark, and footer. Regenerate them manually with
`python sample_docs/generate_samples.py`.

## Local development

```bash
pip install -r requirements.txt
# Tesseract must also be installed on the system, e.g.:
#   apt-get install tesseract-ocr
export HF_TOKEN=hf_...   # optional, enables the chat tab
python app.py
```

## Files

- `app.py` — Gradio UI and orchestration.
- `ocr_engine.py` — PDF/image loading and OCR (PyMuPDF + Tesseract).
- `extractors.py` — keyword notification scanning, category-scoped
  standard field extraction, and generic label->value custom field
  extraction.
- `chat_config.py` — chat assistant that turns natural-language
  instructions into extraction settings via a Hugging Face chat model.