1import { Actor, log, ApifyClient } from 'apify';
2import { CheerioCrawler } from 'crawlee';
3import OpenAI from 'openai';
4
5
6interface Input {
7 query: string;
8 maxActorsToTest?: number;
9 testTimeout?: number;
10}
11
12interface ActorCandidate {
13 id: string;
14 name: string;
15 username: string;
16 title: string;
17 description: string;
18 url: string;
19 actorId: string;
20 stats: {
21 totalUsers: number;
22 totalRuns: number;
23 };
24 categories: string[];
25 readme?: string;
26 pricing?: string;
27 inputSchema?: Record<string, any>;
28}
29
30interface PreliminaryScore {
31 actor: ActorCandidate;
32 score: number;
33 reasoning: string;
34}
35
36interface TestRun {
37 actorId: string;
38 actorName: string;
39 success: boolean;
40 input: Record<string, any>;
41 output: any[] | null;
42 error?: string;
43 duration: number;
44 itemCount: number;
45}
46
47interface FinalResult {
48 rank: number;
49 actorId: string;
50 actorName: string;
51 actorUrl: string;
52 username: string;
53 preliminaryScore: number;
54 testResult: {
55 success: boolean;
56 itemCount: number;
57 duration: number;
58 sampleOutput: any;
59 error?: string;
60 };
61 finalScore: number;
62 verdict: string;
63 strengths: string[];
64 weaknesses: string[];
65}
66
67
68const MODEL = 'google/gemini-2.5-flash';
69const MAX_TEST_RESULTS = 3;
70
71
72await Actor.init();
73
74const input = await Actor.getInput<Input>();
75if (!input?.query) {
76 throw new Error('Query is required');
77}
78
79const {
80 query,
81 maxActorsToTest = 3,
82 testTimeout = 60
83} = input;
84
85const startTime = Date.now();
86const apifyClient = new ApifyClient({ token: process.env.APIFY_TOKEN });
87
88log.info('🔍 Actor Scout v2 - Starting', { query, maxActorsToTest });
89
90
91log.info('Step 1: Analyzing query...');
92const { keywords, intent } = await analyzeQuery(query);
93log.info('Query analyzed', { keywords, intent });
94
95
96log.info('Step 2: Searching Apify Store...');
97const candidates = await searchApifyStore(keywords, 12);
98log.info(`Found ${candidates.length} candidates`);
99
100if (candidates.length === 0) {
101 await Actor.setValue('OUTPUT', { error: 'No actors found for query', query });
102 await Actor.exit();
103}
104
105
106log.info('Step 3: Preliminary ranking (metadata + README)...');
107const detailedCandidates = await fetchActorDetails(candidates, apifyClient);
108const preliminaryRanking = await preliminaryRank(detailedCandidates, query, intent);
109const topCandidates = preliminaryRanking.slice(0, maxActorsToTest);
110
111log.info('Top candidates for testing:', {
112 actors: topCandidates.map(p => p.actor.title)
113});
114
115
116log.info('Step 4: Generating test inputs for each actor...');
117const testInputs = await generateTestInputs(topCandidates, query, intent);
118
119
120log.info('Step 5: Running parallel tests...');
121const testResults = await runParallelTests(
122 testInputs,
123 apifyClient,
124 testTimeout
125);
126
127
128log.info('Step 6: Comparing outputs with LLM...');
129const finalRanking = await compareOutputs(
130 testResults,
131 query,
132 intent,
133 preliminaryRanking
134);
135
136
137const duration = ((Date.now() - startTime) / 1000).toFixed(1);
138const output = formatFinalOutput(query, finalRanking, duration);
139
140
141await Actor.setValue('OUTPUT', {
142 query,
143 intent,
144 results: finalRanking,
145 formattedOutput: output,
146 metadata: {
147 candidatesFound: candidates.length,
148 actorsTested: testResults.length,
149 successfulTests: testResults.filter(t => t.success).length,
150 duration: `${duration}s`,
151 model: MODEL,
152 },
153});
154
155await Actor.pushData(finalRanking);
156
157console.log('\n' + output);
158
159log.info('✅ Actor Scout complete!', {
160 winner: finalRanking[0]?.actorName,
161 duration: `${duration}s`
162});
163
164await Actor.exit();
165
166
167
168function getOpenAI(): OpenAI {
169 return new OpenAI({
170 baseURL: 'https://openrouter.apify.actor/api/v1',
171 apiKey: 'apify',
172 defaultHeaders: {
173 Authorization: `Bearer ${process.env.APIFY_TOKEN}`,
174 },
175 });
176}
177
178async function analyzeQuery(query: string): Promise<{ keywords: string[]; intent: string }> {
179 const openai = getOpenAI();
180
181 const response = await openai.chat.completions.create({
182 model: MODEL,
183 messages: [{
184 role: 'user',
185 content: `Analyze this request for finding an Apify Actor (web scraping tool).
186
187Request: "${query}"
188
189Return JSON:
190{
191 "keywords": ["keyword1", "keyword2", "keyword3"], // 2-4 search terms
192 "intent": "Brief description of what data the user wants and from where"
193}
194
195Only return the JSON:`
196 }],
197 temperature: 0,
198 });
199
200 const content = response.choices[0]?.message?.content || '{}';
201 try {
202 return JSON.parse(content.replace(/```json\n?|\n?```/g, '').trim());
203 } catch {
204 return {
205 keywords: query.split(' ').filter(w => w.length > 3).slice(0, 4),
206 intent: query
207 };
208 }
209}
210
211async function searchApifyStore(keywords: string[], limit: number): Promise<ActorCandidate[]> {
212 const searchQuery = keywords.join(' ');
213 const url = `https://api.apify.com/v2/store?search=${encodeURIComponent(searchQuery)}&limit=${limit}`;
214
215 const response = await fetch(url, {
216 headers: { Authorization: `Bearer ${process.env.APIFY_TOKEN}` },
217 });
218
219 if (!response.ok) throw new Error(`Store API error: ${response.status}`);
220
221 const data = await response.json();
222
223 return data.data.items.map((item: any) => ({
224 id: item.id,
225 name: item.name,
226 username: item.username,
227 title: item.title || item.name,
228 description: item.description || '',
229 url: `https://apify.com/${item.username}/${item.name}`,
230 actorId: `${item.username}/${item.name}`,
231 stats: {
232 totalUsers: item.stats?.totalUsers || 0,
233 totalRuns: item.stats?.totalRuns || 0,
234 },
235 categories: item.categories || [],
236 }));
237}
238
239async function fetchActorDetails(
240 actors: ActorCandidate[],
241 client: ApifyClient
242): Promise<ActorCandidate[]> {
243 const detailed: ActorCandidate[] = [];
244
245 for (const actor of actors) {
246 try {
247
248 const actorInfo = await client.actor(actor.actorId).get();
249
250 detailed.push({
251 ...actor,
252 readme: actorInfo?.description || actor.description,
253 inputSchema: actorInfo?.defaultRunOptions?.build
254 ? undefined
255 : (actorInfo as any)?.inputSchema,
256 });
257 } catch (e) {
258
259 detailed.push(actor);
260 }
261 }
262
263
264 const readmeMap = new Map<string, string>();
265
266 const crawler = new CheerioCrawler({
267 maxRequestsPerCrawl: Math.min(actors.length, 10),
268 maxConcurrency: 5,
269 requestHandler: async ({ request, $ }) => {
270 const readme = $('article').first().text() ||
271 $('.markdown-body').first().text() || '';
272 readmeMap.set(request.userData.actorId, readme.slice(0, 3000));
273 },
274 failedRequestHandler: async () => {},
275 });
276
277 await crawler.run(
278 actors.slice(0, 10).map(a => ({
279 url: a.url,
280 userData: { actorId: a.actorId },
281 }))
282 );
283
284 return detailed.map(actor => ({
285 ...actor,
286 readme: readmeMap.get(actor.actorId) || actor.readme || actor.description,
287 }));
288}
289
290async function preliminaryRank(
291 actors: ActorCandidate[],
292 query: string,
293 intent: string
294): Promise<PreliminaryScore[]> {
295 const openai = getOpenAI();
296
297 const actorSummaries = actors.map((a, i) =>
298 `${i + 1}. ${a.title} (${a.actorId})
299 Users: ${a.stats.totalUsers}, Runs: ${a.stats.totalRuns}
300 Description: ${a.description?.slice(0, 200)}
301 README excerpt: ${a.readme?.slice(0, 300) || 'N/A'}`
302 ).join('\n\n');
303
304 const response = await openai.chat.completions.create({
305 model: MODEL,
306 messages: [{
307 role: 'user',
308 content: `You're evaluating Apify Actors for this user request.
309
310USER REQUEST: "${query}"
311USER INTENT: ${intent}
312
313CANDIDATE ACTORS:
314${actorSummaries}
315
316Score each actor 1-10 based on:
317- How well it matches the user's intent
318- Documentation quality
319- Popularity/trust (user count, runs)
320- Likelihood of working correctly
321
322Return JSON array sorted by score (highest first):
323[
324 {"index": 1, "score": 9, "reasoning": "Best match because..."},
325 {"index": 3, "score": 7, "reasoning": "Good but..."},
326 ...
327]
328
329Only return the JSON array:`
330 }],
331 temperature: 0.2,
332 });
333
334 const content = response.choices[0]?.message?.content || '[]';
335 try {
336 const rankings = JSON.parse(content.replace(/```json\n?|\n?```/g, '').trim());
337 return rankings.map((r: any) => ({
338 actor: actors[r.index - 1],
339 score: r.score,
340 reasoning: r.reasoning,
341 })).filter((r: any) => r.actor);
342 } catch {
343
344 return actors
345 .sort((a, b) => b.stats.totalUsers - a.stats.totalUsers)
346 .map(actor => ({ actor, score: 5, reasoning: 'Fallback ranking by popularity' }));
347 }
348}
349
350async function generateTestInputs(
351 candidates: PreliminaryScore[],
352 query: string,
353 intent: string
354): Promise<Array<{ actor: ActorCandidate; input: Record<string, any>; prelim: PreliminaryScore }>> {
355 const openai = getOpenAI();
356 const results: Array<{ actor: ActorCandidate; input: Record<string, any>; prelim: PreliminaryScore }> = [];
357
358 for (const prelim of candidates) {
359 const actor = prelim.actor;
360
361
362 let schemaInfo = 'No schema available - generate reasonable defaults';
363 try {
364 const schemaUrl = `https://api.apify.com/v2/acts/${actor.actorId}/input-schema`;
365 const schemaRes = await fetch(schemaUrl, {
366 headers: { Authorization: `Bearer ${process.env.APIFY_TOKEN}` },
367 });
368 if (schemaRes.ok) {
369 const schema = await schemaRes.json();
370 schemaInfo = JSON.stringify(schema, null, 2).slice(0, 2000);
371 }
372 } catch {}
373
374 const response = await openai.chat.completions.create({
375 model: MODEL,
376 messages: [{
377 role: 'user',
378 content: `Generate a minimal test input for this Apify Actor.
379
380USER WANTS: "${query}"
381INTENT: ${intent}
382
383ACTOR: ${actor.title} (${actor.actorId})
384DESCRIPTION: ${actor.description}
385
386INPUT SCHEMA:
387${schemaInfo}
388
389Generate a JSON input that:
3901. Matches what the user is looking for
3912. Uses MINIMAL settings (we want just 1-${MAX_TEST_RESULTS} results to test)
3923. Is valid for this actor's schema
393
394Return ONLY the JSON input object (no explanation):`
395 }],
396 temperature: 0.1,
397 });
398
399 const content = response.choices[0]?.message?.content || '{}';
400 try {
401 const input = JSON.parse(content.replace(/```json\n?|\n?```/g, '').trim());
402 results.push({ actor, input, prelim });
403 } catch {
404
405 results.push({
406 actor,
407 input: { maxItems: MAX_TEST_RESULTS },
408 prelim
409 });
410 }
411 }
412
413 return results;
414}
415
416async function runParallelTests(
417 testInputs: Array<{ actor: ActorCandidate; input: Record<string, any>; prelim: PreliminaryScore }>,
418 client: ApifyClient,
419 timeoutSecs: number
420): Promise<TestRun[]> {
421 const testPromises = testInputs.map(async ({ actor, input }) => {
422 const startTime = Date.now();
423
424 try {
425 log.info(`Testing: ${actor.title}`, { input });
426
427
428 const run = await client.actor(actor.actorId).call(input, {
429 timeout: timeoutSecs,
430 memory: 256,
431 });
432
433
434 const { items } = await client.dataset(run.defaultDatasetId).listItems({
435 limit: MAX_TEST_RESULTS,
436 });
437
438 const duration = (Date.now() - startTime) / 1000;
439
440 return {
441 actorId: actor.actorId,
442 actorName: actor.title,
443 success: true,
444 input,
445 output: items,
446 duration,
447 itemCount: items.length,
448 };
449 } catch (error: any) {
450 const duration = (Date.now() - startTime) / 1000;
451
452 return {
453 actorId: actor.actorId,
454 actorName: actor.title,
455 success: false,
456 input,
457 output: null,
458 error: error.message || 'Unknown error',
459 duration,
460 itemCount: 0,
461 };
462 }
463 });
464
465 return Promise.all(testPromises);
466}
467
468async function compareOutputs(
469 testResults: TestRun[],
470 query: string,
471 intent: string,
472 preliminaryRanking: PreliminaryScore[]
473): Promise<FinalResult[]> {
474 const openai = getOpenAI();
475
476
477 const resultSummaries = testResults.map((t, i) => {
478 if (!t.success) {
479 return `${i + 1}. ${t.actorName} - ❌ FAILED
480 Error: ${t.error}
481 Duration: ${t.duration.toFixed(1)}s`;
482 }
483
484 const sampleOutput = JSON.stringify(t.output?.[0] || {}, null, 2).slice(0, 1000);
485 return `${i + 1}. ${t.actorName} - ✅ SUCCESS
486 Items returned: ${t.itemCount}
487 Duration: ${t.duration.toFixed(1)}s
488 Sample output:
489 ${sampleOutput}`;
490 }).join('\n\n');
491
492 const response = await openai.chat.completions.create({
493 model: MODEL,
494 messages: [{
495 role: 'user',
496 content: `Compare these Apify Actor test results for the user's request.
497
498USER REQUEST: "${query}"
499INTENT: ${intent}
500
501TEST RESULTS:
502${resultSummaries}
503
504For each actor, evaluate:
5051. Did it succeed?
5062. Does the output contain what the user needs?
5073. Is the data quality good?
5084. Is it fast enough?
509
510Return JSON array with final ranking:
511[
512 {
513 "actorName": "Name",
514 "finalScore": 9.5,
515 "verdict": "Best choice because...",
516 "strengths": ["strength1", "strength2"],
517 "weaknesses": ["weakness1"]
518 },
519 ...
520]
521
522Sort by finalScore descending. Only return JSON:`
523 }],
524 temperature: 0.2,
525 });
526
527 const content = response.choices[0]?.message?.content || '[]';
528 let llmRankings: any[] = [];
529
530 try {
531 llmRankings = JSON.parse(content.replace(/```json\n?|\n?```/g, '').trim());
532 } catch {
533 llmRankings = testResults.map(t => ({
534 actorName: t.actorName,
535 finalScore: t.success ? 7 : 2,
536 verdict: t.success ? 'Test passed' : 'Test failed',
537 strengths: t.success ? ['Completed successfully'] : [],
538 weaknesses: t.success ? [] : [t.error || 'Failed'],
539 }));
540 }
541
542
543 return llmRankings.map((llm, index) => {
544 const testResult = testResults.find(t => t.actorName === llm.actorName) || testResults[index];
545 const prelim = preliminaryRanking.find(p => p.actor.title === llm.actorName);
546
547 return {
548 rank: index + 1,
549 actorId: testResult?.actorId || '',
550 actorName: llm.actorName,
551 actorUrl: `https://apify.com/${testResult?.actorId}`,
552 username: testResult?.actorId?.split('/')[0] || '',
553 preliminaryScore: prelim?.score || 0,
554 testResult: {
555 success: testResult?.success || false,
556 itemCount: testResult?.itemCount || 0,
557 duration: testResult?.duration || 0,
558 sampleOutput: testResult?.output?.[0] || null,
559 error: testResult?.error,
560 },
561 finalScore: llm.finalScore,
562 verdict: llm.verdict,
563 strengths: llm.strengths || [],
564 weaknesses: llm.weaknesses || [],
565 };
566 });
567}
568
569function formatFinalOutput(
570 query: string,
571 results: FinalResult[],
572 duration: string
573): string {
574 const line = '─'.repeat(70);
575 const doubleLine = '═'.repeat(70);
576
577 let output = `
578${doubleLine}
579 🔍 ACTOR SCOUT v2 - TEST RESULTS
580${doubleLine}
581
582Query: "${query}"
583Tested: ${results.length} actors | Duration: ${duration}s
584
585${line}
586 🏆 WINNER
587${line}
588`;
589
590 if (results.length > 0) {
591 const winner = results[0];
592 const statusIcon = winner.testResult.success ? '✅' : '❌';
593
594 output += `
595 ${winner.actorName}
596 ${winner.actorUrl}
597
598 Final Score: ${winner.finalScore}/10
599 Test Status: ${statusIcon} ${winner.testResult.success ? 'PASSED' : 'FAILED'}
600 Items Retrieved: ${winner.testResult.itemCount}
601 Test Duration: ${winner.testResult.duration.toFixed(1)}s
602
603 💡 Verdict: ${winner.verdict}
604
605 ✓ Strengths:
606${winner.strengths.map(s => ` • ${s}`).join('\n')}
607
608 ⚠ Weaknesses:
609${winner.weaknesses.map(w => ` • ${w}`).join('\n') || ' • None identified'}
610`;
611
612 if (winner.testResult.sampleOutput) {
613 output += `
614 📦 Sample Output:
615${JSON.stringify(winner.testResult.sampleOutput, null, 2).split('\n').map(l => ' ' + l).join('\n').slice(0, 800)}
616`;
617 }
618 }
619
620 output += `
621${line}
622 📊 ALL RESULTS
623${line}
624
625 Rank Actor Test Score Verdict
626 ──── ───────────────────────────────── ─────── ────── ─────────────────
627`;
628
629 for (const r of results) {
630 const name = r.actorName.length > 33 ? r.actorName.slice(0, 30) + '...' : r.actorName;
631 const status = r.testResult.success ? '✅ Pass' : '❌ Fail';
632 const verdictShort = r.verdict.slice(0, 20) + (r.verdict.length > 20 ? '...' : '');
633 output += ` #${r.rank} ${name.padEnd(33)} ${status} ${String(r.finalScore).padStart(4)}/10 ${verdictShort}\n`;
634 }
635
636
637 if (results.length > 1) {
638 output += `
639${line}
640 📝 RUNNER-UP DETAILS
641${line}
642`;
643 for (const r of results.slice(1)) {
644 const statusIcon = r.testResult.success ? '✅' : '❌';
645 output += `
646 #${r.rank} ${r.actorName} (${r.finalScore}/10)
647 ${statusIcon} ${r.testResult.success ? `Returned ${r.testResult.itemCount} items in ${r.testResult.duration.toFixed(1)}s` : `Failed: ${r.testResult.error}`}
648 ${r.verdict}
649`;
650 }
651 }
652
653 output += `
654${doubleLine}
655 Actor Scout v2 | Model: ${MODEL} | Tested ${results.length} actors
656${doubleLine}
657`;
658
659 return output;
660}