| --- |
| title: PaperHawk |
| emoji: 🦅 |
| colorFrom: red |
| colorTo: yellow |
| sdk: docker |
| pinned: false |
| license: mit |
| short_description: Real-DI-Audit/14 rules/6 anti-halluc/LangGraph/Qwen/MI300X |
| --- |
| |
| <p align="center"> |
| <img src="https://raw.githubusercontent.com/nandorfivince/paperhawk/main/paperhawk.jpeg" alt="PaperHawk" width="900"> |
| </p> |
|
|
| <h1 align="center">PaperHawk</h1> |
|
|
| <p align="center"> |
| <strong>Agentic document intelligence on AMD MI300X</strong><br> |
| Multi-document due diligence with deterministic compliance rules and a 6-layer anti-hallucination stack. |
| </p> |
|
|
| <p align="center"> |
| <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"> |
| <img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python"> |
| <img src="https://img.shields.io/badge/LangGraph-0.6-green.svg" alt="LangGraph"> |
| <img src="https://img.shields.io/badge/AMD-MI300X-red.svg" alt="AMD MI300X"> |
| <img src="https://img.shields.io/badge/Qwen-2.5%2014B-purple.svg" alt="Qwen 2.5 14B"> |
| </p> |
|
|
| <p align="center"> |
| Built for the <strong>AMD Developer Hackathon × lablab.ai</strong> (May 2026). |
| </p> |
|
|
| --- |
|
|
| ## What is PaperHawk? |
|
|
| PaperHawk is an **agentic multi-document intelligence platform** for auditors, lawyers, tax advisors, and DD analysts. It processes 3–50 PDFs simultaneously and detects **cross-document red flags humans miss** — like a 57.5% price drift across three invoices from the same supplier — using a multi-agent LangGraph orchestration on top of Qwen 2.5 14B Instruct served via vLLM on AMD Instinct MI300X. |
|
|
| It is **not** a chatbot. It is a typed-state, multi-graph reasoning system with deterministic compliance rules, verbatim source citations, and a quote validator that catches LLM hallucinations before they reach the user. |
|
|
| ## Why it matters |
|
|
| A senior auditor needs ~8 hours to thoroughly review a 50-page invoice/contract package. ChatGPT, Copilot, and Harvey handle one document at a time, hallucinate citations, and lack jurisdiction-specific compliance knowledge. PaperHawk handles the entire package, applies 14 statutory rules hand-coded in Python, and finishes a 3-document audit in **23.3 seconds** (61.7× faster than manual review) — with auditor-grade citations and ISA/GDPR/HU-VAT mappings. |
|
|
| --- |
|
|
| ## Technical highlights |
|
|
| - **Multi-agent LangGraph 0.6 orchestration** — 4 compiled graphs (pipeline, chat, DD, package_insights) + 6 reusable subgraphs with Send-API parallelism |
| - **5-tool agentic chat** with strict `[Source: filename.pdf]` citations validated by a post-processor (no provenance → no answer) |
| - **6-layer anti-hallucination stack** — `temperature=0`, verbatim source quotes, field-level confidence, plausibility validators, 3-stage LLM-risk filter chain, quote validator |
| - **Provider abstraction** with `configurable_alternatives` — vLLM (production) / Ollama (local dev) / dummy (CI) — swap with one env var, zero code changes |
| - **AMD Instinct MI300X via vLLM** — 192 GB HBM3, 27.6 GB model + 141 GB available KV cache, 307 t/s prompt + 252 t/s generation, 30.4% prefix cache hit rate |
| - **61.7× speedup** vs manual audit on a 3-document package (23.3 sec vs ~24 min) |
| - **Hugging Face Space deployable** with Docker SDK + Git LFS for binary assets |
|
|
| ## Domain highlights |
|
|
| - **14 deterministic statutory rules** hand-coded in Python (NOT prompt-engineered) — ISA 240/320/500 audit standards, HU VAT Act §169 mandatory invoice elements, Ptk. 6:98 disproportionate penalty clauses, Art. 22 tax-ID validation, GDPR Article 28 sub-processor language, Incoterms 2020, AML sanctions list (EU/OFAC fuzzy match) |
| - **Cross-document red flag detection** — three-way matching (invoice + delivery note + PO), package-level pricing anomalies, duplicate-invoice detection (ISA 240), change-of-control trigger detection (M&A DD) |
| - **Multi-agent DD assistant** — 4 specialists (audit / legal / compliance / financial) coordinated by a supervisor and a synthesizer for executive summaries |
| - **Auditor-grade citations** — every finding maps to a regulation source (HU VAT Act §169, ISA 500, GDPR Art. 28, etc.) with verbatim source quote |
| - **Multilingual ingest** — EN / HU / DE OCR via Tesseract, native PDF + DOCX, vision-first scanned-PDF fallback |
|
|
| --- |
|
|
| ## Try the live demo |
|
|
| **Public Hugging Face Space** (no signup, runs in browser): |
|
|
| → <https://huggingface.co/spaces/Vincsipe/paperhawk> |
|
|
| Click **Audit Demo** in the Quick demo section. Three pre-bundled invoices process in ~25 seconds and you'll see the cross-doc 57.5% price drift flag, the 14 deterministic checks, and the auditor-grade citations. |
|
|
| Backed by an AMD MI300X vLLM endpoint serving Qwen 2.5 14B Instruct. |
|
|
| --- |
|
|
| ## Run it locally |
|
|
| Two options depending on whether you have a GPU or just want a quick smoke test. |
|
|
| ### Quick demo (~3 minutes, no GPU needed) |
|
|
| Uses the **deterministic dummy provider** — runs the full pipeline, all 14 domain checks, and the multi-agent orchestration without any LLM calls. Good for verifying the system runs end-to-end. |
|
|
| ```bash |
| git clone https://github.com/nandorfivince/paperhawk |
| cd paperhawk |
| make install |
| LLM_PROFILE=dummy make dev |
| ``` |
|
|
| Open <http://localhost:8501> → **Audit Demo** button. Result in ~5 seconds (dummy provider returns deterministic test data). |
|
|
| ### Full demo (~10 minutes, ~16 GB VRAM recommended) |
|
|
| Uses **Ollama with Qwen 2.5 14B Instruct** (the same model we deployed to AMD MI300X via vLLM). On a consumer GPU like NVIDIA RTX 4090 / RTX PRO 4500 (32 GB VRAM) you'll see real, production-grade multi-agent reasoning. |
|
|
| ```bash |
| git clone https://github.com/nandorfivince/paperhawk |
| cd paperhawk |
| make install |
| |
| # Pull the model (one-time, ~9 GB download) |
| ollama pull qwen2.5:14b-instruct |
| |
| # Run the app pointed at Ollama |
| LLM_PROFILE=ollama OLLAMA_MODEL=qwen2.5:14b-instruct \ |
| streamlit run app/main.py --server.port=8501 --server.fileWatcherType=none |
| ``` |
|
|
| Open <http://localhost:8501> → **Audit Demo** button. |
|
|
| **Expected results on an RTX PRO 4500 (32 GB GDDR7)**: |
|
|
| - Audit Demo: ~80 seconds for 3 invoices, 17.5× speedup vs manual |
| - 8 risk findings (2 HIGH, 4 MEDIUM, 2 LOW), HU VAT Act §169 mappings |
| - Cross-doc package-level analyzer flags the 57.5% price-drift red flag |
| - Quote validator catches 4 of 6 hallucinated citations and downgrades them to `low` confidence |
|
|
| (On AMD MI300X via vLLM: ~23 seconds, 61.7× speedup. 5× faster than Ollama on consumer GPU.) |
|
|
| ### Docker compose (alternative) |
|
|
| ```bash |
| make run-local |
| ``` |
|
|
| Spins up the Streamlit app + Ollama in containers. First run pulls the model (~9 GB). |
|
|
| --- |
|
|
| ## Documentation |
|
|
| | Document | What it covers | |
| |---|---| |
| | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | LangGraph multi-graph design, 14 domain checks, anti-hallucination stack, multi-agent DD | |
| | [`docs/AMD_DEPLOYMENT.md`](docs/AMD_DEPLOYMENT.md) | How we deployed Qwen 2.5 14B via vLLM on AMD Instinct MI300X (DigitalOcean-powered AMD Developer Cloud) | |
| | [`docs/HUGGINGFACE_DEPLOYMENT.md`](docs/HUGGINGFACE_DEPLOYMENT.md) | How we deployed the Streamlit app as a public Hugging Face Space | |
|
|
| For the full submission brief with TAM/SAM, competitor analysis, and the live deployment validation results, see [`docs/SUBMISSION.md`](docs/SUBMISSION.md). |
|
|
| --- |
|
|
| ## License |
|
|
| MIT — see [`LICENSE`](LICENSE). Use, fork, deploy commercially or non-commercially. |
|
|
| ## Built by |
|
|
| **Team csimpicsirkek** (`PÁKÁK the AI warriors!` on the lablab.ai platform): |
|
|
| - Vince Nándorfi — lead, LangGraph architecture, AMD adaptation |
| - Erika Nagy — silent partner |
| - Tamás Vitai |
| - Gábor Murcsik |
|
|
| For the AMD Developer Hackathon × lablab.ai, May 2026. |
|
|
