@podai/plugin-perplexity - Enhanced July 2025 Edition

Advanced web search and research capabilities powered by Perplexity AI for ElizaOS. Enhanced with academic search, async processing, and location-based filtering.

Features ✨

🔍 Enhanced Search Capabilities (July 2025)

• Real-time Web Search: Current information with live citations
• Academic Search Mode: Scholarly sources and peer-reviewed papers
• Async Processing: Long-running queries with comprehensive analysis
• Location-based Filtering: Geo-targeted search results
• Extended Context: Up to 127K tokens for detailed responses

🎯 Advanced Models

• sonar-pro: Premium model with enhanced capabilities
• sonar-small/medium/large: Optimized for different use cases
• Intelligent Model Selection: Auto-selects best model per query

📊 Smart Filtering

• Time Filtering: Hour, day, week, month, year, or all time
• Domain Filtering: Limit to specific websites or sources
• Date Range Filtering: Custom start/end date ranges
• Academic Prioritization: Scholarly and research sources

Configuration

Add your Perplexity API key to your .env file:

PERPLEXITY_API_KEY=your_api_key_here

Usage

Adding to Veil Character

The plugin is automatically loaded when configured in the Veil character:

// In character configuration
plugins: [
  '@podai/plugin-perplexity',
  // other plugins...
]

Available Actions 🚀

1. Web Search (WEB_SEARCH)

Triggers: "search for", "find information about", "look up", "google", "find"

Features:

• Intelligent model selection (academic queries → sonar-pro)
• Auto time filtering ("recent" → day filter)
• Enhanced citation formatting

Example:

User: Search for the latest developments in quantum computing
Agent: [Provides current quantum computing developments with sources]

2. Advanced Search (WEB_SEARCH_ADVANCED)

Triggers: "advanced search", "academic search", "research", "scholarly search"

Features:

• Academic mode prioritization
• Location-aware results
• Extended context (4K tokens)
• Custom date filtering

Advanced Query Syntax:

location:California research climate change impact
domain:edu AI ethics papers since:2024-01-01
until:2024-12-31 quantum computing applications

3. Async Search (WEB_SEARCH_ASYNC)

Triggers: "comprehensive search", "detailed analysis", "async search", "deep research"

Features:

• Up to 16K token responses
• 10-minute processing time
• Comprehensive multi-source analysis
• Progress indicators

Example:

User: Comprehensive analysis of renewable energy trends and future projections
Agent: 🔄 Starting comprehensive async search...
[Detailed multi-perspective analysis with extensive sources]

API

PerplexityService

// Basic Configuration
const service = new PerplexityService({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.perplexity.ai',
  defaultModel: 'sonar-medium',
  timeout: 30000,
  enableAsync: true, // NEW: Enable async capabilities
  asyncPollInterval: 2000, // NEW: Polling interval
  asyncMaxWaitTime: 300000, // NEW: Max wait time
});

// Standard Search
const response = await service.search({
  query: 'Your search query',
  model: 'sonar-pro', // NEW: Premium model
  searchMode: 'academic', // NEW: Academic mode
  searchRecency: 'week',
  location: 'California', // NEW: Location filtering
  searchContextSize: 15, // NEW: Context size
  temperature: 0.7,
  maxTokens: 4000, // NEW: Increased limit
});

// Advanced Search with Date Filtering
const advancedResponse = await service.search({
  query: 'Climate change research',
  model: 'sonar-pro',
  searchMode: 'academic',
  dateFilter: { // NEW: Date range filtering
    start: '2024-01-01',
    end: '2024-12-31'
  },
  searchDomain: 'edu', // Limit to educational domains
  maxTokens: 8000,
});

// Async Search for Complex Queries
const asyncResponse = await service.search({
  query: 'Comprehensive AI impact analysis',
  async: true, // NEW: Async processing
  model: 'sonar-pro',
  maxTokens: 16000,
  searchContextSize: 25,
});

Models 🤖

