Skip to content

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

14.1 KB
Raw Blame
"""knowledge.isolated — document parsing in a short-lived child process.

These run the real child (``python -m openexecutive.knowledge.isolated``):
the reads must come back exactly as they do in-process, and a child that
fails, dies or hangs must surface as an error the readers already handle,
never as a hung or crashed API process.
"""
from __future__ import annotations

import io
import logging
import math
import os
import time
import tracemalloc
from pathlib import Path

import pytest

from openexecutive.knowledge import isolated, pdf_reader
from openexecutive.knowledge.isolated import IsolatedError, ParserBusy, WorkerStopped, run_isolated
from openexecutive.knowledge.loader import _parse_file, extract_text_from_file

from ._isolated_helpers import echo, flood_stderr_and_die
from .test_pdf_reader import _blank_pdf, _image_pdf, _text_pdf


@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()


# ── The mechanism ────────────────────────────────────────────────────────────


def test_a_result_comes_back_from_the_child() -> None:
    assert run_isolated(math.sqrt, 16.0, timeout=60) == 4.0


def test_the_child_does_not_inherit_the_deployments_keys(monkeypatch) -> None:
    monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-should-not-leak")

    assert run_isolated(os.getenv, "ANTHROPIC_API_KEY", timeout=60) is None


def test_a_named_exception_is_raised_again_as_itself() -> None:
    with pytest.raises(ValueError, match="math domain error"):
        run_isolated(math.sqrt, -1.0, timeout=60, reraise=(ValueError,))


def test_any_other_exception_is_an_isolated_error() -> None:
    with pytest.raises(IsolatedError, match="ValueError: math domain error") as info:
        run_isolated(math.sqrt, -1.0, timeout=60)
    assert not isinstance(info.value, WorkerStopped)
    # What callers log: the type, never the message (it can quote the file).
    assert info.value.kind == "ValueError"


def test_a_child_that_dies_without_answering_is_reported() -> None:
    with pytest.raises(WorkerStopped, match="exit code 3"):
        run_isolated(os._exit, 3, timeout=60)


def test_a_child_past_its_timeout_is_killed() -> None:
    started = time.monotonic()
    with pytest.raises(WorkerStopped, match="timed out"):
        run_isolated(time.sleep, 30, timeout=1)
    assert time.monotonic() - started < 20


def test_non_ascii_text_comes_back_intact() -> None:
    text = "café — 30 % growth, 日本"
    assert run_isolated(echo, text, timeout=60) == text


def test_lone_surrogates_come_back_as_they_did_in_process() -> None:
    """pypdf decodes some character maps with surrogatepass, so extracted
    text can hold a lone surrogate; strict UTF-8 would lose the whole file."""
    assert run_isolated(echo, "page\ud800text", timeout=60) == "page\ud800text"


def test_an_answer_past_the_limit_is_refused(monkeypatch) -> None:
    monkeypatch.setattr(isolated, "_MAX_ANSWER_BYTES", 100)

    with pytest.raises(WorkerStopped, match="past the limit"):
        run_isolated(echo, "x" * 200, timeout=60)


def test_a_flood_on_stderr_is_never_held_in_memory(monkeypatch) -> None:
    """Review finding: stderr used to be captured whole. A child that writes
    40 MB to it must cost this process the logged tail, not 40 MB."""
    from unittest.mock import MagicMock

    log = MagicMock()
    monkeypatch.setattr(isolated, "logger", log)
    tracemalloc.start()
    try:
        with pytest.raises(WorkerStopped, match="exit code 5"):
            run_isolated(flood_stderr_and_die, 40, timeout=60)
        _current, peak = tracemalloc.get_traced_memory()
    finally:
        tracemalloc.stop()

    assert peak < 2 * 1024 * 1024
    (call,) = log.warning.call_args_list
    tail = call.args[-1]
    assert tail == "x" * isolated._MAX_STDERR_LOGGED


def _log_flood_pdf(pages: int = 5, fonts: int = 300, name_len: int = 4000) -> bytes:
    """A 9 KB PDF that makes pypdf log ~6 MB: every page shares a font dict
    whose fonts all carry a 4000-character /Encoding name, and pypdf logs
    that name as an error for each font on each page."""
    from pypdf import PdfWriter
    from pypdf.generic import DictionaryObject, NameObject, StreamObject

    writer = PdfWriter()
    font = writer._add_object(DictionaryObject({
        NameObject("/Type"): NameObject("/Font"),
        NameObject("/Subtype"): NameObject("/Type1"),
        NameObject("/BaseFont"): NameObject("/Helvetica"),
        NameObject("/Encoding"): NameObject("/" + "A" * name_len),
    }))
    font_dict = writer._add_object(
        DictionaryObject({NameObject(f"/F{i}"): font for i in range(fonts)})
    )
    for _ in range(pages):
        page = writer.add_blank_page(612, 792)
        page[NameObject("/Resources")] = DictionaryObject({NameObject("/Font"): font_dict})
        content = StreamObject()
        content.set_data(b"BT /F0 12 Tf 72 720 Td (Quarterly plan) Tj ET")
        page[NameObject("/Contents")] = writer._add_object(content)
    out = io.BytesIO()
    writer.write(out)
    return out.getvalue()


