literature-review

# Literature Review Help write academic literature reviews using a multi-engine search integration (S2, OA, CR, PM). ## Capabilities - **Multi-Source Search**: Find relevant academic papers using Semantic Scholar (S2), OpenAlex (OA), Crossref (CR), and PubMed (PM). - **Full Abstracts**: All sources now return complete abstracts (PubMed uses `efetch` for full XML records). - **DOI Extraction**: DOIs are extracted from all sources for cross-referencing and deduplication. - **Automatic Deduplication**: When searching multiple sources (`--source all` or `--source both`), results are automatically deduplicated by DOI. - **Polite Access**: Automatic email identification for OpenAlex/Crossref "Polite Pool" (via `USER_EMAIL` env var). - **Abstract Reconstruction**: Reconstructs abstracts from OpenAlex inverted index format. - **Synthesis**: Group papers by theme and draft review sections based on metadata. ## Environment Variables | Variable | Purpose | Default | |----------|---------|---------| | `USER_EMAIL` | Email for polite API access | `anonymous@example.org` | | `CLAWDBOT_EMAIL` | Fallback if USER_EMAIL not set | — | | `SEMANTIC_SCHOLAR_API_KEY` | Optional S2 API key for higher rate limits | — | | `OPENALEX_API_KEY` | Optional OpenAlex API key | — | ## Workflows ### 1. Broad Search (All Bases) Get a comprehensive overview from all major academic databases. Results are automatically deduplicated by DOI. ```bash python3 scripts/lit_search.py search "impact of glycyrrhiza on bifidobacterium" --limit 5 --source all ``` ### 2. Targeted Search - **OpenAlex** (`oa`): Fast and comprehensive, good abstracts. - **Semantic Scholar** (`s2`): High-quality citation data and TL;DRs. - **Crossref** (`cr`): Precise DOI-based metadata (no abstracts). - **PubMed** (`pm`): Gold standard for biomedical research, full abstracts and PMIDs. ```bash python3 scripts/lit_search.py search "prebiotic effects of liquorice" --source pm ``` ### 3. Comparing Sources Search both S2 and OA simultaneously to ensure nothing is missed. Deduplicated by default. ```bash python3 scripts/lit_search.py search "Bifidobacterium infantis growth" --source both ``` ### 4. Getting Full Details (S2) Retrieve detailed metadata including TL;DR summaries. ```bash python3 scripts/lit_search.py details "DOI:10.1016/j.foodchem.2023.136000" ``` ### 5. Writing the Review 1. **Extract**: Pull key findings from the abstracts found. 2. **Organize**: Group findings into a logical structure (e.g., chronological or thematic). 3. **Draft**: Use the "Think step-by-step" approach to synthesize multiple sources into a coherent narrative. ## Output Format Each result includes: - `id`: Source-specific identifier (PMID for PubMed, OpenAlex ID, S2 paper ID, DOI for Crossref) - `doi`: DOI when available (used for deduplication) - `title`: Paper title - `year`: Publication year - `authors`: List of author names - `abstract`: Full abstract text (when available) - `venue`: Journal or conference name - `citationCount`: Citation count (S2, OA) - `source`: Which database the result came from ## Tips for Success - **Citations**: Always cross-reference the DOI or PMID for accuracy in bibliography. - **Filtering**: Focus on papers with higher `citationCount` or recent years for a more modern review. - **PubMed for Medicine**: Use `--source pm` for the most reliable biomedical literature. - **Deduplication**: Multi-source searches automatically remove duplicates; use single sources if you need raw counts.