Skip to content
Skills Library
AI & agents · Research

alterlab-perplexity

/alterlab-perplexity

Run AI web searches with real-time, citation-grounded answers using Perplexity Sonar models (sonar, sonar-pro, sonar-pro-search agentic search, sonar-reasoning-pro) via LiteLLM and a single OpenRouter API key. Use when searching for current information or recent scientific literature, getting answers grounded in cited web sources, verifying a claim against current evidence, or reaching information beyond the model's training cutoff. Requires an OpenRouter API key. This is the direct single-backend Perplexity tool: for automatic routing between Perplexity and other backends use alterlab-researc

Licence
MIT
Last repository change
23.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
2
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 23.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/perplexity_search.py, scripts/setup_env.py

What it does and when to use it

Run AI web searches with real-time, citation-grounded answers using Perplexity Sonar models (sonar, sonar-pro, sonar-pro-search agentic search, sonar-reasoning-pro) via LiteLLM and a single OpenRouter API key. Use when searching for current information or recent scientific literature, getting answers grounded in cited web sources, verifying a claim against current evidence, or reaching information beyond the model's training cutoff. Requires an OpenRouter API key. This is the direct single-backend Perplexity tool: for automatic routing between Perplexity and other backends use alterlab-researc

Original author description

Run AI web searches with real-time, citation-grounded answers using Perplexity Sonar models (sonar, sonar-pro, sonar-pro-search agentic search, sonar-reasoning-pro) via LiteLLM and a single OpenRouter API key. Use when searching for current information or recent scientific literature, getting answers grounded in cited web sources, verifying a claim against current evidence, or reaching information beyond the model's training cutoff. Requires an OpenRouter API key. This is the direct single-backend Perplexity tool: for automatic routing between Perplexity and other backends use alterlab-researc

How it works

  1. When to Use This Skill
  2. Setup (one-time)
  3. Basic usage
  4. Models
  5. Writing good queries
  6. Programmatic access
  7. Cost
  8. Environment variables
  9. Resources
Original SKILL.md headings · 112 lines, 728 words
SKILL.md preview
---
name: alterlab-perplexity
description: "Run AI web searches with real-time, citation-grounded answers using Perplexity Sonar models (sonar, sonar-pro, sonar-pro-search agentic search, sonar-reasoning-pro) via LiteLLM and a single OpenRouter API key. Use when searching for current information or recent scientific literature, getting answers grounded in cited web sources, verifying a claim against current evidence, or reaching information beyond the model's training cutoff. Requires an OpenRouter API key. This is the direct single-backend Perplexity tool: for automatic routing between Perplexity and other backends use alterlab-research-lookup, and for structured per-paper experimental-data extraction (sample sizes, effect sizes, quality scores) use alterlab-bgpt-search. Part of the AlterLab Academic Skills suite."
license: MIT
allowed-tools: Read WebFetch WebSearch Bash(python:*)
compatibility: An OpenRouter API key (OPENROUTER_API_KEY) is required; uses the litellm Python package and sends queries to OpenRouter/Perplexity.
metadata:
    skill-author: AlterLab
    version: "1.1.0"
    last_updated: "2026-09-23"
---

# Perplexity Search

Run AI web searches using Perplexity Sonar models through LiteLLM and OpenRouter. Perplexity returns real-time, web-grounded answers with source citations — ideal for current information, recent literature, and facts beyond the model's training cutoff. One OpenRouter key covers all models; no separate Perplexity account needed.

## When to Use This Skill

Use for: current developments, latest publications, citation-grounded answers, verifying a claim against current sources, or anything past the training cutoff.

Skip for: arithmetic/logic, code execution, or facts well within training data (answer directly).

### Does NOT Trigger

| Scenario | Use Instead |
|----------|-------------|
| Unsure which search backend fits; want automatic routing and results saved to `sources/` | `alterlab-research-lookup` |
| General web, market, or technical research via Parallel, or extracting a known URL | `alterlab-parallel-web` |
| Per-paper structured experimental data (sample sizes, effect sizes, quality scores) | `alterlab-bgpt-search` |
| Reproducible biomedical database search by MeSH terms or PMIDs | `alterlab-pubmed` |

## Setup (one-time)

```bash
# 1. Get a key at https://openrouter.ai/keys and add credits ($5+ recommended)
# 2. Configure (either form works; setup_env.py writes .env with owner-only permissions)
export OPENROUTER_API_KEY='sk-or-v1-your-key-here'
python scripts/setup_env.py --api-key sk-or-v1-your-key-here   # writes .env

# 3. Install LiteLLM
uv pip install litellm

# 4. Verify
python scripts/perplexity_search.py --check-setup
```

`--check-setup` reads the live environment, not `.env`. After `setup_env.py`, load the file with `set -a; source .env; set +a` (plain `source` does not export) or use python-dotenv, so the variable is actually in scope. Ask the user to set the key themselves rather than pasting it into the conversation. See `references/openrouter_setup.md` for full setup, security, and troubleshooting.

## Basic usage

```bash
python scripts/perplexity_search.py "What are the latest developments in CRISPR gene editing?"
python scripts/perplexity_search.py "Recent CAR-T therapy clinical trials" --output results.json
python scripts/perplexity_search.py "Compare mRNA and viral vector vaccines" --model sonar-pro-search
python scripts/perplexity_search.py "Quantum computing for drug discovery" --verbose
```

