Perplexity Research Query Patterns

Reference patterns for .claude/agents/perplexity-research.md.

Core Rule

Use only:

python3 $CLAUDE_PROJECT_DIR/.claude/skills/earnings-orchestrator/scripts/pit_fetch.py --source perplexity --op research ...

Return the wrapper JSON envelope directly.

PIT Mode (Historical)

python3 $CLAUDE_PROJECT_DIR/.claude/skills/earnings-orchestrator/scripts/pit_fetch.py \
  --source perplexity --op research \
  --query "Comprehensive analysis of AAPL Q1 2025 earnings" \
  --pit 2025-02-01T00:00:00-05:00 \
  --search-context-size high \
  --timeout 120

In PIT mode, the synthesis item is excluded from data[] (its availableat = now > PIT). Agent works from PIT-filtered searchresults only.

Open Mode (Live)

python3 $CLAUDE_PROJECT_DIR/.claude/skills/earnings-orchestrator/scripts/pit_fetch.py \
  --source perplexity --op research \
  --query "Comprehensive analysis of AAPL Q1 2025 earnings" \
  --search-context-size high \
  --timeout 120

In open mode, data[] includes searchresults plus a synthesis item (recordtype: "synthesis") with answer and citations.

Notes

• Uses Perplexity sonar-deep-research model via POST /chat/completions.
• Slow: Deep research takes 30+ seconds. Always use --timeout 120.
• pitfetch.py normalizes each searchresult with:

- availableat (date-only -> start-of-day NY tz) - availableatsource: "providermetadata"

• Synthesis item has recordtype: "synthesis", answer, citations, availableat, availableatsource.
• Authentication is handled by pitfetch.py via .env (PERPLEXITYAPI_KEY).
• Response is JSON-only (data[], gaps[]) for deterministic hook validation.