@mars-stack/cli 0.2.0 → 1.0.2

package/template/.cursor/skills/configure-ai/SKILL.md

@@ -0,0 +1,617 @@
+# Skill: Configure AI Integration
+
+Set up an AI provider (OpenAI or Anthropic) in a MARS application with streaming, structured output, and cost management.
+
+## When to Use
+
+Use this skill when the user asks to add AI, LLM, chatbot, content generation, embeddings, RAG, or integrate OpenAI / Anthropic / GPT / Claude.
+
+## Prerequisites
+
+- `appConfig.features.ai` set to `true` (add it if missing)
+- `appConfig.services.ai.provider` set to `'openai'` or `'anthropic'`
+- An API key from the chosen provider
+
+## Step 1: Install the SDK
+
+**OpenAI:**
+
+```bash
+yarn add openai
+```
+
+**Anthropic:**
+
+```bash
+yarn add @anthropic-ai/sdk
+```
+
+## Step 2: Environment Variables
+
+**OpenAI:**
+
+```bash
+OPENAI_API_KEY="sk-..."
+OPENAI_MODEL="gpt-4o"
+```
+
+**Anthropic:**
+
+```bash
+ANTHROPIC_API_KEY="sk-ant-..."
+ANTHROPIC_MODEL="claude-sonnet-4-20250514"
+```
+
+Add the variables to `src/core/env/` via `buildEnvSchema()` with lazy validation so the app doesn't crash at import time when the key is absent.
+
+## Step 3: Define the Provider Interface
+
+```typescript
+// src/features/ai/types.ts
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface ChatParams {
+  messages: ChatMessage[];
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  jsonMode?: boolean;
+  tools?: ToolDefinition[];
+}
+
+export interface ChatResponse {
+  content: string;
+  usage: { promptTokens: number; completionTokens: number; totalTokens: number };
+  finishReason: string;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+export interface AIProvider {
+  chat(params: ChatParams): Promise<ChatResponse>;
+  stream(params: ChatParams): ReadableStream;
+}
+```
+
+## Step 4: Create the AI Client
+
+### OpenAI Provider
+
+```typescript
+// src/lib/core/ai/client.ts
+import 'server-only';
+
+import OpenAI from 'openai';
+
+let _client: OpenAI | null = null;
+
+export function createOpenAIClient(): OpenAI {
+  if (_client) return _client;
+
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      'OPENAI_API_KEY is not set.\n'
+      + '  → Get your key from https://platform.openai.com/api-keys\n'
+      + '  → Add it to your .env file',
+    );
+  }
+
+  _client = new OpenAI({ apiKey });
+  return _client;
+}
+```
+
+### OpenAI AIProvider Implementation
+
+```typescript
+// src/features/ai/server/openai-provider.ts
+import 'server-only';
+
+import { createOpenAIClient } from '@/lib/core/ai/client';
+import type { AIProvider, ChatParams, ChatResponse } from '../types';
+
+const DEFAULT_MODEL = process.env.OPENAI_MODEL || 'gpt-4o';
+
+export const openaiProvider: AIProvider = {
+  async chat(params: ChatParams): Promise<ChatResponse> {
+    const client = createOpenAIClient();
+
+    const response = await client.chat.completions.create({
+      model: params.model || DEFAULT_MODEL,
+      messages: params.messages,
+      temperature: params.temperature ?? 0.7,
+      max_tokens: params.maxTokens,
+      ...(params.jsonMode && { response_format: { type: 'json_object' } }),
+      ...(params.tools?.length && {
+        tools: params.tools.map((t) => ({
+          type: 'function' as const,
+          function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+          },
+        })),
+      }),
+    });
+
+    const choice = response.choices[0];
+
+    return {
+      content: choice.message.content ?? '',
+      usage: {
+        promptTokens: response.usage?.prompt_tokens ?? 0,
+        completionTokens: response.usage?.completion_tokens ?? 0,
+        totalTokens: response.usage?.total_tokens ?? 0,
+      },
+      finishReason: choice.finish_reason,
+    };
+  },
+
+  stream(params: ChatParams): ReadableStream {
+    const client = createOpenAIClient();
+
+    return new ReadableStream({
+      async start(controller) {
+        const stream = await client.chat.completions.create({
+          model: params.model || DEFAULT_MODEL,
+          messages: params.messages,
+          temperature: params.temperature ?? 0.7,
+          max_tokens: params.maxTokens,
+          stream: true,
+        });
+
+        for await (const chunk of stream) {
+          const content = chunk.choices[0]?.delta?.content;
+          if (content) {
+            controller.enqueue(new TextEncoder().encode(content));
+          }
+        }
+
+        controller.close();
+      },
+    });
+  },
+};
+```
+
+### Anthropic Provider
+
+```typescript
+// src/lib/core/ai/anthropic-client.ts
+import 'server-only';
+
+import Anthropic from '@anthropic-ai/sdk';
+
+let _client: Anthropic | null = null;
+
+export function createAnthropicClient(): Anthropic {
+  if (_client) return _client;
+
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      'ANTHROPIC_API_KEY is not set.\n'
+      + '  → Get your key from https://console.anthropic.com/settings/keys\n'
+      + '  → Add it to your .env file',
+    );
+  }
+
+  _client = new Anthropic({ apiKey });
+  return _client;
+}
+```
+
+### Anthropic AIProvider Implementation
+
+```typescript
+// src/features/ai/server/anthropic-provider.ts
+import 'server-only';
+
+import { createAnthropicClient } from '@/lib/core/ai/anthropic-client';
+import type { AIProvider, ChatParams, ChatResponse } from '../types';
+
+const DEFAULT_MODEL = process.env.ANTHROPIC_MODEL || 'claude-sonnet-4-20250514';
+
+export const anthropicProvider: AIProvider = {
+  async chat(params: ChatParams): Promise<ChatResponse> {
+    const client = createAnthropicClient();
+
+    const systemMessage = params.messages.find((m) => m.role === 'system');
+    const nonSystemMessages = params.messages.filter((m) => m.role !== 'system');
+
+    const response = await client.messages.create({
+      model: params.model || DEFAULT_MODEL,
+      max_tokens: params.maxTokens ?? 4096,
+      ...(systemMessage && { system: systemMessage.content }),
+      messages: nonSystemMessages.map((m) => ({
+        role: m.role as 'user' | 'assistant',
+        content: m.content,
+      })),
+      ...(params.tools?.length && {
+        tools: params.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          input_schema: t.parameters,
+        })),
+      }),
+    });
+
+    const textBlock = response.content.find((b) => b.type === 'text');
+
+    return {
+      content: textBlock?.text ?? '',
+      usage: {
+        promptTokens: response.usage.input_tokens,
+        completionTokens: response.usage.output_tokens,
+        totalTokens: response.usage.input_tokens + response.usage.output_tokens,
+      },
+      finishReason: response.stop_reason ?? 'end_turn',
+    };
+  },
+
+  stream(params: ChatParams): ReadableStream {
+    const client = createAnthropicClient();
+
+    const systemMessage = params.messages.find((m) => m.role === 'system');
+    const nonSystemMessages = params.messages.filter((m) => m.role !== 'system');
+
+    return new ReadableStream({
+      async start(controller) {
+        const stream = client.messages.stream({
+          model: params.model || DEFAULT_MODEL,
+          max_tokens: params.maxTokens ?? 4096,
+          ...(systemMessage && { system: systemMessage.content }),
+          messages: nonSystemMessages.map((m) => ({
+            role: m.role as 'user' | 'assistant',
+            content: m.content,
+          })),
+        });
+
+        for await (const event of stream) {
+          if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
+            controller.enqueue(new TextEncoder().encode(event.delta.text));
+          }
+        }
+
+        controller.close();
+      },
+    });
+  },
+};
+```
+
+## Step 5: Provider Factory
+
+```typescript
+// src/features/ai/server/index.ts
+import 'server-only';
+
+import { appConfig } from '@/config/app.config';
+import type { AIProvider } from '../types';
+
+export async function getAIProvider(): Promise<AIProvider> {
+  const provider = appConfig.services?.ai?.provider ?? 'openai';
+
+  switch (provider) {
+    case 'anthropic': {
+      const { anthropicProvider } = await import('./anthropic-provider');
+      return anthropicProvider;
+    }
+    case 'openai':
+    default: {
+      const { openaiProvider } = await import('./openai-provider');
+      return openaiProvider;
+    }
+  }
+}
+```
+
+## Step 6: OpenAI Embeddings (for RAG)
+
+```typescript
+// src/features/ai/server/embeddings.ts
+import 'server-only';
+
+import { createOpenAIClient } from '@/lib/core/ai/client';
+
+export async function createEmbedding(text: string): Promise<number[]> {
+  const client = createOpenAIClient();
+  const response = await client.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: text,
+  });
+  return response.data[0].embedding;
+}
+
+export async function createEmbeddings(texts: string[]): Promise<number[][]> {
+  const client = createOpenAIClient();
+  const response = await client.embeddings.create({
+    model: 'text-embedding-3-small',
+    input: texts,
+  });
+  return response.data.map((d) => d.embedding);
+}
+```
+
+## Step 7: Streaming API Route
+
+```typescript
+// src/app/api/protected/ai/chat/route.ts
+import { handleApiError, withAuthNoParams, type AuthenticatedRequest } from '@/lib/mars';
+import { getAIProvider } from '@/features/ai/server';
+import { checkRateLimit, RATE_LIMITS } from '@mars-stack/core/rate-limit';
+import { z } from 'zod';
+
+const chatSchema = z.object({
+  messages: z.array(z.object({
+    role: z.enum(['system', 'user', 'assistant']),
+    content: z.string().min(1).max(32_000),
+  })).min(1).max(100),
+  stream: z.boolean().default(true),
+});
+
+const AI_RATE_LIMIT = { maxRequests: 30, windowMs: 60_000 };
+
+export const POST = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    await checkRateLimit(request.session.userId, AI_RATE_LIMIT);
+    const { messages, stream } = chatSchema.parse(await request.json());
+    const provider = await getAIProvider();
+
+    if (stream) {
+      const readableStream = provider.stream({ messages });
+      return new Response(readableStream, {
+        headers: {
+          'Content-Type': 'text/plain; charset=utf-8',
+          'Transfer-Encoding': 'chunked',
+          'Cache-Control': 'no-cache',
+        },
+      });
+    }
+
+    const response = await provider.chat({ messages });
+    return Response.json(response);
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/ai/chat' });
+  }
+});
+```
+
+## Step 8: Usage Logging and Cost Management
+
+```typescript
+// src/features/ai/server/usage.ts
+import 'server-only';
+
+import { prisma } from '@/lib/prisma';
+import { logger } from '@/lib/mars';
+
+interface UsageRecord {
+  userId: string;
+  model: string;
+  promptTokens: number;
+  completionTokens: number;
+  endpoint: string;
+}
+
+export async function logUsage(record: UsageRecord): Promise<void> {
+  logger.info('ai.usage', {
+    userId: record.userId,
+    model: record.model,
+    promptTokens: record.promptTokens,
+    completionTokens: record.completionTokens,
+    totalTokens: record.promptTokens + record.completionTokens,
+    endpoint: record.endpoint,
+  });
+}
+
+export async function getUserTokenUsage(
+  userId: string,
+  since: Date,
+): Promise<number> {
+  // Query your usage tracking table or aggregated logs
+  // This is a placeholder — implement based on your storage strategy
+  return 0;
+}
+```
+
+## Step 9: Feature Directory Structure
+
+```
+src/
+├── lib/core/ai/
+│   ├── client.ts              # OpenAI client (lazy singleton)
+│   └── anthropic-client.ts    # Anthropic client (lazy singleton)
+├── features/ai/
+│   ├── types.ts               # AIProvider interface, ChatParams, ChatResponse
+│   ├── server/
+│   │   ├── index.ts           # Provider factory (getAIProvider)
+│   │   ├── openai-provider.ts # OpenAI AIProvider implementation
+│   │   ├── anthropic-provider.ts # Anthropic AIProvider implementation
+│   │   ├── embeddings.ts      # Embedding generation for RAG
+│   │   └── usage.ts           # Token usage logging and cost tracking
+│   ├── hooks/
+│   │   └── use-chat.ts        # Client-side chat hook (optional)
+│   └── validation/
+│       └── schemas.ts         # Zod schemas for AI API inputs
+└── app/api/protected/ai/
+    └── chat/
+        └── route.ts           # Streaming chat endpoint
+```
+
+## Step 10: Client-Side Chat Hook (Optional)
+
+```typescript
+// src/features/ai/hooks/use-chat.ts
+'use client';
+
+import { useState, useCallback } from 'react';
+import type { ChatMessage } from '../types';
+
+interface UseChatOptions {
+  onError?: (error: Error) => void;
+}
+
+export function useChat(options: UseChatOptions = {}) {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+
+  const send = useCallback(async (content: string) => {
+    const userMessage: ChatMessage = { role: 'user', content };
+    const updatedMessages = [...messages, userMessage];
+    setMessages(updatedMessages);
+    setIsLoading(true);
+
+    try {
+      const response = await fetch('/api/protected/ai/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ messages: updatedMessages, stream: true }),
+      });
+
+      if (!response.ok) throw new Error(`AI request failed: ${response.status}`);
+
+      const reader = response.body?.getReader();
+      if (!reader) throw new Error('No response stream');
+
+      const decoder = new TextDecoder();
+      let assistantContent = '';
+
+      setMessages((prev) => [...prev, { role: 'assistant', content: '' }]);
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        assistantContent += decoder.decode(value, { stream: true });
+        setMessages((prev) => {
+          const next = [...prev];
+          next[next.length - 1] = { role: 'assistant', content: assistantContent };
+          return next;
+        });
+      }
+    } catch (error) {
+      options.onError?.(error instanceof Error ? error : new Error(String(error)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [messages, options]);
+
+  const reset = useCallback(() => setMessages([]), []);
+
+  return { messages, isLoading, send, reset };
+}
+```
+
+## Common Patterns
+
+### Content Generation
+
+```typescript
+const provider = await getAIProvider();
+const result = await provider.chat({
+  messages: [
+    { role: 'system', content: 'You are a professional copywriter.' },
+    { role: 'user', content: `Write a product description for: ${product.name}` },
+  ],
+  temperature: 0.8,
+});
+```
+
+### Structured Output (JSON Mode — OpenAI)
+
+```typescript
+const result = await provider.chat({
+  messages: [
+    { role: 'system', content: 'Extract entities from the text. Respond with JSON: { "entities": [{ "name": string, "type": string }] }' },
+    { role: 'user', content: userText },
+  ],
+  jsonMode: true,
+});
+const parsed = JSON.parse(result.content);
+```
+
+### Classification
+
+```typescript
+const result = await provider.chat({
+  messages: [
+    { role: 'system', content: 'Classify the support ticket. Respond with one of: billing, technical, account, general.' },
+    { role: 'user', content: ticket.body },
+  ],
+  temperature: 0,
+  maxTokens: 10,
+});
+```
+
+### Summarization
+
+```typescript
+const result = await provider.chat({
+  messages: [
+    { role: 'system', content: 'Summarize the following in 2-3 sentences.' },
+    { role: 'user', content: longDocument },
+  ],
+  temperature: 0.3,
+});
+```
+
+## Config Integration
+
+Add to `app.config.ts`:
+
+```typescript
+services: {
+  ai: {
+    provider: 'openai', // or 'anthropic'
+  },
+},
+features: {
+  ai: true,
+},
+```
+
+## Tests
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('@/lib/core/ai/client', () => ({
+  createOpenAIClient: vi.fn(() => ({
+    chat: {
+      completions: {
+        create: vi.fn().mockResolvedValue({
+          choices: [{ message: { content: 'Hello!' }, finish_reason: 'stop' }],
+          usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+        }),
+      },
+    },
+  })),
+}));
+```
+
+## Checklist
+
+- [ ] AI SDK installed (`openai` or `@anthropic-ai/sdk`)
+- [ ] Environment variables set (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`)
+- [ ] Lazy client created in `src/lib/core/ai/`
+- [ ] `AIProvider` interface defined in `src/features/ai/types.ts`
+- [ ] Provider implementation(s) in `src/features/ai/server/`
+- [ ] Provider factory in `src/features/ai/server/index.ts`
+- [ ] All server modules import `'server-only'`
+- [ ] Streaming chat API route with per-user rate limiting
+- [ ] Zod validation on all API inputs
+- [ ] Auth wrapper (`withAuthNoParams`) on protected route
+- [ ] Usage logging for cost tracking
+- [ ] Feature flag checked (`appConfig.features.ai`)
+- [ ] Config integration with `appConfig.services.ai.provider`
+- [ ] Tests written with mocked AI client