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**:
- 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**:...

# Perplexity Research Skill

AI agent skill for conducting deep research using Perplexity Agent API with web search, reasoning, and multi-model analysis capabilities.

## Structure

```
perplexity-research/
├── SKILL.md              # Main skill instructions for the AI agent
├── examples.md           # Practical usage examples
├── reference.md          # Complete API reference documentation
├── README.md            # This file
└── scripts/
    ├── perplexity_client.py  # Perplexity API client implementation
    └── .env.example          # Environment variable template
```

## Setup

1. **Install dependencies:**
   ```bash
   pip install perplexity python-dotenv
   ```

2. **Configure API key:**
   
   Create `.env` file in the `scripts/` directory:
   ```bash
   cd .cursor/skills/perplexity-research/scripts
   cp .env.example .env
   # Edit .env and add your actual API key
   ```
   
   Or export as environment variable:
   ```bash
   export PERPLEXITY_API_KEY='your_api_key_here'
   ```

3. **Get your API key:**
   - Sign up at [Perplexity API](https://www.perplexity.ai/api)
   - Generate an API key from your dashboard

## Quick Usage

### As CLI Tool

```bash
cd .cursor/skills/perplexity-research

# Research mode (recommended for deep analysis)
python scripts/perplexity_client.py research "What are the latest developments in AI chip manufacturing?"

# Quick web search
python scripts/perplexity_client.py search "NVIDIA latest earnings report"

# Streaming response
python scripts/perplexity_client.py stream "Explain quantum computing"

# Compare multiple models
python scripts/perplexity_client.py compare "What are the risks in semiconductor industry?"
```

### As Python Library

```python
import sys
from pathlib import Path

# Add scripts to path
skill_dir = Path(".cursor/skills/perplexity-research")
sys.path.insert(0, str(skill_dir / "scripts"))

from perplexity_client import PerplexityClient

# Initialize client
client = PerplexityClient()

# Conduct research
resul...