sragent

What this skill does

# SRAgent: Sequence Read Archive Data and Publication Retrieval

## Overview

SRAgent is an agentic workflow system for working with the NCBI Sequence Read Archive (SRA) and Gene Expression Omnibus (GEO) databases.
It automates literature discovery, metadata extraction, and manuscript retrieval for genomics datasets.

## Setup Instructions

### 1. Install SRAgent

SRAgent requires Python ≥3.11. Check to see if SRAgent is already installed:
```bash
which SRAgent
```

If SRAgent is not installed, follow the instructions below.

Install using `uv`:

```bash
# Clone the repository
git clone https://github.com/ArcInstitute/SRAgent.git
cd SRAgent

# Create and activate virtual environment with uv
uv venv
source .venv/bin/activate

# Install the package
uv pip install .
```

Verify installation:
```bash
SRAgent --help
```

### 2. Configure environment variables

The following environment variables are required:
- `OPENAI_API_KEY=sk-openai-...`
  - Needed to use OpenAI models
- `ANTHROPIC_API_KEY=sk-ant-...`
  - Needed to use Claude models
- `DYNACONF`
  - Needed to switch between Claude and OpenAI models
- `[email protected]`
  - Needed for using the Entrez API
- `NCBI_API_KEY=your-ncbi-key`
  - Optional for increased rate limits when using the Entrez API
- `CORE_API_KEY=your-core-key`
  - Optional for paper downloads from the CORE API
- `GCP_PROJECT_ID=your-project-id`
  - Needed for using Google BigQuery
- `GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json`
  - Needed for using Google BigQuery

Prompt the user to provide the environment variables if they are not already set as environment variables: `export MY_SECRET_VAR=my-secret-value`.

### 3. Configure Settings

SRAgent uses a settings file (`settings.yml`) to configure models and behavior.
The default configuration works for most users, but you can customize it.

#### Option A: Use Default Settings
No action needed - SRAgent ships with sensible defaults.

#### Option B: Custom Settings File

See `./references/example-settings.yml` for an example settings file that you can modify as needed.

### 4. Verify Setup

Test your configuration:

```bash
# Check which model is being used
python -c "from SRAgent.agents.utils import load_settings; s = load_settings(); print(s['models']['default'])"

# Test basic functionality
SRAgent entrez "Convert GSE121737 to SRX accessions"
```

## Core Capabilities

### 1. Accession Conversion
Convert between different genomics database accession formats:
- **GEO Series:** GSE* → SRA Study (SRP*)
- **SRA Study:** SRP*/PRJNA* → SRA Experiments (SRX*)
- **SRA Experiment:** SRX*/ERX* → SRA Runs (SRR*/ERR*)

### 2. Metadata Extraction
Query comprehensive metadata from SRA/GEO:
- Sequencing platform (Illumina, PacBio, Oxford Nanopore)
- Library preparation technology (10X Genomics, Smart-seq, etc.)
- Organism, tissue, cell type
- Study design and experimental details
- Single-cell vs bulk RNA-seq identification

### 3. BigQuery Analysis
Leverage NCBI's BigQuery dataset for large-scale queries:
- Batch accession conversions
- Technology identification across studies
- Filtering by platform, assay type, organism
- Study/experiment/run relationship mapping

### 4. Publication Retrieval
Automatically find and download manuscripts:
- Link SRA accessions to PubMed publications
- Extract DOIs from PubMed records
- Download full-text PDFs from multiple sources:
  - Preprint servers (arXiv, bioRxiv, medRxiv)
  - CORE API
  - Europe PMC
  - Unpaywall
- Batch processing with CSV input

## When to Use This Skill

Use SRAgent when the user:
- Mentions SRA, GEO, or genomics accessions (GSE, SRP, SRX, SRR)
- Needs to convert between accession formats
- Wants metadata about sequencing experiments
- Needs to find or download papers associated with datasets
- References the Sequence Read Archive (SRA), European Nucleotide Archive (ENA), or Gene Expression Omnibus (GEO)

## Available Commands

### Command 1: `SRAgent entrez`
**Purpose:** Low-level NCBI Entrez database queries

