Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

22.9 KB
Raw Blame
"""knowledge.pdf_reader — reading scanned / image-only PDFs.

The model is stubbed (no network): `_model_provider` is patched to a fake
with `messages_create`. OCR runs for real in one test (skipped when RapidOCR
is not installed) and is stubbed elsewhere so the rest stay fast.

The parsers run in-process here (``isolated.enabled = False``) so the
monkeypatches below reach them; ``test_isolated.py`` covers the same reads
through the real child process.
"""
from __future__ import annotations

import io
from types import SimpleNamespace
from typing import Any

import pytest
from pypdf import PdfReader, PdfWriter

from openexecutive.knowledge import isolated, pdf_reader
from openexecutive.knowledge.pdf_reader import PdfReadResult, read_pdf_text


@pytest.fixture(autouse=True)
def _provider_reading_on(monkeypatch):
    """Provider reading is opt-in (off by default); most tests here exercise
    that path, so they turn it on. The default is pinned by its own test."""
    monkeypatch.setenv("PDF_PROVIDER_READING", "true")


@pytest.fixture(autouse=True)
def _parse_in_process(monkeypatch):
    monkeypatch.setattr(isolated, "enabled", False)


@pytest.fixture(autouse=True)
def _fresh_cache():
    pdf_reader.clear_cache()
    pdf_reader.reset_inbound_budget()
    yield
    pdf_reader.clear_cache()
    pdf_reader.reset_inbound_budget()


# ── PDF builders ─────────────────────────────────────────────────────────────


def _blank_pdf(pages: int = 1) -> bytes:
    """Pages with no text layer — what a scan looks like to pypdf."""
    writer = PdfWriter()
    for _ in range(pages):
        writer.add_blank_page(width=612, height=792)
    out = io.BytesIO()
    writer.write(out)
    return out.getvalue()


def _text_pdf(text: str) -> bytes:
    """A one-page PDF with a real text layer (Helvetica, one line)."""
    stream = f"BT /F1 12 Tf 72 720 Td ({text}) Tj ET".encode()
    objects = [
        b"<< /Type /Catalog /Pages 2 0 R >>",
        b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
        b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] "
        b"/Resources << /Font << /F1 5 0 R >> >> /Contents 4 0 R >>",
        b"<< /Length %d >>\nstream\n" % len(stream) + stream + b"\nendstream",
        b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
    ]
    out = io.BytesIO()
    out.write(b"%PDF-1.4\n")
    offsets = []
    for i, body in enumerate(objects, start=1):
        offsets.append(out.tell())
        out.write(b"%d 0 obj\n" % i + body + b"\nendobj\n")
    xref = out.tell()
    out.write(b"xref\n0 %d\n0000000000 65535 f \n" % (len(objects) + 1))
    for off in offsets:
        out.write(b"%010d 00000 n \n" % off)
    out.write(
        b"trailer\n<< /Size %d /Root 1 0 R >>\nstartxref\n%d\n%%%%EOF\n"
        % (len(objects) + 1, xref)
    )
    return out.getvalue()


def _image_pdf(lines: list[str]) -> bytes:
    """An image-only PDF with ``lines`` drawn on it, like a scanned page."""
    from PIL import Image, ImageDraw, ImageFont

    img = Image.new("RGB", (1240, 1754), "white")
    draw = ImageDraw.Draw(img)
    try:
        font: Any = ImageFont.truetype("DejaVuSans.ttf", 44)
    except OSError:
        font = ImageFont.load_default(size=44)
    for i, line in enumerate(lines):
        draw.text((100, 150 + i * 110), line, fill="black", font=font)
    out = io.BytesIO()
    img.save(out, format="PDF", resolution=150)
    return out.getvalue()


# ── Fakes ────────────────────────────────────────────────────────────────────


