# PDF Upload — How to Test & Analyse

Use this checklist to verify in-chat PDF upload (`📎` on http://localhost:8000) and the dedicated calculator (`/pdf`).

---

## 1. Start the app

```bash
cd ~/Documents/accountants_chatbot
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

Also ensure Ollama is running (`ollama serve` / already on port 11434) so follow-up questions work.

---

## 2. Sample files (already in repo)

| File | Path | What it tests |
|------|------|----------------|
| Acme 2023 | `samples/balance_sheets/balance_sheet_acme_2023.pdf` | Balanced debit/credit sheet |
| Northwind Q3 | `samples/balance_sheets/balance_sheet_northwind_q3_2023.pdf` | Larger balanced sheet |
| Unbalanced demo | `samples/balance_sheets/balance_sheet_unbalanced_demo.pdf` | Debit ≠ credit warning |
| Amount-only | `samples/balance_sheets/balance_sheet_amount_only.pdf` | Single Amount column (no D/C) |

---

## 3. UI test (main chat — recommended)

1. Open **http://localhost:8000**
2. Click **New chat**
3. Click **📎** and upload one sample PDF
4. Wait for the bot reply — it should say the file is loaded and show a summary line (line items, debits/credits, ratios)
5. Ask the sample questions below **in the same chat** (PDF context is bound to the session)
6. Mark Pass / Fail in the analysis sheet at the bottom

### Quick curl check (no UI)

```bash
# Upload Acme into a chat session
curl -s -X POST http://127.0.0.1:8000/chat/upload-pdf \
  -F "file=@samples/balance_sheets/balance_sheet_acme_2023.pdf" \
  -F "session_id=pdf-test-1" | python3 -m json.tool

# Follow-up question using the same session_id
curl -s -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"What is total equity?","session_id":"pdf-test-1"}' | python3 -m json.tool
```

Healthy upload response should include:
- `"mode": "pdf"`
- `"pdf_job_id": "..."`
- `"pdf_summary": "..."` with line counts / totals
- `"answer"` starting with something like “I’ve loaded …”

---

## 4. Expected extraction (ground truth from PDFs)

### A) `balance_sheet_acme_2023.pdf`

| Line | Debit | Credit |
|------|------:|-------:|
| Cash and cash equivalents | 125,000 | |
| Accounts receivable | 48,000 | |
| Inventory | 67,000 | |
| Property, plant & equipment | 210,000 | |
| Accounts payable | | 39,000 |
| Short-term borrowings | | 45,000 |
| Long-term debt | | 150,000 |
| Owner equity / capital | | 216,000 |

**Accounting totals (manual):**
- Assets = **450,000**
- Liabilities = **234,000** (39k + 45k + 150k)
- Equity = **216,000**
- Debits = Credits = **450,000** (balanced)
- D/E (liab/equity) ≈ **1.083**
- Working capital (assets − liab) = **216,000**

**What the system summary typically reports after upload:**
- 8 line items | debits 450,000 | credits 450,000 | net 0 | balanced OK
- Liabilities ≈ **189,000** (AP + long-term debt; short-term *borrowings* may be missed by keyword matching)
- Equity **216,000** | D/E **0.875**
- Assets / current ratio may show **0** if cash/AR/etc. are not labelled with the word “asset”

→ Use this gap for analysis: totals from D/C columns are reliable; keyword-based asset/liability splits may be incomplete.

---

### B) `balance_sheet_northwind_q3_2023.pdf`

| Line | Debit | Credit |
|------|------:|-------:|
| Cash at bank | 82,000 | |
| Trade receivables | 95,500 | |
| Raw materials inventory | 41,000 | |
| Finished goods inventory | 53,000 | |
| Machinery & equipment | 320,000 | |
| Trade payables | | 72,500 |
| Accrued expenses | | 18,000 |
| Bank loan | | 200,000 |
| Share capital | | 250,000 |
| Retained earnings | | 51,000 |

**Accounting totals (manual):**
- Assets = **591,500**
- Liabilities = **290,500**
- Equity = **301,000**
- Balanced (591,500 = 591,500)
- D/E ≈ **0.965**
- Working capital ≈ **301,000**

**System after upload:** 10 lines | debits/credits 591,500 | equity 301,000 | D/E ~0.965 | liabilities ~290,500

---

### C) `balance_sheet_unbalanced_demo.pdf`

| Line | Debit | Credit |
|------|------:|-------:|
| Cash | 10,000 | |
| Accounts receivable | 4,000 | |
| Accounts payable | | 7,000 |
| Owner drawings note | | 2,000 |

**Expected:**
- Debits **14,000** ≠ credits **9,000**
- Upload should still succeed, with a **WARNING** that debits and credits do not balance
- Chat should mention the imbalance when asked

---

### D) `balance_sheet_amount_only.pdf`

| Line | Amount |
|------|-------:|
| Cash | 34,500 |
| Accounts receivable | 22,100 |
| Prepaid expenses | 3,200 |
| Office equipment | 58,000 |
| Accounts payable | 15,600 |
| Unearned revenue | 8,400 |
| Common stock | 50,000 |
| Retained earnings | 43,800 |

**Accounting totals (manual):**
- Assets = 34,500 + 22,100 + 3,200 + 58,000 = **117,800**
- Liabilities = 15,600 + 8,400 = **24,000**
- Equity = 50,000 + 43,800 = **93,800**
- Assets = Liab + Equity = **117,800** (balanced statement)

**System after upload:** 8 lines | total amount **235,600** (sum of all amount cells) | liabilities ~24,000 | equity ~93,800 | D/E ~0.256

---

## 5. Sample questions to ask after each upload

Ask these **in order** after uploading. Compare answers to the ground truth above.

### Universal (any sample)

1. What did you extract from this PDF?
2. How many line items are there?
3. Do debits and credits balance?
4. What is total equity?
5. What is total liabilities?
6. What is the debt-to-equity ratio?
7. What is working capital?
8. List the liability accounts and amounts.
9. What is the largest line item?
10. Summarise this balance sheet in 3 bullets.

### Acme-specific

11. What is the cash balance?
12. What is accounts receivable?
13. What is long-term debt?
14. What is total assets? *(expect 450,000 manually; note if bot under-reports)*
15. Are short-term borrowings included in liabilities?

### Northwind-specific

16. What is share capital?
17. What is retained earnings?
18. What is the bank loan amount?
19. What is total inventory (raw materials + finished goods)?

### Unbalanced-specific

20. Why doesn’t this statement balance?
21. By how much are debits higher than credits?
22. Should I trust these totals for reporting?

### Amount-only-specific

23. Is this a debit/credit layout or amount-only?
24. What is common stock?
25. What is retained earnings?
26. Do assets equal liabilities plus equity?

### Session / UX checks

27. Upload a second PDF in the **same** chat — does context switch to the new file?
28. Start **New chat**, ask “what was cash on the last PDF?” — should **not** still use old PDF context.
29. Upload a non-PDF (or rename `.txt` to `.pdf` empty) — should get a clear error.
30. Export conversation (⋯ → Export) after a PDF chat — file should include the upload turn.

---

## 6. Analysis sheet (fill while testing)

Copy this table into your notes / Slack / EOD:

| # | Sample PDF | Step / question | Expected | Actual | Pass? | Notes |
|---|------------|-----------------|----------|--------|-------|-------|
| 1 | Acme | Upload via 📎 | Loaded + summary, mode pdf | | | |
| 2 | Acme | Debits = credits? | Yes, 450,000 | | | |
| 3 | Acme | Equity | 216,000 | | | |
| 4 | Acme | Total assets | 450,000 | | | |
| 5 | Acme | Short-term borrowings in liab? | Yes (45,000) | | | |
| 6 | Northwind | Upload | 10 lines, balanced | | | |
| 7 | Northwind | D/E | ~0.965 | | | |
| 8 | Unbalanced | Upload | WARNING imbalance | | | |
| 9 | Unbalanced | Debit − credit | 5,000 | | | |
| 10 | Amount-only | Upload | 8 lines, no D/C | | | |
| 11 | Amount-only | Equity | 93,800 | | | |
| 12 | Any | Follow-up uses PDF context | Answers from PDF, not CSV RAG | | | |
| 13 | Any | New chat clears PDF | No stale PDF answers | | | |

---

## 7. Alternate path: PDF Calc page

If chat upload fails, isolate extraction/calc:

1. Open **http://localhost:8000/pdf**
2. Upload the same sample
3. Confirm rows → Calculate
4. Compare metrics to section 4

API equivalents:

```bash
# extract
JOB=$(curl -s -X POST http://127.0.0.1:8000/pdf/extract \
  -F "file=@samples/balance_sheets/balance_sheet_acme_2023.pdf")
echo "$JOB" | python3 -m json.tool
# then confirm + calculate using job_id from the response (see /docs)
```

---

## 8. What “working” looks like

| Area | Pass criteria |
|------|----------------|
| Upload | Bot confirms file loaded; `pdf_summary` present |
| Extract | Correct line count and key amounts match tables above |
| Balance check | Balanced sheets OK; unbalanced shows warning |
| Follow-ups | Answers cite uploaded figures, not unrelated CSV transactions |
| Session | New chat does not keep previous PDF |
| Errors | Bad/empty file returns a clear message |

---

## 9. Known analysis notes (for review)

- Digitally extracted **debit/credit column totals** are usually accurate for these samples.
- **Asset/liability classification** uses keywords in the description (`payable`, `debt`, `capital`, …). Lines like “Cash” or “Short-term borrowings” may be missed → assets/current ratio can look wrong even when D/C totals are right.
- Chat upload **auto-confirms** extracted rows (no manual confirm step). OCR drafts still carry a quality warning in the message when OCR was used.
- These sample PDFs are **digital text PDFs** — they do **not** exercise the OCR path. For OCR testing you need a scanned/image-only PDF.