#Step 05 — 구조화된 출력 (zod)

import { initChatModel } from "langchain";

const model = await initChatModel("anthropic:claude-sonnet-4-6");

const raw = await model.invoke(
  "다음 리뷰의 별점(1~5)과 감정을 알려줘: '배송은 빨랐는데 가격이 너무 비싸요. 그래도 품질은 만족.'",
);
console.log(raw.content);

const text = String(raw.content);
const guessed = text.match(/([1-5])\s*(?:점|\/\s*5|stars?)/)?.[1];
// "3~4점" → "3" 이 잡힘. 근데 이게 맞는 답인가?

import * as z from "zod";

const Review = z.object({
  rating: z.number().min(1).max(5).describe("별점 1~5"),
  sentiment: z.enum(["positive", "negative", "neutral"]).describe("전체 감정"),
});

const structured = await model.withStructuredOutput(Review).invoke(
  "다음 리뷰를 분석해: '배송은 빨랐는데 가격이 너무 비싸요. 그래도 품질은 만족.'",
);
console.log(structured);

import * as z from "zod";

const Ticket = z.object({
  // string / number — 가장 기본
  title: z.string().describe("티켓 제목. 한 문장, 40자 이내."),
  priority: z.number().min(1).max(5).describe("우선순위. 1=가장 급함, 5=여유."),

  // enum — 모델의 선택지를 강제한다. 분류 작업의 핵심.
  category: z.enum(["bug", "feature", "question", "billing"]).describe("티켓 분류. 넷 중 하나만."),

  // array — 개수 제한도 걸 수 있다
  tags: z.array(z.string()).max(3).describe("검색용 태그. 소문자, 1~2단어."),

  // optional — "키가 없어도 된다"
  assignee: z.string().optional().describe("담당자 이름. 글에 없으면 생략."),

  // nullable — "키는 있는데 값이 null 이어도 된다"
  dueDate: z.string().nullable().describe("마감일 YYYY-MM-DD. 글에 없으면 반드시 null."),

  // 중첩 객체 — 얕게 유지할 것
  reporter: z.object({
    name: z.string().describe("신고자 이름"),
    email: z.string().describe("신고자 이메일. 없으면 빈 문자열."),
  }).describe("신고자 정보"),
});

type Ticket = z.infer<typeof Ticket>;  // 스키마가 곧 타입

const result = Ticket.safeParse({
  title: "로그인 버튼이 안 눌림",
  priority: 9,               // ← max(5) 위반
  category: "urgent",        // ← enum 에 없음
  tags: ["login"],
  dueDate: null,
  reporter: { name: "김민수", email: "kim@example.com" },
});

console.log(result.success ? "OK" : result.error.issues.map(i => `${i.path.join(".")}: ${i.message}`));

const Opt = z.object({ v: z.string().optional() });
const Nul = z.object({ v: z.string().nullable() });

Opt.safeParse({}).success;         // true  — 키 생략 OK
Opt.safeParse({ v: null }).success; // false — null 은 거부!
Nul.safeParse({}).success;          // false — 키 생략 거부!
Nul.safeParse({ v: null }).success; // true  — null OK

import { initChatModel } from "langchain";
import * as z from "zod";

const model = await initChatModel("anthropic:claude-sonnet-4-6");

const Movie = z.object({
  title: z.string().describe("영화 제목"),
  year: z.number().describe("개봉 연도"),
  director: z.string().describe("감독 이름"),
  rating: z.number().describe("10점 만점 평점"),
});

const modelWithStructure = model.withStructuredOutput(Movie);
const response = await modelWithStructure.invoke("영화 인셉션의 정보를 알려줘");
console.log(response);

// includeRaw: 파싱된 것과 원본 메시지를 함께 받는다
import type { AIMessage } from "@langchain/core/messages";

const withRaw = model.withStructuredOutput(Movie, { includeRaw: true });
const both = await withRaw.invoke("영화 매트릭스의 정보를 알려줘");
console.log(both.parsed);  // { title: '매트릭스', ... }

// raw 는 BaseMessage 로 타입이 잡혀 있다 — usage_metadata 를 쓰려면 좁혀야 한다
const raw = both.raw as AIMessage;
console.log(raw.usage_metadata);  // { input_tokens, output_tokens, total_tokens }

// method: 구현 방식을 고른다
const viaJsonSchema = model.withStructuredOutput(Movie, { method: "jsonSchema" });

import { createAgent } from "langchain";
import * as z from "zod";

const ContactInfo = z.object({
  name: z.string().describe("사람 이름"),
  email: z.string().describe("이메일 주소"),
  phone: z.string().describe("전화번호"),
});

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [],
  responseFormat: ContactInfo,     // ← 스키마를 그대로 넘기면 전략은 자동 선택
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "다음에서 연락처를 추출해: John Doe, john@example.com, (555) 123-4567" }],
});

console.log(result.structuredResponse);

import { createAgent, toolStrategy, providerStrategy } from "langchain";

// (A) provider 네이티브 JSON schema 방식
const providerAgent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [],
  responseFormat: providerStrategy(ProductReview),
});

// (B) tool calling 방식
const toolAgent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [],
  responseFormat: toolStrategy(ProductReview),
});

const a = await providerAgent.invoke({ messages: [question] });
const b = await toolAgent.invoke({ messages: [question] });

console.log(a.messages.map(m => m.getType()));
console.log(b.messages.map(m => m.getType()));

const ProductReview = z.object({
  rating: z.number().min(1).max(5).optional(),
  sentiment: z.enum(["positive", "negative"]),
  keyPoints: z.array(z.string()).describe("리뷰의 핵심 포인트. 소문자, 1~3단어."),
});

const CustomerComplaint = z.object({
  issueType: z.enum(["product", "service", "shipping", "billing"]),
  severity: z.enum(["low", "medium", "high"]),
  description: z.string().describe("불만 사항 요약"),
});

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [],
  responseFormat: toolStrategy([ProductReview, CustomerComplaint]),   // ← 배열
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "배송이 3주째 안 와요. 환불해주세요." }],
});
console.log(result.structuredResponse);

const article =
  "지난 분기 매출은 전년 대비 23% 성장했으나, 마케팅 비용이 40% 늘어 영업이익률은 " +
  "오히려 2%p 하락했다. CFO 박정현은 하반기 비용 통제를 예고했다.";

// (A) describe 없음
const Vague = z.object({
  summary: z.string(),
  metric: z.string(),
  person: z.string(),
});

// (B) describe 있음
const Precise = z.object({
  summary: z.string().describe("기사 핵심을 한 문장(60자 이내)으로. 숫자를 반드시 포함할 것."),
  metric: z.string().describe("가장 중요한 단일 지표를 '이름: 값' 형식으로. 예) '영업이익률: -2%p'"),
  person: z.string().describe("등장 인물의 이름만. 직함 제외. 없으면 빈 문자열."),
});

const ProductRating = z.object({
  rating: z.number().min(1).max(5).describe("1~5 사이 별점"),
  comment: z.string().describe("리뷰 코멘트"),
});

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [],
  responseFormat: toolStrategy(ProductRating),
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "이걸 파싱해: Amazing product, 10/10!" }],
});

// (1) 기본값: true — 기본 에러 템플릿으로 재시도
toolStrategy(ProductRating)

// (2) 문자열 — 내가 쓴 문장이 tool 메시지로 간다
toolStrategy(ProductRating, {
  handleError: "rating 은 1~5 사이여야 합니다. 10점 만점 표기는 5점 만점으로 환산하세요.",
})

// (3) 함수 — 에러 종류별로 다르게 대응
import { StructuredOutputParsingError } from "langchain";

toolStrategy(ProductRating, {
  handleError: (error) => {          // error 타입은 추론된다 (아래 함정 참고)
    if (error instanceof StructuredOutputParsingError) {
      return "rating 은 1~5 사이 정수여야 하고 comment 는 비울 수 없습니다.";
    }
    return error.message;            // MultipleStructuredOutputsError 인 경우
  },
})

