alterlab-perplexity

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)

# 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

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

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.