page1-validator

Sub-agent : page1-validator

Role

Verify that a PDF's page 1 matches an expected reference. This is the core anti-homonymy guard of the plugin :

• Confirms the author surname appears on page 1
• Confirms the title has ≥ 30 % keyword similarity with the expected title
• Confirms zero off-domain keywords are present (e.g., "spider" for a Computer Science paper, "carcinoma" for a music paper)

The cascade invokes this validation automatically via pipeline.cascade._save_and_validate. This sub-agent is for manual / explicit validation when the user wants to recheck a specific PDF outside the cascade flow.

Input contract

pdf_path: /absolute/path/to/the.pdf
expected:
  author: "Surname Firstname"   # or just Surname
  title: "Full expected title"
  year: 2020                     # optional, used for cross-check

What this agent does

1. Read the PDF via pdftotext "$pdf_path" - (first page only via -f 1 -l 1)
2. Extract metadata from page 1 (author, title, year if visible)
3. Compute similarity scores :
   • Author match : surname is present (case-insensitive)
   • Title similarity : keyword overlap with expected, ratio ≥ 0.3
   • Off-domain keywords : zero of the domain-blacklist words (e.g., {spider, arachnology, carcinoma, RNA, ...} for non-bio papers — depends on context)
4. Return verdict with explanation

Output contract

{
  "verdict": "ok" | "mismatch" | "unable_to_extract",
  "author_found": true | false,
  "title_similarity": 0.42,
  "off_domain_keywords": [],
  "page1_text_excerpt": "First 500 chars of page 1...",
  "reason": "human-readable explanation"
}

Verdicts :

• ok : all 3 checks pass, PDF accepted as matching the ref
• mismatch : at least 1 check fails — PDF should be quarantined, ref transitioned to blocked_human:title_mismatch or needs_reacquisition
• unable_to_extract : pdftotext produced < 50 chars on page 1 (probably a scan with no text layer) — ref should be transitioned to awaiting_rtfm_ocr