// (4) false — 재시도하지 않고 예외를 그대로 던진다
toolStrategy(ProductRating, { handleError: false })

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [],
  responseFormat: toolStrategy(MeetingAction, {
    toolMessageContent: "액션 아이템을 회의록에 기록했습니다!",
  }),
});

// ❌ 정보가 없으면 모델이 환각한다
z.object({
  rating: z.number().min(1).max(5).describe("별점"),
  comment: z.string().describe("코멘트"),
});

// ✅ 없으면 null 이라고 명시적으로 알려준다
z.object({
  rating: z.number().min(1).max(5).nullable().describe("별점. 글에 없으면 null."),
  comment: z.string().nullable().describe("코멘트. 없으면 null."),
});

const Classification = z.object({
  // 근거를 먼저 쓰게 한다 (5-6 실무 팁 참고)
  reasoning: z.string().describe("이 분류를 택한 이유를 한 문장으로. 먼저 작성할 것."),
  label: z.enum(["bug", "feature", "question", "billing", "spam"]).describe("문의 유형. 다섯 중 정확히 하나."),
  confidence: z.number().min(0).max(1).describe("분류 확신도 0~1. 애매하면 0.5 미만을 쓸 것."),
});

const classifier = model.withStructuredOutput(Classification);
const r = await classifier.invoke("결제했는데 두 번 청구됐어요. 환불 부탁드립니다.");

if (r.confidence < 0.5) {
  // 사람 검토 큐로 보낸다
}

const Extraction = z.object({
  items: z.array(z.object({
    product: z.string().describe("상품명"),
    quantity: z.number().describe("수량. 명시 없으면 1."),
    unitPrice: z.number().nullable().describe("단가(원). 글에 없으면 null."),
  })).describe("주문서에 등장하는 모든 품목. 빠뜨리지 말 것."),
  orderer: z.string().nullable().describe("주문자 이름. 없으면 null."),
});

const order = "안녕하세요, 김민수입니다. 27인치 모니터 2대(대당 459,000원)랑 " +
              "무선 키보드 1개 주문하고 싶습니다. 키보드 가격은 잘 모르겠네요.";

const Route = z.object({
  destination: z.enum(["refund_agent", "tech_support", "sales", "human"])
    .describe("이 문의를 넘길 곳. 확신이 없으면 human."),
  priority: z.enum(["low", "normal", "urgent"]).describe("처리 우선순위"),
  summary: z.string().describe("담당자가 읽을 한 문장 요약"),
});

const decision = await model.withStructuredOutput(Route).invoke(
  "3주 전에 주문한 노트북이 아직 안 왔고 고객센터도 연결이 안 됩니다. 화가 많이 나네요.",
);

// enum 이라 switch 가 타입 안전하다 — default 없이도 모든 분기가 커버된다
switch (decision.destination) {
  case "refund_agent": /* ... */ break;
  case "tech_support": /* ... */ break;
  case "sales":        /* ... */ break;
  case "human":        /* ... */ break;
}

import { createAgent, tool, toolStrategy } from "langchain";
import * as z from "zod";

const checkStock = tool(
  async ({ product }: { product: string }) => {
    const db: Record<string, number> = {
      "27인치 4K 모니터": 12, "무선 키보드": 0, "게이밍 노트북": 3,
    };
    const qty = db[product];
    return qty === undefined ? `'${product}' 는 취급하지 않는 상품입니다.` : `'${product}' 재고: ${qty}개`;
  },
  {
    name: "check_stock",
    description: "상품명을 받아 현재 재고 수량을 조회한다. 상품 문의가 오면 반드시 먼저 호출할 것.",
    schema: z.object({ product: z.string().describe("정확한 상품명") }),
  },
);

const StockAnswer = z.object({
  available: z.array(z.string()).describe("재고가 1개 이상인 상품명 목록. 없으면 빈 배열."),
  unavailable: z.array(z.string()).describe("재고가 0이거나 취급하지 않는 상품명 목록. 없으면 빈 배열."),
  reply: z.string().describe("고객에게 보낼 한국어 답변. 2문장 이내, 존댓말."),
});

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [checkStock],
  systemPrompt:
    "너는 재고 문의를 처리하는 상담원이다. 재고는 반드시 check_stock 도구로 확인하고, " +
    "추측하지 마라. 확인이 끝나면 구조화된 형식으로 답하라.",
  responseFormat: toolStrategy(StockAnswer),   // ← 도구가 있으면 toolStrategy 가 안전
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "27인치 4K 모니터랑 무선 키보드, 그리고 사무용 의자 재고 있나요?" }],
});

console.log(result.messages.map(m => m.getType()));
console.log(result.structuredResponse);

const { available, unavailable, reply } = result.structuredResponse;
// available: string[], unavailable: string[], reply: string — 전부 TypeScript 가 안다

/**
 * Step 05 — 구조화된 출력 (zod)
 * 실행: npx tsx docs/reference/langchain/step-05-structured-output/practice.ts
 *
 * 본문 5-1 ~ 5-9 의 예제를 순서대로 담았습니다.
 * 블록 주석 [5-N] 번호가 교재 소제목과 1:1 대응합니다.
 *
 * 준비물: .env 에 ANTHROPIC_API_KEY=sk-ant-...
 *   (OpenAI 로 바꾸려면 MODEL 상수를 "openai:gpt-5.5" 로, OPENAI_API_KEY 를 설정)
 */
import "dotenv/config";
import * as z from "zod";
import {
  createAgent,
  initChatModel,
  toolStrategy,
  providerStrategy,
  tool,
} from "langchain";
import type { AIMessage } from "@langchain/core/messages";

/** 이 파일 전체가 쓰는 기본 모델. OpenAI 대안: "openai:gpt-5.5" */
const MODEL = "anthropic:claude-sonnet-4-6";

/** 결과를 보기 좋게 찍는 로컬 헬퍼 (외부 의존 없음) */
function show(label: string, value: unknown): void {
  console.log(`\n=== ${label} ===`);
  console.dir(value, { depth: null });
}

/* ===== [5-1] 왜 구조화 출력인가 — 자유 텍스트 파싱의 지옥 ===== */

async function step5_1(): Promise<void> {
  const model = await initChatModel(MODEL);

  // (A) 구조화 없이: 모델은 "말"을 한다. 우리는 그 말을 파싱해야 한다.
  const raw = await model.invoke(
    "다음 리뷰의 별점(1~5)과 감정을 알려줘: '배송은 빨랐는데 가격이 너무 비싸요. 그래도 품질은 만족.'",
  );
  show("[5-1] 자유 텍스트 응답", raw.content);

  // 이 텍스트에서 별점을 뽑으려면 결국 이런 코드를 쓰게 됩니다.
  const text = typeof raw.content === "string" ? raw.content : JSON.stringify(raw.content);
  const guessed = text.match(/([1-5])\s*(?:점|\/\s*5|stars?)/)?.[1];
  show("[5-1] 정규식으로 긁어낸 별점 (신뢰할 수 없음)", guessed ?? "파싱 실패");

  // 문제: 모델이 "다섯 점" 이라고 쓰면? "★★★★☆" 로 쓰면? 영어로 답하면?
  // 정규식은 프롬프트가 바뀔 때마다 깨집니다. 그래서 구조화 출력이 필요합니다.

  // (B) 구조화 출력: 모델이 스키마에 맞는 객체를 준다.
  const Review = z.object({
    rating: z.number().min(1).max(5).describe("별점 1~5"),
    sentiment: z.enum(["positive", "negative", "neutral"]).describe("전체 감정"),
  });

  const structured = await model.withStructuredOutput(Review).invoke(
    "다음 리뷰를 분석해: '배송은 빨랐는데 가격이 너무 비싸요. 그래도 품질은 만족.'",
  );
  show("[5-1] 구조화 응답 (파싱 불필요)", structured);
  // structured.rating 은 number 타입. TypeScript 가 알고 있습니다.
}

/* ===== [5-2] zod 스키마 기초 — 에이전트 개발자에게 필요한 만큼 ===== */