def test_a_pdf_that_floods_the_parser_log_costs_this_process_nothing() -> None:
    data = _log_flood_pdf()
    log = io.StringIO()
    handler = logging.StreamHandler(log)
    logging.getLogger("pypdf").addHandler(handler)
    try:
        in_process = pdf_reader._text_layer(data)
    finally:
        logging.getLogger("pypdf").removeHandler(handler)
    assert len(log.getvalue()) > 5_000_000, "the fixture must actually flood the log"

    tracemalloc.start()
    try:
        isolated_result = run_isolated(pdf_reader._text_layer, data, timeout=120)
        _current, peak = tracemalloc.get_traced_memory()
    finally:
        tracemalloc.stop()

    assert tuple(isolated_result) == in_process
    assert peak < 2 * 1024 * 1024


def test_out_of_memory_at_spawn_is_reported_not_parsed_in_process(monkeypatch) -> None:
    """Review finding: falling back in-process on ENOMEM / EAGAIN would put
    the parse in the API exactly when memory is shortest."""
    import errno

    def no_memory(*_a: object, **_k: object) -> None:
        raise OSError(errno.ENOMEM, "Cannot allocate memory")

    monkeypatch.setattr(isolated.subprocess, "run", no_memory)

    with pytest.raises(WorkerStopped, match="could not start a parser process"):
        run_isolated(math.sqrt, 9.0, timeout=60)


def test_children_wait_for_a_free_slot(monkeypatch) -> None:
    import threading

    slots = threading.BoundedSemaphore(1)
    monkeypatch.setattr(isolated, "_child_slots", slots)

    # A slot is given back after each call, so calls in turn all run.
    assert run_isolated(math.sqrt, 4.0, timeout=60) == 2.0
    assert run_isolated(math.sqrt, 9.0, timeout=60) == 3.0

    monkeypatch.setattr(isolated, "_MAX_SLOT_WAIT_S", 0.2)
    slots.acquire()
    try:
        started = time.monotonic()
        with pytest.raises(ParserBusy, match="no free parser slot"):
            run_isolated(math.sqrt, 16.0, timeout=60)
        # Review finding: two slow files must not hold every other parse
        # for its whole timeout; the wait is short, not the caller's 60 s.
        assert time.monotonic() - started < 5
    finally:
        slots.release()


def test_the_wait_for_a_slot_counts_against_the_timeout(monkeypatch) -> None:
    """A caller's limit covers the wait and the parse together, so Drive
    sync's 120 s still kills the child when its wait_for gives up."""
    import threading

    slots = threading.BoundedSemaphore(1)
    monkeypatch.setattr(isolated, "_child_slots", slots)
    slots.acquire()
    threading.Timer(1.0, slots.release).start()

    started = time.monotonic()
    with pytest.raises(WorkerStopped, match="timed out") as info:
        run_isolated(time.sleep, 30, timeout=3.0)
    assert not isinstance(info.value, ParserBusy)
    assert time.monotonic() - started < 6


def test_the_in_process_fallback_does_not_hold_a_slot(monkeypatch) -> None:
    """An in-process parse cannot be timed out; a hung one must not keep a
    slot the child processes need."""
    import threading

    slots = threading.BoundedSemaphore(1)
    monkeypatch.setattr(isolated, "_child_slots", slots)
    monkeypatch.setattr(isolated.sys, "executable", "/nonexistent/python")

    def slot_is_free() -> bool:
        if slots.acquire(blocking=False):
            slots.release()
            return True
        return False

    assert run_isolated(slot_is_free, timeout=60) is True


def test_a_caller_with_its_own_gate_does_not_wait_on_the_shared_one(monkeypatch) -> None:
    """OCR brings its own gate, so a long OCR run never holds a slot the
    quick text-layer parses need, and they never hold one OCR needs."""
    import threading

    shared = threading.BoundedSemaphore(1)
    monkeypatch.setattr(isolated, "_child_slots", shared)
    shared.acquire()
    try:
        own = threading.BoundedSemaphore(1)
        assert run_isolated(math.sqrt, 25.0, timeout=60, slots=own) == 5.0
    finally:
        shared.release()


def test_without_a_child_process_it_parses_in_process(monkeypatch) -> None:
    monkeypatch.setattr(isolated.sys, "executable", "/nonexistent/python")

    assert run_isolated(math.sqrt, 9.0, timeout=60) == 3.0


