Initial public release of pdf-tools

Command-line tools for marked-up PDFs and scanned handwritten notes:
pdf-scrub, pdf-notes-md, scan-notes-md (Ollama by default, Claude on
request), scan-notes-index (per-page search metadata), and
scan-notes-stats.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZSvbNaLhgFuTm7wmkgbWs
This commit is contained in:
Eric Furst 2026-11-03 07:25:51 -05:00
commit e464871b69
29 changed files with 5296 additions and 0 deletions

308
tests/test_cli.py Normal file
View file

@ -0,0 +1,308 @@
"""End-to-end CLI behavior with Ollama faked and Claude forbidden."""
from __future__ import annotations
import io
import json
import urllib.error
from pathlib import Path
import pypdfium2 as pdfium
import pytest
from click.testing import CliRunner
from PIL import Image
from pdf_tools import extract_scan, ollama
@pytest.fixture
def env(tmp_path, monkeypatch):
root = tmp_path / "ACME"
cfg = tmp_path / "scan-notes.toml"
cfg.write_text(f"""
prompt_extra = "Mark drawings."
stats_log = "{tmp_path / "stats.jsonl"}"
[[ollama.hosts]]
name = "remote"
url = "http://gpu-box:11434"
model = "gemma4:31b"
[[ollama.hosts]]
name = "local"
url = "http://localhost:11434"
model = "gemma4:e4b"
[[confidential]]
root = "{root}"
names = ["Board Person"]
prompt_extra = "Board-only instruction."
[confidential.companion]
type = "meeting-notes"
fields = ["body", "committee"]
sections = ["Attendees", "Discussion", "Decisions", "Action items"]
transcript_section = "Discussion"
[[confidential.companion.paths]]
match = "{{body}}/committees/{{committee}}/**"
[[confidential]]
root = "{tmp_path / "lab"}"
names = ["Lab Person"]
""")
monkeypatch.setenv("PDF_TOOLS_SCAN_CONFIG", str(cfg))
monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
def no_claude(*a, **k):
raise AssertionError("Claude must not be called")
monkeypatch.setattr(extract_scan, "_transcribe_image", no_claude)
folder = root / "ACMEP-BOM" / "committees" / "finance-audit" / "2026-10-29-fa"
folder.mkdir(parents=True)
pdf = folder / "2026-10-29-acmep-fa-notes.pdf"
doc = pdfium.PdfDocument.new()
doc.new_page(200, 260)
doc.save(pdf)
return {"root": root, "pdf": pdf, "tmp": tmp_path}
def fake_ollama(monkeypatch, up: dict[str, list[str]]):
def _fake(method, url, payload, timeout):
base, _, path = url.partition("/api/")
if path == "tags":
if base not in up:
raise OSError("unreachable")
return {"models": [{"name": m} for m in up[base]]}
if path == "ps":
return {"models": [{"name": m, "size": 100, "size_vram": 100,
"context_length": 4096} for m in up.get(base, [])]}
_fake.prompts.append(payload["messages"][0]["content"])
return {"message": {"content": f"transcript via {payload['model']}"},
"prompt_eval_count": 1000, "eval_count": 200, "done_reason": "stop",
"total_duration": 2_000_000_000}
_fake.prompts = []
monkeypatch.setattr(ollama, "_http_json", _fake)
return _fake
def run(*args):
return CliRunner().invoke(extract_scan.main, [str(a) for a in args])
def test_confidential_scan_defaults_to_ollama_and_writes_companion(env, monkeypatch):
fake_ollama(monkeypatch, {"http://localhost:11434": ["gemma4:e4b"]})
r = run(env["pdf"])
assert r.exit_code == 0, r.output
md = env["pdf"].with_suffix(".md").read_text()
assert "body: ACMEP-BOM\ncommittee: finance-audit\ntype: meeting-notes" in md
assert "## Discussion\n\n### Draft transcript (unverified)" in md
assert "transcribed_by: ollama/localhost/gemma4:e4b" in md
assert "transcript via gemma4:e4b" in md
assert "falling back to local" in r.stderr
def test_no_host_exits_without_cloud(env, monkeypatch):
fake_ollama(monkeypatch, {})
monkeypatch.setenv("ANTHROPIC_API_KEY", "set-but-must-not-be-used")
r = run(env["pdf"])
assert r.exit_code == extract_scan.EXIT_NO_HOST
assert "Not falling back to a cloud service" in r.stderr
assert not env["pdf"].with_suffix(".md").exists()
def test_claude_refused_for_confidential_scan(env, monkeypatch):
monkeypatch.setenv("ANTHROPIC_API_KEY", "x")
r = run("--backend", "claude", env["pdf"])
assert r.exit_code == 2 and "--allow-cloud" in r.stderr
def test_claude_refused_even_with_no_companion(env, monkeypatch):
monkeypatch.setenv("ANTHROPIC_API_KEY", "x")
r = run("--backend", "claude", "--no-companion", "--stdout", env["pdf"])
assert r.exit_code == 2 and "--allow-cloud" in r.stderr
def test_forced_remote_fails_clearly(env, monkeypatch):
fake_ollama(monkeypatch, {"http://localhost:11434": ["gemma4:e4b"]})
r = run("--host", "remote", env["pdf"])
assert r.exit_code == extract_scan.EXIT_NO_HOST
assert "remote" in r.stderr and "falling back to local" not in r.stderr
def test_model_flag_overrides_config(env, monkeypatch):
fake_ollama(monkeypatch, {"http://gpu-box:11434": ["qwen3-vl:8b"]})
r = run("--model", "qwen3-vl:8b", "--host", "remote", env["pdf"])
assert r.exit_code == 0, r.output
assert "ollama/gpu-box/qwen3-vl:8b" in env["pdf"].with_suffix(".md").read_text()
def test_non_companion_ollama_output_uses_page_markers(env, monkeypatch):
fake_ollama(monkeypatch, {"http://gpu-box:11434": ["gemma4:31b"]})
img = env["tmp"] / "page.png"
Image.new("RGB", (50, 50), "white").save(img)
r = run("--backend", "ollama", "--stdout", img)
assert r.exit_code == 0, r.output
assert "<!-- page 1 -->" in r.stdout
assert "transcribed_by: ollama/gpu-box/gemma4:31b" in r.stdout
def test_companion_mode_rejects_stdout(env):
r = run("--stdout", env["pdf"])
assert r.exit_code == 2 and "--no-companion" in r.stderr
def test_second_confidential_folder_uses_its_layout(env, monkeypatch):
fake_ollama(monkeypatch, {"http://gpu-box:11434": ["gemma4:31b"]})
lab = env["tmp"] / "lab" / "reviews"
lab.mkdir(parents=True)
pdf = lab / "2026-11-02-review-notes.pdf"
doc = pdfium.PdfDocument.new()
doc.new_page(200, 260)
doc.save(pdf)
monkeypatch.setenv("ANTHROPIC_API_KEY", "x")
assert run("--backend", "claude", pdf).exit_code == 2
r = run(pdf)
assert r.exit_code == 0, r.output
md = pdf.with_suffix(".md").read_text()
assert "type: notes" in md and "## Notes" in md and "body:" not in md
def test_mixing_confidential_and_other_files_refused(env, monkeypatch):
img = env["tmp"] / "page.png"
Image.new("RGB", (50, 50), "white").save(img)
r = run("--backend", "ollama", "--no-companion", "--stdout", env["pdf"], img)
assert r.exit_code == 2 and "do not mix" in r.stderr
def test_names_come_only_from_the_scans_folder(env, monkeypatch):
fake = fake_ollama(monkeypatch, {"http://localhost:11434": ["gemma4:e4b"]})
assert run(env["pdf"]).exit_code == 0
assert "- Board Person" in fake.prompts[0]
assert "Lab Person" not in fake.prompts[0]
assert "Mark drawings." in fake.prompts[0]
assert "Board-only instruction." in fake.prompts[0]
def test_only_top_level_settings_outside_confidential_folders(env, monkeypatch):
fake = fake_ollama(monkeypatch, {"http://localhost:11434": ["gemma4:e4b"]})
img = env["tmp"] / "page.png"
Image.new("RGB", (50, 50), "white").save(img)
assert run("--backend", "ollama", "--stdout", img).exit_code == 0
assert fake.prompts[0] == ollama.build_prompt([], ["Mark drawings."])
assert "Board" not in fake.prompts[0]
def test_no_confidential_folders_without_config(tmp_path, monkeypatch):
monkeypatch.setenv("PDF_TOOLS_SCAN_CONFIG", str(tmp_path / "empty.toml"))
(tmp_path / "empty.toml").write_text("")
from pdf_tools.scan_config import load_config
assert load_config().confidential == []
def test_interrupted_run_resumes_and_cleans_up(env, monkeypatch):
nb = env["tmp"] / "notebooks"
nb.mkdir()
pdf = nb / "2024-04 notebook.pdf"
doc = pdfium.PdfDocument.new()
for _ in range(3):
doc.new_page(200, 260)
doc.save(pdf)
calls = []
def _fake(method, url, payload, timeout):
if url.endswith("/api/tags"):
return {"models": [{"name": "gemma4:e4b"}]}
if url.endswith("/api/ps"):
return {"models": []}
calls.append(1)
if len(calls) == 2 and not getattr(_fake, "healthy", False):
raise OSError("connection reset")
return {"message": {"content": f"page text {len(calls)}"}}
monkeypatch.setattr(ollama, "_http_json", _fake)
r = run("--backend", "ollama", "--host", "local", pdf)
assert r.exit_code == extract_scan.EXIT_TRANSCRIBE_FAILED
assert "pages 1-1 are saved; rerun to resume" in r.stderr
ckpt = nb / ".2024-04 notebook.scan-partial.json"
assert ckpt.exists() and not pdf.with_suffix(".md").exists()
_fake.healthy = True
r = run("--backend", "ollama", "--host", "local", pdf)
assert r.exit_code == 0, r.output
assert "resuming after page 1 of 3" in r.stderr
md = pdf.with_suffix(".md").read_text()
assert "page text 1" in md and "<!-- page 3 -->" in md
assert len(calls) == 4 # page 1 was not sent again
assert not ckpt.exists()
assert {p.name for p in nb.iterdir()} == {pdf.name, pdf.with_suffix(".md").name}
def test_checkpoint_from_other_model_is_ignored(env, monkeypatch):
fake_ollama(monkeypatch, {"http://localhost:11434": ["gemma4:e4b"]})
img = env["tmp"] / "page.png"
Image.new("RGB", (50, 50), "white").save(img)
ckpt = env["tmp"] / ".page.scan-partial.json"
ckpt.write_text('{"key": {"transcribed_by": "other"}, "pages": [{"label": "x", "text": "stale"}]}')
r = run("--backend", "ollama", "--stdout", img)
assert r.exit_code == 0 and "stale" not in r.stdout
assert "ignoring saved progress" in r.stderr and not ckpt.exists()
def test_stats_logged_per_page_without_text(env, monkeypatch):
fake_ollama(monkeypatch, {"http://localhost:11434": ["gemma4:e4b"]})
r = run(env["pdf"])
assert r.exit_code == 0, r.output
assert "1200 tokens" in r.stderr
lines = (env["tmp"] / "stats.jsonl").read_text().splitlines()
assert len(lines) == 1
rec = json.loads(lines[0])
assert rec["model"] == "gemma4:e4b" and rec["host"] == "localhost"
assert (rec["prompt_tokens"], rec["output_tokens"], rec["context_tokens"]) == (1000, 200, 1200)
assert rec["gpu_fraction"] == 1.0 and rec["loaded_num_ctx"] == 4096
assert rec["image_px"][0] > 0 and rec["page"] == 1
assert "transcript via" not in lines[0]
def test_warns_when_output_hits_length_limit(env, monkeypatch):
def _fake(method, url, payload, timeout):
if url.endswith("/api/tags"):
return {"models": [{"name": "gemma4:e4b"}]}
if url.endswith("/api/ps"):
return {"models": [{"name": "gemma4:e4b", "size": 1, "size_vram": 1,
"context_length": 4096}]}
return {"message": {"content": "partial"}, "prompt_eval_count": 3900,
"eval_count": 196, "done_reason": "length"}
monkeypatch.setattr(ollama, "_http_json", _fake)
r = run(env["pdf"])
assert r.exit_code == 0
assert "marked as cut off" in r.stderr
assert "cut off at the output limit" in env["pdf"].with_suffix(".md").read_text()
def test_looping_page_becomes_placeholder_and_run_finishes(env, monkeypatch):
def _fake(method, url, payload, timeout):
if url.endswith("/api/tags"):
return {"models": [{"name": "gemma4:e4b"}]}
if url.endswith("/api/ps"):
return {"models": []}
raise urllib.error.HTTPError(
url, 500, "err", {},
io.BytesIO(b'{"error":"prediction aborted, token repeat limit reached"}'))
monkeypatch.setattr(ollama, "_http_json", _fake)
r = run(env["pdf"])
assert r.exit_code == 0, r.output
assert "writing a placeholder" in r.stderr
assert ollama.REPEAT_PLACEHOLDER in env["pdf"].with_suffix(".md").read_text()
rec = json.loads((env["tmp"] / "stats.jsonl").read_text().splitlines()[0])
assert rec["done_reason"] == "repeat_abort" and rec["retries"] == 2
def test_ollama_is_the_default_backend_outside_confidential_folders(env, monkeypatch):
fake_ollama(monkeypatch, {"http://gpu-box:11434": ["gemma4:31b"]})
monkeypatch.setenv("ANTHROPIC_API_KEY", "set-but-must-not-be-used")
img = env["tmp"] / "page.png"
Image.new("RGB", (50, 50), "white").save(img)
r = run("--stdout", img)
assert r.exit_code == 0, r.output
assert "transcribed_by: ollama/gpu-box/gemma4:31b" in r.stdout

