@fbraza/pi-cite

A standalone Pi extension providing literature-research tools for academic workflows. Registers three tools callable by the agent:

• literature_search — literature workflow search against PubMed using a PubMed-ready query (MeSH [mh], [tiab], [pt], substance [nm], and Boolean logic), with streaming progress and deduplicated results. When a Zotero API key is configured, PubMed candidates are automatically cross-checked against your Zotero library and flagged with in_zotero (read-only — no library writes).
• pubmed_search — direct PubMed query (MeSH, [tiab], [pt], etc.).
• zotero_search — keyword search of your Zotero library (title/creators/year, and indexed full text when qmode=everything); returns metadata and abstracts of papers you already own.

Bundled skill

Ships with the literature skill (skills/literature/), which turns these tools into an end-to-end review workflow: verified-citation search, per-paper experiment extraction, and a structured hypothesis synthesis. Its frontmatter declares allowed-tools covering the extension's tools above, so the skill and extension are paired on purpose.

• references/ — PubMed query syntax, API reference, and common queries.
• scripts/ — Python helpers (extract_experiments.py, synthesis.py, generate_table.py, export_all.py) invoked by the skill.

Install

Published on npm as @fbraza/pi-cite:

# install into your user pi settings
pi install npm:@fbraza/pi-cite

# pin a specific version
pi install npm:@fbraza/[email protected]

# or try it for the current run only (no settings change)
pi -e npm:@fbraza/pi-cite

Pi provides the host packages (@earendil-works/pi-coding-agent, @earendil-works/pi-tui, typebox) at runtime, so they are declared as peer dependencies and are not bundled.

Develop

npm install
npm test            # run the unit tests
npm run pack:check  # preview the published tarball contents

Environment variables

| Variable | Purpose | |---|---| | NCBI_API_KEY / api_key env | PubMed rate limit + E-utilities auth | | ZOTERO_API_KEY | The only Zotero var you need to set. Enables the in_zotero ownership check in literature_search and the zotero_search tool. The library user ID is auto-discovered from the key via /keys/current, so no ID is required for a personal library. | | ZOTERO_USER_ID | Optional override for the user ID (auto-discovered otherwise). Only set if /keys/current does not return the expected ID. | | ZOTERO_LIBRARY | user (default) or group. Set to group only to scan a group library instead of your personal one. | | ZOTERO_GROUP_ID | Group library ID (required only when ZOTERO_LIBRARY=group — a key can access many groups, so there is no default). |

For the common case — a personal Zotero library — set just ZOTERO_API_KEY and you're done. The ownership scan fetches top-level library items (capped at ~2000) and matches PubMed candidates by DOI, PMID, PMCID, or title-year. All Zotero access is read-only; no papers are ever written to your library.