@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 🎉

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

License

MIT