function step5_2(): void {
  // 에이전트 스키마에서 실제로 쓰는 건 이 정도가 전부입니다.
  const Ticket = z.object({
    // string / number — 가장 기본
    title: z.string().describe("티켓 제목. 한 문장, 40자 이내."),
    priority: z.number().min(1).max(5).describe("우선순위. 1=가장 급함, 5=여유."),

    // enum — 모델의 선택지를 강제한다. 분류 작업의 핵심.
    category: z
      .enum(["bug", "feature", "question", "billing"])
      .describe("티켓 분류. 넷 중 하나만."),

    // array — 개수 제한도 걸 수 있다
    tags: z.array(z.string()).max(3).describe("검색용 태그. 소문자, 1~2단어."),

    // optional — "키가 없어도 된다" (undefined 허용)
    assignee: z.string().optional().describe("담당자 이름. 글에 없으면 생략."),

    // nullable — "키는 있는데 값이 null 이어도 된다"
    dueDate: z
      .string()
      .nullable()
      .describe("마감일 YYYY-MM-DD. 글에 없으면 반드시 null."),

    // 중첩 객체 — 얕게 유지할 것 (5-2 함정 참고)
    reporter: z
      .object({
        name: z.string().describe("신고자 이름"),
        email: z.string().describe("신고자 이메일. 없으면 빈 문자열."),
      })
      .describe("신고자 정보"),
  });

  // zod 스키마는 런타임 검증기이자 TypeScript 타입입니다.
  type Ticket = z.infer<typeof Ticket>;

  // 모델 없이도 로컬에서 바로 검증해볼 수 있습니다 — 스키마 개발 시 필수 습관.
  const ok: Ticket = {
    title: "로그인 버튼이 안 눌림",
    priority: 1,
    category: "bug",
    tags: ["login", "ui"],
    dueDate: null,
    reporter: { name: "김민수", email: "kim@example.com" },
    // assignee 는 optional 이라 생략 가능
  };
  show("[5-2] safeParse 성공", Ticket.safeParse(ok).success);

  // 일부러 틀린 값 — 모델이 이런 걸 뱉었을 때 무슨 에러가 나는지 미리 봅니다.
  const bad = { ...ok, priority: 9, category: "urgent" };
  const result = Ticket.safeParse(bad);
  show(
    "[5-2] safeParse 실패 이슈",
    result.success ? null : result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`),
  );

  // optional vs nullable 의 실제 차이 (provider 별 동작 차이는 본문 함정 참고)
  const Opt = z.object({ v: z.string().optional() });
  const Nul = z.object({ v: z.string().nullable() });
  show("[5-2] optional: 키 생략 OK", Opt.safeParse({}).success); // true
  show("[5-2] optional: null 은 거부", Opt.safeParse({ v: null }).success); // false
  show("[5-2] nullable: 키 생략은 거부", Nul.safeParse({}).success); // false
  show("[5-2] nullable: null 은 OK", Nul.safeParse({ v: null }).success); // true
}

/* ===== [5-3] .withStructuredOutput(schema) — 모델 레벨 ===== */

async function step5_3(): Promise<void> {
  const model = await initChatModel(MODEL);

  const Movie = z.object({
    title: z.string().describe("영화 제목"),
    year: z.number().describe("개봉 연도"),
    director: z.string().describe("감독 이름"),
    rating: z.number().describe("10점 만점 평점"),
  });

  // withStructuredOutput 은 "구조화된 응답을 주는 새 모델"을 반환합니다. 원본은 안 변합니다.
  const modelWithStructure = model.withStructuredOutput(Movie);
  const response = await modelWithStructure.invoke("영화 인셉션의 정보를 알려줘");
  show("[5-3] withStructuredOutput 결과", response);

  // includeRaw: true → { parsed, raw } 로 받습니다. 토큰 사용량·중단 사유가 필요할 때.
  const withRaw = model.withStructuredOutput(Movie, { includeRaw: true });
  const both = await withRaw.invoke("영화 매트릭스의 정보를 알려줘");
  show("[5-3] includeRaw.parsed", both.parsed);

  // 주의: raw 의 타입은 AIMessage 가 아니라 BaseMessage 입니다.
  // usage_metadata 는 AIMessage 에만 있으므로 좁혀서 써야 합니다 (본문 5-3 함정 참고).
  const raw = both.raw as AIMessage;
  show("[5-3] includeRaw.raw 의 토큰 사용량", raw.usage_metadata);

  // method 로 구현 방식을 고를 수 있습니다: "jsonSchema" | "functionCalling" | "jsonMode"
  // (지원 여부는 provider 마다 다릅니다 — 본문 5-5 표 참고)
  const viaJsonSchema = model.withStructuredOutput(Movie, { method: "jsonSchema" });
  show("[5-3] method: jsonSchema", await viaJsonSchema.invoke("영화 기생충의 정보를 알려줘"));
}

/* ===== [5-4] createAgent({ responseFormat }) → result.structuredResponse ===== */

async function step5_4(): Promise<void> {
  const ContactInfo = z.object({
    name: z.string().describe("사람 이름"),
    email: z.string().describe("이메일 주소"),
    phone: z.string().describe("전화번호"),
  });

  // 스키마를 그대로 넘기면 LangChain 이 전략을 자동 선택합니다.
  const agent = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: ContactInfo,
  });

  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content: "다음에서 연락처를 추출해: John Doe, john@example.com, (555) 123-4567",
      },
    ],
  });

  // 에이전트는 messages 와 structuredResponse 를 함께 돌려줍니다.
  show("[5-4] structuredResponse", result.structuredResponse);
  show("[5-4] messages 개수", result.messages.length);
  show("[5-4] 마지막 메시지 role", result.messages.at(-1)?.getType());
}

/* ===== [5-5] 전략 비교 — toolStrategy vs providerStrategy ===== */

async function step5_5(): Promise<void> {
  const ProductReview = z.object({
    rating: z.number().min(1).max(5).optional(),
    sentiment: z.enum(["positive", "negative"]),
    keyPoints: z.array(z.string()).describe("리뷰의 핵심 포인트. 소문자, 1~3단어."),
  });

  const question = {
    role: "user" as const,
    content: "이 리뷰를 분석해: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'",
  };

  // (A) providerStrategy — provider 가 API 레벨에서 스키마를 강제. 신뢰도 높음.
  const providerAgent = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: providerStrategy(ProductReview),
  });
  const a = await providerAgent.invoke({ messages: [question] });
  show("[5-5] providerStrategy", a.structuredResponse);

  // (B) toolStrategy — "스키마 모양의 도구"를 하나 더 만들어 모델이 호출하게 함.
  //     도구 호출을 지원하는 모든 모델에서 동작. 재시도 제어가 가능한 게 장점.
  const toolAgent = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(ProductReview),
  });
  const b = await toolAgent.invoke({ messages: [question] });
  show("[5-5] toolStrategy", b.structuredResponse);

  // toolStrategy 는 메시지 흐름에 tool 메시지가 남습니다 — 그게 providerStrategy 와의 관찰 가능한 차이.
  show(
    "[5-5] toolStrategy 의 메시지 타입 흐름",
    b.messages.map((m) => m.getType()),
  );
  show(
    "[5-5] providerStrategy 의 메시지 타입 흐름",
    a.messages.map((m) => m.getType()),
  );

  // (C) toolStrategy 만 되는 것: 여러 스키마 중 택1 (union 처럼 동작)
  const CustomerComplaint = z.object({
    issueType: z.enum(["product", "service", "shipping", "billing"]),
    severity: z.enum(["low", "medium", "high"]),
    description: z.string().describe("불만 사항 요약"),
  });

  const unionAgent = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy([ProductReview, CustomerComplaint]),
  });
  const c = await unionAgent.invoke({
    messages: [{ role: "user", content: "배송이 3주째 안 와요. 환불해주세요." }],
  });
  show("[5-5] 스키마 배열 → 모델이 택1", c.structuredResponse);
}

/* ===== [5-6] .describe() 가 곧 프롬프트다 ===== */

async function step5_6(): Promise<void> {
  const article =
    "지난 분기 매출은 전년 대비 23% 성장했으나, 마케팅 비용이 40% 늘어 영업이익률은 " +
    "오히려 2%p 하락했다. CFO 박정현은 하반기 비용 통제를 예고했다.";

  // (A) describe 없음 — 모델이 필드 이름만 보고 "추측"한다.
  const Vague = z.object({
    summary: z.string(),
    metric: z.string(),
    person: z.string(),
  });

  // (B) describe 있음 — 필드마다 정확히 무엇을 원하는지 지시한다.
  const Precise = z.object({
    summary: z
      .string()
      .describe("기사 핵심을 한 문장(60자 이내)으로. 숫자를 반드시 포함할 것."),
    metric: z
      .string()
      .describe(
        "기사에서 가장 중요한 단일 지표를 '이름: 값' 형식으로. 예) '영업이익률: -2%p'",
      ),
    person: z
      .string()
      .describe("기사에 등장하는 인물의 이름만. 직함 제외. 없으면 빈 문자열."),
  });

  const model = await initChatModel(MODEL);
  const prompt = `다음 기사를 분석해:\n${article}`;

  show("[5-6] describe 없음", await model.withStructuredOutput(Vague).invoke(prompt));
  show("[5-6] describe 있음", await model.withStructuredOutput(Precise).invoke(prompt));

  // 같은 모델, 같은 기사, 같은 필드 이름. 다른 건 .describe() 뿐입니다.
  // (A)의 person 은 "CFO 박정현" 처럼 직함이 섞여 나오기 쉽고,
  // (B)는 "박정현" 만 나옵니다. 필드 설명이 곧 프롬프트라는 뜻입니다.
}

/* ===== [5-7] 검증 실패 처리 — 재시도, 부분 실패 ===== */

async function step5_7(): Promise<void> {
  const ProductRating = z.object({
    rating: z.number().min(1).max(5).describe("1~5 사이 별점"),
    comment: z.string().describe("리뷰 코멘트"),
  });

  // (A) 기본값(handleError: true) — 검증 실패 시 에러를 tool 메시지로 돌려주고 자동 재시도.
  //     "10/10!" 은 rating=10 을 유도하지만 max(5) 에 걸립니다. 그래도 최종 결과는 나옵니다.
  const autoRetry = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(ProductRating),
  });
  const r1 = await autoRetry.invoke({
    messages: [{ role: "user", content: "이걸 파싱해: Amazing product, 10/10!" }],
  });
  show("[5-7] 자동 재시도 후 결과", r1.structuredResponse);
  show(
    "[5-7] 재시도 흔적 (tool 메시지에 에러가 남는다)",
    r1.messages.map((m) => `${m.getType()}: ${String(m.content).slice(0, 80)}`),
  );

  // (B) 커스텀 에러 메시지 — 모델에게 무엇을 고쳐야 하는지 직접 알려준다.
  const customMsg = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(ProductRating, {
      handleError:
        "rating 은 반드시 1~5 사이 정수여야 합니다. 10점 만점 표기는 5점 만점으로 환산하세요.",
    }),
  });
  const r2 = await customMsg.invoke({
    messages: [{ role: "user", content: "이걸 파싱해: Amazing product, 10/10!" }],
  });
  show("[5-7] 커스텀 에러 메시지 후 결과", r2.structuredResponse);

  // (C) handleError: false — 재시도하지 않고 예외를 그대로 던진다.
  //     "조용한 잘못된 성공"보다 "시끄러운 실패"가 나은 배치/파이프라인에서 씁니다.
  const strict = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(ProductRating, { handleError: false }),
  });
  try {
    const r3 = await strict.invoke({
      messages: [{ role: "user", content: "이걸 파싱해: Amazing product, 10/10!" }],
    });
    show("[5-7] handleError:false — 이번엔 한 번에 성공", r3.structuredResponse);
  } catch (error) {
    show("[5-7] handleError:false — 예외 발생", (error as Error).message.slice(0, 200));
  }

  // (D) toolMessageContent — 재시도가 아니라 "성공했을 때" 대화에 남는 문구를 바꾼다.
  const MeetingAction = z.object({
    task: z.string().describe("완료해야 할 구체적 작업"),
    assignee: z.string().describe("담당자"),
    priority: z.enum(["low", "medium", "high"]).describe("우선순위"),
  });
  const withMessage = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(MeetingAction, {
      toolMessageContent: "액션 아이템을 회의록에 기록했습니다!",
    }),
  });
  const r4 = await withMessage.invoke({
    messages: [
      { role: "user", content: "회의 내용: 사라가 프로젝트 일정을 최대한 빨리 업데이트해야 함" },
    ],
  });
  show("[5-7] toolMessageContent 적용", {
    structuredResponse: r4.structuredResponse,
    lastToolMessage: r4.messages.find((m) => m.getType() === "tool")?.content,
  });

  // (E) 부분 실패 방어 — 모든 필드를 필수로 두지 말고, 모르면 null 을 쓰게 한다.
  const Lenient = z.object({
    rating: z.number().min(1).max(5).nullable().describe("별점. 글에 없으면 null."),
    comment: z.string().nullable().describe("코멘트. 없으면 null."),
  });
  const lenient = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(Lenient),
  });
  const r5 = await lenient.invoke({
    messages: [{ role: "user", content: "이걸 파싱해: (내용 없음)" }],
  });
  show("[5-7] 관대한 스키마 — 억지 환각 대신 null", r5.structuredResponse);
}

/* ===== [5-8] 실전 패턴 — 분류, 추출, 라우팅 ===== */

async function step5_8(): Promise<void> {
  const model = await initChatModel(MODEL);

  // 패턴 1: 분류(classification) — enum + 근거 + 확신도
  const Classification = z.object({
    // 근거를 먼저 쓰게 하면 정확도가 올라갑니다. 필드 순서가 곧 사고 순서입니다.
    reasoning: z.string().describe("이 분류를 택한 이유를 한 문장으로. 먼저 작성할 것."),
    label: z
      .enum(["bug", "feature", "question", "billing", "spam"])
      .describe("문의 유형. 다섯 중 정확히 하나."),
    confidence: z
      .number()
      .min(0)
      .max(1)
      .describe("분류 확신도 0~1. 애매하면 0.5 미만을 쓸 것."),
  });

  const classifier = model.withStructuredOutput(Classification);
  const inquiries = [
    "결제했는데 두 번 청구됐어요. 환불 부탁드립니다.",
    "다크 모드 지원 계획 있나요?",
    "앱이 실행하자마자 흰 화면에서 멈춥니다.",
  ];
  for (const text of inquiries) {
    show(`[5-8] 분류: "${text.slice(0, 20)}..."`, await classifier.invoke(text));
  }

  // 패턴 2: 추출(extraction) — 비정형 텍스트 → 배열 레코드
  const Extraction = z.object({
    items: z
      .array(
        z.object({
          product: z.string().describe("상품명"),
          quantity: z.number().describe("수량. 명시 없으면 1."),
          unitPrice: z.number().nullable().describe("단가(원). 글에 없으면 null."),
        }),
      )
      .describe("주문서에 등장하는 모든 품목. 빠뜨리지 말 것."),
    orderer: z.string().nullable().describe("주문자 이름. 없으면 null."),
  });

  const order =
    "안녕하세요, 김민수입니다. 27인치 모니터 2대(대당 459,000원)랑 " +
    "무선 키보드 1개 주문하고 싶습니다. 키보드 가격은 잘 모르겠네요.";
  show("[5-8] 추출", await model.withStructuredOutput(Extraction).invoke(order));

  // 패턴 3: 라우팅(routing) — 구조화 출력으로 다음 행동을 고른다
  const Route = z.object({
    destination: z
      .enum(["refund_agent", "tech_support", "sales", "human"])
      .describe("이 문의를 넘길 곳. 확신이 없으면 human."),
    priority: z.enum(["low", "normal", "urgent"]).describe("처리 우선순위"),
    summary: z.string().describe("담당자가 읽을 한 문장 요약"),
  });

  const router = model.withStructuredOutput(Route);
  const decision = await router.invoke(
    "3주 전에 주문한 노트북이 아직 안 왔고 고객센터도 연결이 안 됩니다. 화가 많이 나네요.",
  );
  show("[5-8] 라우팅 결정", decision);

  // 라우팅 결과는 그냥 문자열이 아니라 union 타입이라, switch 가 안전합니다.
  switch (decision.destination) {
    case "refund_agent":
      console.log("→ 환불 담당 에이전트 호출");
      break;
    case "tech_support":
      console.log("→ 기술 지원 에이전트 호출");
      break;
    case "sales":
      console.log("→ 영업 에이전트 호출");
      break;
    case "human":
      console.log("→ 사람에게 에스컬레이션");
      break;
  }
}

/* ===== [5-9] 종합 — 도구 + 구조화 출력을 함께 쓰는 에이전트 ===== */

async function step5_9(): Promise<void> {
  // 사내 재고를 조회하는 가짜 도구
  const checkStock = tool(
    async ({ product }: { product: string }) => {
      const db: Record<string, number> = {
        "27인치 4K 모니터": 12,
        "무선 키보드": 0,
        "게이밍 노트북": 3,
      };
      const qty = db[product];
      return qty === undefined
        ? `'${product}' 는 취급하지 않는 상품입니다.`
        : `'${product}' 재고: ${qty}개`;
    },
    {
      name: "check_stock",
      description: "상품명을 받아 현재 재고 수량을 조회한다. 상품 문의가 오면 반드시 먼저 호출할 것.",
      schema: z.object({ product: z.string().describe("정확한 상품명") }),
    },
  );

  // 도구를 여러 번 호출한 뒤, 최종 답변만 구조화해서 받습니다.
  const StockAnswer = z.object({
    available: z
      .array(z.string())
      .describe("재고가 1개 이상인 상품명 목록. 없으면 빈 배열."),
    unavailable: z
      .array(z.string())
      .describe("재고가 0이거나 취급하지 않는 상품명 목록. 없으면 빈 배열."),
    reply: z.string().describe("고객에게 보낼 한국어 답변. 2문장 이내, 존댓말."),
  });

  const agent = createAgent({
    model: MODEL,
    tools: [checkStock],
    systemPrompt:
      "너는 재고 문의를 처리하는 상담원이다. 재고는 반드시 check_stock 도구로 확인하고, " +
      "추측하지 마라. 확인이 끝나면 구조화된 형식으로 답하라.",
    // 도구를 쓰는 에이전트에서는 toolStrategy 가 안전한 기본값입니다 (본문 5-9 함정 참고).
    responseFormat: toolStrategy(StockAnswer),
  });

  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content: "27인치 4K 모니터랑 무선 키보드, 그리고 사무용 의자 재고 있나요?",
      },
    ],
  });

  show("[5-9] 도구 호출 흐름", result.messages.map((m) => m.getType()));
  show("[5-9] 최종 구조화 응답", result.structuredResponse);

  // 타입이 살아있으므로 후속 로직을 안전하게 이어붙일 수 있습니다.
  const { available, unavailable, reply } = result.structuredResponse;
  console.log(`\n재고 있음 ${available.length}건 / 재고 없음 ${unavailable.length}건`);
  console.log(`고객 답변: ${reply}`);
}

/* ===== 실행 ===== */

async function main(): Promise<void> {
  await step5_1();
  step5_2(); // 이 절만 모델 호출이 없습니다 (API 키 없이도 실행됨)
  await step5_3();
  await step5_4();
  await step5_5();
  await step5_6();
  await step5_7();
  await step5_8();
  await step5_9();
}

main().catch((error) => {
  console.error("실행 실패:", error);
  process.exitCode = 1;
});

/**
 * Step 05 — 구조화된 출력 (zod) · 연습문제
 * 실행: npx tsx docs/reference/langchain/step-05-structured-output/exercise.ts
 *
 * 각 [문제 N] 블록 아래를 직접 채우세요.
 * 그대로 실행하면 아무것도 출력되지 않습니다 (정상입니다 — main() 의 주석을 풀면서 진행하세요).
 * 정답은 solution.ts 에 있습니다. 먼저 스스로 풀어보세요.
 */
import "dotenv/config";
import * as z from "zod";
import {
  createAgent,
  initChatModel,
  toolStrategy,
  providerStrategy,
  tool,
} from "langchain";

const MODEL = "anthropic:claude-sonnet-4-6";

function show(label: string, value: unknown): void {
  console.log(`\n=== ${label} ===`);
  console.dir(value, { depth: null });
}

/* ===== [문제 1] optional vs nullable 을 몸으로 익히기 =====
 *
 * 아래 요구사항을 만족하는 zod 스키마 `Profile` 을 만드세요.
 *   - name    : 문자열, 필수
 *   - nickname: 문자열, "키 자체가 없어도 됨"
 *   - bio     : 문자열, "키는 반드시 있어야 하지만 값이 null 이어도 됨"
 *
 * 그리고 아래 4가지 입력에 대해 safeParse 결과(true/false)를 출력하세요.
 *   (a) { name: "김민수" }
 *   (b) { name: "김민수", nickname: null }
 *   (c) { name: "김민수", bio: null }
 *   (d) { name: "김민수", bio: null, nickname: "민수" }
 *
 * 어느 것이 왜 실패하는지 주석으로 적으세요.
 */
function exercise1(): void {
  // 여기에 작성
}

/* ===== [문제 2] 자유 텍스트 파싱을 구조화 출력으로 대체하기 =====
 *
 * 아래 `receipt` 문자열에서 다음을 추출하는 스키마를 만들고
 * model.withStructuredOutput() 으로 뽑아내세요.
 *   - storeName: 상점 이름
 *   - total    : 총액 (숫자, 원 단위)
 *   - date     : YYYY-MM-DD 형식 문자열
 *   - items    : { name, price } 배열
 *
 * 모든 필드에 .describe() 를 반드시 붙이세요.
 */
async function exercise2(): Promise<void> {
  const receipt = `
    스타벅스 강남점
    2026-07-15 14:32
    아메리카노(T)      4,500
    카페라떼(G)        5,900
    치즈케이크         6,500
    ------------------------
    합계              16,900
  `;
  // 여기에 작성
}

/* ===== [문제 3] .describe() 가 정확도를 바꾸는 걸 직접 확인하기 =====
 *
 * 같은 필드 이름으로 스키마 두 개를 만드세요.
 *   (A) describe 없음:  z.object({ company: z.string(), amount: z.string() })
 *   (B) describe 있음:  company 는 "회사 이름만. 법인격(주식회사/(주)/Inc.) 제외."
 *                       amount 는 "금액을 숫자와 단위만. 예) '350억원'"
 *
 * 아래 news 로 둘 다 호출해 결과를 나란히 출력하고,
 * 무엇이 달라졌는지 주석으로 적으세요.
 */
async function exercise3(): Promise<void> {
  const news =
    "주식회사 넥스트테크는 시리즈B 라운드에서 총 350억원 규모의 투자를 유치했다고 밝혔다.";
  // 여기에 작성
}

/* ===== [문제 4] providerStrategy 와 toolStrategy 의 메시지 흐름 비교 =====
 *
 * 같은 스키마·같은 질문으로 에이전트 두 개를 만드세요.
 *   (A) responseFormat: providerStrategy(Schema)
 *   (B) responseFormat: toolStrategy(Schema)
 *
 * 각각 invoke 한 뒤 result.messages.map(m => m.getType()) 을 출력해
 * 두 전략의 메시지 흐름 차이를 관찰하고 주석으로 설명하세요.
 * (힌트: 한쪽에만 "tool" 이 등장합니다. 왜일까요?)
 */
async function exercise4(): Promise<void> {
  const Sentiment = z.object({
    label: z.enum(["positive", "negative", "neutral"]).describe("감정"),
    score: z.number().min(-1).max(1).describe("-1(부정) ~ 1(긍정)"),
  });
  const question = "이 문장의 감정을 분석해: '기대했던 것보단 별로였지만 못 쓸 정도는 아니에요.'";
  // 여기에 작성
}

/* ===== [문제 5] 검증 실패를 일부러 유발하고 재시도 관찰하기 =====
 *
 * `z.number().min(1).max(5)` 인 rating 필드를 가진 스키마를 만들고,
 * "이 제품 100점 만점에 200점!" 같은 입력으로 검증 실패를 유도하세요.
 *
 * (a) 기본 handleError(=true) 로 실행 → 최종 structuredResponse 와
 *     messages 안에 남은 에러 tool 메시지를 출력하세요.
 * (b) handleError: false 로 실행 → try/catch 로 감싸 예외를 잡아 출력하세요.
 * (c) 커스텀 문자열 handleError 로 실행 → 결과를 출력하세요.
 *
 * 셋의 차이를 주석으로 정리하세요.
 */
async function exercise5(): Promise<void> {
  // 여기에 작성
}

/* ===== [문제 6] 분류기 만들기 — enum + reasoning + confidence =====
 *
 * 고객 문의를 ["bug", "feature", "question", "billing", "spam"] 중 하나로 분류하는
 * 스키마를 만드세요. 단 다음 조건을 지키세요.
 *   - reasoning 필드를 label 보다 "먼저" 선언할 것 (왜 그래야 할까요?)
 *   - confidence 는 0~1 사이 number
 *   - label 은 enum
 *
 * 아래 3개 문의를 모두 분류해 출력하세요.
 */
async function exercise6(): Promise<void> {
  const inquiries = [
    "비밀번호 재설정 메일이 안 옵니다.",
    "🔥🔥 지금 클릭하면 아이폰 무료 증정 🔥🔥 http://spam.example.com",
    "엑셀 내보내기 기능도 추가해주실 수 있나요?",
  ];
  // 여기에 작성
}

/* ===== [문제 7] 중첩 깊이의 함정 확인하기 =====
 *
 * 같은 정보를 담되 구조가 다른 스키마 두 개를 만드세요.
 *   (A) 깊게 중첩:
 *       { order: { customer: { profile: { name, tier } }, payment: { method, amount } } }
 *   (B) 평평하게:
 *       { customerName, customerTier, paymentMethod, paymentAmount }
 *
 * 아래 텍스트로 둘 다 호출해 결과를 비교하고,
 * 어느 쪽이 더 안정적인지 주석으로 적으세요.
 */
async function exercise7(): Promise<void> {
  const text =
    "VIP 고객 이수진님이 신용카드로 129,000원을 결제했습니다.";
  // 여기에 작성
}

/* ===== [문제 8] 도구 + 구조화 출력을 함께 쓰는 라우팅 에이전트 =====
 *
 * (a) 주문번호를 받아 배송 상태를 돌려주는 가짜 도구 `lookup_order` 를 만드세요.
 *     (예: "ORD-1001" → "배송중, 예상 도착 2026-07-19")
 * (b) 그 도구를 쓰는 에이전트를 만들고, 최종 답변을 아래 스키마로 구조화하세요.
 *       - destination: enum(["refund_agent", "tech_support", "sales", "human"])
 *       - priority   : enum(["low", "normal", "urgent"])
 *       - summary    : 담당자가 읽을 한 문장 요약
 * (c) "ORD-1001 주문이 3주째 안 오는데 환불해주세요" 로 실행하고,
 *     messages 의 타입 흐름과 structuredResponse 를 함께 출력하세요.
 * (d) destination 값으로 switch 문을 써서 각 분기를 console.log 하세요.
 *     (힌트: enum 이라 switch 가 타입 안전합니다)
 */
async function exercise8(): Promise<void> {
  // 여기에 작성
}

async function main(): Promise<void> {
  // 푼 문제부터 하나씩 주석을 푸세요.
  // exercise1();
  // await exercise2();
  // await exercise3();
  // await exercise4();
  // await exercise5();
  // await exercise6();
  // await exercise7();
  // await exercise8();
}

main().catch((error) => {
  console.error("실행 실패:", error);
  process.exitCode = 1;
});

/**
 * Step 05 — 구조화된 출력 (zod) · 정답과 해설
 * 실행: npx tsx docs/reference/langchain/step-05-structured-output/solution.ts
 *
 * exercise.ts 를 스스로 풀어본 뒤에 열어보세요.
 * 각 정답 위 주석에 채점 포인트와 함정이 적혀 있습니다.
 */
import "dotenv/config";
import * as z from "zod";
import {
  createAgent,
  initChatModel,
  toolStrategy,
  providerStrategy,
  tool,
} from "langchain";

const MODEL = "anthropic:claude-sonnet-4-6";

function show(label: string, value: unknown): void {
  console.log(`\n=== ${label} ===`);
  console.dir(value, { depth: null });
}

/* ===== [정답 1] optional vs nullable =====
 *
 * 채점 포인트: 둘은 대체재가 아니라 서로 다른 축을 다룹니다.
 *   .optional() = 키가 없어도 됨 (undefined 허용, null 은 거부)
 *   .nullable() = 값이 null 이어도 됨 (키는 필수, 생략은 거부)
 *
 * 결과 (zod 4.4.3 실측): (a) false / (b) false / (c) true / (d) true
 *   (a) 가 실패하는 이유: bio 는 .nullable() 이므로 키가 "필수"입니다.
 *       nullable 은 값에 null 을 허용할 뿐, 키를 생략해도 된다는 뜻이 아닙니다.
 *       → "bio: Invalid input: expected string, received undefined"
 *   (b) 가 실패하는 이유: 두 가지가 겹칩니다.
 *       nickname 은 .optional() 이라 undefined 는 되지만 null 은 거부되고,
 *       bio 키가 여전히 빠져 있습니다.
 *   (c),(d) 는 통과합니다.
 *
 * 한 줄 요약: optional 은 "키" 축, nullable 은 "값" 축입니다. 축이 다릅니다.
 * 둘 다 허용하려면 .nullish() (= .optional().nullable()) 를 씁니다.
 */
function solution1(): void {
  const Profile = z.object({
    name: z.string().describe("이름"),
    nickname: z.string().optional().describe("별명. 없으면 생략."),
    bio: z.string().nullable().describe("자기소개. 없으면 null."),
  });

  const cases: Array<[string, unknown]> = [
    ["(a) { name }", { name: "김민수" }],
    ["(b) { name, nickname: null }", { name: "김민수", nickname: null }],
    ["(c) { name, bio: null }", { name: "김민수", bio: null }],
    ["(d) 전부", { name: "김민수", bio: null, nickname: "민수" }],
  ];

  for (const [label, input] of cases) {
    const r = Profile.safeParse(input);
    show(`[정답 1] ${label}`, {
      success: r.success,
      issues: r.success ? undefined : r.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`),
    });
  }

  // 실무 결론: 에이전트 스키마에서는 "모르면 null" 이 "모르면 생략" 보다 낫습니다.
  // 모델은 키를 생략하는 것보다 null 을 쓰는 걸 훨씬 안정적으로 해냅니다.
}