# ── PDFs: same reads as in-process ───────────────────────────────────────────


async def test_a_text_layer_pdf_reads_the_same_as_in_process(tmp_path: Path, monkeypatch) -> None:
    data = _text_pdf("Revenue grew 30 percent year over year in every region we serve")
    path = tmp_path / "report.pdf"
    path.write_bytes(data)

    from_path = await pdf_reader.read_pdf_text(path, filename="report.pdf")
    pdf_reader.clear_cache()
    from_bytes = await pdf_reader.read_pdf_text(data, filename="report.pdf")
    pdf_reader.clear_cache()
    monkeypatch.setattr(isolated, "enabled", False)
    in_process = await pdf_reader.read_pdf_text(data, filename="report.pdf")

    assert from_path == from_bytes == in_process
    assert from_path.method == "text_layer"
    assert "Revenue grew 30 percent" in from_path.text


async def test_a_damaged_pdf_is_reported_through_the_child(tmp_path: Path) -> None:
    path = tmp_path / "bad.pdf"
    path.write_bytes(b"%PDF-1.4 not really a pdf")

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

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


async def test_the_page_ceiling_holds_in_the_child(monkeypatch) -> None:
    """The ceiling is passed to the child, which never sees a patched module."""
    monkeypatch.setattr(pdf_reader, "_MAX_PDF_PAGES", 5)

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

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


async def test_a_reader_that_runs_out_of_time_never_raises(monkeypatch) -> None:
    monkeypatch.setattr(pdf_reader, "_TEXT_LAYER_TIMEOUT_S", 0.001)

    result = await pdf_reader.read_pdf_text(_text_pdf("Quarterly plan"), filename="slow.pdf")

    assert result.method == "none"
    assert result.note == "the PDF could not be read: it was too large or took too long"


async def test_a_missing_file_is_reported_not_raised(tmp_path: Path) -> None:
    result = await pdf_reader.read_pdf_text(tmp_path / "gone.pdf", filename="gone.pdf")

    assert result.method == "none"
    assert result.note == "the file could not be read"


async def test_a_scan_is_ocrd_in_the_child(tmp_path: Path, monkeypatch) -> None:
    pytest.importorskip("rapidocr_onnxruntime")
    pytest.importorskip("pypdfium2")
    # test_pdf_reader.py loads the engine in-process on purpose; start clean
    # so the check below sees only what this read did.
    monkeypatch.setattr(pdf_reader, "_ocr_engine", None)
    monkeypatch.setenv("PDF_PROVIDER_READING", "false")
    monkeypatch.setenv("PDF_OCR_ENABLED", "true")
    path = tmp_path / "scan.pdf"
    path.write_bytes(_image_pdf(["Board meeting notes", "Approve the hiring plan"]))

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

    assert result.method == "ocr"
    assert "Board meeting notes" in result.text
    assert "Approve the hiring plan" in result.text
    # The OCR model was loaded in the child, not here.
    assert pdf_reader._ocr_engine is None


# ── Word / Excel ─────────────────────────────────────────────────────────────


def test_a_docx_reads_the_same_as_in_process(tmp_path: Path) -> None:
    from docx import Document

    doc = Document()
    doc.add_paragraph("Hiring plan")
    doc.add_paragraph("")
    doc.add_paragraph("Two engineers in Q3, one designer in Q4.")
    path = tmp_path / "plan.docx"
    doc.save(str(path))

    text = extract_text_from_file(path)

    assert text == _parse_file(path)
    assert text == "Hiring plan\n\nTwo engineers in Q3, one designer in Q4."


def test_a_corrupt_docx_raises_naming_the_parser_error(tmp_path: Path) -> None:
    path = tmp_path / "broken.docx"
    path.write_bytes(b"not a zip archive")

    with pytest.raises(IsolatedError, match="PackageNotFoundError"):
        extract_text_from_file(path)


def test_what_a_parser_prints_does_not_spoil_the_answer() -> None:
    """Output a library writes to stdout goes to stderr, not into the JSON."""
    assert run_isolated(print, "noise from a parser", timeout=60) is None


async def test_a_pdf_met_by_busy_parsers_says_so_and_is_not_cached(monkeypatch) -> None:
    import threading

    slots = threading.BoundedSemaphore(1)
    monkeypatch.setattr(isolated, "_child_slots", slots)
    monkeypatch.setattr(isolated, "_MAX_SLOT_WAIT_S", 0.1)
    data = _text_pdf("Hire two engineers in the third quarter")

    slots.acquire()
    try:
        busy = await pdf_reader.read_pdf_text(data, filename="plan.pdf")
    finally:
        slots.release()
    read = await pdf_reader.read_pdf_text(data, filename="plan.pdf")

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