Add Perplexity web search

Author: danielcampagnolitg

package.json

@@ -116,6 +116,7 @@
     "@opentelemetry/sdk-node": "^0.57.1",
     "@opentelemetry/sdk-trace-base": "^1.30.1",
     "@opentelemetry/semantic-conventions": "^1.29.0",
+    "@perplexity-ai/perplexity_ai": "^0.10.0",
     "@sinclair/typebox": "^0.34.41",
     "@slack/bolt": "^4.4.0",
     "@slack/web-api": "^7.9.3",

pnpm-lock.yaml

@@ -0,0 +1,159 @@
+import { expect } from 'chai';
+import { agentContextStorage } from '#agent/agentContextLocalStorage';
+import type { AgentContext } from '#shared/agent/agent.model';
+import { setupConditionalLoggerOutput } from '#test/testUtils';
+import { Perplexity } from './perplexity';
+
+describe('Perplexity Integration Tests', () => {
+	setupConditionalLoggerOutput();
+
+	let perplexity: Perplexity;
+	let mockAgentContext: AgentContext;
+
+	beforeEach(() => {
+		perplexity = new Perplexity();
+		mockAgentContext = {
+			agentId: 'test-agent-id',
+			memory: {},
+		} as AgentContext;
+	});
+
+	describe('research', () => {
+		it('should perform research and return results when saveToMemory is false', async function () {
+			this.timeout(30000);
+
+			const researchTask = 'What are the latest TypeScript 5.9 features?';
+
+			const result = await agentContextStorage.run(mockAgentContext, async () => {
+				return await perplexity.research(researchTask, false);
+			});
+
+			expect(result).to.be.a('string');
+			expect(result.length).to.be.greaterThan(0);
+			expect(result).to.include('TypeScript');
+		});
+
+		it('should save research to memory and return memory key when saveToMemory is true', async function () {
+			this.timeout(30000);
+
+			const researchTask = 'What is the capital of France?';
+
+			const memoryKey = await agentContextStorage.run(mockAgentContext, async () => {
+				return await perplexity.research(researchTask, true);
+			});
+
+			expect(memoryKey).to.be.a('string');
+			expect(memoryKey).to.match(/^Perplexity-/);
+			expect(mockAgentContext.memory[memoryKey]).to.be.a('string');
+			expect(mockAgentContext.memory[memoryKey].length).to.be.greaterThan(0);
+		});
+
+		it('should handle complex research queries', async function () {
+			this.timeout(30000);
+
+			const researchTask = 'Compare the performance characteristics of Node.js async/await versus callbacks in 2025';
+
+			const result = await agentContextStorage.run(mockAgentContext, async () => {
+				return await perplexity.research(researchTask, false);
+			});
+
+			expect(result).to.be.a('string');
+			expect(result.length).to.be.greaterThan(100);
+		});
+
+		it('should handle short queries', async function () {
+			this.timeout(30000);
+
+			const researchTask = 'TypeScript';
+
+			const result = await agentContextStorage.run(mockAgentContext, async () => {
+				return await perplexity.research(researchTask, false);
+			});
+
+			expect(result).to.be.a('string');
+			expect(result.length).to.be.greaterThan(0);
+		});
+	});
+
+	describe('search', () => {
+		it('should perform basic web search and return results', async function () {
+			this.timeout(30000);
+
+			const result = await agentContextStorage.run(mockAgentContext, async () => {
+				return await perplexity.search('TypeScript 5.9 features', {
+					max_results: 5,
+				});
+			});
+
+			expect(result).to.have.property('results');
+			expect(result.results).to.be.an('array');
+			expect(result.results.length).to.be.greaterThan(0);
+			expect(result.results.length).to.be.at.most(5);
+
+			const firstResult = result.results[0];
+			expect(firstResult).to.have.property('title');
+			expect(firstResult).to.have.property('url');
+			expect(firstResult.title).to.be.a('string');
+			expect(firstResult.url).to.be.a('string');
+		});
+
+		it('should support multi-query search', async function () {
+			this.timeout(30000);
+
+			const result = await agentContextStorage.run(mockAgentContext, async () => {
+				return await perplexity.search(['Node.js performance', 'JavaScript async patterns'], {
+					max_results: 10,
+				});
+			});
+
+			expect(result.results).to.be.an('array');
+			expect(result.results.length).to.be.greaterThan(0);
+		});
+
+		it('should return snippets when requested', async function () {
+			this.timeout(30000);
+
+			const result = await agentContextStorage.run(mockAgentContext, async () => {
+				return await perplexity.search('React best practices 2025', {
+					max_results: 3,
+					return_snippets: true,
+				});
+			});
+
+			expect(result.results).to.be.an('array');
+			expect(result.results.length).to.be.greaterThan(0);
+
+			const resultsWithSnippets = result.results.filter((r) => r.snippet);
+			expect(resultsWithSnippets.length).to.be.greaterThan(0);
+		});
+
+		it('should support country filtering', async function () {
+			this.timeout(30000);
+
+			const result = await agentContextStorage.run(mockAgentContext, async () => {
+				return await perplexity.search('local tech events', {
+					max_results: 5,
+					country: 'US',
+				});
+			});
+
+			expect(result.results).to.be.an('array');
+			expect(result.results.length).to.be.greaterThan(0);
+		});
+
+		it('should handle errors gracefully', async function () {
+			this.timeout(30000);
+
+			await agentContextStorage.run(mockAgentContext, async () => {
+				try {
+					await perplexity.search('', {
+						max_results: 5,
+					});
+					expect.fail('Should have thrown an error');
+				} catch (error) {
+					expect(error).to.exist;
+				}
+			});
+		});
+	});
+});

