@fd-fastest/ai-recommendations

AI-powered performance recommendations for FD-Fastest using Vercel AI SDK.

Features

• 🤖 AI-powered analysis using OpenAI or Anthropic models
• 📊 Structured recommendations with severity levels and impact estimates
• 🎯 Detailed fixing prompts for AI code generation tools
• 💾 In-memory caching to reduce API costs
• 🔒 Type-safe with Zod schema validation
• 📦 ESM module with full TypeScript support

Installation

pnpm add @fd-fastest/ai-recommendations

Usage

Basic Example

import { AIRecommender } from '@fd-fastest/ai-recommendations';
import type { Report } from '@fd-fastest/reporter-json';

// Initialize with OpenAI
const recommender = new AIRecommender({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini', // optional
  temperature: 0.3, // optional
  maxRecommendations: 10, // optional
  enableCaching: true, // optional
});

// Generate recommendations
const result = await recommender.generateRecommendations(report);

console.log(`Generated ${result.recommendations.length} recommendations`);
console.log(`Model: ${result.model}`);
console.log(`Tokens used: ${result.tokensUsed}`);

result.recommendations.forEach((rec) => {
  console.log(`[${rec.severity}] ${rec.category}: ${rec.issue}`);
  console.log(`Recommendation: ${rec.recommendation}`);
  console.log(`Impact: ${rec.impact}`);
});

Using Anthropic

const recommender = new AIRecommender({
  provider: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-3-5-sonnet-20241022',
});

Generating Fixing Prompts

import { FixingPromptGenerator } from '@fd-fastest/ai-recommendations';

const generator = new FixingPromptGenerator();

// Single prompt
const prompt = generator.generate({
  recommendation: result.recommendations[0],
  projectContext: 'Next.js 14 App Router project',
});

console.log(prompt);

// Batch prompts
const prompts = generator.generateBatch(
  result.recommendations,
  'Next.js 14 App Router project'
);

prompts.forEach((prompt, key) => {
  console.log(`\n=== ${key} ===`);
  console.log(prompt);
});

API

AIRecommender

Constructor Options

interface AIRecommenderConfig {
  provider: 'openai' | 'anthropic';
  apiKey: string;
  model?: string;
  temperature?: number; // 0.0-1.0
  maxRecommendations?: number;
  enableCaching?: boolean;
}

Methods

• generateRecommendations(report: Report): Promise<AIRecommendationResult>
• static clearCache(): void

FixingPromptGenerator

Methods

• generate(options: FixingPromptOptions): string
• generateBatch(recommendations: AIRecommendation[], projectContext?: string): Map<string, string>

Types

AIRecommendation

interface AIRecommendation {
  severity: 'critical' | 'warning' | 'info';
  category: string;
  issue: string;
  recommendation: string;
  fixingPrompt: string;
  impact: 'high' | 'medium' | 'low';
  estimatedImprovement?: string;
  affectedRoutes?: string[];
}

AIRecommendationResult

interface AIRecommendationResult {
  recommendations: AIRecommendation[];
  generatedAt: string;
  model: string;
  tokensUsed?: number;
}

Environment Variables

# For OpenAI
OPENAI_API_KEY=your_key_here

# For Anthropic
ANTHROPIC_API_KEY=your_key_here

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test

# Type check
pnpm type-check

License

MIT