@kood/claude-code 0.1.1 → 0.1.3

package/templates/tanstack-start/docs/library/ai-sdk/providers.md

@@ -0,0 +1,403 @@
+# AI SDK - 프로바이더
+
+> **상위 문서**: [AI SDK](./index.md)
+
+---
+
+## 개요
+
+AI SDK 프로바이더는 다양한 AI 모델 서비스와의 연결을 표준화합니다.
+
+---
+
+## 설치
+
+```bash
+# 필요한 프로바이더만 설치
+npm install @ai-sdk/openai      # OpenAI (GPT-4, GPT-4o)
+npm install @ai-sdk/anthropic   # Anthropic (Claude)
+npm install @ai-sdk/google      # Google (Gemini)
+npm install @ai-sdk/mistral     # Mistral
+npm install @ai-sdk/groq        # Groq
+npm install @ai-sdk/cohere      # Cohere
+```
+
+---
+
+## OpenAI
+
+### 기본 사용
+
+```typescript
+import { openai } from '@ai-sdk/openai'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello!',
+})
+```
+
+### 커스텀 설정
+
+```typescript
+import { createOpenAI } from '@ai-sdk/openai'
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: 'https://api.openai.com/v1', // 커스텀 엔드포인트
+  organization: 'org-xxx', // 조직 ID
+})
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello!',
+})
+```
+
+### 사용 가능한 모델
+
+| 모델 | 설명 |
+|------|------|
+| `gpt-4o` | 최신 GPT-4 Omni |
+| `gpt-4o-mini` | 경량화된 GPT-4o |
+| `gpt-4-turbo` | GPT-4 Turbo |
+| `gpt-3.5-turbo` | GPT-3.5 |
+| `o1` | 추론 최적화 모델 |
+| `o1-mini` | 경량 추론 모델 |
+
+### 환경 변수
+
+```bash
+OPENAI_API_KEY=sk-...
+```
+
+---
+
+## Anthropic (Claude)
+
+### 기본 사용
+
+```typescript
+import { anthropic } from '@ai-sdk/anthropic'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: anthropic('claude-3-5-sonnet-20241022'),
+  prompt: 'Explain TypeScript.',
+})
+```
+
+### 커스텀 설정
+
+```typescript
+import { createAnthropic } from '@ai-sdk/anthropic'
+
+const anthropic = createAnthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  baseURL: 'https://api.anthropic.com', // 커스텀 엔드포인트
+})
+
+const { text } = await generateText({
+  model: anthropic('claude-3-5-sonnet-20241022'),
+  prompt: 'Hello!',
+})
+```
+
+### 사용 가능한 모델
+
+| 모델 | 설명 |
+|------|------|
+| `claude-3-5-sonnet-20241022` | Claude 3.5 Sonnet (최신) |
+| `claude-3-5-haiku-20241022` | Claude 3.5 Haiku (빠름) |
+| `claude-3-opus-20240229` | Claude 3 Opus (강력) |
+| `claude-3-sonnet-20240229` | Claude 3 Sonnet |
+| `claude-3-haiku-20240307` | Claude 3 Haiku |
+
+### 환경 변수
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+---
+
+## Google (Gemini)
+
+### 기본 사용
+
+```typescript
+import { google } from '@ai-sdk/google'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: google('gemini-1.5-pro'),
+  prompt: 'What is machine learning?',
+})
+```
+
+### 커스텀 설정
+
+```typescript
+import { createGoogleGenerativeAI } from '@ai-sdk/google'
+
+const google = createGoogleGenerativeAI({
+  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
+})
+
+const { text } = await generateText({
+  model: google('gemini-1.5-pro'),
+  prompt: 'Hello!',
+})
+```
+
+### 사용 가능한 모델
+
+| 모델 | 설명 |
+|------|------|
+| `gemini-1.5-pro` | Gemini 1.5 Pro |
+| `gemini-1.5-flash` | Gemini 1.5 Flash (빠름) |
+| `gemini-2.0-flash-exp` | Gemini 2.0 Flash (실험) |
+
+### 환경 변수
+
+```bash
+GOOGLE_GENERATIVE_AI_API_KEY=...
+```
+
+---
+
+## Google Vertex AI
+
+Vertex AI는 Google Cloud 환경에서 사용합니다.
+
+### 설치
+
+```bash
+npm install @ai-sdk/google-vertex
+```
+
+### 기본 사용
+
+```typescript
+import { vertex } from '@ai-sdk/google-vertex'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: vertex('gemini-1.5-pro'),
+  prompt: 'Hello!',
+})
+```
+
+### Vertex AI + Anthropic
+
+```typescript
+import { vertexAnthropic } from '@ai-sdk/google-vertex/anthropic'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: vertexAnthropic('claude-3-5-sonnet@20240620'),
+  prompt: 'Write a poem.',
+})
+```
+
+### 커스텀 설정
+
+```typescript
+import { createVertexAnthropic } from '@ai-sdk/google-vertex/anthropic'
+
+const vertexAnthropic = createVertexAnthropic({
+  project: 'my-project-id',
+  location: 'us-central1',
+})
+
+// Edge 런타임용
+import { createVertexAnthropic } from '@ai-sdk/google-vertex/anthropic/edge'
+```
+
+### 환경 변수
+
+```bash
+GOOGLE_VERTEX_PROJECT=my-project-id
+GOOGLE_VERTEX_LOCATION=us-central1
+```
+
+---
+
+## Groq
+
+### 설치
+
+```bash
+npm install @ai-sdk/groq
+```
+
+### 기본 사용
+
+```typescript
+import { groq } from '@ai-sdk/groq'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: groq('llama-3.1-70b-versatile'),
+  prompt: 'Hello!',
+})
+```
+
+### 환경 변수
+
+```bash
+GROQ_API_KEY=gsk_...
+```
+
+---
+
+## Mistral
+
+### 설치
+
+```bash
+npm install @ai-sdk/mistral
+```
+
+### 기본 사용
+
+```typescript
+import { mistral } from '@ai-sdk/mistral'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: mistral('mistral-large-latest'),
+  prompt: 'Hello!',
+})
+```
+
+### 환경 변수
+
+```bash
+MISTRAL_API_KEY=...
+```
+
+---
+
+## AI Gateway (통합 프로바이더)
+
+AI Gateway는 여러 프로바이더를 하나의 인터페이스로 통합합니다.
+
+```typescript
+import { gateway } from 'ai'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: gateway('openai/gpt-4o'), // 프로바이더/모델 형식
+  prompt: 'Hello!',
+})
+
+// 다른 프로바이더도 동일한 방식
+const { text: text2 } = await generateText({
+  model: gateway('anthropic/claude-3-5-sonnet'),
+  prompt: 'Hello!',
+})
+```
+
+---
+
+## 프로바이더 비교
+
+| 프로바이더 | 장점 | 단점 |
+|-----------|------|------|
+| **OpenAI** | 가장 다양한 모델, 안정적 | 비용이 높을 수 있음 |
+| **Anthropic** | 긴 컨텍스트, 안전성 | 모델 종류 적음 |
+| **Google** | 멀티모달 강점, 무료 티어 | API 제한 |
+| **Groq** | 매우 빠른 추론 속도 | 모델 종류 제한 |
+| **Mistral** | 유럽 데이터 레지던시, 오픈소스 | 상대적으로 새로운 서비스 |
+
+---
+
+## 모델 파라미터
+
+모든 프로바이더에서 공통으로 사용 가능한 파라미터:
+
+```typescript
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello!',
+
+  // 공통 파라미터
+  temperature: 0.7,        // 창의성 (0-2, 기본 1)
+  maxTokens: 1000,         // 최대 토큰 수
+  topP: 0.9,               // 핵 샘플링
+  frequencyPenalty: 0.5,   // 반복 억제
+  presencePenalty: 0.5,    // 새로운 주제 유도
+  stopSequences: ['\n\n'], // 생성 중단 시퀀스
+})
+```
+
+---
+
+## OpenRouter (통합 게이트웨이)
+
+하나의 API 키로 수백 개 모델에 접근할 수 있는 통합 게이트웨이입니다.
+
+### 설치
+
+```bash
+npm install @openrouter/ai-sdk-provider
+```
+
+### 기본 사용
+
+```typescript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider'
+import { generateText } from 'ai'
+
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+})
+
+const { text } = await generateText({
+  model: openrouter.chat('anthropic/claude-3.5-sonnet'),
+  prompt: 'Hello!',
+})
+```
+
+### 인기 모델
+
+| 모델 ID | 설명 |
+|---------|------|
+| `anthropic/claude-3.5-sonnet` | Claude 3.5 Sonnet |
+| `openai/gpt-4o` | GPT-4o |
+| `google/gemini-pro-1.5` | Gemini Pro 1.5 |
+| `meta-llama/llama-3.1-70b-instruct` | Llama 3.1 70B |
+
+자세한 내용: [OpenRouter 가이드](./openrouter.md)
+
+---
+
+## 환경 변수 요약
+
+```bash
+# .env
+
+# OpenAI
+OPENAI_API_KEY=sk-...
+
+# Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Google
+GOOGLE_GENERATIVE_AI_API_KEY=...
+
+# Google Vertex AI
+GOOGLE_VERTEX_PROJECT=my-project
+GOOGLE_VERTEX_LOCATION=us-central1
+
+# Groq
+GROQ_API_KEY=gsk_...
+
+# Mistral
+MISTRAL_API_KEY=...
+
+# OpenRouter
+OPENROUTER_API_KEY=sk-or-v1-...
+```

