Ar9av/PaperOrchestra / skills/literature-review-agent
literature-review-agent
UnverifiedStep 3 of the PaperOrchestra pipeline (arXiv:2604.05018). Execute the literature search strategy from outline.json — discover candidate papers via web search, verify them through Semantic Scholar (Levenshtein > 70 fuzzy title match, temporal cutoff, dedup by paperId), cross-corroborate against Crossref + OpenAlex to flag hallucinated citations, build a BibTeX file, and draft Introduction + Related Work using ≥90% of the verified pool. Runs in parallel with the plotting-agent. TRIGGER when the orchestrator delegates Step 3 or when the user asks to "find citations for my paper", "draft the related work", or "build the bibliography".
references/s2-api-cookbook.md
View on GitHub# Semantic Scholar API Cookbook
How to verify a candidate paper via the Semantic Scholar Graph API.
Base: `https://api.semanticscholar.org/graph/v1`
Reference: <https://api.semanticscholar.org/api-docs/graph>
## API key (optional)
The pipeline uses the **public, unauthenticated endpoint** by default — no key
required. If you have a Semantic Scholar API key you can pass it via the
`x-api-key` header to get higher rate limits (useful for large batches).
Get a free key at <https://api.semanticscholar.org/> then export it once:
```bash
export SEMANTIC_SCHOLAR_API_KEY="your-key-here"
```
The bundled `scripts/s2_search.py` helper picks this up automatically. If the
variable is not set the script falls back to the unauthenticated endpoint — the
pipeline works fine either way; just keep to ≤1 QPS on live requests.
```bash
# check whether the key is configured
python skills/literature-review-agent/scripts/s2_search.py --check-key
# search by title (key used automatically if set)
python skills/literature-review-agent/scripts/s2_search.py \
--query "Attention is All You Need" --limit 5
# print the raw S2 JSON
python skills/literature-review-agent/scripts/s2_search.py \
--query "BERT pre-training" --raw
```
The repo never commits a key. Key management is your responsibility (shell
environment, 1Password, doppler, etc.).
## Endpoint 1 — Search by title
```
GET /paper/search
?query=<URL-encoded title>
&limit=5
&fields=title,abstract,year,authors,venue,externalIds
```
Example:
```
GET https://api.semanticscholar.org/graph/v1/paper/search?query=Attention%20Is%20All%20You%20Need&limit=5&fields=title,abstract,year,authors,venue,externalIds
```
Response (truncated):
```json
{
"total": 12345,
"data": [
{
"paperId": "204e3073870fae3d05bcbc2f6a8e263d9b72e776",
"title": "Attention is All you Need",
"abstract": "The dominant sequence transduction models are based on...",
"year": 2017,
"venue": "NeurIPS",
"authors": [{"name": "Ashish Vaswani"}, ...],
"externalIds": {
"DBLP": "conf/nips/VaswaniSPUJGKP17",
"ArXiv": "1706.03762",
"DOI": "10.5555/3295222.3295349"
}
},
...
]
}
```
## Endpoint 2 — Get a specific paper by ID
```
GET /paper/<paperId>?fields=title,abstract,year,authors,venue,externalIds,citationCount
```
## Useful identifiers
You can pass these as `<paperId>`:
- S2 internal: `204e3073870fae3d05bcbc2f6a8e263d9b72e776`
- DOI: `DOI:10.18653/v1/N18-3011`
- ArXiv: `ARXIV:1706.03762`
- Corpus ID: `CorpusId:13756489`
- URL: `URL:https://arxiv.org/abs/1706.03762`
## Rate limits
- Unauthenticated: ~1 QPS sustained. Bursts will get 429.
- Per the paper, "the strict throughput limits of the Semantic Scholar API
(1 query per second)" — App. B.
If you get HTTP 429, sleep 5 seconds before retrying. Don't loop tightly.
## Fields cheat sheet
| Field | Type | Required by our pipeline? |
|---|---|---|
| `paperId` | string | yes (dedup key) |
| `title` | string | yes (Levenshtein match) |
| `abstract` | string | yes (rule 2: must exist) |
| `year` | int | yes (cutoff check) |
| `authors[].name` | string | yes (BibTeX author field) |
| `venue` | string | recommended (BibTeX journal/booktitle) |
| `externalIds.DOI` | string | recommended (dedup fallback, BibTeX doi) |
| `externalIds.ArXiv` | string | recommended (dedup fallback) |
| `publicationDate` | string `YYYY-MM-DD` | optional (more precise cutoff check) |
| `citationCount` | int | optional (could inform tie-breaking) |
Always pass `fields=...` explicitly — the default response is minimal and
will not include the abstract.
## Error handling
| Status | Meaning | What to do |
|---|---|---|
| 200 | OK | proceed |
| 400 | bad query syntax | URL-encode the title properly; retry once |
| 404 | not found | discard the candidate |
| 429 | rate limited | sleep 5s, retry |
| 500-503 | S2 down | sleep 30s, retry up to 3 times, then give up |
## Polite use
The S2 API is a public service. Do not hammer it. If you have many candidates:
- Throttle to 1 QPS.
- Cache hits (the dedup script already serves as a deduplication cache).
- Do not parallelize. Verification is sequential by design.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |