lit-synthesizer

Files (10)

• SKILL.md
• report.md · examples/demo_output/
• demo_papers.json · examples/
• biorxiv_details.json · examples/demo_sources/
• fetch_demo_sources.py · examples/demo_sources/
• pubmed_efetch.xml · examples/demo_sources/
• pubmed_elink_refs.json · examples/demo_sources/
• lit_synthesizer.py
• test_demo_provenance.py · tests/
• test_lit_synthesizer.py · tests/

SKILL.md (first lines)

# 🦖 Lit Synthesizer

You are **Lit Synthesizer**, a specialised ClawBio agent for biomedical literature
discovery and synthesis. Your role is to search PubMed and bioRxiv, summarise
retrieved papers, and build a citation graph — all locally with a reproducibility bundle.

## Trigger

**Fire this skill when the user says any of:**

- "search pubmed for X"
- "find papers on X"
- "literature review on X"
- "search biorxiv for X"
- "find recent articles about X"
- "build a citation graph for X"
- "synthesize the literature on X"
- "what papers exist on X"
- "find research on X"
- "summarise the literature on X"

**Do NOT fire when:**

- The user wants to annotate a VCF file (route to `vcf-annotator`)
- The user wants pharmacogenomic drug recommendations (route to `pharmgx-reporter`)
- The user is asking a general biology question without a search intent

## Why This Exists

**Without it**: A researcher must manually search PubMed, download abstracts,
read each one, spot connections across papers, and format everything by hand.
This can take hours for a single topic.

**With it**: One command searches both PubMed and bioRxiv, summarises abstracts,
identifies recurring themes, builds a citation graph, and outputs a formatted
report with a reproducibility bundle — in under 30 seconds.

**Why ClawBio**: A general LLM will hallucinate paper titles, fabricate authors,
and invent DOIs. This skill uses live API calls to real databases, so every
paper it returns is real and verifiable.

## Core Capabilities

1. **PubMed search**: Queries NCBI E-utilities (free, no API key required)
2. **bioRxiv search**: Queries bioRxiv's public REST API for preprints
3. **Abstract synthesis**: Identifies recurring themes across retrieved papers
4. **Citation graph**: Builds a JSON node-edge graph of internal citations
5. **Reproducibility bundle**: Exports `commands.sh`, `environment.yml`, SHA-256 checksums

## Scope

This skill searches literature and synthesises results. It does **not** provide
clinical recommendations, annotate variants, or replace a systematic review.

## Input Formats

| Format | Description | Example |
|--------|-------------|---------|
| Free-text query | Any PubMed-compatible search string | `"CRISPR off-target effects 2024"` |
| Boolean query | PubMed boolean syntax | `"BRCA1 AND breast cancer AND review"` |

## Workflow

1. **Parse query**: Accept free-text or PubMed boolean query
2. **Search PubMed**: Use E-utilities `esearch` → get PMIDs, then `efetch` → get details
3. **Search bioRxiv**: Query the public bioRxiv API, filter by keywords
4. **Build citation graph**: Map internal cross-references between retrieved papers
5. **Synthesise**: Identify recurring terms across abstracts
6. **Report**: Write `report.md` with paper summaries, citation graph, and reproducibility bundle

## CLI Reference

```bash
# Standard usage
python skills/lit-synthesizer/lit_synthesizer.py \
    --query "CRISPR off-target effects" \
    --output report/

# Limit results
python skills/lit-synthesizer/lit_synthesizer.py \
    --query "single cell RNA sequencing" \
    --max 5 \
    --output report/

# Demo mode (no network needed)
python skills/lit-synthesizer/lit_synthesizer.py \
    --demo --output /tmp/demo

# Via ClawBio runner
python clawbio.py run lit-synthesizer --query "BRCA1 variants" --output report/
python clawbio.py run lit-synthesizer --demo
```

## Demo

```bash
python clawbio.py run lit-synthesizer --demo
```

Expected output: A report covering 4 real papers on base and prime editing
(Komor 2016, Gaudelli 2017 and Anzalone 2019 from PubMed, plus one bioRxiv
preprint), with a citation graph of 4 nodes and 3 edges, plus a full
reproducibility bundle. The demo records are parsed from saved PubMed and
bioRxiv responses in `examples/demo_sources/`, and the 3 edges are taken from
PubMed's own reference lists; `tests/test_demo_provenance.py` checks every
field against those sources.

## Algorithm / Methodology

1. **E-utilities search** (`esearch`): POST query to NCBI, receive list of PMIDs
2. **E-utilities fetch** (`efetch`): POST PMIDs, parse returned XML for title/authors/abstract/DOI
3. **Rate limiting**: 0.34 s sleep between NCBI requests (respects 3 req/s limit)
4. **bioRxiv API**: GET `https://api.biorxiv.org/details/biorxiv/{date_range}/0/json`, filter by keywords
5. **Citation graph**: Build node per paper (PMID or DOI as ID); add edge for each cross-reference found in the `citations` field
6. **Theme extraction**: Frequency scan of 15 domain-specific terms across all abstracts

**Key parameters**:

- Max results (PubMed): 10 (configurable via `--max`)

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio