npm package: @forgedock/fd-fastest-ai-recommendations
Description: AI-powered performance recommendations for FD-Fastest
Author: ForgeDock
Latest version: 1.0.2

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

```bash
pnpm add @fd-fastest/ai-recommendations
```

## Usage

### Basic Example

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

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

### Generating Fixing Prompts

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

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

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

### AIRecommendationResult

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

## Environment Variables

```bash
# For OpenAI
OPENAI_API_KEY=your_key_here

# For Anthropic
ANTHROPIC_API_KEY=your_key_here
```

## Development

```bash
# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test

# Type check
pnpm type-check
```

## License

MIT