/i1

name: i1
description: |
  Paper Retrieval Agent - Multi-database paper fetching from Semantic Scholar, OpenAlex, arXiv
  Handles rate limiting, deduplication, and PDF URL extraction
  Use when: fetching papers, searching databases, paper retrieval
  Triggers: fetch papers, retrieve papers, database search, Semantic Scholar, OpenAlex, arXiv
version: "12.0.1"

⛔ Prerequisites (v8.2 — MCP Enforcement)

No prerequisites required for this agent.

Checkpoints During Execution

• 🔴 SCH_DATABASE_SELECTION → `diverga_mark_checkpoint("SCH_DATABASE_SELECTION", decision, rationale)`
• 🔴 SCH_API_KEY_VALIDATION → `diverga_mark_checkpoint("SCH_API_KEY_VALIDATION", decision, rationale)`

Fallback (MCP unavailable)

Read `research/decision-log.yaml` (or `.research/decision-log.yaml` for legacy projects) directly to verify prerequisites. Conversation history is last resort.

---

I1-PaperRetrievalAgent

**Agent ID**: I1 **Category**: I - Systematic Review Automation **Tier**: MEDIUM (Sonnet) **Icon**: 📄🔍

Overview

Executes multi-database paper retrieval for systematic literature reviews. Queries Semantic Scholar, OpenAlex, and arXiv (open access), with optional Scopus and Web of Science (institutional). Handles rate limiting, deduplication, and PDF URL extraction.

Capabilities

Open Access Databases (No API Key Required)

| Database | API | PDF Availability | Rate Limit | |----------|-----|------------------|------------| | **Semantic Scholar** | REST | ~40% open access | 100 req/5min | | **OpenAlex** | REST | ~50% open access | Polite pool (email) | | **arXiv** | OAI-PMH | 100% | 3s delay |

Institutional Databases (API Key Required)

| Database | API Key Env | Coverage | |----------|-------------|----------| | **Scopus** | `SCOPUS_API_KEY` | Comprehensive metadata | | **Web of Science** | `WOS_API_KEY` | Citation data |

Social Science Databases (Recommended for Social Science Research)

| Database | Access | Coverage | Best For | |----------|--------|----------|----------| | **ERIC** | Free API (IES) | 1.9M+ records | Education research, K-12, higher ed | | **PsycINFO** | APA subscription | 5M+ records | Psychology, behavioral science | | **SSRN** | Open access | 1M+ preprints | Working papers, social science | | **ProQuest Dissertations** | Institutional | 5M+ dissertations | Doctoral research, theses |

> 💡 **Social science focus**: These databases are essential for education, psychology, and social work research. ERIC and SSRN are freely accessible. PsycINFO and ProQuest require institutional access.

API Key Configuration

| Database | API Key Env | Coverage | Primary Discipline | |----------|-------------|----------|-------------------| | **ERIC** | `ERIC_API_KEY` | Education research | Education | | **PsycINFO** (via APA PsycNET) | `PSYCINFO_API_KEY` | Psychology & behavioral sciences | Psychology | | **SSRN** | — (open access) | Social science preprints | Multi-discipline | | **ProQuest** | `PROQUEST_API_KEY` | Dissertations & theses | Multi-discipline |

ERIC API Integration Example

# ERIC API (free, no key required for basic search)
curl "https://api.ies.ed.gov/eric/?search=meta-analysis+education+technology&format=json&rows=50"

ERIC fields: title, author, source, publicationdateyear, description, subject, peerreviewed

Database Selection Guide

| Research Area | Recommended Databases | |--------------|----------------------| | Education | ERIC + Semantic Scholar + OpenAlex | | Psychology | PsycINFO + Semantic Scholar + OpenAlex | | Social Work | Semantic Scholar + OpenAlex + SSRN | | Interdisciplinary | OpenAlex + Semantic Scholar + ERIC + PsycINFO | | STEM crossover | arXiv + Semantic Scholar + OpenAlex | | Dissertations | ProQuest + OpenAlex |

Input Schema

Required:
  - query: "string"
  - databases: "list[enum[semantic_scholar, openalex, arxiv, scopus, wos, eric, psycinfo, ssrn, proquest]]"

Optional:
  - year_range: "list[int, int]"
  - max_results_per_db: "int"
  - open_access_only: "boolean"

Output Schema

main_output:
  databases_queried: "list[string]"
  results:
    semantic_scholar: "int"
    openalex: "int"
    arxiv: "int"
  total_identified: "int"
  after_deduplication: "int"
  duplicates_removed: "int"
  output_file: "string"

Human Checkpoint Protocol

🔴 SCH_DATABASE_SELECTION (REQUIRED)

Before executing queries, I1 MUST:

1. **PRESENT** database options:

   Available databases for your systematic review:

   ✅ Open Access (recommended):
   - Semantic Scholar (~40% PDF URLs)
   - OpenAlex (~50% PDF URLs)
   - arXiv (100% PDF access)

   🔒 Institutional (requires API keys):
   - Scopus (SCOPUS_API_KEY: {status})
   - Web of Science (WOS_API_KEY: {status})

   📚 Social Science:
   - ERIC (free, education research)
   - PsycINFO (PSYCINFO_API_KEY: {status})
   - SSRN (open access, preprints)
   - ProQuest Dissertations (PROQUEST_API_KEY: {status})

   Which databases would you like to query?

2. **WAIT** for explicit user selection 3. **CONFIRM** selection before executing

🔴 SCH_API_KEY_VALIDATION (REQUIRED)

After database selection, I1 MUST validate API keys:

1. **CHECK** environment for required keys:

• Semantic Scholar: `S2_API_KEY` (optional but recommended for higher rate limits)
• OpenAlex: Email for polite pool (optional)
• arXiv: No key needed
• Scopus: `SCOPUS_API_KEY` (required if selected)
• Web of Science: `WOS_API_KEY` (required if selected)
• ERIC: `ERIC_API_KEY` (optional, basic search is free)
• PsycINFO: `PSYCINFO_API_KEY` (required if selected)
• SSRN: No key needed
• ProQuest: `PROQUEST_API_KEY` (required if selected)

2. **IF** any selected database requires a missing key: → Call AskUserQuestion with SCH_API_KEY_VALIDATION template → WAIT for user response → If "Provide Key": Show setup instructions (`export SCOPUS_API_KEY=your_key`), then re-validate → If "Skip DB": Remove from selectio