291
tests/test_companion.py Normal file
View file

@ -0,0 +1,291 @@
"""Companion files: front matter from paths, and preserving existing text."""
from __future__ import annotations
from pathlib import Path
import pytest
from pdf_tools import companion as comp
from pdf_tools.companion import CompanionSpec, PathRule
ROOT = Path("/tmp/acme-test-root")
# A meetings layout like the one in the user's config (test data only; the
# code knows nothing about any organization).
SPEC = CompanionSpec(
type="meeting-notes",
fields=["body", "committee"],
sections=["Attendees", "Discussion", "Decisions", "Action items"],
transcript_section="Discussion",
section_text={"Action items": "- [ ] Owner: task (due date)"},
title="{body}, {date}",
allowed={"body": ["ACME-BOD", "ACMEP-BOM", "ACMEF-BOT"]},
acronyms={"acmep", "ceo"},
paths=[
PathRule("{body}/committees/{committee}/**", title="{body.short} {committee}, {date}"),
PathRule("{body}/meetings/**", set={"committee": "board"}),
PathRule("chair/{committee}/**", set={"body": "chair"}, title="{committee}, {date}"),
PathRule("{body}/{committee}/**", title="{body.short} {committee}, {date}"),
PathRule("{body}/**"),
],
)
TITLES = {
"ACME-BOD": "ACME Board of Directors", "ACME-BOD.short": "ACME",
"ACMEP-BOM": "ACMEP Board of Managers", "ACMEP-BOM.short": "ACMEP",
"finance-audit": "Finance and Audit Committee",
}
def meta(rel: str) -> comp.NoteMeta:
return comp.meta_from_path(ROOT / rel, ROOT, SPEC)
@pytest.mark.parametrize("rel, date, body, committee", [
("ACMEP-BOM/committees/finance-audit/2026-10-29-fa/2026-10-29-acmep-fa-notes.pdf",
"2026-10-29", "ACMEP-BOM", "finance-audit"),
("ACME-BOD/meetings/2026-11-12/2026-11-12-acme-bod-notes.pdf",
"2026-11-12", "ACME-BOD", "board"),
("chair/acmep-ceo-search/2026-10-30-acmep-ceo-search-notes.pdf",
"2026-10-30", "chair", "acmep-ceo-search"),
("ACME-BOD/committees/iac/2026-06-xx/notes.pdf",
"2026-06-xx", "ACME-BOD", "iac"),
("ACMEP-BOM/meetings/2026-06-08/scan.pdf",
"2026-06-08", "ACMEP-BOM", "board"),
])
def test_meta_from_path(rel, date, body, committee):
m = meta(rel)
assert (m.date, m.fields["body"], m.fields["committee"]) == (date, body, committee)
assert m.scan == Path(rel).name
def test_filename_date_wins_over_folder():
m = meta("ACMEP-BOM/meetings/2026-06-08/2026-06-09-acmep-notes.pdf")
assert m.date == "2026-06-09"
def test_unknown_location_warns():
m = meta("inbox/scan.pdf")
assert m.fields["body"] == "" and m.date == ""
assert any("body" in w for w in m.warnings)
assert any("date" in w for w in m.warnings)
def test_partial_date_warns():
assert any("no day" in w for w in meta("ACME-BOD/meetings/2026-06-xx/n.pdf").warnings)
def test_titles():
def t(rel, titles=TITLES):
return comp.title_for(meta(rel), SPEC, titles)
assert t("ACMEP-BOM/committees/finance-audit/x/2026-10-29-n.pdf") == \
"ACMEP Finance and Audit Committee, October 29, 2026"
assert t("ACME-BOD/meetings/2026-11-12/n.pdf") == \
"ACME Board of Directors, November 12, 2026"
assert t("chair/acmep-ceo-search/2026-10-30-n.pdf") == \
"ACMEP CEO Search, October 30, 2026"
assert t("chair/acmep-ceo-search/2026-10-30-n.pdf",
{"acmep-ceo-search": "ACMEP CEO search"}).startswith("ACMEP CEO search,")
assert t("ACME-BOD/meetings/x/n.pdf") == "ACME Board of Directors"
def test_allowed_values_and_rule_order():
m = meta("inbox/2026-01-02-n.pdf") # "inbox" is not an allowed body
assert m.fields == {"body": "", "committee": ""}
m = meta("ACME-BOD/2026-01-02-n.pdf") # matched by the last rule
assert m.fields == {"body": "ACME-BOD", "committee": ""}
assert any("committee" in w for w in m.warnings)
@pytest.mark.parametrize("pattern, folders, expected", [
("a/{x}", ("a", "b"), {"x": "b"}),
("a/{x}", ("a", "b", "c"), None),
("a/{x}/**", ("a", "b", "c"), {"x": "b"}),
("a/**", ("a",), {}),
("{x}/b", ("a", "c"), None),
])
def test_match(pattern, folders, expected):
assert comp._match(pattern, folders, {}) == expected
def test_new_companion_matches_template():
m = meta("ACMEP-BOM/committees/finance-audit/2026-10-29-fa/2026-10-29-acmep-fa-notes.pdf")
text = comp.new_companion(m, ["page one", "page two"], "ollama/gpu-box/gemma4:31b",
SPEC, TITLES)
assert text.startswith(
"---\ndate: 2026-10-29\nbody: ACMEP-BOM\ncommittee: finance-audit\n"
"type: meeting-notes\nscan: 2026-10-29-acmep-fa-notes.pdf\nsubjects: []\n"
"transcribed_by: ollama/gpu-box/gemma4:31b\n---\n")
for h in ("## Attendees", "## Discussion", comp.DRAFT_HEADING,
"## Decisions", "## Action items"):
assert h in text
assert text.index("## Discussion") < text.index(comp.DRAFT_HEADING) < text.index("## Decisions")
assert "<!-- page 1 -->" in text and "<!-- page 2 -->" in text
assert comp.PENDING_LINE not in text
def test_transcript_keeps_layout_and_fences_headings():
page = "# 3 items\n - indented\n\nafter blank"
r = comp.render_transcript([page])
assert "```text\n# 3 items\n - indented\n\nafter blank\n```" in r
r2 = comp.render_transcript(["has ``` inside"])
assert "````text\nhas ``` inside\n````" in r2
# ---- preserving existing companion text -----------------------------------
EXISTING = """\
---
date: 2026-10-29
body: ACMEP-BOM
committee: finance-audit
type: meeting-notes
scan: 2026-10-29-acmep-fa-notes.pdf
subjects: [ACMEP performance, audit timeline]
---
# ACMEP Finance and Audit Committee, October 29, 2026
## Attendees
Pat, the committee, staff.
## Discussion
My own summary paragraph.
With an indented line.
{middle}
## Decisions
- Decision I wrote.
## Action items
- [ ] Owner: task (due date)
"""
def _mine(text: str) -> list[str]:
"""Every line Pat wrote, which must survive any merge."""
return [l for l in EXISTING.format(middle="").splitlines() if l.strip()]
def assert_preserved(before: str, after: str):
after_lines = after.splitlines()
pos = 0
for line in _mine(before):
assert line in after_lines[pos:], f"lost or reordered: {line!r}"
pos = after_lines.index(line, pos) + 1
def test_pending_line_replaced():
before = EXISTING.format(middle=comp.PENDING_LINE + "\n")
after = comp.merge_companion(before, ["draft"], "ollama/localhost/gemma4:e4b", "Discussion")
assert comp.PENDING_LINE not in after
assert after.count(comp.DRAFT_HEADING) == 1
assert_preserved(before, after)
assert after.index("My own summary") < after.index(comp.DRAFT_HEADING) \
< after.index("## Decisions")
def test_block_added_when_missing():
before = EXISTING.format(middle="")
after = comp.merge_companion(before, ["draft"], "ollama/localhost/gemma4:e4b", "Discussion")
assert after.count(comp.DRAFT_HEADING) == 1
assert_preserved(before, after)
assert after.index("With an indented line.") < after.index(comp.DRAFT_HEADING) \
< after.index("## Decisions")
assert "\n\n## Decisions" in after
def test_existing_block_replaced_not_duplicated():
before = EXISTING.format(middle="")
once = comp.merge_companion(before, ["first draft"], "ollama/localhost/gemma4:e4b", "Discussion")
twice = comp.merge_companion(once, ["second draft"], "ollama/gpu-box/gemma4:31b", "Discussion")
assert twice.count(comp.DRAFT_HEADING) == 1
assert "second draft" in twice and "first draft" not in twice
assert_preserved(before, twice)
assert "transcribed_by: ollama/gpu-box/gemma4:31b" in twice
assert twice.count("transcribed_by:") == 1
def test_rerun_is_stable():
before = EXISTING.format(middle="")
once = comp.merge_companion(before, ["same"], "x", "Discussion")
assert comp.merge_companion(once, ["same"], "x", "Discussion") == once
def test_old_block_without_end_marker_stops_at_next_heading():
before = EXISTING.format(middle=(
f"{comp.DRAFT_HEADING}\n\nold draft text\n\n"
"### My corrections\n\nKeep this.\n"))
after = comp.merge_companion(before, ["new"], "x", "Discussion")
assert "old draft text" not in after
assert "### My corrections\n\nKeep this." in after
assert_preserved(before, after)
def test_hash_line_inside_transcript_does_not_end_block():
before = EXISTING.format(middle="")
once = comp.merge_companion(before, ["# not a heading\nmore"], "x", "Discussion")
twice = comp.merge_companion(once, ["replacement"], "x", "Discussion")
assert "not a heading" not in twice and "more\n" not in twice.split("## Decisions")[0]
def test_front_matter_only_gains_transcribed_by():
before = EXISTING.format(middle="")
after = comp.merge_companion(before, ["d"], "ollama/localhost/gemma4:e4b", "Discussion")
fm_before = before.split("\n---\n", 1)[0]
fm_after = after.split("\n---\n", 1)[0]
assert fm_after == fm_before + "\ntranscribed_by: ollama/localhost/gemma4:e4b"
def test_no_discussion_section_appends_at_end():
before = "---\ndate: 2026-10-29\n---\n\n# Notes\n\nFree text.\n"
after = comp.merge_companion(before, ["d"], "x")
assert after.startswith("---\ndate: 2026-10-29\ntranscribed_by: x\n---\n\n# Notes\n\nFree text.\n\n")
assert after.rstrip().endswith(comp.END_MARKER)
def test_write_companion_creates_then_preserves(tmp_path):
folder = tmp_path / "ACMEP-BOM" / "committees" / "finance-audit" / "2026-10-29-fa"
folder.mkdir(parents=True)
pdf = folder / "2026-10-29-acmep-fa-notes.pdf"
pdf.write_bytes(b"%PDF-1.4")
path, created, _ = comp.write_companion(pdf, tmp_path, ["one"], "x", SPEC)
assert created and path == pdf.with_suffix(".md")
edited = path.read_text().replace("subjects: []", "subjects: [audit]") \
.replace("## Attendees\n", "## Attendees\n\nSomeone.\n")
path.write_text(edited)
_, created, _ = comp.write_companion(pdf, tmp_path, ["two"], "y", SPEC)
final = path.read_text()
assert not created
assert "subjects: [audit]" in final and "Someone." in final
assert "two" in final and "\none\n" not in final
assert {p.name for p in folder.iterdir()} == {pdf.name, path.name}
# ---- basic layout (no companion table) -----------------------------------
def test_basic_layout_meta_has_no_body_or_warnings():
m = comp.meta_from_path(ROOT / "projects" / "2026-11-02-lab-review-notes.pdf", ROOT)
assert (m.date, m.fields, m.warnings) == ("2026-11-02", {}, [])
def test_basic_layout_template():
m = comp.meta_from_path(ROOT / "x" / "2026-11-02-lab-review-notes.pdf", ROOT)
text = comp.new_companion(m, ["p"], "ollama/localhost/gemma4:e4b")
assert text.startswith(
"---\ndate: 2026-11-02\ntype: notes\nscan: 2026-11-02-lab-review-notes.pdf\n"
"subjects: []\ntranscribed_by: ollama/localhost/gemma4:e4b\n---\n\n"
"# Lab Review Notes, November 2, 2026\n\n## Notes\n\n" + comp.DRAFT_HEADING)
assert "body:" not in text and "## Attendees" not in text
def test_basic_layout_merge_keeps_text():
before = ("---\ndate: 2026-11-02\n---\n\n# Notes\n\n## Notes\n\nMine.\n\n"
"## Later\n\nAlso mine.\n")
after = comp.merge_companion(before, ["d"], "x")
assert after.index("Mine.") < after.index(comp.DRAFT_HEADING) < after.index("## Later")
assert "Also mine." in after

