fix(extraction): graceful typed errors for scanned/corrupt PDFs (closes #8)

[aircode610]

Summary

Fixes #8 — uploading a scanned, image-only PDF (no text layer) crashed the letter-upload flow with a raw exception that surfaced as a 500.

This PR closes the gap at the source across all three extraction entry points, turning every "can't read this document" failure into a typed, user-facing error envelope instead of an unhandled crash.

Root cause

1. extraction.extract_from_letter_file() raised a raw RuntimeError when the vision model returned no tool call — the expected outcome for a text-layer-less scan.
2. pdf_pages.pdf_to_image_bytes() let raw pdf2image/poppler exceptions (corrupt/password-protected file, missing poppler) escape.
3. The SSE /process path (ai/react_agent/ocr.py) base64-encoded raw %PDF bytes and shipped them to the image OCR model labelled image/jpeg, so scanned PDFs never produced text; a malformed/blank response then raised KeyError/IndexError.

Changes

• pdf_pages.py — new PdfRenderError; normalize every render failure (incl. zero pages) into it.
• extraction.py — new ExtractionError; replace the raw RuntimeError, add an empty-page guard, and guard malformed tool-call JSON.
• ai/react_agent/ocr.py — new OcrError + _parse_ocr_response() that defensively extracts text (blank/malformed → typed error).
• orchestrator.py — new _ocr_letter_file() renders PDFs → page PNGs before OCR (so scanned PDFs actually work, and fail cleanly when blank); map PdfRenderError/ExtractionError to friendly SSE error events.
• routers (POST /letters, /api/letters) — map PdfRenderError → PDF_RENDER_FAILED and ExtractionError → EXTRACTION_FAILED (502) with actionable copy ("try uploading it as an image instead").

Tests

backend/tests/test_scanned_pdf_graceful.py — 21 regression tests covering every path (OCR parse, PDF render, structured extraction, the SSE pipeline, and the production POST /letters endpoint named in the issue). All pass; ruff clean on every touched file.

21 passed in 1.40s

Note on the other open PRs (#10, #11, #12)

This is a clean, focused alternative: it contains only the substantive logic + tests, with none of the repo-wide ruff reformatting that made #10/#11/#12 large and hard to review (the concern raised in the issue thread). Diff is ~260 lines across 6 files. Introduces zero new lint errors vs. main baseline. Recommend closing the reformat-heavy PRs in favour of this one.

Closes #8