npm package: @podai/plugin-perplexity
Description: Enhanced Perplexity AI integration plugin for ElizaOS - Advanced web search, academic research, and async capabilities (July 2025)
Author: PodAI
Latest version: 1.0.0

# @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:

```env
PERPLEXITY_API_KEY=your_api_key_here
```

## Usage

### Adding to Veil Character

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

```typescript
// 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

```typescript
// 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 🔧

```bash
# 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**

```bash
# 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**

```env
# 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