103
tests/test_config.py Normal file
View file

@ -0,0 +1,103 @@
"""Confidential-folder declarations in the config file."""
from __future__ import annotations
from pathlib import Path
import pytest
from pdf_tools.companion import BASIC
from pdf_tools.scan_config import load_config
EXAMPLE = Path(__file__).resolve().parent.parent / "scan-notes.example.toml"
def cfg_from(tmp_path, text: str):
p = tmp_path / "scan-notes.toml"
p.write_text(text)
return load_config(p)
def test_nothing_built_in(tmp_path, monkeypatch):
monkeypatch.delenv("PDF_TOOLS_SCAN_CONFIG", raising=False)
monkeypatch.setattr("pdf_tools.scan_config.DEFAULT_CONFIG_PATH", tmp_path / "none.toml")
cfg = load_config()
assert cfg.confidential == []
assert [h.url for h in cfg.hosts] == ["http://localhost:11434"]
def test_example_file_loads():
cfg = load_config(EXAMPLE)
assert len(cfg.confidential) == 2
basic, meetings = cfg.confidential
assert basic.companion is BASIC
assert meetings.companion.transcript_section == "Discussion"
assert meetings.companion.fields == ["body", "committee"]
assert [r.match for r in meetings.companion.paths][0] == "{body}/committees/{committee}/**"
assert meetings.titles["BOD.short"] == "Board"
def test_folder_without_companion_is_basic(tmp_path):
cfg = cfg_from(tmp_path, f'[[confidential]]\nroot = "{tmp_path / "x"}"\n')
assert cfg.confidential[0].companion is BASIC
def test_transcript_section_defaults_to_first_section(tmp_path):
cfg = cfg_from(tmp_path, f'[[confidential]]\nroot = "{tmp_path}"\n'
'[confidential.companion]\nsections = ["Summary", "Log"]\n')
assert cfg.confidential[0].companion.transcript_section == "Summary"
def test_tilde_expanded_and_deepest_root_wins(tmp_path):
outer, inner = tmp_path / "a", tmp_path / "a" / "b"
cfg = cfg_from(tmp_path,
f'[[confidential]]\nroot = "{outer}"\n\n'
f'[[confidential]]\nroot = "{inner}"\n')
assert cfg.confidential_folder(inner / "c" / "s.pdf").root == inner
assert cfg.confidential_folder(outer / "s.pdf").root == outer
assert cfg.confidential_folder(tmp_path / "other.pdf") is None
# A sibling whose name merely starts with the root's name is not inside it.
assert cfg.confidential_folder(tmp_path / "ab" / "s.pdf") is None
cfg = cfg_from(tmp_path, '[[confidential]]\nroot = "~/somewhere"\n')
assert cfg.confidential[0].root == Path.home() / "somewhere"
def test_names_are_per_folder(tmp_path):
a, b = tmp_path / "a", tmp_path / "b"
cfg = cfg_from(tmp_path, f'names = ["Everyone"]\n'
f'[[confidential]]\nroot = "{a}"\nnames = ["Alpha", "Everyone"]\n'
f'[[confidential]]\nroot = "{b}"\nnames = ["Beta"]\n')
fa, fb = cfg.confidential
assert cfg.names_for(fa) == ["Everyone", "Alpha"]
assert cfg.names_for(fb) == ["Everyone", "Beta"]
assert cfg.names_for(None) == ["Everyone"]
@pytest.mark.parametrize("text", [
'[[confidential]]\nnames = []\n', # no root
'[[confidential]]\nroot = "/x"\ncompanion = "acme"\n', # old string form
'[[confidential]]\nroot = "/x"\nnmaes = []\n', # typo
'[[confidential]]\nroot = "/x"\n[confidential.companion]\nsectoins = []\n',
'[[confidential]]\nroot = "/x"\n[[confidential.companion.paths]]\ntitle = "t"\n',
# A top-level key written after a host table lands inside that table.
'[[ollama.hosts]]\nname = "l"\nurl = "http://x"\nmodel = "m"\nprompt_extra = "x"\n',
'[ollama]\ntimeout_s = 5\nnames = []\n',
'prompt_extar = "x"\n',
])
def test_bad_entries_rejected(tmp_path, text):
with pytest.raises(SystemExit):
cfg_from(tmp_path, text)
def test_prompt_extra_top_level_and_per_folder(tmp_path):
a, b = tmp_path / "a", tmp_path / "b"
cfg = cfg_from(tmp_path, 'prompt_extra = "Figures."\n'
f'[[confidential]]\nroot = "{a}"\nprompt_extra = "Board terms."\n'
f'[[confidential]]\nroot = "{b}"\n')
fa, fb = cfg.confidential
assert cfg.extras_for(fa) == ["Figures.", "Board terms."]
assert cfg.extras_for(fb) == ["Figures."]
assert cfg.extras_for(None) == ["Figures."]
def test_example_prompt_extra_mentions_figures():
assert "[FIGURE:" in load_config(EXAMPLE).prompt_extra