package/templates/tanstack-start/docs/library/ai-sdk/streaming.md

@@ -0,0 +1,320 @@
+# AI SDK - 텍스트 생성
+
+> **상위 문서**: [AI SDK](./index.md)
+
+---
+
+## 개요
+
+AI SDK는 두 가지 주요 텍스트 생성 방식을 제공합니다:
+- `generateText`: 전체 응답을 한 번에 반환
+- `streamText`: 실시간 스트리밍 응답
+
+---
+
+## generateText
+
+전체 응답이 완료될 때까지 기다린 후 결과를 반환합니다.
+
+### 기본 사용
+
+```typescript
+import { generateText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const { text, usage, finishReason } = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Explain quantum computing.',
+})
+
+console.log(text)
+console.log(`Tokens: ${usage.totalTokens}`)
+console.log(`Finish reason: ${finishReason}`)
+```
+
+### 메시지 기반 (채팅)
+
+```typescript
+import { generateText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  system: 'You are a helpful assistant.',
+  messages: [
+    { role: 'user', content: 'What is TypeScript?' },
+    { role: 'assistant', content: 'TypeScript is a typed superset of JavaScript.' },
+    { role: 'user', content: 'How do I get started?' },
+  ],
+})
+```
+
+### 반환값
+
+```typescript
+const result = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello!',
+})
+
+// 주요 속성
+result.text           // 생성된 텍스트
+result.usage          // { promptTokens, completionTokens, totalTokens }
+result.finishReason   // 'stop' | 'length' | 'content-filter' | 'tool-calls' | ...
+result.toolCalls      // 도구 호출 목록
+result.toolResults    // 도구 실행 결과
+result.response       // 원본 응답 객체
+result.steps          // 다중 단계 실행 시 각 단계 정보
+```
+
+---
+
+## streamText
+
+실시간으로 응답을 스트리밍합니다. 사용자 경험이 중요한 채팅 애플리케이션에 적합합니다.
+
+### 기본 사용
+
+```typescript
+import { streamText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const result = streamText({
+  model: openai('gpt-4o'),
+  prompt: 'Write a haiku about programming.',
+})
+
+// AsyncIterable로 스트리밍
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+### 메시지 기반 스트리밍
+
+```typescript
+import { streamText, convertToModelMessages } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const result = streamText({
+  model: openai('gpt-4o'),
+  system: 'You are a helpful assistant.',
+  messages: convertToModelMessages([
+    { id: '1', role: 'user', content: 'Hello!' },
+    { id: '2', role: 'assistant', content: 'Hi there!' },
+    { id: '3', role: 'user', content: 'How are you?' },
+  ]),
+})
+
+for await (const chunk of result.textStream) {
+  console.log(chunk)
+}
+```
+
+### 스트리밍 속성
+
+```typescript
+const result = streamText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello!',
+})
+
+// 다양한 스트림 접근
+result.textStream        // 텍스트만 스트리밍
+result.fullStream        // 전체 이벤트 스트리밍 (도구 호출 포함)
+
+// 최종 결과 (Promise)
+const finalText = await result.text
+const finalUsage = await result.usage
+const finalFinishReason = await result.finishReason
+```
+
+### fullStream 이벤트
+
+```typescript
+for await (const event of result.fullStream) {
+  switch (event.type) {
+    case 'text-delta':
+      console.log('Text:', event.textDelta)
+      break
+    case 'tool-call':
+      console.log('Tool call:', event.toolName, event.input)
+      break
+    case 'tool-result':
+      console.log('Tool result:', event.output)
+      break
+    case 'finish':
+      console.log('Finished:', event.finishReason)
+      break
+    case 'error':
+      console.error('Error:', event.error)
+      break
+  }
+}
+```
+
+---
+
+## API Route에서 사용
+
+### TanStack Start / Next.js
+
+```typescript
+// app/api/chat/route.ts
+import { streamText, convertToModelMessages } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    messages: convertToModelMessages(messages),
+  })
+
+  // UI 메시지 스트림으로 변환
+  return result.toUIMessageStreamResponse()
+}
+```
+
+### 텍스트 스트림으로 반환
+
+```typescript
+export async function POST(req: Request) {
+  const { prompt } = await req.json()
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    prompt,
+  })
+
+  // 순수 텍스트 스트림
+  return result.toTextStreamResponse()
+}
+```
+
+### 에러 핸들링
+
+```typescript
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    messages: convertToModelMessages(messages),
+  })
+
+  // 에러 메시지를 UI로 전달
+  return result.toUIMessageStreamResponse({
+    getErrorMessage: (error) => {
+      if (error instanceof Error) {
+        return error.message
+      }
+      return 'An error occurred'
+    },
+  })
+}
+```
+
+---
+
+## 고급 옵션
+
+### 온도 및 토큰 제한
+
+```typescript
+const result = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Write a creative story.',
+  temperature: 0.9,      // 높을수록 창의적 (0-2)
+  maxTokens: 2000,       // 최대 출력 토큰
+  topP: 0.95,            // 핵 샘플링
+})
+```
+
+### 중단 조건
+
+```typescript
+import { generateText, stopWhen, stepCountIs } from 'ai'
+
+const result = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Solve this problem step by step.',
+  stopWhen: stepCountIs(5), // 최대 5단계
+})
+```
+
+### 응답 메시지 접근
+
+```typescript
+const { text, response } = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello!',
+})
+
+// v5에서 responseMessages 접근 방법
+const responseMessages = response.messages
+```
+
+---
+
+## onFinish 콜백
+
+스트리밍 완료 시 실행되는 콜백:
+
+```typescript
+const result = streamText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello!',
+  onFinish: async ({ text, usage, finishReason }) => {
+    console.log('Completed:', text)
+    console.log('Tokens used:', usage.totalTokens)
+
+    // DB에 저장 등
+    await saveToDatabase({ text, usage })
+  },
+})
+```
+
+---
+
+## TanStack Start Server Function 통합
+
+```typescript
+// lib/ai.ts
+import { createServerFn } from '@tanstack/react-start'
+import { generateText, streamText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+// 비스트리밍 버전
+export const generateResponse = createServerFn({ method: 'POST' })
+  .inputValidator((data: { prompt: string }) => data)
+  .handler(async ({ data }) => {
+    const { text } = await generateText({
+      model: openai('gpt-4o'),
+      prompt: data.prompt,
+    })
+    return { text }
+  })
+
+// 스트리밍은 API Route 사용 권장
+```
+
+---
+
+## 파라미터 요약
+
+| 파라미터 | 타입 | 설명 |
+|---------|------|------|
+| `model` | Model | AI 모델 인스턴스 |
+| `prompt` | string | 단일 프롬프트 |
+| `messages` | Message[] | 메시지 배열 (채팅) |
+| `system` | string | 시스템 프롬프트 |
+| `temperature` | number | 창의성 (0-2) |
+| `maxTokens` | number | 최대 출력 토큰 |
+| `topP` | number | 핵 샘플링 (0-1) |
+| `frequencyPenalty` | number | 반복 억제 (-2 to 2) |
+| `presencePenalty` | number | 새로운 주제 유도 (-2 to 2) |
+| `stopSequences` | string[] | 생성 중단 시퀀스 |
+| `tools` | ToolSet | 도구 정의 |
+| `onFinish` | Function | 완료 콜백 |