perplexity-research

使用 Perplexity Agent API 进行网络搜索、推理和多模型分析进行深入研究。当用户需要当前信息、市场研究、趋势分析、投资见解或需要网络搜索和推理能力的任何主题的综合研究时使用。

## 概述（中文）

使用 Perplexity Agent API 进行网络搜索、推理和多模型分析进行深入研究。当用户需要当前信息、市场研究、趋势分析、投资见解或需要网络搜索和推理能力的任何主题的综合研究时使用。

## 原文

# 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**:
- Web search for current information
- High reasoning effort for deep analysis
- Multi-model comparison
- Streaming responses
- Cost tracking

## Common Research Patterns

### 1. Deep Research Query

Use for comprehensive analysis requiring web search and reasoning:

```python
# 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:

```python
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:

```python
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:

```python
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:
- `anthropic/claude-3-5-sonnet` - Strong reasoning, balanced performance
- `google/gemini-2.0-flash` - Fast, cost-effective
- `meta/llama-3.3-70b` - Open source alternative

Switch models based on:
- Quality needs (GPT-5.2 for best results)
- Speed requirements (Gemini Flash for quick answers)
- Cost constraints (compare costs in results)

## Reasoning Effort Levels

Control analysis depth with `reasoning_effort`:

- `"low"` - Quick answers, minimal reasoning
- `"medium"` - Balanced reasoning (default for most queries)
- `"high"` - Deep analysis, comprehensive research (recommended for research)

## Environment Setup

Ensure `PERPLEXITY_API_KEY` is set:

```bash
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:

```python
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

- Use `max_tokens` to limit response length
- Start with lower reasoning effort, increase if needed
- Use `search_query()` instead of `research_query()` for simpler questions
- Monitor costs via `result["cost"]` field

## Integration Examples

### Investment Research

```python
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

```python
# 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

```python
# 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](reference.md) for complete API documentation, or `scripts/perplexity_client.py` for:
- Full method signatures
- Additional parameters
- CLI usage examples
- Implementation details

## Command Line Usage

Run from the skill directory:

```bash
# 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"
```

---

## 中文说明

# Perplexity Research

由 Perplexity Agent API 驱动的研究助手，具备网络搜索和推理能力。

## 快速开始

Perplexity 客户端位于本技能文件夹中的 `scripts/perplexity_client.py`。

**默认模型**：`openai/gpt-5.2`（最新 GPT）

**核心能力**：
- 网络搜索以获取当前信息
- 高强度推理以进行深度分析
- 多模型比较
- 流式响应
- 成本跟踪

## 常见研究模式

### 1. 深度研究查询

用于需要网络搜索和推理的综合分析：

```python
# 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. 快速网络搜索

用于时效性强或当前的信息：

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

### 3. 模型比较

当输出质量至关重要时使用：

```python
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. 长响应的流式传输

用于改善冗长分析的用户体验：

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

## 研究工作流

进行研究时：

1. **初步探索**：在启用网络搜索的情况下使用 `research_query()`
2. **验证结论**：使用 `compare_models()` 跨模型比较关键见解
3. **深入挖掘**：对特定方面使用流式传输进行详细分析
4. **成本意识**：在结果中监控令牌用量和成本

## 模型选择

**默认：`openai/gpt-5.2`**（最新 GPT 模型）

备选模型：
- `anthropic/claude-3-5-sonnet` - 推理能力强，性能均衡
- `google/gemini-2.0-flash` - 快速、性价比高
- `meta/llama-3.3-70b` - 开源替代方案

根据以下因素切换模型：
- 质量需求（GPT-5.2 获得最佳结果）
- 速度要求（Gemini Flash 用于快速回答）
- 成本约束（在