litreview-search 0.1.1

One-line multi-source academic literature review (11 free APIs)

litreview

One-line multi-source academic literature review using 11 free APIs — no paid subscriptions required.

Default run uses 9 sources (no API key). Add semantic_scholar or core with a free API key when you want them.

Install

pip install litreview-search

For Excel export (--excel):

pip install "litreview-search[excel]"

Note: The PyPI name litreview is taken by an unrelated legacy package. This project publishes as litreview-search. The CLI command is still litreview, and the Python import is still from litreview import review.

Install from GitHub (alternative):

pip install git+https://github.com/abdullahkarasan/litreview.git

Usage

Python

from litreview import review

papers, stats = review("federated learning privacy")

That's it. Results are saved as .json in the current folder.

Add excel=True (Python) or --excel (CLI) for a styled spreadsheet too.

papers, stats = review("federated learning privacy", excel=True)

litreview "federated learning privacy" --excel

Command line

litreview "federated learning privacy"

Multi-word and multiple topics

Multi-word queries (use quotes in the shell)

A topic with spaces is one search phrase, not separate keywords. Each API receives the full string (e.g. "federated learning privacy").

CLI — wrap the phrase in quotes so the shell passes it as a single argument:

litreview "federated learning privacy"
litreview "retrieval augmented generation"

Without quotes, only the first word is used:

litreview federated learning privacy   # searches "federated" only

Python — pass a normal string; no special quoting needed:

papers, stats = review("federated learning privacy")

Output filenames turn spaces into underscores: federated_learning_privacy.json.

Multiple topics — separate files (loop)

Call review() once per topic. Each run writes its own JSON (and optional Excel) file:

from litreview import review

topics = [
    "federated learning privacy",
    "differential privacy healthcare",
    "machine learning fairness",
]

for topic in topics:
    papers, stats = review(topic)

CLI equivalent:

for topic in "federated learning privacy" "differential privacy healthcare"; do
  litreview "$topic"
done

Multiple topics — one merged file (run_search)

To search several topics in a single run and save one combined JSON/Excel (with a Category column per topic), use Settings and run_search():

from pathlib import Path

from litreview.config import Settings
from litreview.pipeline import run_search

settings = Settings(
    output_basename="multi_topic_review",
    year_start=2020,
    year_end=2026,
    export_excel=True,
    required_title_terms=[],   # same open search as review()
    relevance_rag_terms=[],
    search_plans=[
        {"category": "Federated learning privacy", "default_query": "federated learning privacy"},
        {"category": "DP in healthcare", "default_query": "differential privacy healthcare"},
    ],
)

papers, stats = run_search(settings=settings, output_dir=Path("."))
# → multi_topic_review.json, multi_topic_review.xlsx

Each entry in search_plans needs a category (label in output) and default_query (search text). You can also set per-source queries, e.g. "arxiv": "federated learning", when a source needs different wording.

Options

papers, stats = review(
    "transformer attention mechanism",
    year_start=2022,          # default: 2020
    year_end=2026,            # default: 2026
    max_per_query=200,        # results per source, default: 100
    output_dir="results/",    # default: current directory
    excel=True,               # also save .xlsx, default: False
    sources=["semantic_scholar", "arxiv", "openalex"],
    debug=True,               # show live progress, default: True
)

litreview "CRISPR gene editing" --year-start 2022 --sources semantic_scholar arxiv
litreview "climate change AI" --output-dir ./results --excel --max 200 --no-debug

Sources

Source	Key	Notes
Semantic Scholar	semantic_scholar	Required SEMANTIC_SCHOLAR_API_KEY (free)
arXiv	arxiv	Free, no key needed
OpenAlex	openalex	Free, set OPENALEX_MAILTO for polite pool
Crossref	crossref	Free, set CROSSREF_MAILTO
Europe PMC	europe_pmc	Free
PubMed	pubmed	Optional NCBI_API_KEY + NCBI_EMAIL
DBLP	dblp	Free, CS-focused
DOAJ	doaj	Open access journals
HAL	hal	French open archive
Zenodo	zenodo	Free
CORE	core	Required CORE_API_KEY (free registration)

Output

Each run saves a JSON file named after your keyword:

• federated_learning_privacy.json — array of papers (Title, Authors, Year, Venue, Citations, Category, Source, DOI, URL, Abstract).

Optional Excel (--excel or excel=True):

• federated_learning_privacy.xlsx — styled spreadsheet with summary sheets by source and category.

Optional API Keys (environment variables)

export SEMANTIC_SCHOLAR_API_KEY=your_key   # required for --sources semantic_scholar
export CORE_API_KEY=your_key               # required for --sources core
export NCBI_API_KEY=your_key               # optional, faster PubMed
export NCBI_EMAIL=[e-mail]
export OPENALEX_MAILTO=[e-mail]     # polite pool (faster)
export CROSSREF_MAILTO=[e-mail]     # polite pool (faster)

When you include semantic_scholar or core in --sources, litreview prompts for the key if it is not already set (terminal only).

litreview "topic" --sources semantic_scholar arxiv
# prompts: Enter SEMANTIC_SCHOLAR_API_KEY:

litreview "topic" --sources semantic_scholar --semantic-scholar-key YOUR_KEY

License

MIT