class _FakeProvider:
    """Records each request and answers with one text block per call."""

    def __init__(self, *, reply: str = "TRANSCRIBED", stop_reason: str = "end_turn",
                 error: Exception | None = None, fits_pages: int | None = None) -> None:
        self.calls: list[dict[str, Any]] = []
        self.reply = reply
        self.stop_reason = stop_reason
        self.error = error
        # A slice of more pages than this runs into max_tokens.
        self.fits_pages = fits_pages

    async def messages_create(self, **kwargs: Any) -> Any:
        self.calls.append(kwargs)
        if self.error is not None:
            raise self.error
        prompt = kwargs["messages"][0]["content"][1]["text"]
        pages = prompt.rsplit("These are pages ", 1)[1].split(" of ")[0]
        text = f"{self.reply} [{pages}]" if self.reply else ""
        stop_reason = self.stop_reason
        if self.fits_pages is not None and _pages_in(kwargs) > self.fits_pages:
            stop_reason = "max_tokens"
        return SimpleNamespace(
            stop_reason=stop_reason,
            content=[SimpleNamespace(type="text", text=text)],
        )


def _use_provider(monkeypatch: pytest.MonkeyPatch, provider: Any) -> None:
    monkeypatch.setattr(pdf_reader, "_model_provider", lambda model: provider)


def _stub_ocr(monkeypatch: pytest.MonkeyPatch, text: str = "--- page 1 ---\nOCR TEXT") -> list:
    calls: list = []

    def fake(data: bytes, max_pages: int) -> tuple[str, int]:
        calls.append(max_pages)
        return text, max_pages

    monkeypatch.setattr(pdf_reader, "_ocr_pdf", fake)
    return calls


def _pages_in(call: dict[str, Any]) -> int:
    block = call["messages"][0]["content"][0]
    import base64

    return len(PdfReader(io.BytesIO(base64.b64decode(block["source"]["data"]))).pages)


# ── Text layer ───────────────────────────────────────────────────────────────


async def test_pdf_with_a_text_layer_is_read_without_a_model_call(monkeypatch):
    provider = _FakeProvider()
    _use_provider(monkeypatch, provider)
    ocr = _stub_ocr(monkeypatch)
    body = "Quarterly revenue grew twenty three percent against plan this year"

    result = await read_pdf_text(_text_pdf(body), filename="report.pdf")

    assert result.method == "text_layer"
    assert body in result.text
    assert not result.converted
    assert provider.calls == [] and ocr == []


# ── Claude (document blocks) ─────────────────────────────────────────────────


async def test_scanned_pdf_is_transcribed_from_a_document_block(monkeypatch):
    provider = _FakeProvider(reply="Revenue 4.2M")
    _use_provider(monkeypatch, provider)
    ocr = _stub_ocr(monkeypatch)

    result = await read_pdf_text(_blank_pdf(2), filename="scan.pdf")

    assert result == PdfReadResult("Revenue 4.2M [1 to 2]", "model", 2)
    assert result.converted
    assert ocr == []
    (call,) = provider.calls
    document, instruction = call["messages"][0]["content"]
    assert document["type"] == "document"
    assert document["source"]["type"] == "base64"
    assert document["source"]["media_type"] == "application/pdf"
    assert instruction["type"] == "text"
    assert _pages_in(call) == 2


async def test_long_scan_is_sent_in_slices_and_joined_in_order(monkeypatch):
    monkeypatch.setenv("PDF_VISION_PAGES_PER_CALL", "20")
    provider = _FakeProvider(reply="part")
    _use_provider(monkeypatch, provider)

    result = await read_pdf_text(_blank_pdf(45), filename="scan.pdf")

    assert result.method == "model"
    assert result.text == "part [1 to 20]\n\npart [21 to 40]\n\npart [41 to 45]"
    assert sorted(_pages_in(c) for c in provider.calls) == [5, 20, 20]


async def test_pages_past_the_cap_are_skipped_with_a_note(monkeypatch):
    monkeypatch.setenv("PDF_VISION_MAX_PAGES", "10")
    provider = _FakeProvider()
    _use_provider(monkeypatch, provider)

    result = await read_pdf_text(_blank_pdf(25), filename="scan.pdf")

    assert result.method == "model"
    assert result.pages == 25
    assert result.note == "only the first 10 of 25 pages were read"
    assert sum(_pages_in(c) for c in provider.calls) == 10


# ── Non-Claude deployments and failures fall back to OCR ─────────────────────


