Spaces:
Build error
Build error
| title: PageParse | |
| emoji: 📄 | |
| colorFrom: blue | |
| colorTo: green | |
| sdk: docker | |
| app_port: 7860 | |
| <!-- | |
| SPDX-FileCopyrightText: 2026 Team Centurions | |
| SPDX-License-Identifier: AGPL-3.0-or-later | |
| --> | |
| # PageParse | |
| **Any handwritten page → clean structured data. On CPU. Fully offline.** | |
| PageParse reads a scanned or photographed page of handwritten notes entirely on | |
| your own device and turns it into structured, schema-validated records in a local | |
| database — no GPU, no CUDA, no cloud. Point it at a handwritten page; it cleans the | |
| image, recognises the ink on CPU, maps the messy text to a defined JSON schema, and | |
| saves it to SQLite. It keeps working with the Wi-Fi switched off. | |
| > Built for **The CPU-First Hackathon** — _"Build AI that runs anywhere."_ | |
| <p> | |
| <img alt="CPU-first" src="https://img.shields.io/badge/inference-CPU--only-blue"> | |
| <img alt="Offline" src="https://img.shields.io/badge/network-offline--first-green"> | |
| <img alt="License" src="https://img.shields.io/badge/license-AGPL--3.0-orange"> | |
| <img alt="Python" src="https://img.shields.io/badge/python-3.11-yellow"> | |
| </p> | |
| --- | |
| ## Table of Contents | |
| - [The Idea](#the-idea) | |
| - [Why It Matters](#why-it-matters) | |
| - [How It Works](#how-it-works) | |
| - [Architecture](#architecture) | |
| - [Model & Runtime (CPU-first)](#model--runtime-cpu-first) | |
| - [Output Schema](#output-schema) | |
| - [Data Model (SQLite)](#data-model-sqlite) | |
| - [Tech Stack](#tech-stack) | |
| - [Project Structure](#project-structure) | |
| - [Getting Started](#getting-started) | |
| - [Usage](#usage) | |
| - [Offline-First by Design](#offline-first-by-design) | |
| - [Quality Gates (CI/CD)](#quality-gates-cicd) | |
| - [Judging Criteria Mapping](#judging-criteria-mapping) | |
| - [Roadmap](#roadmap) | |
| - [Team & Work Division](#team--work-division) | |
| - [Contributing](#contributing) | |
| - [License](#license) | |
| --- | |
| ## The Idea | |
| People still write on paper — to-do lists, planners, field surveys, recipe cards, | |
| clinic notes. That ink almost never makes it into a system you can search, sort, | |
| or query. **PageParse bridges paper and database, entirely on-device.** | |
| Drop in a scan or photo of a handwritten page. PageParse: | |
| 1. **reads** the handwriting on CPU, | |
| 2. **maps** it to a defined, relational schema using a small local language model, and | |
| 3. **stores** clean structured rows in SQLite you can query and export — | |
| all while completely air-gapped. | |
| The reference build is anchored to one note type — a **handwritten to-do / planner | |
| page** — because the schema is tight and objectively measurable. The same engine | |
| generalises to survey forms, recipe cards, and meeting notes with only a new schema | |
| and grammar. | |
| --- | |
| ## Why It Matters | |
| GPUs are scarce, costly, and online. Most computing isn't. PageParse is a | |
| demonstration that **the CPU is enough**, and that a genuinely useful app keeps | |
| working when the network doesn't — in clinics, fields, classrooms, and anywhere | |
| connectivity is unreliable. | |
| It also tackles the hackathon's core mission head-on: handwriting is about as | |
| **unstructured** as input gets, and PageParse maps it to a strict, **structured** | |
| schema. Handwriting recognition is a hard, real problem — and that difficulty is | |
| exactly what makes the result worth scoring. | |
| --- | |
| ## How It Works | |
| PageParse follows the required **Ingestion → Processing → Transformation → Storage** | |
| workflow, with every inference step on CPU and offline. | |
| | Stage | What happens | Runs on | | |
| | ----- | ------------ | ------- | | |
| | **1. Ingestion** | Load a handwritten page (JPG / PNG / PDF). | local | | |
| | **2. Processing** | OpenCV cleanup: grayscale, deskew, adaptive threshold, denoise. | CPU | | |
| | **3. Recognition** | On-device OCR converts ink → raw text (handwriting tier + printed fallback). | CPU | | |
| | **4. Transformation** | A small language model maps raw text → JSON, grammar-constrained to the schema. | CPU | | |
| | **5. Storage** | Validated rows persisted to SQLite; optional local semantic search. | local | | |
| --- | |
| ## Architecture | |
| ``` | |
| ┌──────────────────────────────────────────────┐ | |
| │ PageParse │ | |
| │ (100% on-device, CPU) │ | |
| └──────────────────────────────────────────────┘ | |
| scan / photo OpenCV ONNX / Tesseract llama.cpp + GBNF SQLite | |
| JPG · PNG · PDF ┌──────────┐ ┌────────────────┐ ┌────────────────┐ ┌──────────┐ | |
| ───────────────▶│ Ingestion│──────▶│ Preprocessing │──▶│ OCR (on CPU) │──▶│ Transform│──▶│ Storage │ | |
| │ │ clean │ deskew·binarize│ │ TrOCR / Surya /│ │ SLM→JSON │ │ + vec │ | |
| └──────────┘ denoise└────────────────┘ │ Tesseract │ │ validated│ └──────────┘ | |
| └────────────────┘ └────────────────┘ | |
| │ | |
| ┌─────────▼─────────┐ | |
| │ query · search │ | |
| │ export · review │ | |
| └───────────────────┘ | |
| ``` | |
| --- | |
| ## Model & Runtime (CPU-first) | |
| Declared explicitly per the rules. **No GPU or CUDA anywhere in the inference path.** | |
| All weights are fetched once and cached locally, so runtime needs no network. | |
| | Stage | Model | Runtime | Precision | | |
| | ------------------- | --------------------------------------- | ---------------------- | --------- | | |
| | Handwriting OCR | TrOCR-small (handwritten) / Surya OCR 2 | ONNX Runtime (CPU EP) | INT8 | | |
| | Printed fallback | Tesseract LSTM | Tesseract (CPU) | — | | |
| | Text → schema (SLM) | Qwen2.5-1.5B-Instruct | llama.cpp | Q4_K_M | | |
| | Semantic search | all-MiniLM-L6-v2 | ONNX Runtime (CPU EP) | INT8 | | |
| Schema validity is **guaranteed** by **llama.cpp GBNF grammar-constrained | |
| decoding**: the model is structurally prevented from emitting anything that is not | |
| valid against the PageParse schema, then re-validated with Pydantic. | |
| --- | |
| ## Output Schema | |
| The structured target that unstructured handwriting is mapped to: | |
| ```json | |
| { | |
| "source_page": "string (filename)", | |
| "captured_date": "YYYY-MM-DD", | |
| "tasks": [ | |
| { | |
| "task": "string", | |
| "due_date": "YYYY-MM-DD | null", | |
| "priority": "high | medium | low", | |
| "category": "string | null", | |
| "status": "todo | done", | |
| "ocr_confidence": 0.0 | |
| } | |
| ] | |
| } | |
| ``` | |
| --- | |
| ## Data Model (SQLite) | |
| ```sql | |
| CREATE TABLE pages ( | |
| id INTEGER PRIMARY KEY, | |
| filename TEXT, | |
| captured_date TEXT, | |
| raw_ocr_text TEXT, | |
| created_at TEXT | |
| ); | |
| CREATE TABLE tasks ( | |
| id INTEGER PRIMARY KEY, | |
| page_id INTEGER REFERENCES pages(id), | |
| task TEXT NOT NULL, | |
| due_date TEXT, | |
| priority TEXT CHECK (priority IN ('high', 'medium', 'low')), | |
| category TEXT, | |
| status TEXT DEFAULT 'todo', | |
| ocr_confidence REAL | |
| ); | |
| ``` | |
| --- | |
| ## Tech Stack | |
| **Language & core** | |
| - Python 3.11 | |
| **Computer vision / OCR** | |
| - OpenCV — image preprocessing | |
| - ONNX Runtime (CPU EP) — TrOCR / Surya handwriting OCR | |
| - Tesseract — printed-text fallback | |
| **AI / structuring** | |
| - llama.cpp (`llama-cpp-python`) — Qwen2.5-1.5B Q4_K_M GGUF inference | |
| - GBNF grammar — guaranteed-valid JSON | |
| - Pydantic — schema validation | |
| **Storage & retrieval** | |
| - SQLite — structured persistence | |
| - sqlite-vec + all-MiniLM-L6-v2 (ONNX) — optional semantic search | |
| **Interface** | |
| - Typer — CLI (primary) | |
| - FastAPI + PWA — web interface | |
| **Observability** | |
| - psutil — live CPU & memory telemetry | |
| **Tooling & quality** | |
| - Ruff, mypy, Bandit, pip-audit, detect-secrets, pytest, gitlint, yamllint, | |
| markdownlint, REUSE | |
| - pre-commit, GitLab CI (self-hosted Docker runner) | |
| **License** | |
| - AGPL-3.0-or-later | |
| --- | |
| ## Project Structure | |
| ``` | |
| pageparse/ | |
| ├── src/ | |
| │ └── pageparse/ | |
| │ ├── __init__.py | |
| │ ├── ingest.py # load image / PDF input | |
| │ ├── preprocess.py # OpenCV cleanup pipeline | |
| │ ├── ocr/ | |
| │ │ ├── __init__.py | |
| │ │ ├── handwriting.py # TrOCR / Surya (ONNX) | |
| │ │ └── printed.py # Tesseract fallback | |
| │ ├── extract.py # SLM + GBNF → JSON | |
| │ ├── schema.py # Pydantic models | |
| │ ├── store.py # SQLite persistence | |
| │ ├── search.py # optional semantic search | |
| │ ├── telemetry.py # psutil CPU/RAM panel | |
| │ ├── config.py # paths, model settings, airgap flag | |
| │ ├── cli.py # Typer CLI entry point | |
| │ └── web.py # FastAPI + PWA | |
| ├── grammars/ | |
| │ └── task.gbnf # schema-constraining grammar | |
| ├── models/ # bundled GGUF / ONNX weights (gitignored) | |
| ├── scripts/ | |
| │ ├── fetch_models.py # one-time online model download | |
| │ └── init_db.py # initialise SQLite | |
| ├── samples/ # real handwritten demo pages | |
| ├── tests/ | |
| │ ├── test_preprocess.py | |
| │ ├── test_extract.py | |
| │ ├── test_schema.py | |
| │ └── test_store.py | |
| ├── web/ | |
| │ ├── static/ # PWA assets, service worker | |
| │ └── templates/ | |
| ├── docs/ | |
| │ └── architecture.md | |
| ├── .gitlab-ci.yml | |
| ├── .pre-commit-config.yaml | |
| ├── .gitignore | |
| ├── .secrets.baseline | |
| ├── pyproject.toml | |
| ├── CONTRIBUTING.md | |
| ├── CHANGELOG.md | |
| ├── LICENSE # AGPL-3.0 | |
| └── README.md | |
| ``` | |
| --- | |
| ## Getting Started | |
| ### Prerequisites | |
| - Python 3.11+ | |
| - Tesseract OCR — `apt install tesseract-ocr` / `brew install tesseract` | |
| - ~3 GB free disk for bundled models | |
| ### Installation | |
| ```bash | |
| # Clone | |
| git clone https://code.swecha.org/centurions/pageparse.git | |
| cd pageparse | |
| # Environment | |
| python -m venv .venv | |
| source .venv/bin/activate # Windows: .venv\Scripts\activate | |
| # Install (with dev tooling) | |
| pip install -e ".[dev]" | |
| # Fetch models ONCE while online — cached locally thereafter | |
| python scripts/fetch_models.py | |
| # Initialise the local database | |
| python scripts/init_db.py | |
| ``` | |
| After `fetch_models.py` runs once, **disconnect from the network entirely** — | |
| everything below works offline. | |
| --- | |
| ## Usage | |
| ### CLI | |
| ```bash | |
| # Process a single handwritten page | |
| pageparse process samples/todo_page_01.jpg | |
| # Process a whole folder | |
| pageparse process samples/ --batch | |
| # Force air-gapped mode (any outbound call fails loudly) | |
| pageparse process samples/todo_page_01.jpg --airgap | |
| # Query and search | |
| pageparse list --priority high | |
| pageparse search "supplier" | |
| # Export | |
| pageparse export --format json > out.json | |
| ``` | |
| ### Web (PWA) | |
| ```bash | |
| pageparse serve # http://localhost:8000 | |
| ``` | |
| Upload a page, watch the **queued → processing → saved** status, and view the | |
| structured result. Installable as a PWA for offline use. | |
| --- | |
| ## Offline-First by Design | |
| The core feature works with **no cloud calls**, and the demo proves it: | |
| - **Air-gap toggle** — a UI switch and `--airgap` flag assert zero network access; | |
| any accidental outbound call fails loudly rather than silently. | |
| - **Status badge** — every page shows `queued → processing → saved`, making caching | |
| and graceful handling observable. | |
| - **Graceful degradation** — low-confidence OCR lines are flagged for review | |
| instead of crashing; pages queue and process as the CPU frees up. | |
| - **Live resource panel** — a psutil readout of CPU % and RAM during inference, so | |
| the footprint is measured, not guessed. | |
| **Demo procedure:** enable airplane mode / pull the Ethernet, then run a full | |
| ingestion → extraction → storage cycle on a real handwritten page. | |
| --- | |
| ## Quality Gates (CI/CD) | |
| All checks run locally via **pre-commit** and in CI on a **self-hosted GitLab | |
| runner** (Docker executor). These are real checks — no stub jobs, no `exit 0`. | |
| | # | Check | Tool | | |
| | -- | ------------------- | ---------------- | | |
| | 1 | Lint | Ruff | | |
| | 2 | Format | Ruff format | | |
| | 3 | Type-check | mypy | | |
| | 4 | Security (SAST) | Bandit | | |
| | 5 | Dependency CVEs | pip-audit | | |
| | 6 | Secret scan | detect-secrets | | |
| | 7 | Unit tests | pytest | | |
| | 8 | Semantic commits | gitlint | | |
| | 9 | CI YAML lint | yamllint | | |
| | 10 | Docs lint | markdownlint | | |
| | 11 | License compliance | REUSE | | |
| | 12 | Smoke build | app boots headless | | |
| ```bash | |
| pre-commit run --all-files | |
| pytest | |
| ``` | |
| Conventional Commits are enforced (`feat:`, `fix:`, `chore:`, …). | |
| --- | |
| ## Judging Criteria Mapping | |
| | Criterion | How PageParse addresses it | | |
| | ---------------------- | ------------------------------------------------------------ | | |
| | **Model performance** | OCR confidence + extraction accuracy reported on real pages. | | |
| | **Resource efficiency**| Live psutil CPU/RAM panel during inference. | | |
| | **Offline resiliency** | Air-gap toggle; full cycle demoed with the network off. | | |
| | **Schema alignment** | GBNF grammar guarantees valid JSON every run. | | |
| | **Graceful handling** | Queued processing + flagged low-confidence lines + caching. | | |
| --- | |
| ## Roadmap | |
| - [ ] **MVP:** scanned to-do page → validated JSON → SQLite (offline, CPU) | |
| - [ ] Printed-text fallback path | |
| - [ ] Web PWA with air-gap toggle and status badge | |
| - [ ] Live CPU/RAM telemetry panel | |
| - [ ] Semantic search over extracted notes (`sqlite-vec`) | |
| - [ ] Additional note types: survey forms, recipe cards, meeting notes | |
| - [ ] Indic-script handwriting support | |
| --- | |
| ## Contributing | |
| See [CONTRIBUTING.md](CONTRIBUTING.md). Branch from `main`, keep commits | |
| Conventional, ensure `pre-commit run --all-files` and `pytest` pass, then open a | |
| merge request. All contributions are licensed under AGPL-3.0-or-later. | |
| --- | |
| ## License | |
| Licensed under the **GNU Affero General Public License v3.0 or later** | |
| (AGPL-3.0-or-later). See [LICENSE](LICENSE). | |
| AGPL is chosen deliberately: as strong copyleft, it closes the network/SaaS | |
| loophole that plain GPL leaves open, ensuring anyone who runs a modified PageParse | |
| as a network service must also share their source. |