@kood/claude-code 0.1.6 → 0.1.9

package/templates/hono/docs/library/ai-sdk/structured-output.md

@@ -1,55 +1,41 @@
-# AI SDK - 구조화된 출력 (Hono)
+# AI SDK - 구조화된 출력
 
-> **상위 문서**: [AI SDK](./index.md)
-
----
-
-## 개요
-
-AI SDK의 `generateObject`와 `streamObject`를 Hono에서 사용하면 타입 안전한 구조화된 데이터를 생성할 수 있습니다. Zod 스키마를 사용하여 출력 형식을 정의합니다.
+> Zod 스키마로 타입 안전한 객체 생성
 
 ---
 
 ## generateObject
 
-### 기본 사용
-
 ```typescript
-import { Hono } from 'hono'
 import { generateObject } from 'ai'
 import { openai } from '@ai-sdk/openai'
 import { z } from 'zod'
 
-const app = new Hono()
+const userSchema = z.object({
+  name: z.string(),
+  age: z.number(),
+  email: z.email(),
+})
 
 app.post('/api/generate-user', async (c) => {
   const { prompt } = await c.req.json()
 
   const { object } = await generateObject({
     model: openai('gpt-4o'),
-    schema: z.object({
-      name: z.string(),
-      age: z.number(),
-      email: z.string().email(),
-    }),
+    schema: userSchema,
     prompt,
   })
 
-  // object는 타입 안전: { name: string, age: number, email: string }
+  // object: { name: string, age: number, email: string }
   return c.json(object)
 })
 ```
 
-### 복잡한 스키마
-
-```typescript
-import { Hono } from 'hono'
-import { generateObject } from 'ai'
-import { openai } from '@ai-sdk/openai'
-import { z } from 'zod'
+---
 
-const app = new Hono()
+## 복잡한 스키마
 
+```typescript
 const recipeSchema = z.object({
   name: z.string().describe('Recipe name'),
   ingredients: z.array(
@@ -60,106 +46,20 @@ const recipeSchema = z.object({
     })
   ),
   steps: z.array(z.string()),
-  prepTime: z.number().describe('Preparation time in minutes'),
-  cookTime: z.number().describe('Cooking time in minutes'),
-  servings: z.number(),
+  prepTime: z.number().describe('Prep time in minutes'),
+  cookTime: z.number().describe('Cook time in minutes'),
   difficulty: z.enum(['easy', 'medium', 'hard']),
 })
 
