Acquire Paper PDF

Acquire Paper PDF

Retrieve exactly one paper and return either a validated PDF or a structured human handoff. Do not attach the file to Zotero or analyze it; those are downstream responsibilities.

Required Input

Resolve before downloading:

• exact title
• DOI when available
• target author or compatible author list
• canonical publisher URL
• output directory and expected filename

If the caller provides only a citekey or Zotero key, resolve these fields from Zotero first. Never guess a DOI or treat a title-only near match as the paper.

Safety Rules

• Use only access the user is lawfully entitled to use: open access, author manuscript, institutional repository, or the user's normal subscribed publisher session.
• Never invoke Browser, Computer Use, Playwright, Selenium, or other UI automation. Never bypass a paywall, CAPTCHA, access control, robots challenge, rate limit, or institutional authentication. Do not use proxy rotation, cookie extraction, session-token inspection, URL-signature manipulation, or unauthorized mirrors.
• Never ask for credentials, cookies, API tokens, or a copied session. Ask the user to sign in or complete the blocked browser step themselves.
• Keep attempts bounded: one metadata/OA discovery pass, one standard HTTP attempt per distinct verified URL, and one authenticated-browser attempt per publisher route. Do not loop on 403/429/challenge responses.
• Never accept a file merely because it ends in .pdf. Validate file type and paper identity.
• Preserve unrelated files in the download directory. Delete a failed candidate only when it was created by the current run and is confirmed to be HTML, corrupt, or the wrong paper.

Workflow

1. Establish Identity and Routes

Verify the DOI/title/authors against Crossref, OpenAlex, the publisher record, or the researcher's official publication list. Build ordered routes:

1. publisher-hosted open PDF
2. exact arXiv record
3. PubMed Central or institutional repository
4. accepted author manuscript or verified lab page
5. user-assisted download through a lawful subscription when automated routes fail

Require exact title and compatible authorship for preprints or manuscripts. Record whether the retrieved file is the version of record, accepted manuscript, or preprint.

2. Try Standard HTTP

For each verified direct URL, run:

python <SKILL_DIR>\scripts\download_candidate.py `
  --url "<verified-url>" `
  --output "<target.pdf>" `
  --title "<exact-title>" `
  --doi "<doi>"

Continue to the next route on http-error, html-instead-of-pdf, identity-mismatch, or challenge-suspected. Do not vary identity headers or repeatedly retry the same blocked URL.

3. Hand Off Web Interaction

Do not control a browser. When standard HTTP and lawful open repositories fail, provide the user with the exact title, DOI, canonical publisher page, expected filename, and destination directory. Ask the user to complete any subscription login, institution selection, CAPTCHA, terms acceptance, or download manually. After the user confirms completion, detect only the newly supplied file and validate it with validate_pdf_identity.py.

4. Validate Identity

Run:

python <SKILL_DIR>\scripts\validate_pdf_identity.py `
  "<candidate.pdf>" --title "<exact-title>" --doi "<doi>" --strict

Require status: valid. A DOI match is strongest; otherwise require strong normalized-title evidence in PDF metadata or extracted first-page text. review is not completion.

After validation, return the absolute path, SHA-256, source URL, version type, and validation evidence. Leave moving/attaching to the caller.

5. Hand Off to the User

After all non-browser routes fail, ask for one precise action. Include:

• exact title
• DOI and canonical publisher link
• reason automation stopped
• the exact browser step needed, or expected filename and destination if manual download is required

Use this form:

User help is needed for one paper:
Title: ...
DOI: ...
Publisher: ...
Blocked at: login / institution selection / CAPTCHA / 403 / no lawful full text
Action: Complete this step in the current browser, or download the PDF to <directory> as <expected.pdf>.

Once supplied, validate the file before reporting success.

Result Contract

Return one of:

• acquired: validated local PDF with path, SHA-256, source, and version
• needs-user: exact blocked step and requested action
• not-found: discovery exhausted with routes checked
• identity-conflict: candidate exists but DOI/title/authorship does not match

Never report acquired for a landing-page HTML file, browser-only viewer, abstract, supplementary file, or unvalidated PDF.