parallel-search

What this skill does

# Parallel Search

Web research using Parallel's Search API with extended excerpts (up to 30K chars per result).

## When to Use

Use for comprehensive research on:
- Technical topics requiring multiple perspectives
- New frameworks, libraries, technologies
- Comparative analysis
- Current events
- Documentation synthesis

## Prerequisites

**Required:**
- `PARALLEL_API_KEY` environment variable
- Get key: https://platform.parallel.ai/

**Dependencies:** Auto-installed via pnpm

## Workflow

When user requests research:

1. Analyze question to identify main objective
2. Generate 3-5 targeted query angles for multi-perspective coverage
3. Execute single bash command with `--objective` and `--queries` parameters
4. API returns deduplicated results from parallel execution
5. Analyze extended excerpts and synthesize findings
6. Save report to `docs/research/parallel/TIMESTAMP-topic.md`

## Usage

### Comprehensive Research (Recommended)

```bash
cd plugins/knowledge-work/skills/parallel-search
pnpm tsx scripts/search.ts \
  --objective "Production RAG system architecture" \
  --queries \
    "RAG chunking strategies" \
    "RAG evaluation metrics" \
    "RAG deployment challenges" \
    "RAG vector database selection"
```

The API executes all queries in parallel and returns deduplicated results automatically.

### Quick Single Query

```bash
pnpm tsx scripts/search.ts --objective "When was the UN founded?"
```

### Processor Levels

```bash
# Default: pro (balanced quality/speed)
pnpm tsx scripts/search.ts --objective "..."

# Ultra: maximum quality for critical research
pnpm tsx scripts/search.ts --objective "..." --processor ultra
```

## Parameters

- `--objective` (required): Main search objective (natural language, be specific)
- `--queries`: Additional query angles (max 5, 200 chars each)
- `--processor`: lite/base/pro/ultra (default: pro)
- `--max-results`: Results per search (default: 15)
- `--max-chars`: Excerpt length per result (default: 5000, max: 30000)

## Output Format

Returns markdown with:
- Search metadata (objective, result count, execution time)
- Top domains distribution
- Ranked results:
  - Title and URL
  - Domain
  - Extended excerpts (joined with double newlines)
  - Rank

## Query Generation Strategy

**For broad topics:** Generate queries covering different aspects

Example: "RAG systems"
- Objective: "Production RAG system architecture overview"
- Queries: "chunking strategies", "evaluation metrics", "deployment patterns", "vector databases"

**For comparisons:** Generate queries for each option plus general comparison

Example: "PostgreSQL vs MongoDB"
- Objective: "PostgreSQL vs MongoDB comparison"
- Queries: "PostgreSQL use cases", "MongoDB use cases", "relational vs document databases"

**For current events:** Use temporal and source diversity

Example: "Latest AI developments"
- Objective: "Recent AI model releases and benchmarks"
- Queries: "GPT-4 updates", "open source LLMs", "AI safety research", "industry adoption"

## Research Persistence

After synthesis, save report:

1. Get timestamp: Use `timestamp` skill for YYYYMMDDHHMMSS format
2. Sanitize topic: Use `sanitizeForFilename` from formatter.ts (kebab-case, 50 char limit)
3. Save to: `docs/research/parallel/TIMESTAMP-topic.md`
4. Include: Findings, sources with URLs, analysis

## Error Handling

**Missing API key:**
```bash
export PARALLEL_API_KEY="your-key-here"
```

**Rate limit exceeded:** Wait for reset time (shown in error message)

**Network errors:** Retry with `--processor lite` for faster response

**Validation errors:** Check constraints (max 5 queries, 200 chars each)

## Constraints

- Max 5 queries per request
- Max 200 chars per query
- Max 30K chars per excerpt (not guaranteed above 30K)
- Rate limits depend on API plan tier
- Requires internet connection

## Best Practices

- Use specific objectives: "Production RAG architecture" > "RAG systems"
- Leverage all 5 query slots for comprehensive coverage
- Use `--max-chars` up to 30000 for deep content analysis
- Adapt processor level to urgency: pro for most, ultra for critical
- Save multi-query research for future reference

## Implementation

**Files:**
- `types.ts` - Interfaces and error types
- `parallel-client.ts` - API client with validation
- `formatter.ts` - Markdown output formatting
- `log.ts` - CLI logging
- `search.ts` - CLI entry point

**Testing:**
```bash
pnpm test
```