pi-ads

A pi extension for querying NASA's Astrophysics Data System (ADS).

Provides three tools for searching papers, fetching paper details, and exploring citation graphs — all directly from your pi coding agent.

Setup

1. Get an ADS API token

1. Create a free account at ui.adsabs.harvard.edu and log in.
2. Go to Settings → Token and click "Generate a new key".

2. Set the environment variable

export ADS_API_TOKEN="your-token-here"

Add this to your ~/.bashrc, ~/.zshrc, or equivalent so it persists across sessions.

3. Install the package

pi install npm:@guanyilun/pi-ads

Or install from the GitHub repository:

pi install git:github.com/guanyilun/pi-ads

For a quick one-shot test without installing:

pi -e /path/to/pi-ads

Tools

ads_search — Search ADS papers

Search the full ADS database with fielded queries, filters, and sorting.

Parameters:

| Parameter | Type | Description | |---|---|---| | query | string | Required. Search query. Supports fielded syntax: title:exoplanets, author:"Spergel, D", keyword:"dark matter", year:2023, bibcode:2023ApJ...950L..12A, doi:10.3847/.... Unfielded terms search all metadata. Use quotes for phrases, +/- for inclusion/exclusion. | | database | string | Filter by database: astronomy, physics, or general. | | doctype | string | Filter by document type: article, proceedings, thesis, book, catalog, software, proposal. | | refereed | boolean | Filter to only peer-reviewed papers. | | year_from | string | Start year for date range, e.g. "2020". | | year_to | string | End year for date range, e.g. "2024". | | max_results | number | Max papers to return (default 10, max 50). | | sort_by | string | Sort order: relevance (default), date, citation_count, read_count. | | start | number | Pagination offset (default 0). | | detail | string | Output detail level: compact (default) or full. Compact shows title, first author, year, bibcode, citations — minimal context usage. Full includes abstract, all authors, keywords, DOI. |

Example prompts:

• "Search ADS for recent papers about fast radio bursts"
• "Find highly-cited papers about dark energy by Spergel, sorted by citation count"
• "Search for refereed articles about exoplanets in the astronomy database from 2023"
• "Find papers with 'transiting exoplanets' in the title, excluding Kepler"

ads_paper — Fetch a specific paper

Look up a paper by its ADS bibcode, DOI, or arXiv ID.

Parameters:

| Parameter | Type | Description | |---|---|---| | id | string | Required. ADS bibcode (2023ApJ...950L..12A), DOI (10.3847/2041-8213/acb7e0), or arXiv ID (arXiv:2301.01234). | | bibtex | boolean | Include BibTeX citation in the result (default false). |

Example prompts:

• "Look up bibcode 2023ApJ...950L..12A on ADS and give me the BibTeX"
• "Find the ADS entry for DOI 10.3847/2041-8213/acb7e0"
• "Fetch arxiv paper 2301.01234 from ADS"

ads_download_pdf — Download a paper's PDF

Download the PDF of a paper from ADS. Tries publisher → ADS → arXiv sources in fallback order.

Parameters:

| Parameter | Type | Description | |---|---|---| | id | string | Required. ADS bibcode, DOI, or arXiv ID (same resolution as ads_paper). | | output_path | string | File path to save the PDF. Defaults to {pdfDownloadDir}/{safeName}.pdf (see config below). If a directory is given, saves as {dir}/{safeName}.pdf. | | source | string | Preferred PDF source: auto (default, tries publisher → ADS → arXiv), publisher (PUB_PDF), ads (ADS_PDF), or arxiv (EPRINT_PDF). |

Example prompts:

• "Download the PDF for bibcode 2023ApJ...950L..12A"
• "Download the PDF for arxiv 2301.01234 and save it to ~/papers/"
• "Get the PDF for DOI 10.3847/2041-8213/acb7e0 from arxiv"

PDF sources:

• Publisher (PUB_PDF): Direct from the journal. May be behind a paywall.
• ADS (ADS_PDF): ADS-hosted scan. Available for many older papers.
• arXiv (EPRINT_PDF): arXiv preprint. Usually open access but may differ from published version.

Behavior notes:

• If the file already exists, the download is skipped and the existing file path is returned.
• Bibcode dots are replaced 1:1 with underscores in filenames: 2023ApJ...950L..12A → 2023ApJ___950L__12A.pdf. Since bibcodes never contain underscores, this is fully reversible.

Default download directory

Add to ~/.pi/agent/settings.json to configure a default download folder:

{
  "ads": {
    "pdfDownloadDir": "~/papers"
  }
}

When set, PDFs are saved to ~/papers/2023ApJ_950L_12A.pdf by default. Without this setting, the current working directory is used.

ads_citations — Explore citation graphs

Find papers that cite a given paper (forward citations) or that a given paper cites (backward references).

Parameters:

| Parameter | Type | Description | |---|---|---| | bibcode | string | Required. ADS bibcode of the paper. | | direction | string | citations (papers citing this one — default) or references (papers this one cites). | | max_results | number | Max papers to return (default 10, max 50). | | sort_by | string | Sort order: date (default), citation_count, or read_count. | | start | number | Pagination offset (default 0). | | detail | string | Output detail level: compact (default) or full. Compact shows title, first author, year, bibcode, citations — minimal context usage. Full includes abstract, all authors, keywords, DOI. |

Example prompts:

• "Find papers citing 2023ApJ...950L..12A"
• "Show me the references of 2019ARA&A..57..417P sorted by citation count"
• "What are the most-cited papers that cite bibcode 2020MNRAS.498.1424W?"

Advanced Query Syntax

The query parameter in ads_search supports the full ADS/Solr search syntax:

• Fielded search: title:exoplanets, author:"Hubble, E", abstract:"dark energy", keyword:"gravitational waves"
• Phrase search: "black holes" (use quotes for exact phrases)
• Boolean operators: "transiting exoplanets" +JWST -Kepler
• Date ranges: year:2023, year:[2020 TO 2024], pubdate:[2023-01-00 TO *]
• Wildcard: title:exoplanet*

Rate Limits

The ADS API allows 5,000 queries per day per token. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in API responses.

License

MIT