async def test_without_a_claude_provider_the_pages_are_ocrd(monkeypatch):
    _use_provider(monkeypatch, None)
    ocr = _stub_ocr(monkeypatch)

    result = await read_pdf_text(_blank_pdf(3), filename="scan.pdf")

    assert result == PdfReadResult("--- page 1 ---\nOCR TEXT", "ocr", 3)
    assert ocr == [3]


@pytest.mark.parametrize(
    "provider",
    [
        _FakeProvider(error=RuntimeError("boom")),
        _FakeProvider(stop_reason="refusal"),
        _FakeProvider(reply=""),
    ],
    ids=["error", "refusal", "empty"],
)
async def test_a_failed_transcription_falls_back_to_ocr(monkeypatch, provider):
    _use_provider(monkeypatch, provider)
    _stub_ocr(monkeypatch)

    result = await read_pdf_text(_blank_pdf(), filename="scan.pdf")

    assert result.method == "ocr"
    assert provider.calls


def test_each_deployment_gets_its_own_pdf_reader(monkeypatch):
    """The PDF goes to whatever provider the model routes to — Anthropic,
    OpenRouter, or a local server that says it takes PDFs — and only a model
    with no way to receive one falls to local OCR."""
    from openexecutive.providers import registry
    from openexecutive.providers.anthropic_provider import AnthropicProvider
    from openexecutive.providers.openai_compatible import OpenAICompatibleProvider
    from openexecutive.providers.openrouter_provider import OpenRouterProvider

    registry._reset_for_tests()
    try:
        assert isinstance(pdf_reader._model_provider("claude-sonnet-5"), AnthropicProvider)

        registry._reset_for_tests()
        monkeypatch.setenv("OPENROUTER_ENABLED", "true")
        monkeypatch.setenv("OPENROUTER_API_KEY", "sk-or-test")
        assert isinstance(pdf_reader._model_provider("claude-sonnet-5"), OpenRouterProvider)
        assert isinstance(pdf_reader._model_provider("openai/gpt-6-astra"), OpenRouterProvider)

        registry._reset_for_tests()
        monkeypatch.setenv("LOCAL_MODELS_ENABLED", "true")
        monkeypatch.setenv("LOCAL_BASE_URL", "http://localhost:11434/v1")
        monkeypatch.setenv("LOCAL_MODELS", "llama3.3")
        assert pdf_reader._model_provider("llama3.3") is None
        monkeypatch.setenv("LOCAL_PDF_INPUT", "true")
        assert isinstance(pdf_reader._model_provider("llama3.3"), OpenAICompatibleProvider)
    finally:
        registry._reset_for_tests()


def test_the_pdf_model_defaults_to_the_deployments_model(monkeypatch):
    monkeypatch.delenv("PDF_VISION_MODEL", raising=False)
    monkeypatch.setenv("DEFAULT_MODEL", "openai/gpt-6-astra")
    assert pdf_reader._pdf_model() == "openai/gpt-6-astra"
    monkeypatch.setenv("PDF_VISION_MODEL", "claude-haiku-4-5")
    assert pdf_reader._pdf_model() == "claude-haiku-4-5"


async def test_ocr_not_installed_says_so(monkeypatch):
    _use_provider(monkeypatch, None)

    def unavailable() -> Any:
        raise pdf_reader.OcrUnavailable("no module")

    monkeypatch.setattr(pdf_reader, "_get_ocr_engine", unavailable)

    result = await read_pdf_text(_blank_pdf(), filename="scan.pdf")

    assert result.method == "none"
    assert result.text == ""
    assert "OCR is not installed" in result.note


async def test_ocr_can_be_turned_off(monkeypatch):
    monkeypatch.setenv("PDF_OCR_ENABLED", "false")
    _use_provider(monkeypatch, None)
    ocr = _stub_ocr(monkeypatch)

    result = await read_pdf_text(_blank_pdf(), filename="scan.pdf")

    assert result.method == "none"
    assert "turned off" in result.note
    assert ocr == []