240
tests/test_index.py Normal file
View file

@ -0,0 +1,240 @@
"""scan-notes-index: transcript parsing, page files, and the CLI with Ollama faked."""
from __future__ import annotations
import io
import json
import urllib.error
import pypdfium2 as pdfium
import pytest
from click.testing import CliRunner
from pdf_tools import companion, ollama, scan_index
from pdf_tools.extract_scan import to_plain_markdown
from pdf_tools.scan_config import OllamaHost, load_config
from pdf_tools.scan_stats import read_log, summarize
HOST = OllamaHost("local", "http://localhost:11434", "gemma4:31b", num_ctx=8192)
KINDS = ["calculation", "idea", "meeting notes", "other", "blank"]
def answer(**over):
a = {"summary": "Estimate of a drag force.", "key_points": ["F = 6 pi eta a U"],
"kind": "calculation", "topics": ["Stokes drag"], "references": [],
"event": "", "event_date": "", "people": [],
"continues_from_previous": False, "continues_to_next": True}
return {**a, **over}
def make_scan(folder, pages=("first page", "second page", "third page")):
folder.mkdir(parents=True, exist_ok=True)
pdf = folder / "2009 notebook.pdf"
doc = pdfium.PdfDocument.new()
for _ in pages:
doc.new_page(200, 260)
doc.save(pdf)
md = pdf.with_suffix(".md")
md.write_text(to_plain_markdown(list(pages), pdf.stem, "ollama/localhost/gemma4:31b"))
return pdf
@pytest.fixture
def env(tmp_path, monkeypatch):
cfg = tmp_path / "scan-notes.toml"
cfg.write_text(f"""
names = ["Global Person"]
stats_log = "{tmp_path / "stats.jsonl"}"
[ollama]
max_output_tokens = 2048
[[ollama.hosts]]
name = "local"
url = "http://localhost:11434"
model = "gemma4:31b"
num_ctx = 8192
[index]
names = ["Board Member"]
prompt_extra = "Index-only instruction."
""")
monkeypatch.setenv("PDF_TOOLS_SCAN_CONFIG", str(cfg))
return tmp_path
def fake(monkeypatch, replies=None):
"""Ollama with gemma4:31b; chat replies come from the list, then answer()."""
replies = list(replies or [])
def _fake(method, url, payload, timeout):
base, _, path = url.partition("/api/")
if path == "tags":
return {"models": [{"name": "gemma4:31b"}]}
if path == "ps":
return {"models": [{"name": "gemma4:31b", "size": 20, "size_vram": 20,
"context_length": 8192}]}
_fake.payloads.append(payload)
r = replies.pop(0) if replies else answer()
if isinstance(r, Exception):
raise r
if isinstance(r, dict) and "message" in r:
return r
return {"message": {"content": r if isinstance(r, str) else json.dumps(r)},
"prompt_eval_count": 2000, "eval_count": 300, "done_reason": "stop",
"total_duration": 9_000_000_000}
_fake.payloads = []
monkeypatch.setattr(ollama, "_http_json", _fake)
return _fake
def run(*args):
return CliRunner().invoke(scan_index.main, [str(a) for a in args])
def test_reads_plain_and_companion_transcripts(tmp_path):
plain = tmp_path / "a.md"
plain.write_text(to_plain_markdown(["one", "has ``` inside", ""], "a", "ollama/x/m"))
pages, by = scan_index.read_transcript(plain)
assert pages == {1: "one", 2: "has ``` inside", 3: ""} and by == "ollama/x/m"
comp = tmp_path / "b.md"
comp.write_text("---\ntranscribed_by: ollama/y/m\n---\n\n## Notes\n\n"
+ companion.draft_block(["alpha", "beta"]) + "\n")
pages, by = scan_index.read_transcript(comp)
assert pages == {1: "alpha", 2: "beta"} and by == "ollama/y/m"
def test_prompt_has_kinds_note_extras_and_names():
p = scan_index.build_index_prompt(KINDS, ["Pat Doe"], ["Extra rule."])
assert '"calculation" for derivations' in p
assert p.index("Extra rule.") < p.index(ollama.NAMES_PROMPT) < p.index("- Pat Doe")
assert '"calculation"' not in scan_index.build_index_prompt(["idea", "other"], [], [])
def test_page_prompt_marks_this_page_and_neighbors():
pages = {1: "p1", 2: "p2" * 50, 3: "p3"}
p = scan_index.page_prompt("BASE", pages, 1, chars=10)
assert "Previous page transcript: (none)" in p
assert "THIS page's draft transcript:\n<<<\np1\n>>>" in p
p = scan_index.page_prompt("BASE", pages, 3, chars=10)
assert "<<<\n" + "p2" * 5 + "\n>>>" in p and "Next page transcript: (none)" in p
def test_clean_coerces_types_and_unknown_kind():
m = scan_index.clean({"summary": None, "kind": "derivation", "topics": "one",
"people": ["", " A "], "continues_to_next": "yes"}, KINDS)
assert m["summary"] == "" and m["kind"] == "other"
assert m["topics"] == ["one"] and m["people"] == ["A"]
assert m["continues_to_next"] is False and m["references"] == []
def test_render_page_front_matter_and_sections():
meta = scan_index.clean(answer(references=['Smith, "x", J. Fluid Mech. 1 (2001)'],
continues_from_previous=True), KINDS)
text = scan_index.render_page("nb", "nb.pdf", 1, 3, meta, "a ``` b", "ollama/h/m",
"ollama/h/t", "2026-11-02")
assert text.startswith('---\nnotebook: "nb"\nscan: "nb.pdf"\npage: 1\nkind: "calculation"')
assert 'references: ["Smith, \\"x\\", J. Fluid Mech. 1 (2001)"]' in text
assert "continues_from: null\ncontinues_to: 2\n" in text # page 1 has no previous
assert "transcribed_by: ollama/h/t" in text
assert scan_index.SUMMARY_HEADING + "\n\nEstimate of a drag force." in text
assert "## Key points\n\n- F = 6 pi eta a U" in text
assert "````text\na ``` b\n````" in text
def test_cli_writes_one_file_per_page(env, monkeypatch):
f = fake(monkeypatch)
pdf = make_scan(env / "nb")
r = run(pdf)
assert r.exit_code == 0, r.output
out = env / "nb" / "2009 notebook pages"
files = sorted(p.name for p in out.iterdir())
assert files == [f"2009 notebook p00{n}.md" for n in (1, 2, 3)]
p2 = (out / "2009 notebook p002.md").read_text()
assert "page: 2\n" in p2 and "continues_to: 3" in p2 and "second page" in p2
assert "indexed_by: ollama/localhost/gemma4:31b" in p2
assert "continues_to: null" in (out / "2009 notebook p003.md").read_text()
req = f.payloads[1]
assert req["format"]["properties"]["kind"]["enum"][0] == "calculation"
assert req["options"] == {"temperature": 0, "num_ctx": 8192, "num_predict": 1536}
prompt = req["messages"][0]["content"]
assert "- Global Person" in prompt and "- Board Member" in prompt
assert "Index-only instruction." in prompt
assert "<<<\nsecond page\n>>>" in prompt and "<<<\nfirst page\n>>>" in prompt
log = read_log(env / "stats.jsonl")
assert [x["task"] for x in log] == ["index"] * 3 and log[0]["kind"] == "calculation"
assert "summary" not in json.dumps(log) # no generated text in the log
assert "index: gemma4:31b on localhost" in summarize(log)
def test_existing_pages_are_skipped_unless_forced(env, monkeypatch):
f = fake(monkeypatch)
pdf = make_scan(env / "nb")
out = env / "nb" / "2009 notebook pages"
out.mkdir()
(out / "2009 notebook p001.md").write_text("kept")
assert run(pdf).exit_code == 0
assert len(f.payloads) == 2 and (out / "2009 notebook p001.md").read_text() == "kept"
r = run(pdf)
assert r.exit_code == 0 and "already indexed" in r.stderr and len(f.payloads) == 2
assert run("--force", pdf).exit_code == 0 and len(f.payloads) == 5
def test_bad_json_is_retried(env, monkeypatch):
f = fake(monkeypatch, ["not json", {"summary": "missing the other keys"}])
pdf = make_scan(env / "nb", pages=("only",))
assert run(pdf).exit_code == 0
assert len(f.payloads) == 3
log = read_log(env / "stats.jsonl")
assert log[0]["retries"] == 2 and log[0]["retry_reasons"] == ["bad_json", "bad_json"]
def test_failed_page_reported_and_others_written(env, monkeypatch):
def err():
return urllib.error.HTTPError("u", 500, "x", {}, io.BytesIO(b'{"error":"token repeat limit"}'))
fake(monkeypatch, [err(), err(), err()])
pdf = make_scan(env / "nb", pages=("a", "b"))
r = run(pdf)
assert r.exit_code == scan_index.EXIT_TRANSCRIBE_FAILED
assert "1 page(s) failed (1)" in r.stderr
out = env / "nb" / "2009 notebook pages"
assert [p.name for p in out.iterdir()] == ["2009 notebook p002.md"]
def test_page_count_mismatch_refused(env, monkeypatch):
fake(monkeypatch)
pdf = make_scan(env / "nb")
pdf.with_suffix(".md").write_text(to_plain_markdown(["a"], "x", "y"))
r = run(pdf)
assert r.exit_code == 2 and "1 transcribed pages" in r.stderr
def test_missing_transcript_refused(env, monkeypatch):
fake(monkeypatch)
pdf = make_scan(env / "nb")
pdf.with_suffix(".md").unlink()
r = run(pdf)
assert r.exit_code == 2 and "run scan-notes-md first" in r.stderr
def test_no_host_exits_without_cloud(env, monkeypatch):
def down(*a):
raise urllib.error.URLError("refused")
monkeypatch.setattr(ollama, "_http_json", down)
pdf = make_scan(env / "nb")
r = run(pdf)
assert r.exit_code == scan_index.EXIT_NO_HOST
assert "Not falling back to a cloud service" in r.stderr
def test_index_config_rejects_unknown_keys(tmp_path, capsys):
cfg = tmp_path / "c.toml"
cfg.write_text("[index]\nkind = ['x']\n")
with pytest.raises(SystemExit):
load_config(cfg)
assert "unknown key(s) in [index]: kind" in capsys.readouterr().err
cfg.write_text("[index]\nkinds = []\n")
with pytest.raises(SystemExit):
load_config(cfg)