/* ===== [정답 2] 영수증 추출 =====
 *
 * 채점 포인트:
 *   1) total 을 z.string() 이 아니라 z.number() 로 두었는가.
 *      문자열로 두면 "16,900원" 같은 값이 와서 결국 다시 파싱해야 합니다.
 *      숫자 타입이면 모델이 콤마와 단위를 알아서 떼줍니다.
 *   2) date 의 describe 에 "YYYY-MM-DD" 형식을 명시했는가.
 *      안 쓰면 "2026년 7월 15일", "07/15/2026" 등이 섞여 나옵니다.
 *   3) 영수증엔 시각(14:32)도 있지만 date 만 요구했으므로
 *      "시각은 제외" 를 describe 에 적어주면 더 안정적입니다.
 */
async function solution2(): Promise<void> {
  const receipt = `
    스타벅스 강남점
    2026-07-15 14:32
    아메리카노(T)      4,500
    카페라떼(G)        5,900
    치즈케이크         6,500
    ------------------------
    합계              16,900
  `;

  const Receipt = z.object({
    storeName: z.string().describe("상점 이름. 지점명 포함."),
    total: z.number().describe("총액. 원 단위 정수. 콤마와 '원' 없이 숫자만."),
    date: z.string().describe("결제 날짜 YYYY-MM-DD 형식. 시각은 제외."),
    items: z
      .array(
        z.object({
          name: z.string().describe("품목명. 괄호 안 사이즈 표기 포함."),
          price: z.number().describe("품목 가격. 원 단위 정수."),
        }),
      )
      .describe("영수증의 모든 품목. 합계 줄은 제외."),
  });

  const model = await initChatModel(MODEL);
  const result = await model.withStructuredOutput(Receipt).invoke(
    `다음 영수증에서 정보를 추출해:\n${receipt}`,
  );
  show("[정답 2] 영수증 추출", result);

  // 타입이 살아있으므로 바로 계산에 쓸 수 있습니다 — 이게 구조화 출력의 목적입니다.
  const sum = result.items.reduce((acc, item) => acc + item.price, 0);
  show("[정답 2] 검산 (품목 합 == total?)", { sum, total: result.total, match: sum === result.total });
}