async def test_a_damaged_pdf_is_reported_not_raised(monkeypatch):
    _use_provider(monkeypatch, _FakeProvider())

    result = await read_pdf_text(b"%PDF-1.4 not really a pdf", filename="bad.pdf")

    assert result.method == "none"
    assert "could not be opened" in result.note


# ── Cache ────────────────────────────────────────────────────────────────────


async def test_the_same_pdf_is_converted_once(monkeypatch):
    provider = _FakeProvider()
    _use_provider(monkeypatch, provider)
    data = _blank_pdf()

    first = await read_pdf_text(data, filename="a.pdf")
    second = await read_pdf_text(data, filename="a.pdf")

    assert first == second
    assert len(provider.calls) == 1


async def test_a_file_read_by_path_is_cached(tmp_path):
    path = tmp_path / "plan.pdf"
    path.write_bytes(_text_pdf("Hire two engineers in the third quarter"))

    await read_pdf_text(path, filename="plan.pdf")

    assert len(pdf_reader._cache) == 1


async def test_a_file_replaced_while_it_is_read_is_not_cached(tmp_path, monkeypatch):
    """The cache key is the hash of the file as first read; if the file is
    rewritten before the parse (an upload under the same name), the text is
    the new file's and must not be stored under the old file's hash."""
    path = tmp_path / "plan.pdf"
    path.write_bytes(_text_pdf("Hire two engineers in the third quarter"))
    original = pdf_reader._text_layer

    def replaced_mid_read(source: Any, max_pages: int | None = None) -> tuple[str, int]:
        path.write_bytes(_text_pdf("Freeze hiring until the next board meeting"))
        return original(source, max_pages)

    monkeypatch.setattr(pdf_reader, "_text_layer", replaced_mid_read)

    result = await read_pdf_text(path, filename="plan.pdf")

    assert "Freeze hiring" in result.text
    assert len(pdf_reader._cache) == 0


async def test_an_unreadable_result_is_not_cached(monkeypatch):
    """A failure (no key yet, OCR off) must not stick once it is fixed."""
    monkeypatch.setenv("PDF_OCR_ENABLED", "false")
    _use_provider(monkeypatch, None)
    data = _blank_pdf()
    assert (await read_pdf_text(data)).method == "none"

    _use_provider(monkeypatch, _FakeProvider())
    assert (await read_pdf_text(data)).method == "model"


# ── Real OCR ─────────────────────────────────────────────────────────────────


def test_ocr_reads_an_image_only_pdf():
    pytest.importorskip("rapidocr_onnxruntime")
    pytest.importorskip("pypdfium2")
    data = _image_pdf(["Board meeting notes", "Approve the hiring plan"])
    assert PdfReader(io.BytesIO(data)).pages[0].extract_text() == ""

    text, read = pdf_reader._ocr_pdf(data, max_pages=5)

    assert read == 1
    assert text.startswith("--- page 1 ---")
    assert "Board meeting notes" in text
    assert "Approve the hiring plan" in text


# ── Resource bounds ──────────────────────────────────────────────────────────


def test_a_huge_page_is_rendered_within_the_pixel_budget():
    """A page's size is whatever its MediaBox says; a 20000pt-square page at
    the normal scale would allocate gigabytes."""
    assert pdf_reader._render_scale(612, 792) == pdf_reader._OCR_RENDER_SCALE
    scale = pdf_reader._render_scale(20_000, 20_000)
    assert (20_000 * scale) ** 2 <= pdf_reader._OCR_MAX_PAGE_PIXELS * 1.0001


def test_ocr_renders_a_huge_page_at_the_capped_scale(monkeypatch):
    pytest.importorskip("pypdfium2")
    writer = PdfWriter()
    writer.add_blank_page(width=14_000, height=14_000)
    buf = io.BytesIO()
    writer.write(buf)
    sizes: list[tuple[int, int]] = []

    class Engine:
        def __call__(self, image: Any) -> tuple[None, None]:
            sizes.append(image.shape[:2])
            return None, None

    monkeypatch.setattr(pdf_reader, "_get_ocr_engine", lambda: Engine())

    assert pdf_reader._ocr_pdf(buf.getvalue(), max_pages=1) == ("", 1)
    (height, width), = sizes
    assert height * width <= pdf_reader._OCR_MAX_PAGE_PIXELS * 1.001