**Best for:**
- Simple accession conversions
- Quick dataset summaries
- Cross-database linking
- When you know exactly what Entrez tool to use (esearch, efetch, elink)

**Examples:**
```bash
# Convert GEO to SRX
SRAgent --no-progress --no-summaries entrez "Convert GSE121737 to SRX accessions"

# Summarize a dataset
SRAgent --no-progress --no-summaries entrez "Summarize SRX4967527"

# Link to publications
SRAgent --no-progress --no-summaries entrez "Find publications for GSE196830"
```

### Command 2: `SRAgent sragent`
**Purpose:** Comprehensive metadata extraction with multiple tools

**Best for:**
- Complex metadata queries
- Technology identification
- When simple Entrez queries aren't enough
- Determining if data is single-cell

**Tools available:**
- Entrez agent (all databases)
- BigQuery (large-scale queries)
- NCBI web scraping
- sra-stat (direct sequence file analysis)

**Examples:**
```bash
# Check sequencing technology
SRAgent --no-progress --no-summaries sragent "Which 10X Genomics technology was used for ERX11887200?"

# Comprehensive summary
SRAgent --no-progress --no-summaries sragent "Summarize SRX4967527"

# Verify data type
SRAgent --no-progress --no-summaries sragent "Is SRX4967527 single-cell RNA-seq data?"

# Get organism info
SRAgent --no-progress --no-summaries sragent "What organism was sequenced in study PRJNA498286?"
```

### Command 3: `SRAgent papers`
**Purpose:** Find and download manuscripts associated with SRA accessions

**Best for:**
- Downloading papers for datasets
- Batch retrieval of publications
- Enriching CSV files with DOIs and download paths

**Input formats:**
- Single accession: `SRX4967527`
- Study accession: `SRP167700` or `PRJNA498286`
- CSV file with `accession` column

**Examples:**
```bash
# Single experiment
SRAgent --no-progress --no-summaries papers SRX4967527

# Entire study
SRAgent --no-progress --no-summaries papers PRJNA498286

# Batch from CSV
SRAgent --no-progress --no-summaries papers accessions.csv --output-dir papers/

# Custom accession column name
SRAgent --no-progress --no-summaries papers my-data.csv --accession-column "experiment_id"

# Control concurrency
SRAgent --no-progress --no-summaries papers accessions.csv --max-concurrency 3
```

**Output:**
- PDFs saved to `--output-dir/<accession>/`
- Console summary showing:
  - PubMed IDs found
  - DOIs extracted
  - Download success/failure status
- Updated CSV (when input is CSV) with columns:
  - `pubmed_id`
  - `doi`
  - `download_path`

## Usage Patterns

### Pattern 1: Dataset Investigation Workflow
```bash
# Step 1: Convert GEO accession to SRX
SRAgent --no-progress --no-summaries entrez "Convert GSE121737 to SRX accessions"

# Step 2: Get detailed metadata
SRAgent --no-progress --no-summaries sragent "For each SRX from GSE121737, determine: Is it single-cell? What library prep?"

# Step 3: Find associated publications
SRAgent --no-progress --no-summaries papers GSE121737 --output-dir manuscripts/
```

### Pattern 2: Technology Verification
```bash
# Check if dataset meets specific criteria
SRAgent --no-progress --no-summaries sragent "Is SRX4967527 Illumina paired-end single-cell RNA-seq data?"

# Get specific technology details
SRAgent --no-progress --no-summaries sragent "Which 10X Genomics chemistry was used: SRX4967527?"

# Verify organism
SRAgent --no-progress --no-summaries sragent "What organism is SRX4967527?"
```

### Pattern 3: Batch Processing
```bash
# Create CSV with accessions
cat > accessions.csv << EOF
accession
SRX4967527
SRX4967528
SRX4967529
EOF

# Download all papers
SRAgent --no-progress --no-summaries \
  papers accessions.csv \
    --output-dir papers/ \
    --max-concurrency 5

# Result: CSV enriched with DOIs and download paths
```

### Pattern 4: Study-Level Analysis
```bash
# Get all experiments in a study
SRAgent --no-progress --no-summaries entrez "List all SRX accessions for study SRP167700"

# Or use a BioProject accession
SRAgent --no-progress --no-summaries entrez "