247
tests/test_ollama_hosts.py Normal file
View file

@ -0,0 +1,247 @@
"""Host selection, fallback, and response cleanup. All HTTP is faked."""
from __future__ import annotations
import io
import json
import urllib.error
import pytest
from pdf_tools import ollama
from pdf_tools.scan_config import OllamaHost
REMOTE = OllamaHost("remote", "http://gpu-box:11434", "gemma4:31b")
LOCAL = OllamaHost("local", "http://localhost:11434", "gemma4:e4b")
def fake_http(tags: dict[str, list[str] | None], chat=None):
"""tags maps base URL -> model names, or None for an unreachable host."""
calls = []
def _fake(method, url, payload, timeout):
calls.append((method, url, payload, timeout))
base, _, path = url.partition("/api/")
if path == "tags":
models = tags.get(base)
if models is None:
raise urllib.error.URLError("connection refused")
return {"models": [{"name": m} for m in models]}
if path == "chat":
return chat(payload) if chat else {"message": {"content": "ok"}}
raise AssertionError(url)
_fake.calls = calls
return _fake
def test_remote_used_when_available(monkeypatch, capsys):
monkeypatch.setattr(ollama, "_http_json", fake_http({
REMOTE.url: ["gemma4:31b"], LOCAL.url: ["gemma4:e4b"]}))
assert ollama.select_host([REMOTE, LOCAL], 2.5) is REMOTE
assert capsys.readouterr().err == ""
def test_falls_back_when_remote_unreachable(monkeypatch, capsys):
monkeypatch.setattr(ollama, "_http_json", fake_http({
REMOTE.url: None, LOCAL.url: ["gemma4:e4b"]}))
assert ollama.select_host([REMOTE, LOCAL], 2.5) is LOCAL
err = capsys.readouterr().err.strip().splitlines()
assert len(err) == 1
assert "unreachable" in err[0] and "falling back to local" in err[0]
def test_falls_back_when_remote_lacks_model(monkeypatch, capsys):
monkeypatch.setattr(ollama, "_http_json", fake_http({
REMOTE.url: ["qwen3-vl:8b"], LOCAL.url: ["gemma4:e4b"]}))
assert ollama.select_host([REMOTE, LOCAL], 2.5) is LOCAL
assert "does not have gemma4:31b" in capsys.readouterr().err
def test_probe_uses_short_timeout(monkeypatch):
fake = fake_http({REMOTE.url: ["gemma4:31b"]})
monkeypatch.setattr(ollama, "_http_json", fake)
ollama.select_host([REMOTE, LOCAL], 2.5)
assert fake.calls == [("GET", f"{REMOTE.url}/api/tags", None, 2.5)]
def test_no_host_raises(monkeypatch):
monkeypatch.setattr(ollama, "_http_json", fake_http({}))
with pytest.raises(ollama.NoHostAvailable):
ollama.select_host([REMOTE, LOCAL], 2.5)
def test_forced_host_skips_others(monkeypatch):
fake = fake_http({REMOTE.url: ["gemma4:31b"], LOCAL.url: ["gemma4:e4b"]})
monkeypatch.setattr(ollama, "_http_json", fake)
assert ollama.select_host([REMOTE, LOCAL], 2.5, forced="local") is LOCAL
assert [c[1] for c in fake.calls] == [f"{LOCAL.url}/api/tags"]
def test_forced_host_unavailable_is_error_not_fallback(monkeypatch):
monkeypatch.setattr(ollama, "_http_json", fake_http({
REMOTE.url: None, LOCAL.url: ["gemma4:e4b"]}))
with pytest.raises(ollama.NoHostAvailable, match="remote"):
ollama.select_host([REMOTE, LOCAL], 2.5, forced="remote")
def test_forced_host_unknown_name(monkeypatch):
monkeypatch.setattr(ollama, "_http_json", fake_http({}))
with pytest.raises(ollama.NoHostAvailable, match="no Ollama host named"):
ollama.select_host([REMOTE, LOCAL], 2.5, forced="laptop")
def test_untagged_model_matches_latest(monkeypatch):
host = OllamaHost("x", "http://x:11434", "llama3.2")
monkeypatch.setattr(ollama, "_http_json", fake_http({host.url: ["llama3.2:latest"]}))
assert ollama.select_host([host], 1) is host
def test_chat_request_shape(monkeypatch):
seen = {}
def chat(payload):
seen.update(payload)
return {"message": {"content": "line one\n line two"}}
monkeypatch.setattr(ollama, "_http_json", fake_http({}, chat))
out = ollama.transcribe_png(b"\x89PNG", REMOTE, "PROMPT", 300)
assert out.text == "line one\n line two"
assert seen["stream"] is False and seen["think"] is False
assert seen["options"]["temperature"] == 0
assert seen["model"] == "gemma4:31b"
assert len(seen["messages"]) == 1 and seen["messages"][0]["images"]
def test_retries_without_think_when_rejected(monkeypatch):
payloads = []
def _fake(method, url, payload, timeout):
payloads.append(dict(payload))
if "think" in payload:
raise urllib.error.HTTPError(
url, 400, "Bad Request", {},
io.BytesIO(json.dumps({"error": "model does not support thinking"}).encode()))
return {"message": {"content": "text"}}
monkeypatch.setattr(ollama, "_http_json", _fake)
assert ollama.transcribe_png(b"x", LOCAL, "P", 10).text == "text"
assert "think" in payloads[0] and "think" not in payloads[1]
@pytest.mark.parametrize("raw, clean", [
("<think>hmm, looks like a list</think>\nA\nB", "A\nB"),
("<thinking>x</thinking>A", "A"),
("reasoning without an opening tag</think>\nA", "A"),
("A\n - indented\nB\n", "A\n - indented\nB"),
])
def test_strip_thinking(raw, clean):
assert ollama.strip_thinking(raw) == clean
def test_names_added_only_when_configured():
assert ollama.build_prompt([]) == ollama.HANDWRITING_PROMPT
p = ollama.build_prompt(["Pat Example", "ACME Foundation"])
assert p.startswith(ollama.HANDWRITING_PROMPT)
assert "- Pat Example" in p and "otherwise write\n[illegible]" in p
def test_provenance():
assert ollama.provenance(REMOTE) == "ollama/gpu-box/gemma4:31b"
assert ollama.provenance(LOCAL) == "ollama/localhost/gemma4:e4b"
def test_extras_go_between_base_prompt_and_names():
p = ollama.build_prompt(["Pat"], ["Draw figures as [FIGURE: x].", " "])
assert p.startswith(ollama.HANDWRITING_PROMPT + "\nDraw figures as [FIGURE: x].\n\n")
assert p.index("[FIGURE") < p.index(ollama.NAMES_PROMPT) < p.index("- Pat")
assert ollama.build_prompt([], ["", "\n"]) == ollama.HANDWRITING_PROMPT
def test_page_stats_from_response():
st = ollama.page_stats({"prompt_eval_count": 1200, "eval_count": 300,
"done_reason": "stop", "total_duration": 9_500_000_000,
"load_duration": 0, "prompt_eval_duration": 1_000_000_000,
"eval_duration": 8_000_000_000})
assert st["context_tokens"] == 1500 and st["done_reason"] == "stop"
assert (st["total_s"], st["prompt_s"], st["output_s"]) == (9.5, 1.0, 8.0)
assert ollama.page_stats({})["context_tokens"] == 0
def test_loaded_model_reports_gpu_fit(monkeypatch):
def _fake(method, url, payload, timeout):
assert url.endswith("/api/ps")
return {"models": [{"name": "gemma4:31b", "size": 21_000_000_000,
"size_vram": 19_740_000_000, "context_length": 32768}]}
monkeypatch.setattr(ollama, "_http_json", _fake)
got = ollama.loaded_model(REMOTE, 2)
assert got == {"loaded_bytes": 21_000_000_000, "vram_bytes": 19_740_000_000,
"gpu_fraction": 0.94, "loaded_num_ctx": 32768}
def test_loaded_model_unreachable_is_empty(monkeypatch):
def _down(*a):
raise urllib.error.URLError("connection refused")
monkeypatch.setattr(ollama, "_http_json", _down)
assert ollama.loaded_model(REMOTE, 2) == {}
def _repeat_error(url):
return urllib.error.HTTPError(
url, 500, "Internal Server Error", {},
io.BytesIO(b'{"error":"prediction aborted, token repeat limit reached"}'))
def test_looping_page_retried_with_sampling(monkeypatch):
seen = []
def _fake(method, url, payload, timeout):
seen.append(dict(payload["options"]))
if len(seen) == 1:
raise _repeat_error(url)
return {"message": {"content": "ok"}, "eval_count": 5}
monkeypatch.setattr(ollama, "_http_json", _fake)
out = ollama.transcribe_png(b"x", REMOTE, "P", 10)
assert out.text == "ok" and out.stats["retries"] == 1
assert out.stats["retry_reasons"] == ["repeat_limit"]
assert seen[0] == {"temperature": 0}
assert seen[1] == {"temperature": 0.3, "repeat_penalty": 1.15}
assert out.stats["retry_options"] == ollama.REPEAT_RETRIES[0]
def test_first_try_keeps_temperature_zero(monkeypatch):
seen = []
monkeypatch.setattr(ollama, "_http_json", lambda m, u, p, t: seen.append(p["options"])
or {"message": {"content": "ok"}})
out = ollama.transcribe_png(b"x", REMOTE, "P", 10)
assert seen == [{"temperature": 0}] and out.stats["retries"] == 0
def test_repetition_error_after_all_retries(monkeypatch):
def _fake(method, url, payload, timeout):
raise _repeat_error(url)
monkeypatch.setattr(ollama, "_http_json", _fake)
with pytest.raises(ollama.RepetitionError):
ollama.transcribe_png(b"x", REMOTE, "P", 10)
def test_runaway_output_capped_and_retried(monkeypatch):
seen = []
def _fake(method, url, payload, timeout):
seen.append(dict(payload["options"]))
if len(seen) == 1:
return {"message": {"content": "x x x"}, "done_reason": "length", "eval_count": 2048}
return {"message": {"content": "fine"}, "done_reason": "stop", "eval_count": 300}
monkeypatch.setattr(ollama, "_http_json", _fake)
out = ollama.transcribe_png(b"x", REMOTE, "P", 10, max_output=2048)
assert seen[0] == {"temperature": 0, "num_predict": 2048}
assert out.text == "fine" and out.stats["retries"] == 1
assert out.stats["retry_reasons"] == ["output_cap"]
def test_runaway_on_every_attempt_is_marked_cut_off(monkeypatch):
monkeypatch.setattr(ollama, "_http_json", lambda m, u, p, t: {
"message": {"content": "long"}, "done_reason": "length", "eval_count": 2048})
out = ollama.transcribe_png(b"x", REMOTE, "P", 10, max_output=2048)
assert out.text == "long\n" + ollama.CUT_OFF_MARKER
assert out.stats["retries"] == 2 and out.stats["done_reason"] == "length"

