perplexity

name	perplexity
description	Paid research assistant with real-time web search. Use when user asks "what's the latest", "current pricing for", "recent news about", "search the web for", "fact check this", "what's new in", or needs up-to-date information beyond training data.
allowed-tools	Bash, Read
triggers	["what's the latest","current pricing","recent news","search the web","fact check","what's new in","look up online","research this topic","paid search"]
metadata	{"short-description":"AI research with web search"}

Perplexity Skill

AI-powered research assistant with real-time web search capabilities.

Prerequisites

• PERPLEXITY_API_KEY in .env (get from https://www.perplexity.ai/settings/api)

When to Use

• Current information (news, recent releases, pricing)
• Technical questions requiring up-to-date docs
• Fact-checking and verification
• Research questions needing multiple sources
• Comparisons (libraries, tools, approaches)

Quick Start

# Simple query (quick answer)
python .agents/skills/perplexity/perplexity.py ask "What's new in Python 3.12?"

# With citations (JSON output)
python .agents/skills/perplexity/perplexity.py research "ArangoDB vs Neo4j for knowledge graphs"

# With specific model
python .agents/skills/perplexity/perplexity.py ask --model large "Best practices for Lean4 proofs"

Commands at a Glance

Command	What it does	Notes
ask	Fast answer with short citations preview	Matches the Typer command implemented in perplexity.py ask
research	Full answer + citations JSON	Equivalent to calling _research() and prints JSON unless --no-json
models	Lists available model aliases → API IDs	Useful when wiring the skill into other agents

Every CLI example must include the subcommand (ask, research, or models) because the Typer app requires it; omitting the subcommand will raise a usage error. The shipped SKILL docs now mirror the exact runner arguments, so you can copy/paste them without edits.

CLI Usage

Two commands: ask (quick answer) and research (with citations):

# Quick answer
python .agents/skills/perplexity/perplexity.py ask [OPTIONS] "your question"

# Research with citations (JSON output)
python .agents/skills/perplexity/perplexity.py research [OPTIONS] "your question"

Options:
  --model, -m     small|large|huge  (default: small, fast)
  --system, -s    Custom system prompt
  --json/--no-json  JSON output (research default: --json)

Python API

# Import the internal function
from perplexity import _research

# Research with citations
result = _research("What is BM25 scoring?", model="small")
print(result["answer"])
print(result["citations"])

Note: The CLI commands ask and research are the primary interface. For Python usage, use _research() directly.

Shared Helpers

• .agents/skills/dotenv_helper.py is auto-imported so .env keys (e.g., PERPLEXITY_API_KEY) load without manual sourcing.
• .agents/skills/json_utils.py is available if you need to repair downstream JSON before writing it to files; the research command already emits valid JSON, so most callers can stream it directly.

Models

Model	API Name	Speed	Use Case
small	sonar	Fast	Quick lookups, simple questions
large	sonar-pro	Medium	Technical research, comparisons
huge	sonar-reasoning	Slow	Complex analysis, reasoning

Examples

Technical Research

python .agents/skills/perplexity/perplexity.py ask "How to implement hybrid search with BM25 and vector similarity?"

Current Information

python .agents/skills/perplexity/perplexity.py ask "Latest Anthropic Claude API changes 2024"

Comparison

python .agents/skills/perplexity/perplexity.py ask --model large "sentence-transformers vs OpenAI embeddings for code search"

vs Context7

Perplexity	Context7
General research	Library-specific docs
Real-time web search	Curated documentation
Any topic	Code libraries only
Synthesized answers	Raw doc snippets

Use Context7 for: specific library API syntax, exact function signatures Use Perplexity for: research, comparisons, current information, general questions