@saibolla/ada 0.1.2

package/skills/perplexity-search/references/openrouter_setup.md

@@ -0,0 +1,454 @@
+# OpenRouter Setup Guide
+
+Complete guide to setting up and using OpenRouter for Perplexity model access.
+
+## What is OpenRouter?
+
+OpenRouter is a unified API gateway that provides access to 100+ AI models from various providers through a single API interface. It offers:
+
+- **Single API key**: Access multiple models with one key
+- **Unified format**: OpenAI-compatible API format
+- **Cost tracking**: Built-in usage monitoring and billing
+- **Model routing**: Intelligent fallback and load balancing
+- **Pay-as-you-go**: No subscriptions, pay only for what you use
+
+For Perplexity models specifically, OpenRouter provides exclusive access to certain models like Sonar Pro Search.
+
+## Getting Started
+
+### Step 1: Create OpenRouter Account
+
+1. Visit https://openrouter.ai/
+2. Click "Sign Up" in the top right
+3. Sign up with Google, GitHub, or email
+4. Verify your email if using email signup
+
+### Step 2: Add Payment Method
+
+OpenRouter uses pay-as-you-go billing:
+
+1. Navigate to https://openrouter.ai/account
+2. Click "Credits" tab
+3. Add a payment method (credit card)
+4. Add initial credits (minimum $5 recommended)
+5. Optionally set up auto-recharge
+
+**Pricing notes:**
+- Models have different per-token costs
+- See https://openrouter.ai/perplexity for Perplexity pricing
+- Monitor usage at https://openrouter.ai/activity
+
+### Step 3: Generate API Key
+
+1. Go to https://openrouter.ai/keys
+2. Click "Create Key"
+3. Give your key a descriptive name (e.g., "perplexity-search-skill")
+4. Optionally set usage limits for safety
+5. Copy the key (starts with `sk-or-v1-...`)
+6. **Important**: Save this key securely - you can't view it again!
+
+**Security tips:**
+- Never share your API key publicly
+- Don't commit keys to version control
+- Use separate keys for different projects
+- Set usage limits to prevent unexpected charges
+- Rotate keys periodically
+
+### Step 4: Configure Environment
+
+You have two options for setting up your API key:
+
+#### Option A: Environment Variable (Recommended)
+
+**Linux/macOS:**
+```bash
+export OPENROUTER_API_KEY='sk-or-v1-your-key-here'
+```
+
+To make it permanent, add to your shell profile:
+```bash
+# For bash: Add to ~/.bashrc or ~/.bash_profile
+echo 'export OPENROUTER_API_KEY="sk-or-v1-your-key-here"' >> ~/.bashrc
+source ~/.bashrc
+
+# For zsh: Add to ~/.zshrc
+echo 'export OPENROUTER_API_KEY="sk-or-v1-your-key-here"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Windows (PowerShell):**
+```powershell
+$env:OPENROUTER_API_KEY = "sk-or-v1-your-key-here"
+```
+
+To make it permanent:
+```powershell
+[System.Environment]::SetEnvironmentVariable('OPENROUTER_API_KEY', 'sk-or-v1-your-key-here', 'User')
+```
+
+#### Option B: .env File
+
+Create a `.env` file in your project directory:
+
+```bash
+# Create .env file
+cat > .env << EOF
+OPENROUTER_API_KEY=sk-or-v1-your-key-here
+EOF
+```
+
+Or use the setup script:
+```bash
+python scripts/setup_env.py --api-key sk-or-v1-your-key-here
+```
+
+Then load it before running scripts:
+```bash
+# Load environment variables from .env
+source .env
+
+# Or use python-dotenv
+pip install python-dotenv
+```
+
+**Using python-dotenv in scripts:**
+```python
+from dotenv import load_dotenv
+load_dotenv()  # Loads .env file automatically
+
+import os
+api_key = os.environ.get("OPENROUTER_API_KEY")
+```
+
+### Step 5: Install Dependencies
+
+Install LiteLLM using uv:
+
+```bash
+uv pip install litellm
+```
+
+Or with regular pip:
+```bash
+pip install litellm
+```
+
+**Optional dependencies:**
+```bash
+# For .env file support
+uv pip install python-dotenv
+
+# For additional features
+uv pip install litellm[proxy]  # If using LiteLLM proxy server
+```
+
+### Step 6: Verify Setup
+
+Test your configuration:
+
+```bash
+# Using the setup script
+python scripts/setup_env.py --validate
+
+# Or using the search script
+python scripts/perplexity_search.py --check-setup
+```
+
+You should see:
+```
+✓ OPENROUTER_API_KEY is set (sk-or-v1-...xxxx)
+✓ LiteLLM is installed (version X.X.X)
+✓ Setup is complete! You're ready to use Perplexity Search.
+```
+
+### Step 7: Test Your First Search
+
+Run a simple test query:
+
+```bash
+python scripts/perplexity_search.py "What is CRISPR gene editing?"
+```
+
+Expected output:
+```
+================================================================================
+ANSWER
+================================================================================
+CRISPR (Clustered Regularly Interspaced Short Palindromic Repeats) is a
+revolutionary gene editing technology that allows precise modifications to DNA...
+[detailed answer continues]
+================================================================================
+```
+
+## Usage Monitoring
+
+### Check Your Usage
+
+Monitor your OpenRouter usage and costs:
+
+1. Visit https://openrouter.ai/activity
+2. View requests, tokens, and costs
+3. Filter by date range, model, or key
+4. Export usage data for analysis
+
+### Set Usage Limits
+
+Protect against unexpected charges:
+
+1. Go to https://openrouter.ai/keys
+2. Click on your key
+3. Set "Rate limit" (requests per minute)
+4. Set "Spending limit" (maximum total spend)
+5. Enable "Auto-recharge" with limit if desired
+
+**Recommended limits for development:**
+- Rate limit: 10-20 requests per minute
+- Spending limit: $10-50 depending on usage
+
+### Cost Optimization
+
+Tips for reducing costs:
+
+1. **Choose appropriate models**: Use Sonar for simple queries, not Sonar Pro Search
+2. **Set max_tokens**: Limit response length with `--max-tokens` parameter
+3. **Batch queries**: Combine multiple simple questions when possible
+4. **Monitor usage**: Check costs daily during heavy development
+5. **Use caching**: Store results for repeated queries
+
+## Troubleshooting
+
+### Error: "OpenRouter API key not configured"
+
+**Cause**: Environment variable not set
+
+**Solution**:
+```bash
+# Check if variable is set
+echo $OPENROUTER_API_KEY
+
+# If empty, set it
+export OPENROUTER_API_KEY='sk-or-v1-your-key-here'
+
+# Or use setup script
+python scripts/setup_env.py --api-key sk-or-v1-your-key-here
+```
+
+### Error: "Invalid API key"
+
+**Causes**:
+- Key was deleted or revoked
+- Key has expired
+- Typo in the key
+- Wrong key format
+
+**Solutions**:
+1. Verify key at https://openrouter.ai/keys
+2. Check for extra spaces or quotes
+3. Generate a new key if needed
+4. Ensure key starts with `sk-or-v1-`
+
+### Error: "Insufficient credits"
+
+**Cause**: OpenRouter account has run out of credits
+
+**Solution**:
+1. Go to https://openrouter.ai/account
+2. Click "Credits" tab
+3. Add more credits
+4. Consider enabling auto-recharge
+
+### Error: "Rate limit exceeded"
+
+**Cause**: Too many requests in a short time
+
+**Solutions**:
+1. Wait a few seconds before retrying
+2. Increase rate limit at https://openrouter.ai/keys
+3. Implement exponential backoff in code
+4. Batch requests or reduce frequency
+
+### Error: "Model not found"
+
+**Cause**: Incorrect model name or model no longer available
+
+**Solution**:
+1. Check available models at https://openrouter.ai/models
+2. Use correct format: `openrouter/perplexity/sonar-pro`
+3. Verify model is still supported
+
+### Error: "LiteLLM not installed"
+
+**Cause**: LiteLLM package is not installed
+
+**Solution**:
+```bash
+uv pip install litellm
+```
+
+### Import Error with LiteLLM
+
+**Cause**: Python path issues or version conflicts
+
+**Solutions**:
+1. Verify installation: `pip list | grep litellm`
+2. Reinstall: `uv pip install --force-reinstall litellm`
+3. Check Python version: `python --version` (requires 3.8+)
+4. Use virtual environment to avoid conflicts
+
+## Advanced Configuration
+
+### Using Multiple Keys
+
+For different projects or team members:
+
+```bash
+# Project 1
+export OPENROUTER_API_KEY='sk-or-v1-project1-key'
+
+# Project 2
+export OPENROUTER_API_KEY='sk-or-v1-project2-key'
+```
+
+Or use .env files in different directories.
+
+### Custom Base URL
+
+If using OpenRouter proxy or custom endpoint:
+
+```python
+from litellm import completion
+
+response = completion(
+    model="openrouter/perplexity/sonar-pro",
+    messages=[{"role": "user", "content": "query"}],
+    api_base="https://custom-endpoint.com/v1"  # Custom URL
+)
+```
+
+### Request Headers
+
+Add custom headers for tracking:
+
+```python
+from litellm import completion
+
+response = completion(
+    model="openrouter/perplexity/sonar-pro",
+    messages=[{"role": "user", "content": "query"}],
+    extra_headers={
+        "HTTP-Referer": "https://your-app.com",
+        "X-Title": "Your App Name"
+    }
+)
+```
+
+### Timeout Configuration
+
+Set custom timeouts for long-running queries:
+
+```python
+from litellm import completion
+
+response = completion(
+    model="openrouter/perplexity/sonar-pro-search",
+    messages=[{"role": "user", "content": "complex query"}],
+    timeout=120  # 120 seconds timeout
+)
+```
+
+## Security Best Practices
+
+### API Key Management
+
+1. **Never commit keys**: Add `.env` to `.gitignore`
+2. **Use key rotation**: Rotate keys every 3-6 months
+3. **Separate keys**: Different keys for dev/staging/production
+4. **Monitor usage**: Check for unauthorized access
+5. **Set limits**: Configure spending and rate limits
+
+### .gitignore Template
+
+Add to your `.gitignore`:
+```
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# API keys
+*api_key*
+*apikey*
+*.key
+
+# Sensitive configs
+config/secrets.yaml
+```
+
+### Key Revocation
+
+If a key is compromised:
+
+1. Go to https://openrouter.ai/keys immediately
+2. Click "Delete" on the compromised key
+3. Generate a new key
+4. Update all applications using the old key
+5. Review usage logs for unauthorized access
+6. Contact OpenRouter support if needed
+
+## FAQs
+
+**Q: How much does it cost to use Perplexity via OpenRouter?**
+
+A: Pricing varies by model. Sonar is cheapest (~$0.001-0.002 per query), Sonar Pro is moderate (~$0.002-0.005), and Sonar Pro Search is most expensive (~$0.02-0.05+ per query). See https://openrouter.ai/perplexity for exact pricing.
+
+**Q: Do I need a separate Perplexity API key?**
+
+A: No! OpenRouter provides access to Perplexity models using only your OpenRouter key.
+
+**Q: Can I use OpenRouter for other models besides Perplexity?**
+
+A: Yes! OpenRouter provides access to 100+ models from OpenAI, Anthropic, Google, Meta, and more through the same API key.
+
+**Q: Is there a free tier?**
+
+A: OpenRouter requires payment, but offers very competitive pricing. Initial $5 credit should last for extensive testing.
+
+**Q: How do I cancel my OpenRouter account?**
+
+A: Contact OpenRouter support. Note that unused credits may not be refundable.
+
+**Q: Can I use OpenRouter in production applications?**
+
+A: Yes, OpenRouter is designed for production use with robust infrastructure, SLAs, and enterprise support available.
+
+## Resources
+
+**Official Documentation:**
+- OpenRouter: https://openrouter.ai/docs
+- Perplexity Models: https://openrouter.ai/perplexity
+- LiteLLM: https://docs.litellm.ai/
+
+**Account Management:**
+- Dashboard: https://openrouter.ai/account
+- API Keys: https://openrouter.ai/keys
+- Usage: https://openrouter.ai/activity
+- Billing: https://openrouter.ai/credits
+
+**Community:**
+- OpenRouter Discord: https://discord.gg/openrouter
+- GitHub Issues: https://github.com/OpenRouter
+- LiteLLM GitHub: https://github.com/BerriAI/litellm
+
+## Summary
+
+Setting up OpenRouter for Perplexity access involves:
+
+1. Create account at https://openrouter.ai
+2. Add payment method and credits
+3. Generate API key at https://openrouter.ai/keys
+4. Set `OPENROUTER_API_KEY` environment variable
+5. Install LiteLLM: `uv pip install litellm`
+6. Verify setup: `python scripts/setup_env.py --validate`
+7. Start searching: `python scripts/perplexity_search.py "your query"`
+
+Monitor usage and costs regularly to optimize your spending and ensure security.

package/skills/perplexity-search/references/search_strategies.md

@@ -0,0 +1,258 @@
+# Search Strategies for Perplexity
+
+Best practices and strategies for crafting effective search queries with Perplexity models.
+
+## Query Design Principles
+
+### Be Specific and Detailed
+
+Better results come from specific, well-structured queries rather than broad questions.
+
+**Good examples:**
+- "What are the latest clinical trial results for CAR-T cell therapy in treating B-cell lymphoma published in 2024?"
+- "Compare the efficacy and safety profiles of mRNA vaccines versus viral vector vaccines for COVID-19"
+- "Explain the mechanism of CRISPR-Cas9 off-target effects and current mitigation strategies"
+
+**Bad examples:**
+- "Tell me about cancer treatment" (too broad)
+- "CRISPR" (too vague)
+- "vaccines" (lacks specificity)
+
+### Structure Complex Queries
+
+Break complex questions into clear components:
+
+1. **Topic**: What is the main subject?
+2. **Scope**: What specific aspect are you interested in?
+3. **Context**: What time frame, domain, or constraints apply?
+4. **Output**: What format or type of answer do you need?
+
+**Example:**
+```
+Topic: Protein folding prediction
+Scope: AlphaFold3 improvements over AlphaFold2
+Context: Published research from 2023-2024
+Output: Technical comparison with specific accuracy metrics
+```
+
+**Query:**
+"What improvements does AlphaFold3 offer over AlphaFold2 for protein structure prediction, according to research published between 2023 and 2024? Include specific accuracy metrics and benchmarks."
+
+## Domain-Specific Search Patterns
+
+### Scientific Literature Search
+
+For scientific queries, include:
+- Specific terminology and concepts
+- Time constraints (recent publications)
+- Methodology or study types of interest
+- Journal quality or domain constraints
+
+**Template:**
+"What does recent research (2023-2024) say about [specific scientific concept] in [domain]? Focus on [peer-reviewed/preprint] studies and include [specific metrics/findings]."
+
+**Example:**
+"What does recent research (2023-2024) say about the role of gut microbiome in Parkinson's disease? Focus on peer-reviewed studies and include specific bacterial species identified."
+
+### Technical/Engineering Search
+
+For technical queries, specify:
+- Technology stack or framework
+- Use case or application context
+- Version requirements
+- Performance or implementation constraints
+
+**Template:**
+"How to [specific technical task] using [technology/framework] for [use case]? Include [implementation details/performance considerations]."
+
+**Example:**
+"How to implement real-time data streaming from Kafka to PostgreSQL using Python? Include considerations for handling backpressure and ensuring exactly-once semantics."
+
+### Medical/Clinical Search
+
+For medical queries, include:
+- Specific conditions, treatments, or interventions
+- Patient population or demographics
+- Outcomes of interest
+- Evidence level (RCTs, meta-analyses, etc.)
+
+**Template:**
+"What is the evidence for [intervention] in treating [condition] in [population]? Focus on [study types] and report [specific outcomes]."
+
+**Example:**
+"What is the evidence for intermittent fasting in managing type 2 diabetes in adults? Focus on randomized controlled trials and report HbA1c changes and weight loss outcomes."
+
+## Advanced Query Techniques
+
+### Comparative Analysis
+
+For comparing multiple options:
+
+**Template:**
+"Compare [option A] versus [option B] for [use case] in terms of [criteria 1], [criteria 2], and [criteria 3]. Include [specific evidence or metrics]."
+
+**Example:**
+"Compare PyTorch versus TensorFlow for implementing transformer models in terms of ease of use, performance, and ecosystem support. Include benchmarks from recent studies."
+
+### Trend Analysis
+
+For understanding trends over time:
+
+**Template:**
+"What are the key trends in [domain/topic] over the past [time period]? Highlight [specific aspects] and include [data or examples]."
+
+**Example:**
+"What are the key trends in single-cell RNA sequencing technology over the past 5 years? Highlight improvements in throughput, cost, and resolution, with specific examples."
+
+### Gap Identification
+
+For finding research or knowledge gaps:
+
+**Template:**
+"What are the current limitations and open questions in [field/topic]? Focus on [specific aspects] and identify areas needing further research."
+
+**Example:**
+"What are the current limitations and open questions in quantum error correction? Focus on practical implementations and identify scalability challenges."
+
+### Mechanism Explanation
+
+For understanding how things work:
+
+**Template:**
+"Explain the mechanism by which [process/phenomenon] occurs in [context]. Include [level of detail] and discuss [specific aspects]."
+
+**Example:**
+"Explain the mechanism by which mRNA vaccines induce immune responses. Include molecular details of translation, antigen presentation, and memory cell formation."
+
+## Query Refinement Strategies
+
+### Start Broad, Then Narrow
+
+1. **Initial query**: "Recent developments in cancer immunotherapy"
+2. **Refined query**: "Recent developments in checkpoint inhibitor combination therapies for melanoma"
+3. **Specific query**: "What are the clinical trial results for combining anti-PD-1 and anti-CTLA-4 checkpoint inhibitors in metastatic melanoma patients, published 2023-2024?"
+
+### Add Constraints Iteratively
+
+Start with core query, then add constraints:
+
+1. **Base**: "Machine learning for drug discovery"
+2. **Add domain**: "Machine learning for small molecule drug discovery"
+3. **Add method**: "Deep learning approaches for small molecule property prediction"
+4. **Add context**: "Recent deep learning approaches (2023-2024) for predicting ADMET properties of small molecules, including accuracy benchmarks"
+
+### Specify Desired Output Format
+
+Improve answers by specifying the output format:
+
+- "Provide a step-by-step explanation..."
+- "Summarize in bullet points..."
+- "Create a comparison table of..."
+- "List the top 5 approaches with pros and cons..."
+- "Include specific numerical benchmarks and metrics..."
+
+## Common Pitfalls to Avoid
+
+### Too Vague
+
+**Problem**: "Tell me about AI"
+**Solution**: "What are the current state-of-the-art approaches for few-shot learning in computer vision as of 2024?"
+
+### Loaded Questions
+
+**Problem**: "Why is drug X better than drug Y?"
+**Solution**: "Compare the efficacy and safety profiles of drug X versus drug Y based on clinical trial evidence."
+
+### Multiple Unrelated Questions
+
+**Problem**: "What is CRISPR and how do vaccines work and what causes cancer?"
+**Solution**: Ask separate queries for each topic.
+
+### Assumed Knowledge Without Context
+
+**Problem**: "What are the latest results?" (Latest results for what?)
+**Solution**: "What are the latest clinical trial results for CAR-T cell therapy in treating acute lymphoblastic leukemia?"
+
+## Domain-Specific Keywords
+
+### Biomedical Research
+
+Use precise terminology:
+- "randomized controlled trial" instead of "study"
+- "meta-analysis" instead of "review"
+- "in vitro" vs "in vivo" vs "clinical"
+- "peer-reviewed" for quality filter
+- Specific gene/protein names (e.g., "BRCA1" not "breast cancer gene")
+
+### Computational/AI Research
+
+Use technical terms:
+- "transformer architecture" not "AI model"
+- "few-shot learning" not "learning from limited data"
+- "zero-shot" vs "few-shot" vs "fine-tuning"
+- Specific model names (e.g., "GPT-4" not "language model")
+
+### Chemistry/Drug Discovery
+
+Use IUPAC names and specific terms:
+- "small molecule" vs "biologic"
+- "pharmacokinetics" (ADME) vs "pharmacodynamics"
+- Specific assay types (e.g., "IC50", "EC50")
+- Drug names (generic vs brand)
+
+## Time-Constrained Searches
+
+Perplexity searches real-time web data, making time constraints valuable:
+
+**Templates:**
+- "What papers were published in [journal] in [month/year] about [topic]?"
+- "What are the latest developments (past 6 months) in [field]?"
+- "What was announced at [conference] [year] regarding [topic]?"
+- "What are the most recent clinical trial results (2024) for [treatment]?"
+
+**Examples:**
+- "What papers were published in Nature Medicine in January 2024 about long COVID?"
+- "What are the latest developments (past 6 months) in large language model training efficiency?"
+- "What was announced at NeurIPS 2023 regarding AI safety and alignment?"
+
+## Source Quality Considerations
+
+For high-quality results, mention source preferences:
+
+- "According to peer-reviewed publications..."
+- "Based on clinical trial registries like clinicaltrials.gov..."
+- "From authoritative sources such as Nature, Science, Cell..."
+- "According to FDA/EMA approvals..."
+- "Based on systematic reviews or meta-analyses..."
+
+**Example:**
+"What is the current understanding of microplastics' impact on human health according to peer-reviewed research published in high-impact journals since 2022?"
+
+## Iterative Search Workflow
+
+For comprehensive research:
+
+1. **Broad overview**: Get general understanding
+2. **Specific deep-dives**: Focus on particular aspects
+3. **Comparative analysis**: Compare approaches/methods
+4. **Latest updates**: Find most recent developments
+5. **Critical evaluation**: Identify limitations and gaps
+
+**Example workflow for "CAR-T cell therapy":**
+
+1. "What is CAR-T cell therapy and how does it work?"
+2. "What are the specific molecular mechanisms by which CAR-T cells recognize and kill cancer cells?"
+3. "Compare first-generation, second-generation, and third-generation CAR-T cell designs"
+4. "What are the latest clinical trial results for CAR-T therapy in treating solid tumors (2024)?"
+5. "What are the current limitations and challenges in CAR-T cell therapy, and what approaches are being investigated to address them?"
+
+## Summary
+
+Effective Perplexity searches require:
+1. **Specificity**: Clear, detailed queries
+2. **Structure**: Well-organized questions with context
+3. **Terminology**: Domain-appropriate keywords
+4. **Constraints**: Time frames, sources, output formats
+5. **Iteration**: Refine based on initial results
+
+The more specific and structured your query, the better and more relevant your results will be.