Metadata-Version: 2.4
Name: litreview-search
Version: 0.1.1
Summary: One-line multi-source academic literature review (11 free APIs)
Author: Abdullah Karasan
License-Expression: MIT
Project-URL: Homepage, https://github.com/abdullahkarasan/litreview
Project-URL: Repository, https://github.com/abdullahkarasan/litreview
Project-URL: Bug Tracker, https://github.com/abdullahkarasan/litreview/issues
Keywords: literature-review,academic-search,research,pubmed,arxiv,semantic-scholar,openalex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: pyyaml>=6.0
Requires-Dist: arxiv>=2.1
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == "excel"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install litreview-search
```

For Excel export (`--excel`):

```bash
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):

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

## Usage

### Python

```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.

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

```bash
litreview "federated learning privacy" --excel
```

### Command line

```bash
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:

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

Without quotes, only the first word is used:

```bash
litreview federated learning privacy   # searches "federated" only
```

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

```python
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:

```python
from litreview import review

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

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

CLI equivalent:

```bash
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()`:

```python
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

```python
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
)
```

```bash
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)

```bash
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=you@example.com
export OPENALEX_MAILTO=you@example.com     # polite pool (faster)
export CROSSREF_MAILTO=you@example.com     # 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).

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

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

## License

MIT