36
tests/test_stats.py Normal file
View file

@ -0,0 +1,36 @@
"""The scan-notes-stats summary."""
from __future__ import annotations
from pdf_tools.scan_stats import StatsLog, read_log, summarize
def rec(ctx, run="r1", reason="stop", label="nb.pdf p.1"):
return {"run": run, "host": "gpu-box", "model": "gemma4:31b",
"loaded_num_ctx": 32768, "label": label, "image_px": [2000, 1500],
"prompt_tokens": ctx - 300, "output_tokens": 300, "context_tokens": ctx,
"done_reason": reason, "total_s": 10.0, "gpu_fraction": 0.94,
"vram_bytes": 19.7e9, "loaded_bytes": 21e9}
def test_threshold_counts_and_extremes():
rs = [rec(1500), rec(3000), rec(5000), rec(9000, reason="length", label="big p.9")]
out = summarize(rs, thresholds=(4096, 8192))
assert "4 pages, 1 run(s)" in out
assert "> 4096: 2 (50.0%)" in out and "> 8192: 1 (25.0%)" in out
assert "length limit: 1 page(s)" in out
assert "model looped: 0 page(s) retried, 0 left as placeholders" in out
assert "model in GPU memory: 94-94%" in out
assert out.index("big p.9") < out.index("nb.pdf p.1")
def test_log_roundtrip(tmp_path):
log = StatsLog(tmp_path / "sub" / "s.jsonl")
log.write(rec(100))
log.write(rec(200))
(tmp_path / "sub" / "s.jsonl").open("a").write("not json\n")
assert [r["context_tokens"] for r in read_log(tmp_path / "sub" / "s.jsonl")] == [100, 200]
StatsLog(None).write(rec(1)) # disabled log is a no-op
def test_empty():
assert summarize([]) == "no pages logged yet"