def test_ocr_stops_at_its_time_budget(monkeypatch):
    pytest.importorskip("pypdfium2")
    monkeypatch.setattr(pdf_reader, "_OCR_TIME_BUDGET_S", -1.0)
    monkeypatch.setattr(pdf_reader, "_get_ocr_engine", lambda: object())

    assert pdf_reader._ocr_pdf(_blank_pdf(5), max_pages=5) == ("", 0)


async def test_inbound_files_get_the_smaller_page_cap(monkeypatch):
    monkeypatch.setenv("PDF_INBOUND_MAX_PAGES", "4")
    _use_provider(monkeypatch, None)
    ocr = _stub_ocr(monkeypatch)
    data = _blank_pdf(10)

    inbound = await read_pdf_text(data, inbound=True)
    asked = await read_pdf_text(data)

    assert ocr == [4, 10]
    assert inbound.note == "only the first 4 of 10 pages were read"
    assert asked.note == ""


async def test_a_scan_met_by_busy_ocr_says_so_and_refunds_its_pages(monkeypatch):
    """Review finding: a scan that never got an OCR slot was reported as
    unreadable and still used up the hourly inbound page budget."""
    monkeypatch.setenv("PDF_INBOUND_PAGES_PER_HOUR", "3")
    _use_provider(monkeypatch, None)

    def busy(source: Any, max_pages: int) -> tuple[str, int]:
        raise pdf_reader.ParserBusy("_ocr_pdf found no free parser slot")

    monkeypatch.setattr(pdf_reader, "_ocr_isolated", busy)
    first = await read_pdf_text(_blank_pdf(3), inbound=True)

    assert first.busy and first.method == "none"
    assert "busy reading other documents" in first.note

    ocr = _stub_ocr(monkeypatch)
    monkeypatch.setattr(pdf_reader, "_ocr_isolated", pdf_reader._ocr_pdf)
    second = await read_pdf_text(_blank_pdf(3), inbound=True)

    assert second.method == "ocr", "the busy attempt must not have spent the budget"
    assert ocr == [3]


async def test_pages_the_model_may_have_billed_are_not_refunded(monkeypatch):
    """Review finding: a transcription that fails can still have paid for
    its other slices; refunding when OCR is then busy would let a sender
    run up model spend past the hourly budget."""
    monkeypatch.setenv("PDF_INBOUND_PAGES_PER_HOUR", "3")
    _use_provider(monkeypatch, _FakeProvider(error=RuntimeError("slice failed")))

    def busy(source: Any, max_pages: int) -> tuple[str, int]:
        raise pdf_reader.ParserBusy("_ocr_pdf found no free parser slot")

    monkeypatch.setattr(pdf_reader, "_ocr_isolated", busy)

    first = await read_pdf_text(_blank_pdf(3), inbound=True)
    second = await read_pdf_text(_blank_pdf(2), inbound=True)

    assert first.busy
    assert second.method == "none" and "hourly budget" in second.note


def test_a_refund_returns_its_own_reservation_not_one_of_the_same_size():
    first_pages, first = pdf_reader._take_inbound_pages(2, 10)
    second_pages, second = pdf_reader._take_inbound_pages(2, 10)
    assert first is not None and second is not None

    pdf_reader._refund_inbound_pages(first)

    assert pdf_reader._inbound_spent == [second]
    assert pdf_reader._inbound_spent[0] is second


async def test_inbound_conversions_share_an_hourly_page_budget(monkeypatch):
    monkeypatch.setenv("PDF_INBOUND_PAGES_PER_HOUR", "5")
    _use_provider(monkeypatch, None)
    ocr = _stub_ocr(monkeypatch)

    first = await read_pdf_text(_blank_pdf(3), inbound=True)
    second = await read_pdf_text(_blank_pdf(4), inbound=True)
    third = await read_pdf_text(_blank_pdf(2), inbound=True)
    asked = await read_pdf_text(_blank_pdf(2))

    assert ocr == [3, 2, 2]
    assert first.method == second.method == "ocr"
    assert second.note == "only the first 2 of 4 pages were read"
    assert third.method == "none" and "hourly budget" in third.note
    assert asked.method == "ocr"