/* ===== [정답 3] describe 유무 비교 =====
 *
 * 채점 포인트: 필드 이름만으로는 모델이 "무엇을 원하는지" 모릅니다.
 *   (A) company → "주식회사 넥스트테크" 또는 "넥스트테크" (매번 다름)
 *       amount  → "350억원 규모의 투자" 처럼 문장이 섞여 나오기 쉬움
 *   (B) company → "넥스트테크" (법인격 제거 지시가 먹힘)
 *       amount  → "350억원" (형식 예시가 먹힘)
 *
 * 핵심: .describe() 는 문서가 아니라 "그 필드에만 적용되는 프롬프트"입니다.
 * JSON Schema 의 description 으로 변환되어 실제로 모델에게 전달됩니다.
 */
async function solution3(): Promise<void> {
  const news =
    "주식회사 넥스트테크는 시리즈B 라운드에서 총 350억원 규모의 투자를 유치했다고 밝혔다.";

  const Vague = z.object({
    company: z.string(),
    amount: z.string(),
  });

  const Precise = z.object({
    company: z.string().describe("회사 이름만. 법인격(주식회사/(주)/Inc.) 표기는 제외."),
    amount: z.string().describe("투자 금액을 숫자와 단위만. 예) '350억원'. 부연 설명 금지."),
  });

  const model = await initChatModel(MODEL);
  const prompt = `다음 뉴스에서 정보를 추출해:\n${news}`;

  show("[정답 3] (A) describe 없음", await model.withStructuredOutput(Vague).invoke(prompt));
  show("[정답 3] (B) describe 있음", await model.withStructuredOutput(Precise).invoke(prompt));

  // 모델 응답은 비결정적이라 (A)가 우연히 잘 나올 수도 있습니다.
  // 중요한 건 "우연에 기대는가"입니다. describe 는 그 우연을 제거합니다.
}