The CLI takes the bare model name (e.g. `sonar-pro`); the script prepends `openrouter/perplexity/` automatically.

## Models

Select with `--model` (or set `DEFAULT_MODEL`):

| Model | Use it for |
|-------|------------|
| `sonar-pro` (default) | General research, balanced cost/quality |
| `sonar-pro-search` | Most advanced agentic, multi-step search; comprehensive comparisons. Highest cost; OpenRouter-exclusive |
| `sonar` | Simple fact lookups, cost-sensitive bulk queries |
| `sonar-reasoning-pro` | Tasks needing explicit step-by-step reasoning |

`sonar-reasoning` was retired on OpenRouter (not listed as of 2026-09-23) and the CLI no longer accepts it; a stale `DEFAULT_MODEL=sonar-reasoning` now fails fast with a clear error. See `references/model_comparison.md` for detailed trade-offs, pricing, context windows, and `sonar-deep-research` for programmatic use.

## Writing good queries

Be specific (domain + time frame + desired output). Examples that work well:

- "Latest clinical trial results for CAR-T therapy in B-cell lymphoma published in 2024"
- "Compare PyTorch vs TensorFlow for transformer training: ease of use, performance, ecosystem — with recent benchmarks"
- "Evidence for intermittent fasting on HbA1c in adults with type 2 diabetes; focus on RCTs"

Add source preferences ("peer-reviewed", "clinicaltrials.gov", "FDA-approved") for higher-quality grounding. Full query-design patterns, domain templates, and pitfalls live in `references/search_strategies.md`.

## Programmatic access

```python
from scripts.perplexity_search import search_with_perplexity

result = search_with_perplexity(
    query="What are the latest CRISPR developments?",
    model="openrouter/perplexity/sonar-pro",  # full path required when calling directly
    max_tokens=4000,
    temperature=0.2,
)
if result["success"]:
    print(result["answer"])
    print(f"Tokens: {result['usage']['total_tokens']}")
else:
    print(f"Error: {result['error']}")
```

Saved JSON (`--output`) carries `answer`, `model`, `usage`, and `citations` — a deduplicated list of `{url, title}` gathered from OpenRouter's `url_citation` annotations and Perplexity's `citations`/`search_results` fields, present when the model returns sources. Process with `jq '.answer'` or `jq '.citations[].url'`. Cite the underlying sources, not Perplexity, and open any source you quote: answers are generated summaries and can misattribute a claim.

## Cost

Pricing is per token (plus a per-request fee on `sonar-pro-search`); rough per-query order: `sonar` < `sonar-pro` < `sonar-reasoning-pro` < `sonar-pro-search`. Control spend by matching the model to the query, capping `--max-tokens`, and setting a spending limit in the OpenRouter dashboard. Monitor usage at https://openrouter.ai/activity. Exact rates: `references/model_comparison.md` and https://openrouter.ai/perplexity.

## Environment variables

- `OPENROUTER_API_KEY` (required)
- `DEFAULT_MODEL` (default `sonar-pro`), `DEFAULT_MAX_TOKENS` (default `4000`), `DEFAULT_TEMPERATURE` (default `0.2`) — honored as CLI defaults; override per call with the matching flag.

## Resources

- `scripts/perplexity_search.py` — search CLI / importable function
- `scripts/setup_env.py` — key setup and validation
- `references/openrouter_setup.md` — setup, security, troubleshooting
- `references/model_comparison.md` — model selection and pricing
- `references/search_strategies.md` — query design
- `assets/.env.example` — environment template

Part of the AlterLab Academic Skills suite.

Files in this package (8)
  • SKILL.md 7 KB
  • assets/.env.example 1 KB
  • evals/evals.json 5 KB
  • references/model_comparison.md 11 KB
  • references/openrouter_setup.md 11 KB
  • references/search_strategies.md 10 KB
  • scripts/perplexity_search.py 10 KB
  • scripts/setup_env.py 5 KB

Versions

The database has no other skills named alterlab-perplexity.

Database snapshot: 13.11.2026 · package version 2ca998366a90 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95perplexity-search
    Perform AI-powered web searches with real-time information using Perplexity models via LiteLLM and OpenRouter. This skill should be used when conducting web searches for current information, finding recent scientific literature, getting grounded answers with source citations, or…
  • 100perplexity-search
    Perform AI-powered web searches with real-time information using Perplexity models via LiteLLM and OpenRouter. This skill should be used when conducting web searches for current information, finding recent scientific literature, getting grounded answers with source citations, or…
  • 100perplexity-search
    Perplexity Sonar search and answer generation through AIsa. Use when the task is specifically to call Perplexity Sonar, Sonar Pro, Sonar Reasoning Pro, or Sonar Deep Research for citation-backed web answers, analytical reasoning, or long-form research reports.
  • 100perplexity-research
    Deep research using Perplexity Sonar models via AIsa API. Provides synthesized answers with citations. Supports 4 models from fast to exhaustive deep research. Use when: the user needs web search, research, source discovery, or content extraction.
  • 100perplexity-research
    Live web research through Perplexity's closed synthesis engine — structured web results, deep multi-step investigations with reasoning, and quick sonar answers. Use when you need authoritative primary sources (gov/academic), academic citation discovery, or UK ecology/policy…
  • 100model-routing-fallback-cascade-gateways
    Use this skill when routing queries dynamically between fast/cheap models and frontier models using LiteLLM or OpenRouter.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.