Perplexity Research

Perplexity Research

Research assistant powered by Perplexity Agent API with web search and reasoning capabilities.

Quick Start

The Perplexity client is available at scripts/perplexity_client.py in this skill folder.

Default model: openai/gpt-5.2 (GPT latest)

Key capabilities:

Common Research Patterns

1. Deep Research Query

Use for comprehensive analysis requiring web search and reasoning:

# Import from skill scripts folder
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent / "scripts"))
from perplexity_client import PerplexityClient
client = PerplexityClient()
result = client.research_query(
    query="Your research question here",
    model="openai/gpt-5.2",
    reasoning_effort="high",
    max_tokens=2000
)
if "error" not in result:
    print(result["answer"])
    print(f"Tokens: {result['tokens']}, Cost: ${result['cost']}")

2. Quick Web Search

Use for time-sensitive or current information:

result = client.search_query(
    query="Your question about current events",
    model="openai/gpt-5.2",
    max_tokens=1000
)

3. Model Comparison

Use when output quality is critical:

results = client.compare_models(
    query="Your question",
    models=["openai/gpt-5.2", "anthropic/claude-3-5-sonnet", "google/gemini-2.0-flash"],
    max_tokens=300
)
for result in results:
    if "error" not in result:
        print(f"\n{result['model']}: {result['answer']}")

4. Streaming for Long Responses

Use for better UX with lengthy analysis:

client.stream_query(
    query="Your question",
    model="openai/gpt-5.2",
    use_search=True,
    max_tokens=2000
)

Research Workflow

When conducting research:

1. Initial exploration: Use research_query() with web search enabled 2. Validate findings: Compare key insights across models with compare_models() 3. Deep dive: Use streaming for detailed analysis on specific aspects 4. Cost-aware: Monitor token usage and costs in results

Model Selection

Default: openai/gpt-5.2 (Latest GPT model)

Alternative models:

Switch models based on:

Reasoning Effort Levels

Control analysis depth with reasoning_effort:

Environment Setup

Ensure PERPLEXITY_API_KEY is set:

export PERPLEXITY_API_KEY='your_api_key_here'

Or create .env file in the skill's scripts/ directory:

PERPLEXITY_API_KEY=your_api_key_here

Error Handling

All methods return error information:

result = client.research_query("Your question")
if "error" in result:
    print(f"Error: {result['error']}")
    # Handle error appropriately
else:
    # Process successful result
    print(result["answer"])

Cost Optimization

Integration Examples

Investment Research

client = PerplexityClient()
Market analysis
result = client.research_query(
    query="Analyze recent developments in AI chip market and key competitors",
    reasoning_effort="high"
)
Company deep dive
result = client.search_query(
    query="Latest earnings report for NVIDIA Q4 2025"
)
Multi-model validation
results = client.compare_models(
    query="What are the biggest risks in the semiconductor industry?",
    models=["openai/gpt-5.2", "anthropic/claude-3-5-sonnet"]
)

Trend Analysis

# Current trends with web search
result = client.research_query(
    query="Emerging trends in sustainable investing and ESG adoption rates",
    reasoning_effort="high",
    max_tokens=2000
)
Stream for real-time updates
client.stream_query(
    query="Latest developments in quantum computing commercialization",
    use_search=True
)

Multi-Turn Research

# Build context across multiple queries
messages = [
    {"role": "user", "content": "What is the current state of fusion energy?"},
    {"role": "assistant", "content": "...previous response..."},
    {"role": "user", "content": "Which companies are leading in this space?"}
]
result = client.conversation(
    messages=messages,
    use_search=True
)

Best Practices

1. Default to research_query() for most research tasks - it combines web search with high reasoning 2. Use streaming for user-facing applications to show progress 3. Compare models for critical decisions or when quality is paramount 4. Set reasonable max_tokens - 1000 for summaries, 2000+ for deep analysis 5. Track costs - access via result["cost"] and result["tokens"] 6. Handle errors gracefully - always check for "error" key in results

API Reference

See reference.md for complete API documentation, or scripts/perplexity_client.py for:

Command Line Usage

Run from the skill directory:

# Research mode
python scripts/perplexity_client.py research "Your question"
Web search
python scripts/perplexity_client.py search "Your question"
Streaming
python scripts/perplexity_client.py stream "Your question"
Compare models
python scripts/perplexity_client.py compare "Your question"

The Perplexity client is available at scripts/perplexity_client.py in this skill folder.

Default model: openai/gpt-5.2 (GPT latest)

Key capabilities:

1. Default to research_query() for most research tasks - it combines web search with high reasoning 2. Use streaming for user-facing applications to show progress 3. Compare models for critical decisions or when quality is paramount 4. Set reasonable max_tokens - 1000 for summaries, 2000+ for deep analysis 5. Track costs - access via result["cost"] and result["tokens"] 6. Handle errors gracefully - always check for "error" key in results