/* ===== [정답 4] 두 전략의 메시지 흐름 =====
 *
 * 채점 포인트:
 *   providerStrategy → ["human", "ai"]
 *     provider 가 API 레벨에서 스키마를 강제하므로 도구 호출이 발생하지 않습니다.
 *     대화 기록이 깨끗합니다.
 *   toolStrategy     → ["human", "ai", "tool"]
 *     "Sentiment 라는 이름의 가짜 도구"를 하나 만들어 모델이 그걸 호출하게 하고,
 *     그 인자를 파싱해 structuredResponse 로 돌려줍니다.
 *     그래서 ai(tool_calls) → tool 메시지가 대화에 남습니다.
 *
 * 이 차이가 중요한 이유: toolStrategy 의 tool 메시지는 다음 턴의 컨텍스트에
 * 그대로 쌓입니다. 멀티턴 대화에서 토큰을 먹고, 모델이 "아, 저 도구를 또 부르면 되는구나"
 * 하고 학습하기도 합니다. 반면 재시도 제어(handleError)는 toolStrategy 에만 있습니다.
 */
async function solution4(): Promise<void> {
  const Sentiment = z.object({
    label: z.enum(["positive", "negative", "neutral"]).describe("감정"),
    score: z.number().min(-1).max(1).describe("-1(부정) ~ 1(긍정)"),
  });
  const question = "이 문장의 감정을 분석해: '기대했던 것보단 별로였지만 못 쓸 정도는 아니에요.'";
  const messages = [{ role: "user" as const, content: question }];

  const providerAgent = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: providerStrategy(Sentiment),
  });
  const a = await providerAgent.invoke({ messages });
  show("[정답 4] providerStrategy", {
    flow: a.messages.map((m) => m.getType()),
    structuredResponse: a.structuredResponse,
  });

  const toolAgent = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(Sentiment),
  });
  const b = await toolAgent.invoke({ messages });
  show("[정답 4] toolStrategy", {
    flow: b.messages.map((m) => m.getType()),
    structuredResponse: b.structuredResponse,
  });
}

