Metadata-Version: 2.4
Name: litreview-search
Version: 0.1.0
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"
```

### 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
