Lit_Synth

A command-line, multi-source literature harvester. It queries several free scholarly APIs, merges and de-duplicates the results, ranks them by relevance, and writes a Markdown report plus a CSV table. It can also expand a search along the citation graph in both directions: papers that cite your top hits (forward), and the references of your top hits (backward).

Sources

None require an API key. Semantic Scholar works without a key but is rate-limited; set S2_API_KEY for higher, steadier limits.

Features

• Multi-source query with de-duplication by DOI or normalized title.
• Relevance ranking (query-term match, title-weighted) with a citation tie-break.
• Forward-citation expansion (--cited-by): papers that cite your top hits, unioning the OpenAlex and Semantic Scholar citation graphs so citers that a single graph misses are still found.
• Backward-citation expansion (--snowball): the references of your top hits.
• Retraction flagging (via OpenAlex and PubMed).
• Year filtering and per-source result caps.
• Markdown and CSV output.

Requirements

• Python 3.9 or newer
• requests

Installation

From PyPI:

pip install litsearch

This installs the litsearch command. To run from a source checkout instead:

git clone https://github.com/amir-b-mostaghimi/Lit_Synth.git
cd Lit_Synth
pip install -e .

Configuration (optional)

Both are optional environment variables. Copy .env.example to .env and fill them in, or export them in your shell.

• LITSEARCH_EMAIL - a contact email for the OpenAlex and Crossref "polite pool" (faster, steadier responses).
• S2_API_KEY - a Semantic Scholar API key for higher rate limits.

Usage

After installation, use the litsearch command (from a source checkout, use python litsearch.py instead):

litsearch "QUERY" --since YEAR

Examples:

litsearch "graph neural networks molecules" --since 2020
litsearch "active learning drug discovery" --since 2022 --cited-by --seeds 4
litsearch "bayesian optimal experimental design" --sources arxiv,openalex

Keep queries to two or three content words. Long queries degrade to zero results on several sources (arXiv in particular ANDs the terms together).

Options

Output

Each run writes two files:

• <out>.md - a ranked, human-readable report (title, year, venue, citation count, authors, DOI, open-access link, abstract), with retractions flagged.
• <out>.csv - the same records as a table for spreadsheets or downstream code.

Notes and limitations

• Relevance ranking is lexical (keyword match), not semantic; work that uses different vocabulary can be missed.
• The keyless Semantic Scholar pool returns HTTP 429 under load; the client backs off and retries, and an API key removes most of this.
• This is a discovery aid, not a systematic review.

License

MIT. See LICENSE.