Perplexity Search

Quick Start

Setup (One-time)

1. Get OpenRouter API key:

   • Visit https://openrouter.ai/keys
   • Create account and generate API key
   • Add credits to account (minimum $5 recommended)

2. Configure environment:

   # Set API key
   export OPENROUTER_API_KEY='sk-or-v1-your-key-here'
   
   # Or use setup script
   python scripts/setup_env.py --api-key sk-or-v1-your-key-here
   

3. Install dependencies:

   uv pip install litellm
   

4. Verify setup:

   python scripts/perplexity_search.py --check-setup
   

See references/openrouter_setup.md for detailed setup instructions, troubleshooting, and security best practices.

Basic Usage

Simple search:

python scripts/perplexity_search.py "What are the latest developments in CRISPR gene editing?"

Save results:

python scripts/perplexity_search.py "Recent CAR-T therapy clinical trials" --output results.json

Use specific model:

python scripts/perplexity_search.py "Compare mRNA and viral vector vaccines" --model sonar-pro-search

Verbose output:

python scripts/perplexity_search.py "Quantum computing for drug discovery" --verbose

Available Models

Access models via --model parameter:

• sonar-pro (default): General-purpose search, best balance of cost and quality
• sonar-pro-search: Most advanced agentic search with multi-step reasoning
• sonar: Basic model, most cost-effective for simple queries
• sonar-reasoning-pro: Advanced reasoning with step-by-step analysis
• sonar-reasoning: Basic reasoning capabilities

Model selection guide:

• Default queries → sonar-pro
• Complex multi-step analysis → sonar-pro-search
• Explicit reasoning needed → sonar-reasoning-pro
• Simple fact lookups → sonar
• Cost-sensitive bulk queries → sonar

See references/model_comparison.md for detailed comparison, use cases, pricing, and performance characteristics.

Crafting Effective Queries

Be Specific and Detailed

Good examples:

• "What are the latest clinical trial results for CAR-T cell therapy in treating B-cell lymphoma published in 2024?"
• "Compare the efficacy and safety profiles of mRNA vaccines versus viral vector vaccines for COVID-19"
• "Explain AlphaFold3 improvements over AlphaFold2 with specific accuracy metrics from 2023-2024 research"

Bad examples:

• "Tell me about cancer treatment" (too broad)
• "CRISPR" (too vague)
• "vaccines" (lacks specificity)

Include Time Constraints

Perplexity searches real-time web data:

• "What papers were published in Nature Medicine in 2024 about long COVID?"
• "What are the latest developments (past 6 months) in large language model efficiency?"
• "What was announced at NeurIPS 2023 regarding AI safety?"

Specify Domain and Sources

For high-quality results, mention source preferences:

• "According to peer-reviewed publications in high-impact journals..."
• "Based on FDA-approved treatments..."
• "From clinical trial registries like clinicaltrials.gov..."

Structure Complex Queries

Break complex questions into clear components:

1. Topic: Main subject
2. Scope: Specific aspect of interest
3. Context: Time frame, domain, constraints
4. Output: Desired format or type of answer

Example: "What improvements does AlphaFold3 offer over AlphaFold2 for protein structure prediction, according to research published between 2023 and 2024? Include specific accuracy metrics and benchmarks."

See references/search_strategies.md for comprehensive guidance on query design, domain-specific patterns, and advanced techniques.

Common Use Cases

Scientific Literature Search

python scripts/perplexity_search.py \
  "What does recent research (2023-2024) say about the role of gut microbiome in Parkinson's disease? Focus on peer-reviewed studies and include specific bacterial species identified." \
  --model sonar-pro

Technical Documentation

python scripts/perplexity_search.py \
  "How to implement real-time data streaming from Kafka to PostgreSQL using Python? Include considerations for handling backpressure and ensuring exactly-once semantics." \
  --model sonar-reasoning-pro

Comparative Analysis

python scripts/perplexity_search.py \
  "Compare PyTorch versus TensorFlow for implementing transformer models in terms of ease of use, performance, and ecosystem support. Include benchmarks from recent studies." \
  --model sonar-pro-search

Clinical Research

python scripts/perplexity_search.py \
  "What is the evidence for intermittent fasting in managing type 2 diabetes in adults? Focus on randomized controlled trials and report HbA1c changes and weight loss outcomes." \
  --model sonar-pro

Trend Analysis

python scripts/perplexity_search.py \
  "What are the key trends in single-cell RNA sequencing technology over the past 5 years? Highlight improvements in throughput, cost, and resolution, with specific examples." \
  --model sonar-pro

Working with Results

Programmatic Access

Use perplexity_search.py as a module:

from scripts.perplexity_search import search_with_perplexity

result = search_with_perplexity(
    query="What are the latest CRISPR developments?",
    model="openrouter/perplexity/sonar-pro",
    max_tokens=4000,
    temperature=0.2,
    verbose=False
)

if result["success"]:
    print(result["answer"])
    print(f"Tokens used: {result['usage']['total_tokens']}")