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:

• Analyze question to identify main objective

• Generate 3-5 targeted query angles for multi-perspective coverage

• Execute single bash command with --objective and --queries parameters

• API returns deduplicated results from parallel execution

• Analyze extended excerpts and synthesize findings

• Save report to docs/research/parallel/TIMESTAMP-topic.md

Usage

Comprehensive Research (Recommended)

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

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

Processor Levels

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:

• Get timestamp: Use timestamp skill for YYYYMMDDHHMMSS format

• Sanitize topic: Use sanitizeForFilename from formatter.ts (kebab-case, 50 char limit)

• Save to: docs/research/parallel/TIMESTAMP-topic.md

• Include: Findings, sources with URLs, analysis

Error Handling

Missing API key:

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:

pnpm test