Run Deep Research

Comprehensive/Slow Approach (minutes to complete)

• Provider: Perplexity with deep research model, or OpenAI
• Models: sonar-deep-research (Perplexity), o3-deep-research-2025-06-26 (OpenAI)
• Use when: Thorough analysis needed, critical decisions, comprehensive reports
• Cost: Higher API costs and longer wait times
• Example:

  uv run deep-research-client research "What is CRISPR?" --provider perplexity --model sonar-deep-research
  

  or

  uv run deep-research-client research "What is CRISPR?" --provider openai
  

Specialized Approaches

• Scientific Literature: Use falcon provider for academic/scientific focus
• Academic Papers: Use consensus provider for peer-reviewed research (requires API approval)

Features

• Multiple Providers: OpenAI Deep Research, FutureHouse Falcon, Perplexity AI, Consensus AI
• Rich Output: Comprehensive markdown reports with citations and YAML frontmatter metadata
• Smart Caching: File-based caching in ~/.deep_research_cache/ to avoid expensive re-queries
• Auto-detection: Automatically detects available providers from environment variables
• Templates: Support for reusable research queries with variable substitution
• Citation Management: Citations included by default or saved to separate file

Required Environment Variables

# At least one of these is required:
export OPENAI_API_KEY="your-openai-key"           # For OpenAI Deep Research
export FUTUREHOUSE_API_KEY="your-futurehouse-key" # For Falcon
export PERPLEXITY_API_KEY="your-perplexity-key"   # For Perplexity AI
export CONSENSUS_API_KEY="your-consensus-key"     # For Consensus AI (requires approval)

Basic Usage

Simple Research Query

# Basic query (uses auto-detected provider)
uv run deep-research-client research "What is quantum computing?"

# With specific provider and model
uv run deep-research-client research "What is quantum computing?" --provider perplexity --model sonar-pro

# Save to file
uv run deep-research-client research "Machine learning trends 2024" --output report.md

List Available Providers

uv run deep-research-client providers

Using Templates

Templates allow reusable research queries with variable substitution:

# Use template with variables
uv run deep-research-client research \
  --template gene_research.md \
  --var "gene=TP53" \
  --var "organism=human" \
  --var "tissue=brain tissue" \
  --var "year=2020"

Template files use {variable} placeholders:

Please research the gene {gene} in {organism}, focusing on:
1. Function and molecular mechanisms
2. Disease associations in {tissue} tissue
3. Recent discoveries since {year}

Cache Management

# List cached research
uv run deep-research-client list-cache

# Clear all cache
uv run deep-research-client clear-cache

# Bypass cache for single query
uv run deep-research-client research "query" --no-cache

Output Format

Research results are returned as markdown with YAML frontmatter:

---