src/functions/web/perplexity.int.ts

@@ -1,3 +1,4 @@
+import PerplexitySDK from '@perplexity-ai/perplexity_ai';
 import { agentContext, llms } from '#agent/agentContextLocalStorage';
 import { func, funcClass } from '#functionSchema/functionDecorators';
 import { perplexityReasoningProLLM } from '#llm/services/perplexity-llm';
@@ -10,23 +11,50 @@ export interface PerplexityConfig {
 	key: string;
 }
 
+export interface PerplexitySearchOptions {
+	query: string | string[];
+	max_results?: number;
+	country?: string;
+	return_images?: boolean;
+	return_snippets?: boolean;
+}
+
+export interface PerplexitySearchResult {
+	title: string;
+	url: string;
+	date?: string;
+	snippet?: string;
+	images?: string[];
+}
+
+export interface PerplexitySearchResponse {
+	results: PerplexitySearchResult[];
+}
+
 @funcClass(__filename)
 export class Perplexity {
+	private sdkClient: PerplexitySDK;
+
+	constructor() {
+		// SDK automatically uses PERPLEXITY_API_KEY from environment
+		this.sdkClient = new PerplexitySDK();
+	}
+
 	/**
-	 * Calls Perplexity to perform online research.
-	 * @param researchQuery the natural language query to research
+	 * Calls Perplexity.ai agent to perform online research.
+	 * @param researchTask the comprehensive, detailed task to for the AI agent with online research capabilities to answer.
 	 * @param saveToMemory if the response should be saved to the agent memory.
 	 * @returns {string} if saveToMemory is true then returns the memory key. If saveToMemory is false then returns the research contents.
 	 */
 	@cacheRetry()
 	@func()
-	async research(researchQuery: string, saveToMemory: boolean): Promise<string> {
+	async research(researchTask: string, saveToMemory: boolean): Promise<string> {
 		try {
-			const report: string = await perplexityReasoningProLLM().generateText(researchQuery, { id: 'Perplexity' });
+			const report: string = await perplexityReasoningProLLM().generateText(researchTask, { id: 'Perplexity' });
 
 			if (saveToMemory) {
 				const summary = await llms().easy.generateText(
-					`<query>${researchQuery}</query>\nGenerate a summarised version of the research key in one short sentence at most, with only alphanumeric with underscores for spaces. Answer concisely with only the summary.`,
+					`<query>${researchTask}</query>\nGenerate a summarised version of the research key in one short sentence at most, with only alphanumeric with underscores for spaces. Answer concisely with only the summary.`,
 					{ id: 'Perplexity memory key' },
 				);
 				const key = `Perplexity-${summary}`;
@@ -35,7 +63,35 @@ export class Perplexity {
 			}
 			return report;
 		} catch (e) {
-			log.error(e, `Perplexity error. Query: ${researchQuery}`);
+			log.error(e, `Perplexity error. Query: ${researchTask}`);
+			throw e;
+		}
+	}
+
+	/**
+	 * Performs a web search using Perplexity's search API.
+	 * @param query - The search query.
+	 * @returns {PerplexitySearchResponse} The search results with titles, URLs, snippets.
+	 */
+	@cacheRetry()
+	@func()
+	async webSearch(query: string | string[]): Promise<PerplexitySearchResponse> {
+		const searchParams: PerplexitySearchOptions = { query, max_results: 15, return_snippets: true };
+		try {
+			const response = await this.sdkClient.search.create(searchParams);
+
+			// Transform SDK response to our interface
+			return {
+				results: response.results.map((r: any) => ({
+					title: r.title,
+					url: r.url,
+					date: r.date,
+					snippet: r.snippet,
+					// images: r.images,
+				})),
+			};
+		} catch (e) {
+			log.error(e, `Perplexity web search error. query: ${JSON.stringify(query)}`);
 			throw e;
 		}
 	}