@kood/claude-code 0.1.2 → 0.1.3

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

@@ -0,0 +1,472 @@
+# AI SDK - React Hooks
+
+> **상위 문서**: [AI SDK](./index.md)
+
+---
+
+## 개요
+
+AI SDK는 React 애플리케이션을 위한 훅을 제공합니다:
+- `useChat`: 채팅 인터페이스
+- `useCompletion`: 텍스트 완성
+- `useObject`: 구조화된 객체 생성 (실험적)
+
+```bash
+npm install @ai-sdk/react
+```
+
+---
+
+## useChat
+
+채팅 인터페이스를 쉽게 구현할 수 있는 훅입니다.
+
+### 기본 사용
+
+```tsx
+'use client'
+
+import { useChat } from '@ai-sdk/react'
+
+export default function Chat() {
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+    api: '/api/chat',
+  })
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Type a message..."
+          disabled={isLoading}
+        />
+        <button type="submit" disabled={isLoading}>
+          {isLoading ? 'Sending...' : 'Send'}
+        </button>
+      </form>
+    </div>
+  )
+}
+```
+
+### 반환값
+
+```typescript
+const {
+  // 메시지 관련
+  messages,           // Message[] - 전체 메시지 목록
+  setMessages,        // 메시지 직접 설정
+
+  // 입력 관련
+  input,              // string - 현재 입력값
+  setInput,           // 입력값 직접 설정
+  handleInputChange,  // 입력 변경 핸들러
+
+  // 제출 관련
+  handleSubmit,       // 폼 제출 핸들러
+  append,             // 메시지 추가 및 전송
+  reload,             // 마지막 응답 재생성
+
+  // 상태 관련
+  isLoading,          // 응답 대기 중
+  error,              // 에러 객체
+  stop,               // 스트리밍 중단
+} = useChat()
+```
+
+### 메시지 타입
+
+```typescript
+interface Message {
+  id: string
+  role: 'user' | 'assistant' | 'system'
+  content: string
+  createdAt?: Date
+  toolInvocations?: ToolInvocation[]
+}
+```
+
+### API Route 설정
+
+```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),
+  })
+
+  return result.toUIMessageStreamResponse()
+}
+```
+
+---
+
+## useChat 고급 기능
+
+### 초기 메시지
+
+```tsx
+const { messages } = useChat({
+  api: '/api/chat',
+  initialMessages: [
+    { id: '1', role: 'assistant', content: 'Hello! How can I help you?' },
+  ],
+})
+```
+
+### 동적 요청 데이터
+
+```tsx
+const [temperature, setTemperature] = useState(0.7)
+
+const { messages, handleSubmit } = useChat({
+  api: '/api/chat',
+  body: {
+    temperature,
+    userId: 'user-123',
+  },
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+})
+```
+
+서버에서 추가 데이터 접근:
+
+```typescript
+// app/api/chat/route.ts
+export async function POST(req: Request) {
+  const { messages, temperature, userId } = await req.json()
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    messages: convertToModelMessages(messages),
+    temperature, // 동적 파라미터 사용
+  })
+
+  return result.toUIMessageStreamResponse()
+}
+```
+
+### 콜백 함수
+
+```tsx
+const { messages } = useChat({
+  api: '/api/chat',
+  onResponse: (response) => {
+    console.log('Received response:', response)
+  },
+  onFinish: (message) => {
+    console.log('Finished:', message)
+  },
+  onError: (error) => {
+    console.error('Error:', error)
+    toast.error('Something went wrong')
+  },
+})
+```
+
+### 메시지 직접 추가
+
+```tsx
+const { append } = useChat()
+
+// 사용자 메시지 추가 및 전송
+const handleClick = async () => {
+  await append({
+    role: 'user',
+    content: 'Tell me a joke',
+  })
+}
+```
+
+### 스트리밍 중단
+
+```tsx
+const { stop, isLoading } = useChat()
+
+return (
+  <button onClick={stop} disabled={!isLoading}>
+    Stop generating
+  </button>
+)
+```
+
+### 마지막 응답 재생성
+
+```tsx
+const { reload, messages } = useChat()
+
+return (
+  <button onClick={reload} disabled={messages.length === 0}>
+    Regenerate response
+  </button>
+)
+```
+
+### UI 업데이트 쓰로틀링
+
+대량의 스트리밍 데이터가 있을 때 성능 최적화:
+
+```tsx
+const { messages } = useChat({
+  api: '/api/chat',
+  experimental_throttle: 50, // 50ms마다 UI 업데이트
+})
+```
+
+---
+
+## useCompletion
+
+단순 텍스트 완성을 위한 훅입니다.
+
+### 기본 사용
+
+```tsx
+'use client'
+
+import { useCompletion } from '@ai-sdk/react'
+
+export default function Completion() {
+  const { completion, input, handleInputChange, handleSubmit, isLoading } = useCompletion({
+    api: '/api/completion',
+  })
+
+  return (
+    <div>
+      <form onSubmit={handleSubmit}>
+        <input
+          value={input}
+          onChange={handleInputChange}
+          placeholder="Enter a prompt..."
+        />
+        <button type="submit" disabled={isLoading}>
+          Complete
+        </button>
+      </form>
+
+      <div>{completion}</div>
+    </div>
+  )
+}
+```
+
+### 반환값
+
+```typescript
+const {
+  completion,         // string - 생성된 텍스트
+  complete,           // 직접 완성 요청
+  input,              // string - 현재 입력값
+  setInput,           // 입력값 설정
+  handleInputChange,  // 입력 변경 핸들러
+  handleSubmit,       // 폼 제출 핸들러
+  isLoading,          // 로딩 상태
+  error,              // 에러 객체
+  stop,               // 스트리밍 중단
+  setCompletion,      // 완성 텍스트 직접 설정
+} = useCompletion()
+```
+
+### API Route
+
+```typescript
+// app/api/completion/route.ts
+import { streamText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+export async function POST(req: Request) {
+  const { prompt } = await req.json()
+
+  const result = streamText({
+    model: openai('gpt-4o'),
+    prompt,
+  })
+
+  return result.toUIMessageStreamResponse()
+}
+```
+
+### 프로그래매틱 호출
+
+```tsx
+const { complete, completion } = useCompletion({
+  api: '/api/completion',
+})
+
+const handleClick = async () => {
+  await complete('Write a haiku about programming')
+}
+```
+
+### 콜백
+
+```tsx
+const { completion } = useCompletion({
+  onResponse: (response) => {
+    console.log('Response received')
+  },
+  onFinish: (prompt, completion) => {
+    console.log('Finished:', completion)
+  },
+  onError: (error) => {
+    console.error('Error:', error)
+  },
+})
+```
+
+---
+
+## useObject (실험적)
+
+구조화된 객체를 스트리밍으로 생성합니다.
+
+### 기본 사용
+
+```tsx
+'use client'
+
+import { experimental_useObject as useObject } from '@ai-sdk/react'
+import { z } from 'zod'
+
+const schema = z.object({
+  name: z.string(),
+  age: z.number(),
+  hobbies: z.array(z.string()),
+})
+
+export default function ObjectGenerator() {
+  const { object, submit, isLoading, error } = useObject({
+    api: '/api/generate-object',
+    schema,
+  })
+
+  return (
+    <div>
+      <button onClick={() => submit('Generate a random person')} disabled={isLoading}>
+        Generate
+      </button>
+
+      {object && (
+        <pre>{JSON.stringify(object, null, 2)}</pre>
+      )}
+    </div>
+  )
+}
+```
+
+### API Route
+
+```typescript
+// app/api/generate-object/route.ts
+import { streamObject } from 'ai'
+import { openai } from '@ai-sdk/openai'
+import { z } from 'zod'
+
+const schema = z.object({
+  name: z.string(),
+  age: z.number(),
+  hobbies: z.array(z.string()),
+})
+
+export async function POST(req: Request) {
+  const { prompt } = await req.json()
+
+  const result = streamObject({
+    model: openai('gpt-4o'),
+    schema,
+    prompt,
+  })
+
+  return result.toTextStreamResponse()
+}
+```
+
+---
+
+## 도구 호출 표시
+
+채팅에서 도구 호출을 표시하는 방법:
+
+```tsx
+'use client'
+
+import { useChat } from '@ai-sdk/react'
+
+export default function Chat() {
+  const { messages } = useChat({
+    api: '/api/chat',
+  })
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong>
+
+          {/* 텍스트 콘텐츠 */}
+          {m.content}
+
+          {/* 도구 호출 표시 */}
+          {m.toolInvocations?.map((tool, i) => (
+            <div key={i} className="tool-call">
+              <strong>Tool: {tool.toolName}</strong>
+              <pre>Input: {JSON.stringify(tool.args, null, 2)}</pre>
+              {tool.state === 'result' && (
+                <pre>Result: {JSON.stringify(tool.result, null, 2)}</pre>
+              )}
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+---
+
+## 스트림 프로토콜
+
+AI SDK v5에서는 기본 스트림 프로토콜이 변경되었습니다:
+
+```tsx
+// v5 기본값 (data protocol)
+const { messages } = useChat()
+
+// 레거시 텍스트 프로토콜 사용
+const { messages } = useChat({
+  streamProtocol: 'text',
+})
+```
+
+---
+
+## 타입 안전성
+
+```typescript
+import { useChat, Message } from '@ai-sdk/react'
+
+// 메시지 타입 확장
+interface CustomMessage extends Message {
+  customField?: string
+}
+
+// 타입 지정
+const { messages } = useChat<CustomMessage>()
+```

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

@@ -0,0 +1,264 @@
+# Vercel AI SDK
+
+> **Version**: 4.x / 5.x | TypeScript AI Toolkit
+
+---
+
+## 🚀 Quick Reference (복사용)
+
+```typescript
+// 텍스트 생성
+import { generateText, streamText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Hello, world!',
+})
+
+// 스트리밍
+const result = streamText({
+  model: openai('gpt-4o'),
+  prompt: 'Write a story.',
+})
+
+for await (const chunk of result.textStream) {
+  console.log(chunk)
+}
+
+// 구조화된 출력
+import { generateObject } from 'ai'
+import { z } from 'zod'
+
+const { object } = await generateObject({
+  model: openai('gpt-4o'),
+  schema: z.object({ name: z.string(), age: z.number() }),
+  prompt: 'Generate a user.',
+})
+
+// React Hook
+import { useChat } from '@ai-sdk/react'
+
+const { messages, input, handleInputChange, handleSubmit } = useChat()
+```
+
+---
+
+## 문서 구조
+
+- [프로바이더 설정](./providers.md) - OpenAI, Anthropic, Google 등
+- [OpenRouter](./openrouter.md) - 통합 AI 게이트웨이 (수백 개 모델)
+- [텍스트 생성](./streaming.md) - generateText, streamText
+- [React Hooks](./hooks.md) - useChat, useCompletion
+- [Tool Calling](./tools.md) - 도구 정의 및 호출
+- [구조화된 출력](./structured-output.md) - generateObject, 스키마 기반 출력
+
+---
+
+## 설치
+
+```bash
+# 코어 패키지
+npm install ai
+
+# 프로바이더 패키지 (필요한 것만 설치)
+npm install @ai-sdk/openai      # OpenAI
+npm install @ai-sdk/anthropic   # Anthropic (Claude)
+npm install @ai-sdk/google      # Google (Gemini)
+
+# React Hook 사용 시
+npm install @ai-sdk/react
+```
+
+---
+
+## 핵심 개념
+
+### 프로바이더 (Providers)
+
+AI 모델 서비스와의 연결을 담당합니다.
+
+```typescript
+import { openai } from '@ai-sdk/openai'
+import { anthropic } from '@ai-sdk/anthropic'
+import { google } from '@ai-sdk/google'
+
+// 모델 인스턴스 생성
+const gpt4 = openai('gpt-4o')
+const claude = anthropic('claude-3-5-sonnet-20241022')
+const gemini = google('gemini-1.5-pro')
+```
+
+### 코어 함수
+
+| 함수 | 용도 | 반환 |
+|------|------|------|
+| `generateText` | 텍스트 생성 (비스트리밍) | `{ text, toolCalls, ... }` |
+| `streamText` | 텍스트 스트리밍 | `{ textStream, ... }` |
+| `generateObject` | 구조화된 객체 생성 | `{ object }` |
+| `streamObject` | 구조화된 객체 스트리밍 | `{ partialObjectStream }` |
+
+### React Hooks
+
+| Hook | 용도 |
+|------|------|
+| `useChat` | 채팅 인터페이스 |
+| `useCompletion` | 텍스트 완성 |
+| `useObject` | 구조화된 객체 생성 (실험적) |
+
+---
+
+## 기본 사용법
+
+### 텍스트 생성
+
+```typescript
+import { generateText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const { text, usage } = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Explain quantum computing in simple terms.',
+})
+
+console.log(text)
+console.log(`Tokens used: ${usage.totalTokens}`)
+```
+
+### 스트리밍
+
+```typescript
+import { streamText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const result = streamText({
+  model: openai('gpt-4o'),
+  prompt: 'Write a haiku about programming.',
+})
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk)
+}
+```
+
+### 채팅 (메시지 기반)
+
+```typescript
+import { generateText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What is TypeScript?' },
+  ],
+})
+```
+
+---
+
+## TanStack Start 통합
+
+### API Route 설정
+
+```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),
+  })
+
+  return result.toUIMessageStreamResponse()
+}
+```
+
+### 클라이언트 컴포넌트
+
+```tsx
+'use client'
+
+import { useChat } from '@ai-sdk/react'
+
+export default function Chat() {
+  const { messages, input, handleInputChange, handleSubmit } = useChat({
+    api: '/api/chat',
+  })
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} placeholder="Say something..." />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  )
+}
+```
+
+---
+
+## 환경 변수
+
+```bash
+# .env
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_GENERATIVE_AI_API_KEY=...
+```
+
+---
+
+## v5 주요 변경사항
+
+### 스트림 프로토콜 변경
+
+```typescript
+// v4 - text protocol 명시 필요
+const { messages } = useChat({ streamProtocol: 'text' })
+
+// v5 - 기본값이 data protocol
+const { messages } = useChat()
+```
+
+### 프로바이더 초기화 변경
+
+```typescript
+// v4 (deprecated)
+const openai = new OpenAI({ /* ... */ })
+
+// v5
+import { createOpenAI } from '@ai-sdk/openai'
+const openai = createOpenAI({ /* ... */ })
+```
+
+### responseMessages 제거
+
+```typescript
+// v4
+const { text, responseMessages } = await generateText({ ... })
+
+// v5
+const { text, response } = await generateText({ ... })
+const responseMessages = response.messages
+```
+
+---
+
+## 참고 자료
+
+- [AI SDK 공식 문서](https://sdk.vercel.ai/docs)
+- [AI SDK GitHub](https://github.com/vercel/ai)
+- [AI SDK 예제](https://github.com/vercel/ai/tree/main/examples)