Metadata-Version: 2.4
Name: litsearch
Version: 0.1.0
Summary: Multi-source scholarly literature harvester with citation-graph expansion
Author: Amir Mostaghimi
License-Expression: MIT
Project-URL: Homepage, https://github.com/amir-b-mostaghimi/Lit_Synth
Project-URL: Repository, https://github.com/amir-b-mostaghimi/Lit_Synth
Project-URL: Issues, https://github.com/amir-b-mostaghimi/Lit_Synth/issues
Keywords: literature,bibliometrics,citation,openalex,semantic-scholar,pubmed,crossref,arxiv,systematic-review
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Dynamic: license-file

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

```bash
pip install litsearch
```

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

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

```bash
litsearch "QUERY" --since YEAR
```

Examples:

```bash
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](LICENSE).