-app.post('/api/generate-recipe', async (c) => {
+app.post('/api/recipe', async (c) => {
   const { dish } = await c.req.json()
 
-  const { object: recipe } = await generateObject({
+  const { object } = await generateObject({
     model: openai('gpt-4o'),
     schema: recipeSchema,
     prompt: `Generate a recipe for ${dish}.`,
   })
 
-  return c.json(recipe)
-})
-```
-
----
-
-## 출력 모드
-
-### Object (기본)
-
-```typescript
-app.post('/api/object', async (c) => {
-  const { prompt } = await c.req.json()
-
-  const { object } = await generateObject({
-    model: openai('gpt-4o'),
-    schema: z.object({
-      name: z.string(),
-      age: z.number(),
-    }),
-    prompt,
-  })
-
-  return c.json(object)
-})
-```
-
-### Array
-
-배열 형태의 출력:
-
-```typescript
-app.post('/api/array', async (c) => {
-  const { prompt } = await c.req.json()
-
-  const { object } = await generateObject({
-    model: openai('gpt-4o'),
-    output: 'array',
-    schema: z.object({
-      name: z.string(),
-      class: z.string().describe('Character class'),
-      description: z.string(),
-    }),
-    prompt,
-  })
-
-  // object는 배열
-  return c.json({ characters: object })
-})
-```
-
-### Enum
-
-분류 작업에 유용:
-
-```typescript
-app.post('/api/classify', async (c) => {
-  const { text } = await c.req.json()
-
-  const { object } = await generateObject({
-    model: openai('gpt-4o'),
-    output: 'enum',
-    enum: ['action', 'comedy', 'drama', 'horror', 'sci-fi'],
-    prompt: `Classify this movie: "${text}"`,
-  })
-
-  return c.json({ genre: object })
-})
-```
-
-### No Schema
-
-스키마 없이 자유 형식 JSON 생성:
-
-```typescript
-app.post('/api/freeform', async (c) => {
-  const { prompt } = await c.req.json()
-
-  const { object } = await generateObject({
-    model: openai('gpt-4o'),
-    output: 'no-schema',
-    prompt,
-  })
-
-  // object는 any 타입
   return c.json(object)
 })
 ```
@@ -168,28 +68,17 @@ app.post('/api/freeform', async (c) => {
 
 ## streamObject
 
-스트리밍으로 객체를 점진적으로 생성:
+스트리밍으로 객체 생성.
 
 ```typescript
-import { Hono } from 'hono'
 import { streamObject } from 'ai'
-import { openai } from '@ai-sdk/openai'
-import { z } from 'zod'
-
-const app = new Hono()
 
-const profileSchema = z.object({
-  name: z.string(),
-  bio: z.string(),
-  skills: z.array(z.string()),
-})
-
-app.post('/api/stream-profile', async (c) => {
+app.post('/api/stream-user', async (c) => {
   const { prompt } = await c.req.json()
 
   const result = streamObject({
     model: openai('gpt-4o'),
-    schema: profileSchema,
+    schema: userSchema,
     prompt,
   })
 
@@ -197,297 +86,76 @@ app.post('/api/stream-profile', async (c) => {
 })
 ```
 
-### 부분 객체 처리
+### 부분 객체 수신
 
 ```typescript
-import { Hono } from 'hono'
-import { streamObject } from 'ai'
-import { openai } from '@ai-sdk/openai'
-import { z } from 'zod'
-import { stream } from 'hono/streaming'
-
-const app = new Hono()
-
-app.post('/api/stream-partial', async (c) => {
-  const { prompt } = await c.req.json()
-
-  const result = streamObject({
-    model: openai('gpt-4o'),
-    schema: z.object({
-      name: z.string(),
-      bio: z.string(),
-      skills: z.array(z.string()),
-    }),
-    prompt,
-  })
-
-  return stream(c, async (stream) => {
-    for await (const partialObject of result.partialObjectStream) {
-      await stream.write(JSON.stringify(partialObject) + '\n')
-    }
-  })
-})
-```
-
----
-
-## 스키마 설계 팁
-
-### 필드 설명 추가
-
-```typescript
-const schema = z.object({
-  title: z.string().describe('A catchy title for the article'),
-  summary: z.string().describe('A 2-3 sentence summary'),
-  tags: z.array(z.string()).describe('Relevant topic tags'),
-})
-```
-
-### Optional 필드
-
-```typescript
-const schema = z.object({
-  name: z.string(),
-  nickname: z.string().optional(),
-  age: z.number().nullable(),
-})
-```
-
-### 기본값
-
-```typescript
-const schema = z.object({
-  name: z.string(),
-  role: z.string().default('user'),
-  isActive: z.boolean().default(true),
-})
-```
-
-### Enum 사용
-
-```typescript
-const schema = z.object({
-  status: z.enum(['pending', 'approved', 'rejected']),
-  priority: z.enum(['low', 'medium', 'high', 'critical']),
-})
-```
-
-### 중첩 객체
-
-```typescript
-const schema = z.object({
-  user: z.object({
-    name: z.string(),
-    email: z.string().email(),
-  }),
-  address: z.object({
-    street: z.string(),
-    city: z.string(),
-    country: z.string(),
-  }),
-})
-```
-
----
-
-## 실용 예제
-
-### 데이터 추출
-
-```typescript
-app.post('/api/extract', async (c) => {
-  const { text } = await c.req.json()
-
-  const { object } = await generateObject({
-    model: openai('gpt-4o'),
-    schema: z.object({
-      people: z.array(
-        z.object({
-          name: z.string(),
-          role: z.string().optional(),
-        })
-      ),
-      organizations: z.array(z.string()),
-      locations: z.array(z.string()),
-      dates: z.array(z.string()),
-    }),
-    prompt: `Extract entities from this text: ${text}`,
-  })
-
-  return c.json(object)
-})
-```
-
-### 요약 생성
-
-```typescript
-app.post('/api/summarize', async (c) => {
-  const { content } = await c.req.json()
-
-  const { object } = await generateObject({
-    model: openai('gpt-4o'),
-    schema: z.object({
-      summary: z.string().describe('One paragraph summary'),
-      keyPoints: z.array(z.string()).describe('3-5 key points'),
-      sentiment: z.enum(['positive', 'neutral', 'negative']),
-      topics: z.array(z.string()),
-    }),
-    prompt: `Summarize this content: ${content}`,
-  })
-
-  return c.json(object)
-})
-```
-
-### 폼 데이터 생성
-
-```typescript
-app.post('/api/generate-form', async (c) => {
-  const { description } = await c.req.json()
-
-  const { object } = await generateObject({
-    model: openai('gpt-4o'),
-    schema: z.object({
-      fields: z.array(
-        z.object({
-          name: z.string(),
-          type: z.enum(['text', 'email', 'number', 'select', 'textarea']),
-          label: z.string(),
-          required: z.boolean(),
-          placeholder: z.string().optional(),
-          options: z.array(z.string()).optional(),
-        })
-      ),
-    }),
-    prompt: `Generate form fields for: ${description}`,
-  })
-
-  return c.json(object)
+const result = streamObject({
+  model: openai('gpt-4o'),
+  schema: userSchema,
+  prompt,
 })
-```
-
----
-
-## 에러 처리
-
-```typescript
-import { Hono } from 'hono'
-import { HTTPException } from 'hono/http-exception'
-import { generateObject } from 'ai'
-import { openai } from '@ai-sdk/openai'
-import { z } from 'zod'
-
-const app = new Hono()
-
-app.post('/api/generate', async (c) => {
-  const { prompt } = await c.req.json()
 
-  try {
-    const { object } = await generateObject({
-      model: openai('gpt-4o'),
-      schema: z.object({
-        name: z.string(),
-        age: z.number(),
-      }),
-      prompt,
-    })
-
-    return c.json(object)
-  } catch (error) {
-    if (error instanceof z.ZodError) {
-      // 스키마 검증 실패
-      return c.json(
-        { error: 'Validation error', details: error.errors },
-        400
-      )
-    }
-
-    console.error('Generation error:', error)
-    throw new HTTPException(500, { message: 'Failed to generate object' })
-  }
-})
+for await (const partialObject of result.partialObjectStream) {
+  console.log('Partial:', partialObject)
+  // { name: 'Jo' }
+  // { name: 'John', age: 25 }
+  // { name: 'John', age: 25, email: 'john@...' }
+}
 ```
 
 ---
 
-## 반환값
-
-### generateObject
+## 출력 모드
 
 ```typescript
-const result = await generateObject({
+// Array 모드
+const { object } = await generateObject({
   model: openai('gpt-4o'),
-  schema,
-  prompt,
+  output: 'array',
+  schema: z.object({ name: z.string(), role: z.string() }),
+  prompt: 'List 5 team members.',
 })
+// object: [{ name: 'Alice', role: 'Engineer' }, ...]
 
-result.object     // 생성된 객체 (타입 안전)
-result.usage      // 토큰 사용량
-result.finishReason // 완료 이유
-```
-
-### streamObject
-
-```typescript
-const result = streamObject({
+// Enum 모드
+const { object } = await generateObject({
   model: openai('gpt-4o'),
-  schema,
-  prompt,
+  output: 'enum',
+  enum: ['positive', 'negative', 'neutral'],
+  prompt: 'Classify the sentiment: "I love this product!"',
 })
-
-result.partialObjectStream  // AsyncIterable<PartialObject>
-result.object               // Promise<FinalObject>
-result.usage                // Promise<Usage>
+// object: 'positive'
 ```
 
 ---
 
-## Cloudflare Workers 예제
+## 에러 처리
 
 ```typescript
-import { Hono } from 'hono'
-import { generateObject, streamObject } from 'ai'
-import { createOpenAI } from '@ai-sdk/openai'
-import { z } from 'zod'
-
-type Bindings = {
-  OPENAI_API_KEY: string
-}
-
-const app = new Hono<{ Bindings: Bindings }>()
-
-const productSchema = z.object({
-  name: z.string(),
-  description: z.string(),
-  price: z.number(),
-  features: z.array(z.string()),
-})
-
-app.post('/api/generate-product', async (c) => {
-  const openai = createOpenAI({ apiKey: c.env.OPENAI_API_KEY })
-  const { category } = await c.req.json()
+import { NoObjectGeneratedError, InvalidResponseDataError } from 'ai'
 
+try {
   const { object } = await generateObject({
     model: openai('gpt-4o'),
-    schema: productSchema,
-    prompt: `Generate a product in the ${category} category.`,
+    schema: userSchema,
+    prompt,
   })
-
   return c.json(object)
-})
-
-app.post('/api/stream-product', async (c) => {
-  const openai = createOpenAI({ apiKey: c.env.OPENAI_API_KEY })
-  const { category } = await c.req.json()
+} catch (error) {
+  if (error instanceof NoObjectGeneratedError) {
+    return c.json({ error: 'Failed to generate object' }, 500)
+  }
+  if (error instanceof InvalidResponseDataError) {
+    return c.json({ error: 'Invalid response format' }, 500)
+  }
+  throw error
+}
+```
 
-  const result = streamObject({
-    model: openai('gpt-4o'),
-    schema: productSchema,
-    prompt: `Generate a product in the ${category} category.`,
-  })
+---
 
-  return result.toTextStreamResponse()
-})
+## 관련 문서
 
-export default app
-```
+- [AI SDK 개요](./index.md)
+- [스트리밍](./streaming.md)
+- [도구](./tools.md)