Skill: hushenglang/perplexity-research (version 2.0.0)

--- name: perplexity-research version: 2.0.0 description: Conduct deep research using Perplexity Agent API with web search, reasoning, and multi-model analysis. Use when the user needs current information, market research, trend analysis, investment insights, or comprehensive research on any topic requiring web search and reasoning capabilities. --- # 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**: Compare key insights across models with `compare_models()` 3. **Deep dive**: Use streaming for detailed analysis on specific aspects 4. **Cost-aware**: Monitor token usage and costs in results ## Model Selection **Default: `openai/gpt-5.2`** (Latest GPT model) Alternative models: - `anthropic/claude-3-5-sonnet` - Strong reasoning, balanced performance - `google/gemini-2.0-flash` - Fast, cost-effective - `meta/llama-3.3-70b` - Open source alternative Switch models based on: - Quality needs (GPT-5.2 for best results) - Speed requirements (Gemini Flash for quick answers) - Cost constraints (compare costs in results) ## Reasoning Effort Levels Control analysis depth with `reasoning_effort`: - `"low"` - Quick answers, minimal reasoning - `"medium"` - Balanced reasoning (default for most queries) - `"high"` - Deep analysis, comprehensive research (recommended for research) ## Environment Setup Ensure `PERPLEXITY_API_KEY` is set: ```bash export PERPLEXITY_API_KEY='your_api_key_here' ``` Or create `.env` file in the skill's `scripts/` directory: ``` PERPLEXITY_API_KEY=your_api_key_here ``` ## Error Handling All methods return error information: ```python result = client.research_query("Your question") if "error" in result: print(f"Error: {result['error']}") # Handle error appropriately else: # Process successful result print(result["answer"]) ``` ## Cost Optimization - Use `max_tokens` to limit response length - Start with lower reasoning effort, increase if needed - Use `search_query()` instead of `research_query()` for simpler questions - Monitor costs via `result["cost"]` field ## Integration Examples ### Investment Research ```python client = PerplexityClient() # Market analysis result = client.research_query( query="Analyze recent developments in AI chip market and key competitors", reasoning_effort="high" ) # Company deep dive result = client.search_query( query="Latest earnings report for NVIDIA Q4 2025" ) # Multi-model validation results = client.compare_models( query="What are the biggest risks in the semiconductor industry?", models=["openai/gpt-5.2", "anthropic/claude-3-5-sonnet"] ) ``` ### Trend Analysis ```python # Current trends with web search result = client.research_query( query="Emerging trends in sustainable investing and ESG adoption rates", reasoning_effort="high", max_tokens=2000 ) # Stream for real-time updates client.stream_query( query="Latest developments in quantum computing commercialization", use_search=True ) ``` ### Multi-Turn Research ```python # Build context across multiple queries messages = [ {"role": "user", "content": "What is the current state of fusion energy?"}, {"role": "assistant", "content": "...previous response..."}, {"role": "user", "content": "Which companies are leading in this space?"} ] result = client.conversation( messages=messages, use_search=True ) ``` ## Best Practices 1. **Default to research_query()** for most research tasks - it combines web search with high reasoning 2. **Use streaming** for user-facing applications to show progress 3. **Compare models** for critical decisions or when quality is paramount 4. **Set reasonable max_tokens** - 1000 for summaries, 2000+ for deep analysis 5. **Track costs** - access via `result["cost"]` and `result["tokens"]` 6. **Handle errors gracefully** - always check for "error" key in results ## API Reference See [reference.md](reference.md) for complete API documentation, or `scripts/perplexity_client.py` for: - Full method signatures - Additional parameters - CLI usage examples - Implementation details ## Command Line Usage Run from the skill directory: ```bash # Research mode python scripts/perplexity_client.py research "Your question" # Web search python scripts/perplexity_client.py search "Your question" # Streaming python scripts/perplexity_client.py stream "Your question" # Compare models python scripts/perplexity_client.py compare "Your question" ```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)