/* ===== [정답 5] 검증 실패와 재시도 =====
 *
 * 채점 포인트 — 셋의 차이:
 *   (a) handleError: true (기본값)
 *       검증 에러가 tool 메시지로 모델에게 되돌아가고, 모델이 스스로 고쳐서 재호출합니다.
 *       messages 에 "Error: Failed to parse structured output for tool ..." 이 남습니다.
 *       최종적으로는 rating: 5 같은 유효한 값이 나옵니다.
 *       → 이게 무섭습니다. 성공한 것처럼 보이지만 200점이 5점으로 "조용히 뭉개진" 겁니다.
 *   (b) handleError: false
 *       재시도 없이 예외가 그대로 올라옵니다. 배치 파이프라인에서는 이쪽이 옳습니다.
 *   (c) handleError: "문자열"
 *       기본 에러 템플릿 대신 내가 쓴 문장이 tool 메시지로 갑니다.
 *       "10점 만점은 5점 만점으로 환산하라" 같은 도메인 지식을 주입할 수 있습니다.
 */
async function solution5(): Promise<void> {
  const ProductRating = z.object({
    rating: z.number().min(1).max(5).describe("1~5 사이 별점"),
    comment: z.string().describe("리뷰 코멘트"),
  });
  const messages = [{ role: "user" as const, content: "이 제품 100점 만점에 200점! 최고예요." }];

  // (a) 기본 — 자동 재시도
  const auto = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(ProductRating),
  });
  const r1 = await auto.invoke({ messages });
  show("[정답 5-a] 자동 재시도", {
    structuredResponse: r1.structuredResponse,
    errorTraces: r1.messages
      .filter((m) => m.getType() === "tool" && String(m.content).startsWith("Error:"))
      .map((m) => String(m.content).slice(0, 120)),
  });

  // (b) 예외 전파
  const strict = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(ProductRating, { handleError: false }),
  });
  try {
    const r2 = await strict.invoke({ messages });
    show("[정답 5-b] 예외 없이 통과 (모델이 한 번에 맞힘)", r2.structuredResponse);
  } catch (error) {
    show("[정답 5-b] 예외 전파됨", (error as Error).message.slice(0, 200));
  }

  // (c) 커스텀 에러 메시지
  const custom = createAgent({
    model: MODEL,
    tools: [],
    responseFormat: toolStrategy(ProductRating, {
      handleError:
        "rating 은 1~5 사이여야 합니다. 100점 만점 점수는 20으로 나눠 5점 만점으로 환산하세요.",
    }),
  });
  const r3 = await custom.invoke({ messages });
  show("[정답 5-c] 커스텀 에러 메시지", r3.structuredResponse);
  // 200/20 = 10 → 여전히 5 초과. 모델은 다시 재시도해 5로 클램프합니다.
  // 교훈: 재시도로 못 고치는 입력이 있습니다. 그때는 스키마를 nullable 로 열어주는 게 답입니다.
}

/* ===== [정답 6] 분류기 =====
 *
 * 채점 포인트 — reasoning 을 label 보다 먼저 선언하는 이유:
 *   모델은 JSON 을 "위에서 아래로" 토큰 단위로 생성합니다.
 *   reasoning 이 먼저 오면 근거를 쓰면서 생각한 결과가 label 에 반영됩니다.
 *   label 이 먼저 오면 답을 먼저 뱉고 reasoning 은 그 답을 정당화하는 변명이 됩니다.
 *   (사고의 순서 = 필드의 순서. 스키마 설계에서 자주 놓치는 지점입니다.)
 *
 * 기대 결과: 비밀번호 메일 → bug 또는 question / 아이폰 무료 증정 → spam (confidence 높음)
 *            엑셀 내보내기 → feature
 */