• sonar-pro: Premium model with advanced search (July 2025)
• sonar-small: Fast, efficient searches
• sonar-medium: Balanced performance and quality (default)
• sonar-large: Most comprehensive results

Search Parameters 🎛️

Time Filtering

• hour: Last hour (NEW)
• day: Last 24 hours
• week: Last 7 days
• month: Last 30 days
• year: Last year
• all: All time (default)

Search Modes

• general: Standard web search (default)
• academic: Scholarly sources prioritized (NEW)

Context Sizes

• Standard: 10 results
• Advanced: 15 results
• Async: 20-30 results

Token Limits

• Basic: 1K-2K tokens
• Advanced: 4K tokens
• Async: 8K-16K tokens
• Maximum: 127K tokens (NEW)

Enhanced Features (July 2025) 🆕

New Search Results Format

• Migrated from deprecated citations to search_results field
• Rich metadata including publication dates and source information
• Enhanced formatting with source verification

Async API Integration

• Support for long-running queries (up to 10 minutes)
• Real-time status polling
• Progress indicators for user feedback
• 7-day result retention

Academic Search Mode

• Prioritizes peer-reviewed papers and scholarly articles
• Integration with academic databases
• Enhanced citation formatting for research

Location-Based Results

• Geo-targeted search results
• Regional content prioritization
• Location-aware query processing

Error Handling & Reliability 🛡️

The plugin includes:

• Smart Retry Logic: Exponential backoff with circuit breaker
• Timeout Protection: Configurable timeouts per operation type
• Async Error Recovery: Robust polling with failure detection
• API Key Validation: Pre-flight checks and secure storage
• Rate Limit Handling: Intelligent backoff on API limits
• Progress Feedback: Real-time status for long operations

Integration with ElizaOS 🤖

This enhanced plugin significantly expands AI agent capabilities in the ElizaOS ecosystem:

Market Intelligence

• Real-time Analysis: Track decentralized AI economy trends
• Academic Research: Access to scholarly blockchain research
• Competitive Monitoring: AI agent marketplace developments
• Regulatory Tracking: Policy changes affecting crypto/AI sectors

Technical Research

• Protocol Analysis: Deep dives into blockchain implementations
• Security Research: Latest vulnerabilities and mitigations
• Performance Benchmarking: Comparative analysis of AI models
• Integration Patterns: Best practices from academic sources

Strategic Planning

• Future Projections: Long-term trend analysis via async search
• Risk Assessment: Comprehensive threat landscape analysis
• Opportunity Identification: Emerging technology convergence
• Knowledge Synthesis: Multi-source intelligence correlation

Development & Testing 🔧

# Build the enhanced plugin
cd src/plugins/perplexity
bun run build

# Watch mode for development
bun run dev

# Run comprehensive tests
bun test

# Type checking
bun run type-check

Testing the New Features

# Test basic search
User: "Search for AI developments"

# Test academic search
User: "Find academic papers on quantum computing"

# Test advanced search with filters
User: "location:California domain:edu climate research since:2024-01-01"

# Test async comprehensive search
User: "Comprehensive analysis of renewable energy market trends"

Environment Variables

# Required
PERPLEXITY_API_KEY=your_api_key_here

# Optional: Advanced Configuration
PERPLEXITY_BASE_URL=https://api.perplexity.ai
PERPLEXITY_DEFAULT_MODEL=sonar-pro
PERPLEXITY_ENABLE_ASYNC=true
PERPLEXITY_MAX_TOKENS=8000

What's New in July 2025 🎉

1. sonar-pro Model: Premium model with enhanced search capabilities
2. Academic Search Mode: Prioritizes scholarly and peer-reviewed sources
3. Async API Support: Long-running queries with progress tracking
4. Location Filtering: Geo-targeted search results
5. Extended Context: Up to 127K tokens for comprehensive responses
6. Advanced Date Filtering: Custom date ranges with precise control
7. Enhanced Search Results: Rich metadata and improved citation formatting
8. Intelligent Model Selection: Auto-selects optimal model per query type

License

MIT