litsearch 0.1.0

Multi-source scholarly literature harvester with citation-graph expansion

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

Source	Notes
OpenAlex	Broad coverage, citation counts, citation graph
Europe PMC	Biomedical and public-health coverage, abstracts
Crossref	Widest DOI coverage
arXiv	Preprints
PubMed	NCBI; indexes some records the others miss
Semantic Scholar	Citation graph; used for DOI-based forward-citation

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

Option	Description
query	Search terms (positional).
--since YEAR	Earliest publication year.
--max N	Maximum results per source (default 100).
--sources LIST	Comma-separated subset of openalex,europepmc,crossref,arxiv,pubmed,semanticscholar.
--cited-by	Forward: add papers that cite the top hits.
--snowball	Backward: add the references of the top hits.
--seeds N	How many top hits to expand for --cited-by / --snowball (default 10).
--rank {relevance,citations}	Ranking mode (default relevance).
--min-relevance X	Drop records below this query-term match (default 0.15; 0 disables).
--out BASENAME	Output basename; writes BASENAME.md and BASENAME.csv (default litsearch_results).

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.