How to integrate Zotero¶

Zotero is the bridge between your human curation and the stack: you save papers manually, the stack uses them as a priority source. This guide covers setup and daily use.

Codina principle (UPF)

The human curates, the AI executes. When you run find_top_sources --prefer-zotero, the stack prioritizes YOUR library over external APIs.

One-time setup¶

1. Create account and API key¶

Account: zotero.org/user/register (free tier: 300 MB).
API key: zotero.org/settings/keys → Create new private key.
Allow library access ✓
Allow write access ✓ (to add from DOI)
User ID: on the same page it shows "Your userID for use in API calls is XXXXXXX" (7-8 digits).

2. Add credentials to `.env`¶

ZOTERO_API_KEY=your_key_here
ZOTERO_USER_ID=your_number_here

Never in .env.example

.env.example is public. No inline comments — they go with # on separate lines.

3. Verify connection¶

python tools/zotero_sync.py --list

Items: 0 is normal if you just created the account.

Daily use¶

Save while reading¶

Install the Zotero Connector (Chrome/Firefox/Edge/Safari). One click saves full metadata + PDF. Works with Google Scholar, ScienceDirect, Springer, IEEE Xplore, arXiv, PubMed, and more.

Quick reference commands¶

Command	What it does
`zotero_sync.py --list`	List library items
`zotero_sync.py --export FILE.bib`	Export to BibTeX
`zotero_sync.py --search "query"`	Search the library
`zotero_sync.py --add-doi DOI`	Add paper from DOI
`zotero_sync.py --sync`	Bidirectional sync (on conflict, Zotero wins)
`find_top_sources.py --prefer-zotero`	Prioritize the library in ranking

Prioritize Zotero in source search¶

python tools/find_top_sources.py --claim "SHM digital twin" --prefer-zotero

Flow: searches YOUR library first; if a match with sim ≥ 0.4 → uses that source with score 1.0; otherwise falls back to the normal flow (OpenAlex + Scopus + Semantic Scholar + CrossRef).

Troubleshooting¶

HTTP 403 on --list

Invalid API key or no read permissions. Check "Allow library access" in settings/keys.

--add-doi fails with 403

The key lacks Allow write access. Edit the key and enable it.

Items: 0 even though I uploaded papers

Zotero cache (TTL 1h). Force refresh: rm -rf .cache/zotero/ && python tools/zotero_sync.py --list.

Better BibTeX (pro level)¶

For professional use, install the Better BibTeX plugin: stable citation keys (author_year), real-time auto-export, LaTeX integration.