paper-fetch AGENTS.md

AGENTS.md — for AI agents deploying, adapting, or calling paper-fetch

Most people will point you (an AI coding agent) at this repo and say "set this up for my library" or "explain how this works." This file tells you how to do that correctly, how to know it worked, and where the hard lines are.

What this tool is

A publisher-aware full-text PDF fetcher built as a route ladder: open access (Unpaywall + Semantic Scholar + PMC) → official publisher TDM APIs → the user's own institutional library proxy → a printed resolver link for a manual finish. It is the download end of a pipeline; the reading end is claude-paper-tools, the discovery end is paper-radar.

Deploying it for a user (the happy path)

1. pip install -r requirements.txt. For the proxy layer also python -m patchright install chromium.
2. cp config.example.yaml config.yaml. Fill in:
   • unpaywall_email, rate.contact — the user's email.
   • institution.sfx_base / remote_auth_base / proxy_suffix — the user's library's own endpoints. Ask the user for these, or help them find them — the four off-campus families and where each value hides are in docs/library-setup.md. Do NOT reuse endpoints from anywhere else.
3. Help the user store their own credentials in the local secret store (see README). Never put credential values in config.yaml or anywhere in the repo.
4. Verify layer 1 before touching anything else — this is your smoke test:

   python paper_fetch.py 10.1186/s12984-023-01168-x out.pdf   # a real OA article; must yield a PDF
   

   If that fails, the problem is config or network, not the library. Fix it here, not later.
5. Only then the proxy layer. As of v1.0 all route code (including the full LWW/Ovid flow) ships working — what remains is authentication config: set auth.family: form and point the selectors in config.yaml at the gate's login form (inspect it in devtools; EZproxy preset in docs/library-setup.md), plus auth.persist_cookies. Only SSO gates (OpenAthens/Shibboleth) need a custom login() implementation. Then:

   python library_session.py check                 # is the session alive?
   python library_session.py fetch <DOI> out.pdf   # a DOI the library definitely holds
   

6. Build the holdings table if the user has a library (docs/holdings.md). It is what makes step 7 possible.