parallel-research

What this skill does

# Parallel Research

## Overview

Deep web research, competitive intelligence, entity discovery, and data enrichment using Parallel AI's specialized APIs.

## Quick Decision Tree

```
What do you need?
│
├── Quick factual answer (3-5 seconds)
│   └── Chat API ($0.005/request)
│   └── Script: scripts/parallel_research.py chat "question"
│
├── Comprehensive research report (5min-2hr)
│   └── Deep Research API ($0.30/report for ultra)
│   └── Script: scripts/parallel_research.py research "topic"
│
├── Find entities matching criteria (companies, people)
│   └── FindAll API ($0.03 + $0.10/match)
│   └── Script: scripts/parallel_research.py findall "query"
│
└── Enrich existing data (add fields to records)
    └── Task API with schema ($0.025/record for core)
    └── Script: scripts/parallel_research.py enrich data.csv
```

## Environment Setup

```bash
# Required in .env
PARALLEL_API_KEY=your_api_key_here
```

Get your API key: https://platform.parallel.ai/settings/api-keys

## Common Usage

### Quick Q&A
```bash
python scripts/parallel_research.py chat "What is Anthropic's latest funding round?"
```

### Deep Research Report
```bash
python scripts/parallel_research.py research "Competitive landscape of AI code editors in 2025" --processor ultra
```

### Find Companies
```bash
python scripts/parallel_research.py findall "AI code editor companies that raised funding in 2024-2025" --limit 50
```

### Basic Research (Simplified)
```bash
python scripts/basic_research.py "Company Name"
```

### Vendor Selection
```bash
python scripts/vendor_selection.py "CRM software" --requirements "enterprise,API,automation"
```

## Processor Tiers

| Processor | Cost/1K | Latency | Best For |
|-----------|---------|---------|----------|
| `lite` | $5 | 10-60s | Basic metadata |
| `base` | $10 | 15-100s | Simple research |
| `core` | $25 | 1-5min | Cross-referenced research |
| `pro` | $100 | 2-10min | Exploratory research |
| `ultra` | $300 | 5-25min | Deep research (recommended) |
| `ultra-fast` | $300 | 2-10min | Speed + quality |

## Cost Estimates

| Task | API | Cost |
|------|-----|------|
| 100 quick questions | Chat | $0.50 |
| Market research report | Deep Research (ultra) | $0.30 |
| Find 50 competitors | FindAll (core) | ~$5.00 |
| Enrich 100 leads | Task (core) | $2.50 |

## Free Tier

20,000 requests free (combined across all APIs).

## Security Notes

### Credential Handling
- Store `PARALLEL_API_KEY` in `.env` file (never commit to git)
- Regenerate keys at https://platform.parallel.ai/settings/api-keys
- Never log or print API keys in script output
- Use environment variables, not hardcoded values

### Data Privacy
- Research queries are sent to Parallel AI servers
- Research outputs may contain third-party company information
- Results are stored locally in `.tmp/` directory
- Parallel AI may log queries for service improvement
- Avoid including sensitive internal data in research queries

### Access Scopes
- API key provides full access to all research endpoints
- No granular permission scopes available
- Monitor usage and costs via Parallel AI dashboard

### Compliance Considerations
- **Data Sources**: Research pulls from public web sources
- **Citation**: Always cite sources in research outputs
- **Accuracy**: AI-generated research should be verified
- **Competitive Intel**: Ensure competitive research complies with policies
- **Third-Party Data**: Respect intellectual property of sources
- **PII in Results**: Research results may contain company/individual PII
- **Data Freshness**: Verify currency of time-sensitive information

## Troubleshooting

### Common Issues

#### Issue: Processor timeout
**Symptoms:** Request times out or returns partial results
**Cause:** Complex query requiring more processing time than allowed
**Solution:**
- Use a faster processor tier (`lite` or `base` instead of `ultra`)
- Simplify the research query
- Break complex queries into multiple smaller requests
- Increase timeout in script if configurable

#### Issue: Credits exhausted
**Symptoms:** "Insufficient credits" or quota error
**Cause:** Account credits depleted
**Solution:**
- Check balance at https://platform.parallel.ai/dashboard
- Upgrade plan or purchase additional credits
- Use lower-cost processor tiers for less critical queries
- Monitor usage to avoid unexpected depletion

#### Issue: Invalid response format
**Symptoms:** JSON parsing error or unexpected response structure
**Cause:** API returned error or malformed response
**Solution:**
- Check query format matches API requirements
- Retry the request (may be transient issue)
- Verify API key is valid and active
- Review API documentation for expected response format

#### Issue: Empty or irrelevant results
**Symptoms:** Research returns no results or off-topic content
**Cause:** Query too narrow, ambiguous, or poorly structured
**Solution:**
- Broaden the search query
- Add context to clarify query intent
- Try different phrasing or keywords
- Use Chat API first to validate query understanding

#### Issue: API authentication failed
**Symptoms:** "Invalid API key" or 401 error
**Cause:** API key expired, invalid, or not set
**Solution:**
- Regenerate key at https://platform.parallel.ai/settings/api-keys
- Verify `PARALLEL_API_KEY` is set correctly in `.env`
- Check for leading/trailing whitespace in key
- Ensure key has not been revoked

#### Issue: Rate limited
**Symptoms:** 429 error or "rate limit exceeded"
**Cause:** Too many concurrent requests
**Solution:**
- Add delays between requests
- Reduce parallel request count
- Implement exponential backoff
- Contact support for higher rate limits if needed

## Resources

- **references/api-guide.md** - Complete API documentation
- **references/basic-research.md** - Simple company research
- **references/vendor-selection.md** - Vendor comparison workflow

## Integration Patterns

### Research to Report
**Skills:** parallel-research → content-generation
**Use case:** Create polished reports from research findings
**Flow:**
1. Run deep research on topic/company
2. Generate structured research output
3. Format into branded document via content-generation

### FindAll to CRM
**Skills:** parallel-research → attio-crm
**Use case:** Populate CRM with discovered companies
**Flow:**
1. Use FindAll to discover companies matching criteria
2. Enrich each company with additional data
3. Create/update company records in Attio CRM

### Research to Sheets
**Skills:** parallel-research → google-workspace
**Use case:** Build research database in Google Sheets
**Flow:**
1. Run FindAll or batch research on multiple entities
2. Structure results as tabular data
3. Upload to Google Sheets for team collaboration