# ── Review findings: page-tree ceiling, cut-off transcriptions ───────────────


async def test_a_pdf_past_the_page_ceiling_is_refused_before_parsing(monkeypatch):
    """The page caps bound conversion only; the text-layer pass would
    otherwise extract every page of a crafted many-thousand-page file."""
    from pypdf import PageObject

    monkeypatch.setattr(pdf_reader, "_MAX_PDF_PAGES", 5)

    def never(*_a: Any, **_k: Any) -> str:
        raise AssertionError("no page may be parsed past the ceiling")

    monkeypatch.setattr(PageObject, "extract_text", never)
    provider = _FakeProvider()
    _use_provider(monkeypatch, provider)

    result = await read_pdf_text(_blank_pdf(8), filename="huge.pdf")

    assert result == PdfReadResult(
        "", "none", 8, "the PDF has 8 pages — more than the 5 this reads"
    )
    assert provider.calls == []


async def test_a_cut_off_slice_is_split_until_each_part_fits(monkeypatch):
    monkeypatch.setenv("PDF_VISION_PAGES_PER_CALL", "20")
    provider = _FakeProvider(reply="part", fits_pages=5)
    _use_provider(monkeypatch, provider)

    result = await read_pdf_text(_blank_pdf(20), filename="dense.pdf")

    assert result.method == "model"
    assert result.note == ""
    assert result.text == (
        "part [1 to 5]\n\npart [6 to 10]\n\npart [11 to 15]\n\npart [16 to 20]"
    )
    # 20 -> 10 + 10 -> four slices of 5: seven requests in all.
    assert sorted(_pages_in(c) for c in provider.calls) == [5, 5, 5, 5, 10, 10, 20]


async def test_a_single_page_that_never_fits_is_kept_and_flagged(monkeypatch):
    provider = _FakeProvider(reply="dense page", stop_reason="max_tokens")
    _use_provider(monkeypatch, provider)

    result = await read_pdf_text(_blank_pdf(2), filename="dense.pdf")

    assert result.method == "model"
    assert result.text == (
        "dense page [1 to 1]\n[transcription cut off here]\n\n"
        "dense page [2 to 2]\n[transcription cut off here]"
    )
    assert result.note == "some pages' transcription was cut off"


# ── Keeping scanned PDFs on the server ───────────────────────────────────────


async def test_provider_reading_off_keeps_scans_on_this_server(monkeypatch):
    monkeypatch.setenv("PDF_PROVIDER_READING", "false")
    provider = _FakeProvider()
    _use_provider(monkeypatch, provider)
    ocr = _stub_ocr(monkeypatch)

    result = await read_pdf_text(_blank_pdf(2), filename="scan.pdf")

    assert result.method == "ocr"
    assert provider.calls == []
    assert ocr == [2]


async def test_provider_reading_is_off_by_default(monkeypatch):
    """An upgrade must not start sending scanned PDFs off the server."""
    monkeypatch.delenv("PDF_PROVIDER_READING", raising=False)
    provider = _FakeProvider()
    _use_provider(monkeypatch, provider)
    ocr = _stub_ocr(monkeypatch)

    result = await read_pdf_text(_blank_pdf(2), filename="scan.pdf")

    assert result.method == "ocr"
    assert provider.calls == []
    assert ocr == [2]


async def test_where_scans_go_is_logged_once(monkeypatch):
    from unittest.mock import MagicMock

    monkeypatch.setattr(pdf_reader, "_announced", set())
    log = MagicMock()
    monkeypatch.setattr(pdf_reader, "logger", log)
    _use_provider(monkeypatch, _FakeProvider())

    await read_pdf_text(_blank_pdf(1), filename="a.pdf")
    await read_pdf_text(_blank_pdf(2), filename="b.pdf")

    lines = [c.args[0] % c.args[1:] for c in log.info.call_args_list]
    assert len([line for line in lines if "scanned PDFs are sent to" in line]) == 1
    assert "PDF_PROVIDER_READING is on" in lines[0]