async function solution6(): Promise<void> {
  const Classification = z.object({
    // 순서 중요: reasoning 이 label 보다 위에 있어야 합니다.
    reasoning: z.string().describe("이 분류를 택한 이유를 한 문장으로. 반드시 먼저 작성할 것."),
    label: z
      .enum(["bug", "feature", "question", "billing", "spam"])
      .describe("문의 유형. 다섯 중 정확히 하나."),
    confidence: z
      .number()
      .min(0)
      .max(1)
      .describe("분류 확신도 0~1. 두 카테고리 사이에서 애매하면 0.5 미만을 쓸 것."),
  });

  const model = await initChatModel(MODEL);
  const classifier = model.withStructuredOutput(Classification);

  const inquiries = [
    "비밀번호 재설정 메일이 안 옵니다.",
    "🔥🔥 지금 클릭하면 아이폰 무료 증정 🔥🔥 http://spam.example.com",
    "엑셀 내보내기 기능도 추가해주실 수 있나요?",
  ];

  for (const text of inquiries) {
    const r = await classifier.invoke(`다음 고객 문의를 분류해:\n${text}`);
    show(`[정답 6] "${text.slice(0, 18)}..."`, r);

    // confidence 를 실제로 쓰는 법: 낮으면 사람에게 넘긴다.
    if (r.confidence < 0.5) {
      console.log("  → 확신도 낮음. 사람 검토 큐로 보냅니다.");
    }
  }
}

/* ===== [정답 7] 중첩 깊이 =====
 *
 * 채점 포인트:
 *   (B) 평평한 스키마가 더 안정적입니다.
 *   깊게 중첩할수록 모델은 여는 중괄호와 닫는 중괄호를 짝 맞추는 데 토큰을 쓰고,
 *   "profile 안에 tier 였나, customer 바로 아래였나" 를 헷갈립니다.
 *   4단계쯤 되면 필드를 통째로 빠뜨리거나 엉뚱한 레벨에 넣는 일이 생깁니다.
 *
 *   실무 규칙: 중첩은 2단계까지. 그보다 깊어지면
 *     (1) 평평하게 펴서 접두사로 구분하거나 (customerName, paymentAmount)
 *     (2) 호출을 두 번으로 쪼개세요.
 *   호출 후 우리 코드에서 원하는 모양으로 재조립하는 게 훨씬 싸고 정확합니다.
 */
async function solution7(): Promise<void> {
  const text = "VIP 고객 이수진님이 신용카드로 129,000원을 결제했습니다.";

  // (A) 깊게 중첩 — 4단계
  const Deep = z.object({
    order: z.object({
      customer: z.object({
        profile: z.object({
          name: z.string().describe("고객 이름"),
          tier: z.enum(["VIP", "GOLD", "SILVER", "BRONZE"]).describe("고객 등급"),
        }),
      }),
      payment: z.object({
        method: z.enum(["card", "transfer", "cash"]).describe("결제 수단"),
        amount: z.number().describe("결제 금액. 원 단위 정수."),
      }),
    }),
  });

  // (B) 평평하게 — 1단계
  const Flat = z.object({
    customerName: z.string().describe("고객 이름"),
    customerTier: z.enum(["VIP", "GOLD", "SILVER", "BRONZE"]).describe("고객 등급"),
    paymentMethod: z.enum(["card", "transfer", "cash"]).describe("결제 수단"),
    paymentAmount: z.number().describe("결제 금액. 원 단위 정수."),
  });

  const model = await initChatModel(MODEL);
  const prompt = `다음에서 정보를 추출해:\n${text}`;

  const deep = await model.withStructuredOutput(Deep).invoke(prompt);
  show("[정답 7] (A) 4단계 중첩", deep);

  const flat = await model.withStructuredOutput(Flat).invoke(prompt);
  show("[정답 7] (B) 평평", flat);

  // 원하는 모양이 정말 중첩이라면, 평평하게 받아서 우리가 조립합니다.
  const assembled = {
    order: {
      customer: { profile: { name: flat.customerName, tier: flat.customerTier } },
      payment: { method: flat.paymentMethod, amount: flat.paymentAmount },
    },
  };
  show("[정답 7] (B)를 우리 코드에서 재조립 — 공짜이고 100% 정확", assembled);
}

/* ===== [정답 8] 도구 + 구조화 출력 라우팅 에이전트 =====
 *
 * 채점 포인트:
 *   1) responseFormat 을 toolStrategy 로 감쌌는가.
 *      도구가 있는 에이전트에서 providerStrategy 를 쓰면
 *      "도구 호출"과 "네이티브 구조화 출력"을 동시에 요구하게 되어
 *      provider 에 따라 도구를 무시하거나 에러가 납니다. (본문 5-9 함정)
 *   2) messages 흐름이 human → ai(tool_calls) → tool → ai(구조화) 로 가는가.
 *      도구 호출이 먼저 끝나고 나서 구조화 응답이 나옵니다.
 *   3) switch 가 타입 안전한가. enum 이라 default 없이도 모든 분기가 커버됩니다.
 *
 * 기대 결과: destination="refund_agent", priority="urgent"
 */
async function solution8(): Promise<void> {
  const lookupOrder = tool(
    async ({ orderId }: { orderId: string }) => {
      const db: Record<string, string> = {
        "ORD-1001": "배송중, 예상 도착 2026-07-19, 3주 지연됨",
        "ORD-1002": "배송완료 2026-07-10",
      };
      return db[orderId] ?? `주문번호 '${orderId}' 를 찾을 수 없습니다.`;
    },
    {
      name: "lookup_order",
      description:
        "주문번호(ORD-XXXX 형식)를 받아 현재 배송 상태를 조회한다. 주문 관련 문의는 반드시 먼저 호출할 것.",
      schema: z.object({ orderId: z.string().describe("주문번호. 예) ORD-1001") }),
    },
  );

  const Route = z.object({
    destination: z
      .enum(["refund_agent", "tech_support", "sales", "human"])
      .describe("이 문의를 넘길 곳. 확신이 없으면 human."),
    priority: z
      .enum(["low", "normal", "urgent"])
      .describe("처리 우선순위. 고객이 화가 났거나 지연이 2주 이상이면 urgent."),
    summary: z.string().describe("담당자가 읽을 한 문장 요약. 조회한 배송 상태를 반드시 포함."),
  });

  const agent = createAgent({
    model: MODEL,
    tools: [lookupOrder],
    systemPrompt:
      "너는 고객 문의를 적절한 담당자에게 배정하는 라우터다. " +
      "주문번호가 언급되면 반드시 lookup_order 로 실제 상태를 확인한 뒤 판단하라. 추측하지 마라.",
    responseFormat: toolStrategy(Route),
  });

  const result = await agent.invoke({
    messages: [{ role: "user", content: "ORD-1001 주문이 3주째 안 오는데 환불해주세요" }],
  });

  show("[정답 8] 메시지 흐름", result.messages.map((m) => m.getType()));
  show("[정답 8] 라우팅 결정", result.structuredResponse);

  const { destination, priority, summary } = result.structuredResponse;
  console.log(`\n[${priority.toUpperCase()}] ${summary}`);
  switch (destination) {
    case "refund_agent":
      console.log("→ 환불 담당 에이전트 호출");
      break;
    case "tech_support":
      console.log("→ 기술 지원 에이전트 호출");
      break;
    case "sales":
      console.log("→ 영업 에이전트 호출");
      break;
    case "human":
      console.log("→ 사람에게 에스컬레이션");
      break;
  }
}

async function main(): Promise<void> {
  solution1();
  await solution2();
  await solution3();
  await solution4();
  await solution5();
  await solution6();
  await solution7();
  await solution8();
}

main().catch((error) => {
  console.error("실행 실패:", error);
  process.exitCode = 1;
});