| # CLAUDE.md — paperhawk |
|
|
| Project-level instructions for Claude Code working in this repository. Any |
| session that starts in this folder reads this file automatically. |
|
|
| **Last updated:** 2026-05-03 |
|
|
| --- |
|
|
| ## 1. Project overview |
|
|
| A LangGraph-native, multi-agent Document Intelligence platform built for the |
| **AMD Developer Hackathon × lablab.ai** (May 2026). MIT-licensed, English-only |
| codebase, designed to run on **AMD Instinct MI300X** GPUs via the vLLM runtime |
| serving **Qwen 2.5 Instruct** open-source models. |
|
|
| The system processes business document packages (invoices, contracts, delivery |
| notes, purchase orders, financial reports) end-to-end: |
|
|
| 1. **Ingest** — PDF / DOCX / image with vision-first scanned fallback |
| 2. **Classify** — 6-way doc-type classifier (LLM with structured output) |
| 3. **Extract** — typed Pydantic schema extraction with anti-hallucination |
| 4. **Cross-reference** — three-way matching (invoice + delivery + PO) |
| 5. **Risk analysis** — basic + 14 domain rules + LLM ensemble + 3 filters |
| 6. **Report** — DOCX export, JSON API, executive summary |
|
|
| The chat layer is a 5-tool agentic ReAct loop with explicit `[Source: filename]` |
| citations and an anti-hallucination validator. |
|
|
| --- |
|
|
| ## 2. Workflow rules |
|
|
| ### Language |
|
|
| - **English everywhere** — code, comments, docstrings, prompts, UI, error |
| messages, log lines. |
| - **Multilingual fallback** — for legacy interop and the multilingual demo: |
| some loaders, classifiers, and regex filters accept HU/DE input. EN is |
| always the primary path. |
| - Two HU reference documents are kept under `docs/` with `_HU.md` suffix |
| (`Teljes-rendszer-attekintes-langgraph_HU.md`, `MUKODESI_LEIRAS_HU.md`). |
| These are read-only references; do not edit. |
|
|
| ### License + IP |
|
|
| - **MIT licensed** — see `LICENSE`. |
| - `NOTICE.md` is a non-binding author request (no legal force). |
| - Never paste proprietary code from outside this repo. |
|
|
| ### Provider |
|
|
| - The default chat provider is `vllm` (Qwen 2.5 14B Instruct on AMD MI300X |
| through the OpenAI-compatible vLLM endpoint). |
| - `ollama` is a local dev fallback (Qwen 2.5 7B Instruct on a laptop GPU/CPU). |
| - `dummy` is the deterministic CI / eval / smoke provider (no network, no LLM). |
| - Never re-introduce a Claude / Anthropic provider here — that path is |
| out of scope for the AMD edition. |
|
|
| ### Git |
|
|
| - The AI **NEVER** runs git operations on `main` (no commit, no push, no |
| cherry-pick, no merge). The user runs all `main`-branch git operations. |
| - The AI MAY commit on non-`main` feature branches when explicitly asked. |
| - The AI **NEVER** pushes — push is the user's task only. |
|
|
| ### Build hygiene |
|
|
| - Do not commit `.env`, `chroma_db/`, `data/checkpoints.sqlite`, `__pycache__/`. |
| - Magyar / English commit messages are both fine; English preferred for the |
| public history of an MIT repo. |
|
|
| ### Anti-hallucination is sacred |
|
|
| - The 5+1 layers (`temperature=0`, `_quotes`, `_confidence`, plausibility |
| filters, LLM-risk 3 filters, quote validator) are not optional. Every |
| LLM-generated piece of data is cross-checked. |
| - Source citations in the chat use the canonical `[Source: filename]` format |
| (validator enforces this). |
|
|
| --- |
|
|
| ## 3. Repo layout |
|
|
| ``` |
| paperhawk/ |
| ├── app/ # Streamlit UI (5 tabs) + async runtime |
| ├── config.py # Pydantic Settings (env-bound) |
| ├── domain_checks/ # 14 deterministic rules + base + registry |
| ├── eval/ # Eval harness (questions + run_eval) |
| ├── graph/ # 4 compiled graphs (pipeline / chat / dd / |
| │ # package_insights) + 6 states + checkpointer |
| ├── ingest/ # PDF / DOCX / image / OCR / tables / txt |
| ├── infra/vllm/ # AMD MI300X deployment (Dockerfile + serve.sh + README) |
| ├── load/ # Load benchmarks |
| ├── nodes/ # Per-stage node functions: |
| │ ├── chat/ # chat agent + 5 tools |
| │ ├── dd/ # DD specialists + supervisor + synthesizer |
| │ ├── extract/ # extract + dummy + quote validator |
| │ ├── ingest/ # ingest helpers |
| │ ├── pipeline/ # classify / compare / duplicate / report / docx |
| │ └── risk/ # basic / domain dispatch / LLM risk + 3 filters |
| ├── providers/ # vLLM / Ollama / Dummy LLM providers + embeddings |
| ├── schemas/ # 6 JSON schemas + pydantic_models + flatten_universal |
| ├── store/ # ChromaDB + BM25 hybrid + chunking |
| ├── subgraphs/ # 6 reusable subgraphs (Send API parallelism) |
| ├── tests/ # unit + integration + e2e_api + e2e_screenshot |
| ├── tools/ # 5 chat tools + ChatToolContext |
| ├── utils/ # dates + numbers + docx_export |
| └── validation/ # anti-halluc layers (5+1) |
| ``` |
|
|
| --- |
|
|
| ## 4. Hot files |
|
|
| When fixing bugs or adding features, these are the most-edited files: |
|
|
| - `graph/states/pipeline_state.py` — `Risk`, `Classification`, `ExtractedData`, |
| `merge_risks`, `merge_doc_results` reducers. |
| - `domain_checks/__init__.py` — the 14-check registry. |
| - `domain_checks/check_*_*.py` — individual deterministic rules. |
| - `nodes/risk/_prompts.py` — `RISK_SYSTEM_PROMPT` (anti-halluc 9+6+4 examples). |
| - `nodes/chat/_prompts.py` — `AGENTIC_SYSTEM_PROMPT` (17 rules). |
| - `validation/llm_risk_filters.py` — 3-filter chain. |
| - `app/main.py` — Streamlit UI (5 tabs). |
|
|
| --- |
|
|
| ## 5. Testing |
|
|
| ```bash |
| # Fast: unit + integration (dummy LLM) |
| LLM_PROFILE=dummy pytest tests/unit tests/integration -x --tb=short |
| |
| # Slow: end-to-end with real LLM |
| LLM_PROFILE=vllm pytest tests/e2e_api -m e2e -x --tb=short |
| |
| # UI Playwright (real LLM, slow) |
| LLM_PROFILE=vllm pytest tests/e2e_screenshot -x --tb=short |
| ``` |
|
|
| `LLM_PROFILE=dummy` works without any external service. `LLM_PROFILE=vllm` |
| requires `VLLM_BASE_URL` to point at a running vLLM endpoint. |
|
|
| --- |
|
|
| ## 6. Deploy targets |
|
|
| - **Hugging Face Space** — Streamlit Space under |
| `huggingface.co/spaces/lablab-ai-amd-developer-hackathon/<your-space>`. |
| See `docs/hf-space-deployment.md`. |
| - **AMD Developer Cloud MI300X** — vLLM serving Qwen 2.5 14B (or 32B). |
| See `docs/qwen-vllm-deployment.md` and `infra/vllm/README.md`. |
|
|
| --- |
|
|
| ## 7. Pitch positioning |
|
|
| When writing project descriptions, the README, video, or social posts: |
|
|
| - **Beyond simple RAG** — multi-agent platform with 14 deterministic checks |
| + an LLM ensemble. The 5-tool chat is *agentic*, not retrieval-only. |
| - **Track 1** (AI Agents & Agentic Workflows) is the target track. |
| - **Cross-track**: Build in Public is in scope (AMD GPU prize). |
| - **HF Special Prize** is in scope (Reachy Mini robot — like-vote driven). |
|
|
| --- |
|
|
| ## 8. The Glossary (HU → EN field names) |
|
|
| The full per-field rename map is in |
| `pwc-ai-verseny/document-intelligence-agentic-langgraph-amd/ATIRASI_TERV.md` |
| sections **32 (field names) and 33 (severity literals)**. Keep that file |
| open when editing extraction schemas, domain checks, or anything that |
| touches the `Risk` Pydantic. |
|
|
| --- |
|
|
| ## 9. Common pitfalls |
|
|
| - **Severity literals**: always `"high" | "medium" | "low" | "info"` — |
| never `"magas" | "kozepes" | "alacsony"`. Many `_normalize_severity()` |
| helpers map HU → EN if legacy data sneaks in, but new code emits EN. |
| - **Risk fields**: `description`, `severity`, `rationale`, `kind`, |
| `regulation`, `affected_document`, `source_check_id`. NOT |
| `leiras / sulyossag / indoklas / tipus / jogszabaly / erinto_dokumentum / forras_check_id`. |
| - **Doc types**: `"invoice" | "delivery_note" | "purchase_order" | "contract" | "financial_report" | "other"`. |
| - **`_quotes` alias** (not `_idezetek`) — both in JSON schemas and Pydantic models. |
| - **Multilingual fallback**: read-only in classifiers and regex filters; |
| never emit HU in new code. |
| |
