research-lookup · diff
git:20260611.c1150bd to git:20260704.afa84b4
132 added, 432 removed. Audit B to B.
---
name: research-lookup
- description: 'Look up current research information using parallel-cli search (primary, fast web search), the Parallel Chat API (deep research), or Perplexity sonar-pro-search (academic paper searches). Automatically routes queries to the best backend. Use for finding papers, gathering research data, and verifying scientific information. Note: query text is transmitted to api.parallel.ai (PARALLEL_API_KEY) and, for academic searches, to openrouter.ai (OPENROUTER_API_KEY).'
+ description: 'Look up current research and scientific information across three backends: fast web search via parallel-cli (default), the Parallel Chat API for deep multi-source synthesis, and Perplexity sonar-pro-search for scholarly paper searches. Automatically routes each query to the best backend and saves every result to sources/ for reproducible citation. Use this whenever you need to find papers, gather statistics or market data, verify a scientific claim, collect citations, or research any topic for scientific/technical writing — even if the user does not say "research" explicitly. Note: query text is sent to api.parallel.ai (PARALLEL_API_KEY) and, for academic searches, to openrouter.ai (OPENROUTER_API_KEY).'
allowed-tools: Read Write Edit Bash
license: MIT license
compatibility: parallel-cli required (primary); PARALLEL_API_KEY and OPENROUTER_API_KEY optional for deep/academic backends
required_environment_variables: [{"name": "PARALLEL_API_KEY", "prompt": "Parallel web search API key.", "required_for": "optional features"}, {"name": "OPENROUTER_API_KEY", "prompt": "OpenRouter API key (fallback model access).", "required_for": "optional features"}]
- metadata: {"version": "1.1", "skill-author": "K-Dense Inc.", "openclaw": {"primaryEnv": "PARALLEL_API_KEY", "envVars": [{"name": "PARALLEL_API_KEY", "required": false, "description": "Parallel web search API key."}, {"name": "OPENROUTER_API_KEY", "required": false, "description": "OpenRouter API key (fallback model access)."}]}}
+ metadata: {"version": "1.2", "skill-author": "K-Dense Inc.", "openclaw": {"primaryEnv": "PARALLEL_API_KEY", "envVars": [{"name": "PARALLEL_API_KEY", "required": false, "description": "Parallel web search API key."}, {"name": "OPENROUTER_API_KEY", "required": false, "description": "OpenRouter API key (fallback model access)."}]}}
---
# Research Information Lookup
- ## Overview
-
- This skill provides real-time research information lookup with **intelligent backend routing**:
-
- - **parallel-cli search** (parallel-web skill): **Primary and default backend** for all research queries. Fast, cost-effective web search with academic source prioritization. Uses `parallel-cli search` with `--include-domains` for scholarly sources.
- - **Parallel Chat API** (`core` model): Secondary backend for complex, multi-source deep research requiring extended synthesis (60s-5min latency). Use only when explicitly needed.
- - **Perplexity sonar-pro-search** (via OpenRouter): Used only for academic-specific paper searches where scholarly database access is critical.
-
- The skill automatically detects query type and routes to the optimal backend.
-
- ## When to Use This Skill
+ Real-time research lookup that routes each query to the backend best suited to it, then saves the result so every citation can be traced later.
- Use this skill when you need:
+ ## The three backends
- - **Current Research Information**: Latest studies, papers, and findings
- - **Literature Verification**: Check facts, statistics, or claims against current research
- - **Background Research**: Gather context and supporting evidence for scientific writing
- - **Citation Sources**: Find relevant papers and studies to cite
- - **Technical Documentation**: Look up specifications, protocols, or methodologies
- - **Market/Industry Data**: Current statistics, trends, competitive intelligence
- - **Recent Developments**: Emerging trends, breakthroughs, announcements
+ | Backend | Speed | Use it for | How to call |
+ |---------|-------|-----------|-------------|
+ | **`parallel-cli search`** (default) | 2–10 s | Almost everything: general research, market/industry data, technical lookups, current events, fact-checking, comparisons | `parallel-cli search` (direct) |
+ | **Perplexity sonar-pro-search** | 5–15 s | Scholarly paper searches where peer-reviewed database coverage matters (find papers, DOIs, systematic reviews) | `scripts/research_lookup.py --force-backend perplexity` |
+ | **Parallel Chat API** (`core` model) | 60 s–5 min | Deep, exhaustive multi-source synthesis — only when the user explicitly asks for "deep research" | `scripts/research_lookup.py --force-backend parallel` |
- ## Visual Enhancement with Scientific Schematics
+ > **Naming caution — there are two different "Parallel" things.**
+ > `parallel-cli search` is the fast web-search CLI (the default). The "Parallel Chat API (`core` model)" is a separate, slow deep-research endpoint reached only through `research_lookup.py`. `--force-backend parallel` selects the *slow* Chat API, **not** the fast CLI. Don't conflate them.
- **When creating documents with this skill, always consider adding scientific diagrams and schematics to enhance visual communication.**
+ Default to `parallel-cli search`. It is fast and cheap and handles the large majority of research needs. Reach for the other two only when the query specifically calls for scholarly paper coverage (Perplexity) or exhaustive synthesis (Chat API).
- If your document does not already contain schematics or diagrams:
- - Use the **scientific-schematics** skill to generate AI-powered publication-quality diagrams
- - Simply describe your desired diagram in natural language
+ ## When to use this skill
- ```bash
- python scripts/generate_schematic.py "your diagram description" -o figures/output.png
- ```
+ - **Current research**: latest studies, findings, and developments
+ - **Literature verification**: check facts, statistics, or claims against current sources
+ - **Background research**: gather context and evidence for scientific writing
+ - **Citations**: find relevant papers and studies to cite
+ - **Technical documentation**: specifications, protocols, methodologies
+ - **Market/industry data**: current statistics, trends, competitive intelligence
---
- ## Automatic Backend Selection
-
- The skill automatically routes queries to the best backend based on content:
-
- ### Routing Logic
+ ## Backend selection
```
Query arrives
|
- +-- Contains academic keywords? (papers, DOI, journal, peer-reviewed, etc.)
- | YES --> Perplexity sonar-pro-search (academic search mode)
+ +-- Asks for papers/DOIs/scholarly review? ("find papers", "cite", "systematic review", ...)
+ | --> Perplexity sonar-pro-search (scripts/research_lookup.py --force-backend perplexity)
|
- +-- Needs deep multi-source synthesis? (user says "deep research", "exhaustive")
- | YES --> Parallel Chat API (core model, 60s-5min)
+ +-- User explicitly wants deep/exhaustive/comprehensive research?
+ | --> Parallel Chat API (core) (scripts/research_lookup.py --force-backend parallel)
|
- +-- Everything else (general research, market data, technical info, analysis)
- --> parallel-cli search (fast, default)
+ +-- Everything else (the common case)
+ --> parallel-cli search (fast, default)
```
- ### Default: parallel-cli search (parallel-web skill)
+ `research_lookup.py` applies this same logic automatically when you give it a bare query (no `--force-backend`): it routes academic-keyword queries to Perplexity and everything else to the Parallel Chat API. Use it that way when you want auto-routing between the two API backends; use `parallel-cli search` directly when you want the fast default.
- **Primary backend for all standard research queries.** Fast, cost-effective, and supports academic source prioritization.
+ **Academic keywords that signal a paper search:** `find papers`, `research papers on`, `published studies`, `cite`, `citation`, `doi`, `pubmed`, `pmid`, `peer-reviewed`, `journal article`, `scholarly`, `arxiv`, `preprint`, `systematic review`, `meta-analysis`, `literature search`, `foundational/seminal/landmark papers`, `highly cited`.
- For scientific/technical queries, run two searches to ensure academic coverage:
+ ---
+ ## Default backend: `parallel-cli search`
+
+ Fast, cost-effective web search with optional academic source prioritization. For scientific or technical topics, run **two** searches — one restricted to scholarly domains, one general — and merge them, leading with the academic sources. This surfaces peer-reviewed work that a general search alone tends to bury. For non-scientific queries, a single general search is enough.
+
```bash
- # 1. Academic-focused search
+ mkdir -p sources # so -o can write here (parallel-cli won't create the dir)
+
+ # 1. Academic-focused search (scholarly domains only)
parallel-cli search "your research query" -q "keyword1" -q "keyword2" \
--json --max-results 10 --excerpt-max-chars-total 27000 \
--include-domains "scholar.google.com,arxiv.org,pubmed.ncbi.nlm.nih.gov,semanticscholar.org,biorxiv.org,medrxiv.org,ncbi.nlm.nih.gov,nature.com,science.org,ieee.org,acm.org,springer.com,wiley.com,cell.com,pnas.org,nih.gov" \
-o sources/research_<topic>-academic.json
# 2. General search (catches non-academic sources)
parallel-cli search "your research query" -q "keyword1" -q "keyword2" \
--json --max-results 10 --excerpt-max-chars-total 27000 \
-o sources/research_<topic>-general.json
```
- Options:
- - `--after-date YYYY-MM-DD` for time-sensitive queries
- - `--include-domains domain1.com,domain2.com` to limit to specific sources
-
- Merge results, leading with academic sources. For non-scientific queries, a single general search is sufficient.
-
- All other queries route here by default, including:
-
- - General research questions
- - Market and industry analysis
- - Technical information and documentation
- - Current events and recent developments
- - Comparative analysis
- - Statistical data retrieval
- - Fact-checking and verification
-
- ### Academic Keywords (Routes to Perplexity)
-
- Queries containing these terms are routed to Perplexity for academic-focused search:
-
- - Paper finding: `find papers`, `find articles`, `research papers on`, `published studies`
- - Citations: `cite`, `citation`, `doi`, `pubmed`, `pmid`
- - Academic sources: `peer-reviewed`, `journal article`, `scholarly`, `arxiv`, `preprint`
- - Review types: `systematic review`, `meta-analysis`, `literature search`
- - Paper quality: `foundational papers`, `seminal papers`, `landmark papers`, `highly cited`
-
- ### Deep Research (Routes to Parallel Chat API)
-
- Only used when the user explicitly requests deep, exhaustive, or comprehensive research. Much slower and more expensive than parallel-cli search.
+ Useful flags:
+ - `--after-date YYYY-MM-DD` — restrict to recent results for time-sensitive queries
+ - `--include-domains a.com,b.com` — limit to specific sources
+ - `--max-results N` — how many results to return
+ - `-o path.json` — save results (always do this; see [Saving results](#saving-results))
- ### Manual Override
+ Saved JSON contains the full result objects — `title`, `url`, `publish_date`, and content `excerpts` — everything needed to cite and to re-read later without re-querying.
- You can force a specific backend:
+ To pull the full text of a specific result, extract it:
```bash
- # Force parallel-cli search (fast web search)
- parallel-cli search "your query" -q "keyword" --json --max-results 10 -o sources/research_<topic>.json
-
- # Force Parallel Deep Research (slow, exhaustive)
- python research_lookup.py "your query" --force-backend parallel
-
- # Force Perplexity academic search
- python research_lookup.py "your query" --force-backend perplexity
+ parallel-cli extract "https://example.com/paper" --json
```
---
- ## Core Capabilities
-
- ### 1. General Research Queries (parallel-cli search — DEFAULT)
+ ## Academic paper search: Perplexity sonar-pro-search
- **Primary backend.** Fast, cost-effective web search with academic source prioritization via the parallel-web skill.
+ Use when the query specifically asks for papers, citations, or DOIs. Perplexity searches in academic mode, prioritizing peer-reviewed sources, and returns a summary plus complete citations.
- ```
- Query Examples:
- - "Recent advances in CRISPR gene editing 2025"
- - "Compare mRNA vaccines vs traditional vaccines for cancer treatment"
- - "AI adoption in healthcare industry statistics"
- - "Global renewable energy market trends and projections"
- - "Explain the mechanism underlying gut microbiome and depression"
+ ```bash
+ python scripts/research_lookup.py "Find papers on CRISPR off-target effects in clinical trials" \
+ --force-backend perplexity \
+ -o sources/papers_<topic>.md
```
- ```bash
- # Example: research on CRISPR advances
- parallel-cli search "Recent advances in CRISPR gene editing 2025" \
- -q "CRISPR" -q "gene editing" -q "2025" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- --include-domains "scholar.google.com,arxiv.org,pubmed.ncbi.nlm.nih.gov,nature.com,science.org,cell.com,pnas.org,nih.gov" \
- -o sources/research_crispr_advances-academic.json
+ Returns: a summary of key findings, 5–8 high-quality citations (authors, title, journal, year, DOI when available), citation-count and venue signals where known, and research gaps. Requires `OPENROUTER_API_KEY`.
- parallel-cli search "Recent advances in CRISPR gene editing 2025" \
- -q "CRISPR" -q "gene editing" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- -o sources/research_crispr_advances-general.json
- ```
+ Add `--json` if you need the structured citation objects (`url`, `title`, `date`, `snippet`, `doi`, `type`) for programmatic use such as BibTeX generation.
- **Response includes:**
- - Synthesized findings with inline citations from search results
- - Academic sources prioritized (peer-reviewed, preprints)
- - Specific facts, numbers, and dates
- - Sources section listing all referenced URLs grouped by type
+ ---
- ### 2. Academic Paper Search (Perplexity sonar-pro-search)
+ ## Deep research: Parallel Chat API (`core` model)
- **Used for academic-specific queries.** Prioritizes scholarly databases and peer-reviewed sources. Use when queries specifically ask for papers, citations, or DOIs.
+ Use **only** when the user explicitly asks for deep, exhaustive, or comprehensive research. It is much slower (60 s–5 min) and more expensive than `parallel-cli search` — never make it the default.
- ```
- Query Examples:
- - "Find papers on transformer attention mechanisms in NeurIPS 2024"
- - "Foundational papers on quantum error correction"
- - "Systematic review of immunotherapy in non-small cell lung cancer"
- - "Cite the original BERT paper and its most influential follow-ups"
- - "Published studies on CRISPR off-target effects in clinical trials"
+ ```bash
+ python scripts/research_lookup.py "current state of quantum computing error correction" \
+ --force-backend parallel \
+ -o sources/research_<topic>.md
```
- **Response includes:**
- - Summary of key findings from academic literature
- - 5-8 high-quality citations with authors, titles, journals, years, DOIs
- - Citation counts and venue tier indicators
- - Key statistics and methodology highlights
- - Research gaps and future directions
-
- ### 3. Deep Research (Parallel Chat API — on request only)
+ Returns a comprehensive markdown report with inline citations plus a Sources list (title, URL) and Additional References (DOIs, academic URLs). Requires `PARALLEL_API_KEY`.
- **Used only when user explicitly requests deep/exhaustive research.** Provides comprehensive, multi-source synthesis via the Chat API (`core` model). 60s-5min latency.
+ ---
- ```
- Query Examples:
- - "Deep research on the current state of quantum computing error correction"
- - "Exhaustive analysis of mRNA vaccine platforms for cancer immunotherapy"
- ```
+ ## Prioritizing high-quality papers
- ### 4. Technical and Methodological Information
+ When a query is about the literature, favor influential, well-established work over obscure publications — a reader trusts a claim backed by a landmark paper in a top venue far more than one backed by an unvetted source. Use citation counts and venue as the two main quality signals.
- Use parallel-cli search (default) for quick lookups:
+ ### Citation thresholds (rough guide)
- ```bash
- parallel-cli search "Western blot protocol for protein detection" \
- -q "western blot" -q "protocol" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- -o sources/research_western_blot.json
- ```
+ | Paper age | Citations | Classification |
+ |-----------|-----------|----------------|
+ | 0–3 years | 20+ | Noteworthy |
+ | 0–3 years | 100+ | Highly influential |
+ | 3–7 years | 100+ | Significant |
+ | 3–7 years | 500+ | Landmark |
+ | 7+ years | 500+ | Seminal |
+ | 7+ years | 1000+ | Foundational |
- ### 5. Statistical and Market Data
+ ### Venue tiers (prefer higher)
- Use parallel-cli search (default) for current data:
+ - **Tier 1 — premier:** Nature, Science, Cell, PNAS; NEJM, Lancet, JAMA, BMJ; Nature Medicine/Biotechnology/Methods; NeurIPS, ICML, ICLR, ACL, CVPR
+ - **Tier 2 — high-impact specialized:** journals with impact factor > 10; top subfield conferences (EMNLP, NAACL, ECCV, MICCAI)
+ - **Tier 3 — respected specialized:** journals with impact factor 5–10
- ```bash
- parallel-cli search "Global AI market size and growth projections 2025" \
- -q "AI market" -q "statistics" -q "growth" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- --after-date 2024-01-01 \
- -o sources/research_ai_market.json
- ```
+ These are heuristics, not gates — a directly relevant Tier-3 paper beats a tangential Tier-1 one. When you have the numbers, note them in-line (e.g. "cited 800+ times, Nature 2021") so the reader can judge the evidence themselves.
---
- ## Paper Quality and Popularity Prioritization
+ ## Saving results
- **CRITICAL**: When searching for papers, ALWAYS prioritize high-quality, influential papers.
+ Save every research result to the project's `sources/` folder. Research results are expensive to obtain and are the evidence base for every downstream citation, so keeping them makes the work reproducible and cheap to revisit. Concretely, saved results let you:
- ### Citation-Based Ranking
+ - **Trace** any claim back to the raw source that supports it (and let a reviewer do the same).
+ - **Recover** context after compaction — re-read a saved file instead of re-querying.
+ - **Reuse** one lookup across multiple sections without paying for it again.
+ - **Skip** redundant calls — check `sources/` before querying (`ls sources/`); if a prior result already covers the topic, read it instead.
- | Paper Age | Citation Threshold | Classification |
- |-----------|-------------------|----------------|
- | 0-3 years | 20+ citations | Noteworthy |
- | 0-3 years | 100+ citations | Highly Influential |
- | 3-7 years | 100+ citations | Significant |
- | 3-7 years | 500+ citations | Landmark Paper |
- | 7+ years | 500+ citations | Seminal Work |
- | 7+ years | 1000+ citations | Foundational |
+ Use the `-o` flag on every call. Preserve all citations, URLs, and DOIs in the saved file.
- ### Venue Quality Tiers
+ | Backend | Save target | Filename pattern |
+ |---------|-------------|------------------|
+ | `parallel-cli search` (default) | `sources/research_<topic>.json` | `research_<topic>-academic.json`, `research_<topic>-general.json` |
+ | Perplexity (academic) | `sources/papers_<topic>.md` | `papers_<topic>.md` (add `--json` for structured citations) |
+ | Parallel Chat API (deep) | `sources/research_<topic>.md` | `research_<topic>.md` |
- **Tier 1 - Premier Venues** (Always prefer):
- - **General Science**: Nature, Science, Cell, PNAS
- - **Medicine**: NEJM, Lancet, JAMA, BMJ
- - **Field-Specific**: Nature Medicine, Nature Biotechnology, Nature Methods
- - **Top CS/AI**: NeurIPS, ICML, ICLR, ACL, CVPR
+ `research_lookup.py` creates the `sources/` directory automatically. When calling `parallel-cli` directly, run `mkdir -p sources` first — it won't create the directory for you.
- **Tier 2 - High-Impact Specialized** (Strong preference):
- - Journals with Impact Factor > 10
- - Top conferences in subfields (EMNLP, NAACL, ECCV, MICCAI)
+ When you save a result, log a one-line note so the audit trail is legible, e.g.:
- **Tier 3 - Respected Specialized** (Include when relevant):
- - Journals with Impact Factor 5-10
+ ```
+ [14:30:00] SAVED: sources/research_crispr_advances-academic.json (10 results)
+ [14:30:05] SAVED: sources/papers_transformer_attention.md (6 papers)
+ ```
---
- ## Technical Integration
+ ## Setup
- ### Prerequisites
+ `parallel-cli` is the primary dependency. If it isn't installed:
```bash
- # Primary backend (parallel-cli) - REQUIRED
- # Install parallel-cli if not already available:
curl -fsSL https://parallel.ai/install.sh | bash
- # Or: uv tool install "parallel-web-tools[cli]"
+ # or: uv tool install "parallel-web-tools[cli]"
- # Authenticate:
- parallel-cli auth
- # Or: export PARALLEL_API_KEY="your_parallel_api_key"
+ parallel-cli auth # or: export PARALLEL_API_KEY="..."
```
- ### Environment Variables
+ Environment variables:
```bash
- # Primary backend (parallel-cli search) - REQUIRED
- export PARALLEL_API_KEY="your_parallel_api_key"
-
- # Deep research backend (Parallel Chat API) - optional, for deep research only
- # Uses the same PARALLEL_API_KEY
-
- # Academic search backend (Perplexity) - optional, for academic paper queries
- export OPENROUTER_API_KEY="your_openrouter_api_key"
+ export PARALLEL_API_KEY="..." # parallel-cli search AND the Parallel Chat API (deep research)
+ export OPENROUTER_API_KEY="..." # Perplexity academic search (optional)
```
- ### API Specifications
-
- **parallel-cli search (PRIMARY):**
- - Command: `parallel-cli search` with `--json` output
- - Latency: 2-10 seconds (fast)
- - Output: JSON with title, URL, publish_date, excerpts
- - Academic domains: Use `--include-domains` for scholarly sources
- - Saves results: `-o filename.json` for follow-up and reproducibility
-
- **Parallel Chat API (deep research only):**
- - Endpoint: `https://api.parallel.ai` (OpenAI SDK compatible)
- - Model: `core` (60s-5min latency, complex multi-source synthesis)
- - Output: Markdown text with inline citations
- - Citations: Research basis with URLs, reasoning, and confidence levels
- - Rate limits: 300 req/min
- - Python package: `openai`
-
- **Perplexity sonar-pro-search (academic only):**
- - Model: `perplexity/sonar-pro-search` (via OpenRouter)
- - Search mode: Academic (prioritizes peer-reviewed sources)
- - Search context: High (comprehensive research)
- - Response time: 5-15 seconds
+ ---
- ### Command-Line Usage
+ ## Command reference
```bash
- # Fast web search via parallel-cli (DEFAULT — recommended) — ALWAYS save to sources/
- parallel-cli search "your query" -q "keyword1" -q "keyword2" \
+ # Fast web search (DEFAULT) — always save to sources/
+ parallel-cli search "query" -q "kw1" -q "kw2" \
--json --max-results 10 --excerpt-max-chars-total 27000 \
-o sources/research_<topic>.json
- # Academic-focused search via parallel-cli — ALWAYS save to sources/
- parallel-cli search "your query" -q "keyword1" \
+ # Academic-focused variant (add scholarly domains)
+ parallel-cli search "query" -q "kw1" \
--json --max-results 10 --excerpt-max-chars-total 27000 \
- --include-domains "scholar.google.com,arxiv.org,pubmed.ncbi.nlm.nih.gov,semanticscholar.org,biorxiv.org,medrxiv.org,nature.com,science.org,cell.com,pnas.org,nih.gov" \
+ --include-domains "arxiv.org,pubmed.ncbi.nlm.nih.gov,nature.com,science.org,cell.com,pnas.org,nih.gov" \
-o sources/research_<topic>-academic.json
- # Time-sensitive search via parallel-cli
- parallel-cli search "your query" -q "keyword" \
- --json --max-results 10 --after-date 2024-01-01 \
+ # Time-sensitive
+ parallel-cli search "query" -q "kw" --json --max-results 10 --after-date 2024-01-01 \
-o sources/research_<topic>.json
- # Extract full content from a specific URL (use parallel-web extract)
+ # Extract full text from a URL
parallel-cli extract "https://example.com/paper" --json
- # Force Parallel Deep Research (slow, exhaustive) — via research_lookup.py
- python research_lookup.py "your query" --force-backend parallel -o sources/research_<topic>.md
-
- # Force Perplexity academic search — via research_lookup.py
- python research_lookup.py "your query" --force-backend perplexity -o sources/papers_<topic>.md
-
- # Auto-routed via research_lookup.py (legacy) — ALWAYS save to sources/
- python research_lookup.py "your query" -o sources/research_YYYYMMDD_HHMMSS_<topic>.md
-
- # Batch queries via research_lookup.py — ALWAYS save to sources/
- python research_lookup.py --batch "query 1" "query 2" "query 3" -o sources/batch_research_<topic>.md
- ```
-
- ---
-
- ## MANDATORY: Save All Results to Sources Folder
-
- **Every research-lookup result MUST be saved to the project's `sources/` folder.**
-
- This is non-negotiable. Research results are expensive to obtain and critical for reproducibility.
-
- ### Saving Rules
-
- | Backend | `-o` Flag Target | Filename Pattern |
- |---------|-----------------|------------------|
- | parallel-cli search (default) | `sources/research_<topic>.json` | `research_<brief_topic>.json` or `research_<brief_topic>-academic.json` |
- | Parallel Deep Research | `sources/research_<topic>.md` | `research_YYYYMMDD_HHMMSS_<brief_topic>.md` |
- | Perplexity (academic) | `sources/papers_<topic>.md` | `papers_YYYYMMDD_HHMMSS_<brief_topic>.md` |
- | Batch queries | `sources/batch_<topic>.md` | `batch_research_YYYYMMDD_HHMMSS_<brief_topic>.md` |
-
- ### How to Save
-
- **CRITICAL: Every search MUST save results to the `sources/` folder using the `-o` flag.**
-
- **CRITICAL: Saved files MUST preserve all citations, source URLs, and DOIs.**
-
- ```bash
- # parallel-cli search (DEFAULT) — save JSON to sources/
- parallel-cli search "Recent advances in CRISPR gene editing 2025" \
- -q "CRISPR" -q "gene editing" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- --include-domains "scholar.google.com,arxiv.org,pubmed.ncbi.nlm.nih.gov,nature.com,science.org,cell.com,pnas.org,nih.gov" \
- -o sources/research_crispr_advances-academic.json
-
- parallel-cli search "Recent advances in CRISPR gene editing 2025" \
- -q "CRISPR" -q "gene editing" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- -o sources/research_crispr_advances-general.json
-
- # Academic paper search via Perplexity — save to sources/
- python research_lookup.py "Find papers on transformer attention mechanisms in NeurIPS 2024" \
- -o sources/papers_20250217_143500_transformer_attention.md
-
- # Deep research via Parallel Chat API — save to sources/
- python research_lookup.py "AI regulation landscape" --force-backend parallel \
- -o sources/research_20250217_144000_ai_regulation.md
-
- # Batch queries — save to sources/
- python research_lookup.py --batch "mRNA vaccines efficacy" "mRNA vaccines safety" \
- -o sources/batch_research_20250217_144500_mrna_vaccines.md
- ```
-
- ### Citation Preservation in Saved Files
-
- Each output format preserves citations differently:
-
- | Format | Citations Included | When to Use |
- |--------|-------------------|-------------|
- | parallel-cli JSON (default) | Full result objects: `title`, `url`, `publish_date`, `excerpts` | Standard use — structured, parseable, fast |
- | Text (research_lookup.py) | `Sources (N):` section with `[title] (date) + URL` + `Additional References (N):` with DOIs and academic URLs | Deep research / Perplexity — human-readable |
- | JSON (`--json` via research_lookup.py) | Full citation objects: `url`, `title`, `date`, `snippet`, `doi`, `type` | When you need maximum citation metadata from deep research |
-
- **For parallel-cli search**, saved JSON files include: full search results with title, URL, publish date, and content excerpts for each result.
- **For Parallel Chat API backend**, saved files include: research report + Sources list (title, URL) + Additional References (DOIs, academic URLs).
- **For Perplexity backend**, saved files include: academic summary + Sources list (title, date, URL, snippet) + Additional References (DOIs, academic URLs).
-
- **Use `--json` when you need to:**
- - Parse citation metadata programmatically
- - Preserve full DOI and URL data for BibTeX generation
- - Maintain the structured citation objects for cross-referencing
-
- ### Why Save Everything
-
- 1. **Reproducibility**: Every citation and claim can be traced back to its raw research source
- 2. **Context Window Recovery**: If context is compacted, saved results can be re-read without re-querying
- 3. **Audit Trail**: The `sources/` folder documents exactly how all research information was gathered
- 4. **Reuse Across Sections**: Multiple sections can reference the same saved research without duplicate queries
- 5. **Cost Efficiency**: Check `sources/` for existing results before making new API calls
- 6. **Peer Review Support**: Reviewers can verify the research backing every citation
-
- ### Before Making a New Query, Check Sources First
-
- Before calling `research_lookup.py`, check if a relevant result already exists:
-
- ```bash
- ls sources/ # Check existing saved results
- ```
-
- If a prior lookup covers the same topic, re-read the saved file instead of making a new API call.
+ # Academic paper search (Perplexity)
+ python scripts/research_lookup.py "find papers on <topic>" --force-backend perplexity \
+ -o sources/papers_<topic>.md
- ### Logging
+ # Deep research (Parallel Chat API, slow/expensive — on request only)
+ python scripts/research_lookup.py "deep dive on <topic>" --force-backend parallel \
+ -o sources/research_<topic>.md
- When saving research results, always log:
+ # Auto-route between the two API backends (academic->Perplexity, else->Chat API)
+ python scripts/research_lookup.py "query" -o sources/research_<topic>.md
- ```
- [HH:MM:SS] SAVED: Research lookup to sources/research_20250217_143000_crispr_advances.md (3,800 words, 8 citations)
- [HH:MM:SS] SAVED: Paper search to sources/papers_20250217_143500_transformer_attention.md (6 papers found)
+ # Batch several queries through the API backends
+ python scripts/research_lookup.py --batch "query 1" "query 2" -o sources/batch_<topic>.md
```
---
- ## Integration with Scientific Writing
-
- This skill enhances scientific writing by providing:
-
- 1. **Literature Review Support**: Gather current research for introduction and discussion — **save to `sources/`**
- 2. **Methods Validation**: Verify protocols against current standards — **save to `sources/`**
- 3. **Results Contextualization**: Compare findings with recent similar studies — **save to `sources/`**
- 4. **Discussion Enhancement**: Support arguments with latest evidence — **save to `sources/`**
- 5. **Citation Management**: Provide properly formatted citations — **save to `sources/`**
-
- ## Complementary Tools
-
- | Task | Tool |
- |------|------|
- | General web search (fast) | `parallel-cli search` (built into this skill) |
- | Academic-focused web search | `parallel-cli search --include-domains` (built into this skill) |
- | URL content extraction | `parallel-cli extract` (parallel-web skill) |
- | Deep research (exhaustive) | `research-lookup` via Parallel Chat API or `parallel-web` deep research |
- | Academic paper search | `research-lookup` (auto-routes to Perplexity) |
- | Google Scholar search | `citation-management` skill |
- | PubMed search | `citation-management` skill |
- | DOI to BibTeX | `citation-management` skill |
- | Metadata verification | `parallel-cli extract` (parallel-web skill) |
-
- ---
-
- ## Error Handling and Limitations
-
- **Known Limitations:**
- - parallel-cli search: Requires `parallel-cli` to be installed and authenticated
- - Parallel Chat API (core model): Complex queries may take up to 5 minutes
- - Perplexity: Information cutoff, may not access full text behind paywalls
- - All backends: Cannot access proprietary or restricted databases
-
- **Fallback Behavior:**
- - If `parallel-cli` is not found, install with `curl -fsSL https://parallel.ai/install.sh | bash` or `uv tool install "parallel-web-tools[cli]"`
- - If parallel-cli search returns insufficient results, fall back to Perplexity or Parallel Chat API
- - If the selected backend's API key is missing, tries the other backend
- - If all backends fail, returns structured error response
- - Rephrase queries for better results if initial response is insufficient
-
- ---
-
- ## Usage Examples
-
- ### Example 1: General Research (Routes to parallel-cli search)
-
- **Query**: "Recent advances in transformer attention mechanisms 2025"
-
- **Backend**: parallel-cli search (default, fast)
-
- **Commands**:
- ```bash
- parallel-cli search "Recent advances in transformer attention mechanisms 2025" \
- -q "transformer" -q "attention" -q "2025" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- --include-domains "arxiv.org,semanticscholar.org,nature.com,science.org,ieee.org,acm.org" \
- -o sources/research_transformer_attention-academic.json
-
- parallel-cli search "Recent advances in transformer attention mechanisms 2025" \
- -q "transformer" -q "attention" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- -o sources/research_transformer_attention-general.json
- ```
-
- **Response**: Synthesized findings with inline citations from academic and general sources, covering recent papers, key innovations, and performance benchmarks.
-
- ### Example 2: Academic Paper Search (Routes to Perplexity)
-
- **Query**: "Find papers on CRISPR off-target effects in clinical trials"
-
- **Backend**: Perplexity sonar-pro-search (academic mode)
-
- **Response**: Curated list of 5-8 high-impact papers with full citations, DOIs, citation counts, and venue tier indicators.
-
- ### Example 3: Comparative Analysis (Routes to parallel-cli search)
-
- **Query**: "Compare and contrast mRNA vaccines vs traditional vaccines for cancer treatment"
-
- **Backend**: parallel-cli search (default, fast)
-
- **Response**: Synthesized comparison from multiple web sources with inline citations, structured analysis, and evidence quality notes.
-
- ### Example 4: Market Data (Routes to parallel-cli search)
-
- **Query**: "Global AI adoption in healthcare statistics 2025"
-
- **Backend**: parallel-cli search (default, fast)
-
- ```bash
- parallel-cli search "Global AI adoption in healthcare statistics 2025" \
- -q "AI healthcare" -q "adoption statistics" \
- --json --max-results 10 --excerpt-max-chars-total 27000 \
- --after-date 2024-01-01 \
- -o sources/research_ai_healthcare_adoption.json
- ```
+ ## Related skills
- **Response**: Current market data, adoption rates, growth projections, and regional analysis with source citations.
+ - **`parallel-web`** — the full parallel-cli toolkit (search, extract, data enrichment, deep research) with more options than the essentials shown here. Reach for it for enrichment jobs or advanced extraction.
+ - **`citation-management`** — Google Scholar / PubMed search and DOI→BibTeX conversion. Use it to turn the DOIs and URLs found here into formatted references.
+ - **`scientific-schematics`** — generate publication-quality diagrams. If a research document would be clearer with a figure, hand off to this skill rather than embedding image-generation here.
---
- ## Summary
-
- This skill serves as the primary research interface with intelligent tri-backend routing:
+ ## Errors and limitations
- - **parallel-cli search** (default): Fast, cost-effective web search with academic source prioritization via the parallel-web skill
- - **Parallel Chat API** (`core` model): Deep, exhaustive multi-source synthesis (on explicit request only)
- - **Perplexity sonar-pro-search**: Academic-specific paper searches only
- - **Automatic routing**: Detects query type and routes to the optimal backend
- - **Manual override**: Force any backend when needed
- - **Academic prioritization**: Two-search pattern ensures scholarly sources surface for scientific queries
+ - **`parallel-cli` not found** — install it (see [Setup](#setup)).
+ - **Missing API key** — `parallel-cli search` and the Chat API need `PARALLEL_API_KEY`; Perplexity needs `OPENROUTER_API_KEY`. `research_lookup.py` reports clearly if none is set and, when auto-routing, falls back to whichever backend has a key.
+ - **Deep research is slow** — the Chat API `core` model can take up to 5 minutes; expect it and don't use it for quick lookups.
+ - **Paywalls / restricted data** — none of the backends can read proprietary databases or full text behind paywalls.
+ - **Weak results** — rephrase with more specific terms or a date range, or try a different backend before giving up.