#Step 16 — 검색과 RAG

import { Document } from "@langchain/core/documents";

const doc = new Document({
  pageContent: "Nimbus 는 2019년에 설립되었습니다.",   // 임베딩되고 모델에게 보여질 본문
  metadata: { source: "company.md", title: "회사 소개" }, // 임베딩되지 않는 부가 정보
});

import { DirectoryLoader } from "@langchain/classic/document_loaders/fs/directory";
import { TextLoader } from "@langchain/classic/document_loaders/fs/text";

// 확장자별로 어떤 로더를 쓸지 매핑합니다.
const loader = new DirectoryLoader(kbDir, {
  ".md": (path) => new TextLoader(path),
});
const rawDocs = await loader.load();

import { readFileSync } from "node:fs";
import { Document } from "@langchain/core/documents";
import { PDFParse } from "pdf-parse";

async function loadPdfPages(filePath: string): Promise<Document[]> {
  const parser = new PDFParse({ data: new Uint8Array(readFileSync(filePath)) });
  try {
    const { pages } = await parser.getText();
    return pages.map(
      (page) =>
        new Document({
          pageContent: page.text,
          metadata: { source: filePath, page: page.num - 1 },  // ← 페이지 번호 보존
        }),
    );
  } finally {
    await parser.destroy();   // 반드시 해제
  }
}

import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";

const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 300,      // 청크 하나의 최대 길이(문자)
  chunkOverlap: 60,    // 이웃 청크끼리 겹칠 길이
});
const splits = await splitter.splitDocuments(rawDocs);

const refundPara =
  "Nimbus 클라우드의 유료 플랜은 결제일로부터 14일 이내에 환불을 요청할 수 있습니다. " +
  "환불은 요청 후 영업일 기준 5일 이내에 원결제 수단으로 처리됩니다. " +
  "단, 해당 기간에 누적 사용량이 무료 한도의 3배를 넘은 계정은 환불 대상에서 제외됩니다.";

const a = new RecursiveCharacterTextSplitter({ chunkSize: 60, chunkOverlap: 0 });
console.log(await a.splitText(refundPara));

const b = new RecursiveCharacterTextSplitter({ chunkSize: 60, chunkOverlap: 30 });

import { OpenAIEmbeddings } from "@langchain/openai";

const embeddings = new OpenAIEmbeddings({ model: "text-embedding-3-small" });

const vec = await embeddings.embedQuery("환불은 며칠 안에 되나요?");
console.log(vec.length);          // 1536

const small = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
  dimensions: 256,      // 1536 → 256
});

import { CohereEmbeddings } from "@langchain/cohere";           // multilingual 강함
import { VertexAIEmbeddings } from "@langchain/google-vertexai";
import { BedrockEmbeddings } from "@langchain/aws";
import { MistralAIEmbeddings } from "@langchain/mistralai";

import { MemoryVectorStore } from "@langchain/classic/vectorstores/memory";

// fromDocuments 가 내부에서 embedDocuments 를 호출합니다.
const vectorStore = await MemoryVectorStore.fromDocuments(splits, embeddings);

// 나중에 더 넣기
await vectorStore.addDocuments([handMade]);

// 바꾸는 건 이 두 줄뿐입니다.
import { PGVectorStore } from "@langchain/community/vectorstores/pgvector";
const vectorStore = await PGVectorStore.initialize(embeddings, { postgresConnectionOptions, tableName: "docs" });
// 아래 코드는 한 글자도 안 바뀝니다.

const hits = await vectorStore.similaritySearch("환불은 며칠 안에 되나요?", 2);

const scored = await vectorStore.similaritySearchWithScore("환불은 며칠 안에 되나요?", 4);
for (const [doc, score] of scored) {   // ← [Document, number] 튜플 배열
  console.log(score.toFixed(4), doc.metadata["source"]);
}

const offTopic = await vectorStore.similaritySearchWithScore("피자 굽는 온도는?", 2);

const retriever = vectorStore.asRetriever({ k: 3 });
const docs = await retriever.invoke("Pro 플랜 가격이 얼마인가요?");
await retriever.batch(["질문1", "질문2"]);   // 여러 개 한 번에

const mmrRetriever = vectorStore.asRetriever({
  searchType: "mmr",
  k: 3,                                    // 최종 반환 개수
  searchKwargs: { fetchK: 8, lambda: 0.5 }, // 후보 8개를 가져와 그중 3개를 고름
});

const filtered = scored.filter(([, s]) => s >= 0.3);

import { ScoreThresholdRetriever } from "@langchain/classic/retrievers/score_threshold";

const retriever = ScoreThresholdRetriever.fromVectorStore(vectorStore, {
  minSimilarityScore: 0.3,
  maxK: 5,
  kIncrement: 2,
});

async function classicRag(question: string): Promise<string> {
  // 1) 검색 — 무조건 합니다.
  const docs = await vectorStore.similaritySearch(question, 3);

  // 2) 프롬프트에 끼워넣기 — 출처를 함께 넣어야 인용을 시킬 수 있습니다.
  const context = docs
    .map((d, i) => `[${i + 1}] (출처: ${basename(String(d.metadata["source"]))})\n${d.pageContent}`)
    .join("\n\n");

  // 3) 생성
  const agent = createAgent({
    model: "anthropic:claude-sonnet-4-6",
    tools: [],
    systemPrompt: [
      "너는 Nimbus 클라우드의 고객 지원 담당자다.",
      "아래 <context> 안의 내용만 근거로 답하라.",
      "context 에 답이 없으면 반드시 '제공된 문서에서 찾을 수 없습니다'라고 답하라. 추측하지 마라.",
      "답변 끝에 사용한 출처를 [1] 형식으로 표시하라.",
      "",
      `<context>\n${context}\n</context>`,
    ].join("\n"),
  });

  const result = await agent.invoke({ messages: [{ role: "user", content: question }] });
  return result.messages.at(-1)?.text ?? "";
}

import { createRetrieverTool } from "@langchain/classic/tools/retriever";

const retrieverTool = createRetrieverTool(vectorStore.asRetriever({ k: 3 }), {
  name: "search_nimbus_docs",
  description:
    "Nimbus 클라우드의 공식 문서(요금제, 환불 정책, 사용 한도, 지원 정책)를 검색한다. " +
    "Nimbus 의 정책·가격·한도에 관한 질문에는 반드시 이 도구를 먼저 호출하라.",
});

const ragAgent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [retrieverTool],
  systemPrompt: [
    "너는 Nimbus 클라우드의 고객 지원 담당자다.",
    "Nimbus 에 관한 사실 질문에는 반드시 search_nimbus_docs 를 호출해 근거를 찾아라.",
    "검색 결과에 답이 없으면 '문서에서 찾을 수 없습니다'라고 답하라. 지어내지 마라.",
    "필요하면 검색어를 바꿔 여러 번 호출해도 된다.",
  ].join("\n"),
});

console.log(`(A)는 메시지 ${a1.messages.length}개, (B)는 ${a2.messages.length}개`);
// (A)는 4개 (human, ai+tool_call, tool, ai) / (B)는 2개 (human, ai)

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

const citedSearch = tool(
  async ({ query }) => {
    const results = await vectorStore.similaritySearchWithScore(query, 3);
    if (results.length === 0) return "검색 결과가 없습니다.";

    return results
      .map(([doc, score]) => {
        const src = basename(String(doc.metadata["source"]));
        // 점수를 같이 넘기면 모델이 "이건 별로 관련 없네"를 판단할 재료가 됩니다.
        return `<document source="${src}" score="${score.toFixed(3)}">\n${doc.pageContent}\n</document>`;
      })
      .join("\n\n");
  },
  {
    name: "search_with_citations",
    description:
      "Nimbus 클라우드 공식 문서를 검색한다. 각 결과에 source(파일명)와 score(0~1 유사도)가 붙어서 반환된다.",
    schema: z.object({
      query: z.string().describe("검색어. 사용자 질문을 그대로 넣지 말고 핵심 키워드로 다듬어라."),
    }),
  },
);

const citedAgent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [citedSearch],
  systemPrompt: [
    "너는 Nimbus 클라우드의 고객 지원 담당자다.",
    "사실 질문에는 반드시 search_with_citations 를 호출하라.",
    "답변의 모든 문장 끝에 근거 문서를 (출처: 파일명) 형식으로 붙여라.",
    "score 가 0.3 미만인 문서는 관련 없다고 보고 근거로 쓰지 마라.",
    "쓸 만한 근거가 하나도 없으면 '문서에서 찾을 수 없습니다'라고만 답하라.",
  ].join("\n"),
  responseFormat: z.object({
    answer: z.string().describe("사용자 질문에 대한 답변"),
    sources: z.array(z.string()).describe("근거로 사용한 문서의 파일명 목록. 없으면 빈 배열"),
    confident: z.boolean().describe("문서에 충분한 근거가 있었으면 true"),
  }),
});

const r = await citedAgent.invoke({ messages: [{ role: "user", content: q }] });
if (!r.structuredResponse.confident || r.structuredResponse.sources.length === 0) {
  return "죄송합니다. 문서에서 답을 찾지 못했습니다. 상담원에게 연결해 드릴까요?";
}

async function buildIndex(dir: string): Promise<MemoryVectorStore> {
  const l = new DirectoryLoader(dir, { ".md": (p) => new TextLoader(p) });
  const docs = await l.load();
  const s = new RecursiveCharacterTextSplitter({ chunkSize: 300, chunkOverlap: 60 });
  const chunks = await s.splitDocuments(docs);
  return MemoryVectorStore.fromDocuments(
    chunks,
    new OpenAIEmbeddings({ model: "text-embedding-3-small" }),
  );
}

const store = await buildIndex(kbDir);   // ← 임베딩 비용은 여기서 딱 한 번

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [
    createRetrieverTool(store.asRetriever({ k: 3 }), {
      name: "search_nimbus_docs",
      description: "Nimbus 클라우드 공식 문서를 검색한다. 정책·가격·한도 질문에 사용하라.",
    }),
  ],
  systemPrompt: "Nimbus 고객 지원 담당자다. 사실 질문은 반드시 검색하고, 없으면 모른다고 답하라.",
});

// 질의는 몇 번을 해도 임베딩 비용이 다시 들지 않습니다(질문 임베딩만).
for (const q of ["레이트 리밋은 API 키마다 따로인가요?", "Enterprise 는 응답이 얼마나 빠른가요?"]) {
  const r = await agent.invoke({ messages: [{ role: "user", content: q }] });
  console.log(`Q: ${q}\nA: ${r.messages.at(-1)?.text ?? ""}`);
}

// 1. MemoryVectorStore → 진짜 벡터 DB (프로세스 재시작에도 살아남음)
const store = await PGVectorStore.initialize(embeddings, { postgresConnectionOptions, tableName: "docs" });

// 2. buildIndex 는 앱이 아니라 배치 잡에서 (문서가 바뀔 때만)
//    npm run reindex

/**
 * Step 16 — 검색과 RAG
 * 실행: npx tsx docs/reference/langchain/step-16-retrieval-rag/practice.ts
 *
 * 필요한 환경변수 2개:
 *   ANTHROPIC_API_KEY  — 생성(generation)용
 *   OPENAI_API_KEY     — 임베딩(embedding)용
 *                        Anthropic 에는 임베딩 API 가 없습니다. 자세한 건 [16-4].
 *
 * 이 스텝만 추가로 필요한 패키지:
 *   npm install @langchain/classic @langchain/textsplitters
 */
import "dotenv/config";
import { mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, basename } from "node:path";

import { DirectoryLoader } from "@langchain/classic/document_loaders/fs/directory";
import { TextLoader } from "@langchain/classic/document_loaders/fs/text";
import { MemoryVectorStore } from "@langchain/classic/vectorstores/memory";
import { createRetrieverTool } from "@langchain/classic/tools/retriever";
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";
import { OpenAIEmbeddings } from "@langchain/openai";
import { Document } from "@langchain/core/documents";
import { createAgent, tool } from "langchain";
import * as z from "zod";

import { printSection, printMessages, requireEnv } from "../project/src/lib/print.js";

requireEnv("ANTHROPIC_API_KEY");
requireEnv("OPENAI_API_KEY");

/* ===== [16-1] RAG 파이프라인 전체 그림 ===== */
/*
 * 적재 → 분할 → 임베딩 → 저장  (인덱싱: 미리 한 번)
 * 검색 → 생성                   (질의: 매 요청마다)
 *
 * 아래 [16-2] ~ [16-7] 이 이 6단계를 순서대로 한 번씩 밟습니다.
 */
printSection("[16-1] RAG 파이프라인 — 6단계");
console.log(
  [
    "  인덱싱(미리 한 번)   : 적재 → 분할 → 임베딩 → 저장",
    "  질의(매 요청마다)     : 검색 → 생성",
    "",
    "  이 파일은 위 순서를 그대로 따라갑니다.",
  ].join("\n"),
);

/* ===== [16-2] Document 로더 ===== */

// 실습용 지식 베이스를 임시 디렉터리에 실제 .md 파일로 써 둡니다.
// (문서 사이트에 .md 를 두면 rspress 가 페이지로 만들어 버리므로 런타임에 생성합니다.)
// 문장을 줄바꿈으로 끊지 않고 문단으로 이어 붙였습니다. 실제 문서가 그렇게 생겼고,
// 그래야 분할기가 "문장 중간을 자르는" 진짜 상황이 재현됩니다([16-3]).
const KB: Record<string, string> = {
  "refund.md": `# 환불 정책

Nimbus 클라우드의 유료 플랜은 결제일로부터 14일 이내에 환불을 요청할 수 있습니다. 환불은 요청 후 영업일 기준 5일 이내에 원결제 수단으로 처리됩니다. 단, 해당 기간에 누적 사용량이 무료 한도의 3배를 넘은 계정은 환불 대상에서 제외됩니다. 연간 결제 플랜은 잔여 기간을 일할 계산하여 부분 환불하며, 이 경우 이미 제공된 할인은 회수됩니다.

환불 요청은 대시보드의 결제 메뉴 또는 billing@nimbus.example 로 접수합니다. 환불이 완료되면 해당 계정은 즉시 Free 플랜으로 전환되며, 저장 공간이 Free 한도를 초과한 경우 30일 뒤 초과분이 삭제됩니다.`,

  "pricing.md": `# 요금제

Free 플랜은 월 5,000회 API 호출과 1GB 저장 공간을 무료로 제공합니다. Pro 플랜은 월 29달러이며 월 500,000회 API 호출과 100GB 저장 공간을 제공합니다. Enterprise 플랜은 별도 견적으로 운영되며 호출 한도가 없습니다.

Pro 플랜에서 월 한도를 초과하면 1,000회당 0.5달러가 추가 과금됩니다. 추가 과금은 다음 결제일에 합산 청구되며, 대시보드에서 상한선을 설정하면 그 금액에 도달했을 때 API 가 차단됩니다. 연간 결제를 선택하면 2개월치가 할인됩니다.`,

  "limits.md": `# 사용 한도와 레이트 리밋

모든 플랜에는 초당 100회의 레이트 리밋이 적용됩니다. 레이트 리밋을 초과하면 HTTP 429 응답과 함께 Retry-After 헤더가 반환되므로, 클라이언트는 그 값만큼 기다린 뒤 재시도해야 합니다. Enterprise 플랜은 요청 시 초당 1,000회까지 상향할 수 있습니다.

레이트 리밋은 API 키 단위가 아니라 계정 단위로 계산됩니다. 따라서 키를 여러 개 발급해도 한도가 늘어나지 않습니다. 초과 호출은 과금되지 않지만 429 응답도 월 호출 수에는 포함되지 않습니다.`,

  "support.md": `# 지원 정책

Free 플랜 사용자는 커뮤니티 포럼만 이용할 수 있으며 응답 시간을 보장하지 않습니다. Pro 플랜은 이메일 지원을 제공하며 첫 응답까지 영업일 기준 24시간이 소요됩니다. Enterprise 플랜은 전담 슬랙 채널과 1시간 이내 응답 SLA 를 제공합니다.

장애 신고는 플랜과 무관하게 status.nimbus.example 에서 확인할 수 있습니다. SLA 를 위반한 경우 Enterprise 고객은 해당 월 요금의 10%를 크레딧으로 보상받습니다.`,
};

const kbDir = mkdtempSync(join(tmpdir(), "nimbus-kb-"));
for (const [name, body] of Object.entries(KB)) {
  writeFileSync(join(kbDir, name), body, "utf8");
}

printSection("[16-2] Document 로더 — 로컬 마크다운 적재");

// DirectoryLoader: 확장자별로 어떤 로더를 쓸지 매핑해 줍니다.
const loader = new DirectoryLoader(kbDir, {
  ".md": (path) => new TextLoader(path),
});
const rawDocs = await loader.load();

console.log(`적재된 문서 수: ${rawDocs.length}`);
for (const d of rawDocs) {
  // TextLoader 는 metadata.source 에 절대 경로를 넣어 줍니다.
  const src = String(d.metadata["source"]);
  console.log(`  - ${basename(src)}  (${d.pageContent.length}자)`);
}

// Document 를 직접 만들 수도 있습니다. 로더는 결국 이걸 만들어 주는 도구일 뿐입니다.
const handMade = new Document({
  pageContent: "Nimbus 는 2019년에 설립되었습니다.",
  metadata: { source: "company.md", title: "회사 소개" },
});
console.log(`\n직접 만든 Document: ${handMade.pageContent}`);
console.log(`  metadata: ${JSON.stringify(handMade.metadata)}`);

/* ===== [16-3] 텍스트 분할 ===== */

printSection("[16-3] 텍스트 분할 — chunkOverlap 이 0이면 벌어지는 일");

// 문단 하나만 떼어내 작은 chunkSize 로 자릅니다. 효과를 눈으로 보려고 일부러 작게 잡았습니다.
const refundPara =
  "Nimbus 클라우드의 유료 플랜은 결제일로부터 14일 이내에 환불을 요청할 수 있습니다. " +
  "환불은 요청 후 영업일 기준 5일 이내에 원결제 수단으로 처리됩니다. " +
  "단, 해당 기간에 누적 사용량이 무료 한도의 3배를 넘은 계정은 환불 대상에서 제외됩니다.";

// (A) overlap 0 — 경계에서 문장이 두 동강 납니다.
const splitterNoOverlap = new RecursiveCharacterTextSplitter({
  chunkSize: 60,
  chunkOverlap: 0,
});
const chunksNoOverlap = await splitterNoOverlap.splitText(refundPara);

console.log(`(A) chunkOverlap: 0 → ${chunksNoOverlap.length}개 청크`);
chunksNoOverlap.forEach((c, i) => {
  console.log(`  [${i}] ${JSON.stringify(c)}`);
});
console.log(
  "  ↑ [0] 은 '환불은 요청 후' 에서 끊기고 [1] 은 '영업일 기준...' 으로 시작합니다.\n" +
    "     '환불이 며칠 만에 처리되는가' 라는 사실이 두 청크에 쪼개져, 어느 쪽도 답이 못 됩니다.",
);

// (B) overlap 30 — 앞 청크의 꼬리가 뒤 청크의 머리에 겹쳐 들어갑니다.
const splitterOverlap = new RecursiveCharacterTextSplitter({
  chunkSize: 60,
  chunkOverlap: 30,
});
const chunksOverlap = await splitterOverlap.splitText(refundPara);

console.log(`\n(B) chunkOverlap: 30 → ${chunksOverlap.length}개 청크`);
chunksOverlap.forEach((c, i) => {
  console.log(`  [${i}] ${JSON.stringify(c)}`);
});
console.log(
  "  ↑ [1] 안에 '환불은 요청 후 영업일 기준 5일 이내에...' 문장이 통째로 들어왔습니다.\n" +
    "     청크 수는 3 → 4 로 늘었습니다. 이게 overlap 의 비용입니다.",
);

// 실제 인덱싱에 쓸 분할기. splitDocuments 는 metadata 를 각 청크에 복사해 줍니다.
const splitter = new RecursiveCharacterTextSplitter({
  chunkSize: 300,
  chunkOverlap: 60,
});
const splits = await splitter.splitDocuments(rawDocs);

console.log(`\n원본 ${rawDocs.length}개 문서 → 청크 ${splits.length}개`);
const first = splits[0];
if (first !== undefined) {
  // splitDocuments 는 source 를 그대로 물려주고 loc(줄 번호)을 덧붙입니다.
  console.log(`첫 청크 metadata: ${JSON.stringify(first.metadata)}`);
}

/* ===== [16-4] 임베딩 ===== */

printSection("[16-4] 임베딩 — 텍스트를 벡터로");

// Anthropic 에는 임베딩 API 가 없습니다. @langchain/anthropic 이 내보내는 것은
// ChatAnthropic 뿐입니다. 그래서 생성은 Anthropic, 임베딩은 OpenAI 로 나눠 씁니다.
const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const vec = await embeddings.embedQuery("환불은 며칠 안에 되나요?");
console.log(`text-embedding-3-small 차원: ${vec.length}`);
console.log(`앞 5개 값: [${vec.slice(0, 5).map((v) => v.toFixed(4)).join(", ")}]`);

// dimensions 로 차원을 줄이면 저장 비용과 검색 속도가 좋아집니다(정확도는 조금 손해).
const smallEmbeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
  dimensions: 256,
});
const smallVec = await smallEmbeddings.embedQuery("환불은 며칠 안에 되나요?");
console.log(`dimensions: 256 으로 줄이면 → ${smallVec.length}차원`);

// embedDocuments 는 여러 개를 한 번에 (배치로) 임베딩합니다.
const batch = await embeddings.embedDocuments(["환불 정책", "요금제"]);
console.log(`embedDocuments(2개) → ${batch.length}개 벡터`);

/* ===== [16-5] 벡터 스토어 ===== */

printSection("[16-5] 벡터 스토어 — MemoryVectorStore");

// fromDocuments 는 내부에서 embedDocuments 를 호출합니다.
// = 이 줄에서 청크 수만큼 임베딩 API 비용이 나갑니다. 매 실행마다 다시.
const t0 = Date.now();
const vectorStore = await MemoryVectorStore.fromDocuments(splits, embeddings);
console.log(`청크 ${splits.length}개 인덱싱 완료 (${Date.now() - t0}ms)`);

// 나중에 문서를 더 넣을 수도 있습니다.
await vectorStore.addDocuments([handMade]);
console.log(`문서 1개 추가 → 총 ${vectorStore.memoryVectors.length}개 벡터`);

/* ===== [16-6] Retriever ===== */

printSection("[16-6] Retriever — similaritySearch, k, 점수, MMR");

// (A) 가장 기본 — 상위 k개
const hits = await vectorStore.similaritySearch("환불은 며칠 안에 되나요?", 2);
console.log("(A) similaritySearch(query, k=2)");
for (const h of hits) {
  console.log(`  - ${basename(String(h.metadata["source"]))}: ${h.pageContent.slice(0, 40)}...`);
}

// (B) 점수까지 — [Document, number] 튜플 배열입니다. 코사인 유사도라 1에 가까울수록 유사.
const scored = await vectorStore.similaritySearchWithScore("환불은 며칠 안에 되나요?", 4);
console.log("\n(B) similaritySearchWithScore(query, k=4)");
for (const [doc, score] of scored) {
  console.log(`  ${score.toFixed(4)}  ${basename(String(doc.metadata["source"]))}`);
}

// (C) 검색 실패의 모습 — 지식 베이스에 없는 걸 물어도 k개는 반드시 나옵니다.
const offTopic = await vectorStore.similaritySearchWithScore("피자 굽는 온도는?", 2);
console.log("\n(C) 지식 베이스에 없는 질문 — '피자 굽는 온도는?'");
for (const [doc, score] of offTopic) {
  console.log(`  ${score.toFixed(4)}  ${basename(String(doc.metadata["source"]))}  ← 관련 없는데도 반환됨`);
}

// (D) asRetriever — Runnable 인터페이스. invoke/batch 를 씁니다.
const retriever = vectorStore.asRetriever({ k: 3 });
const viaRetriever = await retriever.invoke("Pro 플랜 가격이 얼마인가요?");
console.log(`\n(D) asRetriever({ k: 3 }).invoke() → ${viaRetriever.length}개`);

// (E) MMR — 유사도만 보지 않고 "이미 뽑은 것과 겹치지 않는" 문서를 섞어 뽑습니다.
//     fetchK 로 후보를 넉넉히 가져와 그중 k개를 고릅니다. lambda 1이면 순수 유사도,
//     0에 가까울수록 다양성 우선.
const mmrRetriever = vectorStore.asRetriever({
  searchType: "mmr",
  k: 3,
  searchKwargs: { fetchK: 8, lambda: 0.5 },
});
const mmrHits = await mmrRetriever.invoke("플랜별로 뭐가 다른가요?");
console.log(`\n(E) MMR(k=3, fetchK=8, lambda=0.5) → ${mmrHits.length}개`);
for (const h of mmrHits) {
  console.log(`  - ${basename(String(h.metadata["source"]))}`);
}

// (F) 점수 임계값은 직접 거릅니다 — 몇 개가 남을지 보장이 없습니다.
const THRESHOLD = 0.3;
const filtered = scored.filter(([, s]) => s >= THRESHOLD);
console.log(`\n(F) 임계값 ${THRESHOLD} 이상만 → ${filtered.length}/${scored.length}개 통과`);

/* ===== [16-7] 고전 RAG 체인 ===== */

printSection("[16-7] 고전 RAG — 검색 → 프롬프트에 끼워넣기 → 생성");

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

// 고전 RAG 는 그냥 함수입니다. 에이전트도 그래프도 필요 없습니다.
async function classicRag(question: string): Promise<string> {
  // 1) 검색 — 무조건 합니다.
  const docs = await vectorStore.similaritySearch(question, 3);

  // 2) 프롬프트에 끼워넣기 — 출처를 함께 넣어야 인용을 시킬 수 있습니다.
  const context = docs
    .map((d, i) => `[${i + 1}] (출처: ${basename(String(d.metadata["source"]))})\n${d.pageContent}`)
    .join("\n\n");

  // 3) 생성
  const agent = createAgent({
    model,
    tools: [],
    systemPrompt: [
      "너는 Nimbus 클라우드의 고객 지원 담당자다.",
      "아래 <context> 안의 내용만 근거로 답하라.",
      "context 에 답이 없으면 반드시 '제공된 문서에서 찾을 수 없습니다'라고 답하라. 추측하지 마라.",
      "답변 끝에 사용한 출처를 [1] 형식으로 표시하라.",
      "",
      `<context>\n${context}\n</context>`,
    ].join("\n"),
  });

  const result = await agent.invoke({
    messages: [{ role: "user", content: question }],
  });
  const last = result.messages.at(-1);
  return last?.text ?? "";
}

console.log("Q: 환불은 며칠 이내에 요청해야 하나요?");
console.log(`A: ${await classicRag("환불은 며칠 이내에 요청해야 하나요?")}`);

// 지식 베이스에 없는 질문 — 검색은 여전히 3개를 가져오지만, 답은 "모른다"여야 합니다.
console.log("\nQ: Nimbus 는 쿠버네티스를 지원하나요?  ← 문서에 없는 내용");
console.log(`A: ${await classicRag("Nimbus 는 쿠버네티스를 지원하나요?")}`);

/* ===== [16-8] 에이전틱 RAG ===== */

printSection("[16-8] 에이전틱 RAG — 검색을 도구로");

// createRetrieverTool 이 retriever 를 도구로 감싸 줍니다.
// 스키마는 { query: string } 이고 반환값은 문서를 이어붙인 문자열입니다.
const retrieverTool = createRetrieverTool(vectorStore.asRetriever({ k: 3 }), {
  name: "search_nimbus_docs",
  // description 이 곧 프롬프트입니다. "언제 이걸 부를지"를 모델에게 알려 줍니다.
  description:
    "Nimbus 클라우드의 공식 문서(요금제, 환불 정책, 사용 한도, 지원 정책)를 검색한다. " +
    "Nimbus 의 정책·가격·한도에 관한 질문에는 반드시 이 도구를 먼저 호출하라.",
});

const ragAgent = createAgent({
  model,
  tools: [retrieverTool],
  systemPrompt: [
    "너는 Nimbus 클라우드의 고객 지원 담당자다.",
    "Nimbus 에 관한 사실 질문에는 반드시 search_nimbus_docs 를 호출해 근거를 찾아라.",
    "검색 결과에 답이 없으면 '문서에서 찾을 수 없습니다'라고 답하라. 지어내지 마라.",
    "필요하면 검색어를 바꿔 여러 번 호출해도 된다.",
  ].join("\n"),
});

// (A) 검색이 필요한 질문 — 도구를 부릅니다.
console.log("(A) Q: Pro 플랜에서 한도를 넘기면 얼마가 더 나오나요?");
const a1 = await ragAgent.invoke({
  messages: [{ role: "user", content: "Pro 플랜에서 한도를 넘기면 얼마가 더 나오나요?" }],
});
printMessages(a1.messages);

// (B) 검색이 필요 없는 인사 — 도구를 건너뜁니다. 고전 RAG 였다면 무조건 검색했을 겁니다.
console.log("\n(B) Q: 안녕하세요!  ← 검색 불필요");
const a2 = await ragAgent.invoke({
  messages: [{ role: "user", content: "안녕하세요!" }],
});
printMessages(a2.messages);
console.log(
  `\n→ (A) 는 메시지 ${a1.messages.length}개, (B) 는 ${a2.messages.length}개.` +
    " 차이가 곧 '검색을 건너뛴 것'입니다.",
);

// (C) 여러 문서를 넘나드는 질문 — 에이전트가 알아서 두 번 이상 검색할 수 있습니다.
console.log("\n(C) Q: Free 랑 Enterprise 는 지원이랑 레이트 리밋이 각각 어떻게 다른가요?");
const a3 = await ragAgent.invoke({
  messages: [
    {
      role: "user",
      content: "Free 랑 Enterprise 는 지원이랑 레이트 리밋이 각각 어떻게 다른가요?",
    },
  ],
});
const toolCallCount = a3.messages.filter(
  (m) => Array.isArray((m as { tool_calls?: unknown[] }).tool_calls) &&
    ((m as { tool_calls?: unknown[] }).tool_calls?.length ?? 0) > 0,
).length;
console.log(`→ 검색 도구를 부른 AI 메시지 수: ${toolCallCount}`);
printMessages(a3.messages.slice(-1));

/* ===== [16-9] 품질 — 인용(citation) 붙이기 ===== */

printSection("[16-9] 인용 — 출처를 강제하는 도구");

// createRetrieverTool 은 본문만 문자열로 돌려줘서 출처가 사라집니다.
// 인용을 시키려면 도구를 직접 만들어 출처를 본문과 함께 실어 보냅니다.
const citedSearch = tool(
  async ({ query }) => {
    const results = await vectorStore.similaritySearchWithScore(query, 3);
    if (results.length === 0) return "검색 결과가 없습니다.";

    return results
      .map(([doc, score]) => {
        const src = basename(String(doc.metadata["source"]));
        // 점수를 같이 넘겨 주면 모델이 "이건 별로 관련 없네"를 판단할 재료가 됩니다.
        return `<document source="${src}" score="${score.toFixed(3)}">\n${doc.pageContent}\n</document>`;
      })
      .join("\n\n");
  },
  {
    name: "search_with_citations",
    description:
      "Nimbus 클라우드 공식 문서를 검색한다. 각 결과에 source(파일명)와 score(0~1 유사도)가 붙어서 반환된다.",
    schema: z.object({
      query: z.string().describe("검색어. 사용자 질문을 그대로 넣지 말고 핵심 키워드로 다듬어라."),
    }),
  },
);

const citedAgent = createAgent({
  model,
  tools: [citedSearch],
  systemPrompt: [
    "너는 Nimbus 클라우드의 고객 지원 담당자다.",
    "사실 질문에는 반드시 search_with_citations 를 호출하라.",
    "답변의 모든 문장 끝에 근거 문서를 (출처: 파일명) 형식으로 붙여라.",
    "score 가 0.3 미만인 문서는 관련 없다고 보고 근거로 쓰지 마라.",
    "쓸 만한 근거가 하나도 없으면 '문서에서 찾을 수 없습니다'라고만 답하라.",
  ].join("\n"),
  responseFormat: z.object({
    answer: z.string().describe("사용자 질문에 대한 답변"),
    sources: z.array(z.string()).describe("근거로 사용한 문서의 파일명 목록. 없으면 빈 배열"),
    confident: z.boolean().describe("문서에 충분한 근거가 있었으면 true"),
  }),
});

console.log("Q: 연간 결제를 중간에 해지하면 환불받을 수 있나요?");
const c1 = await citedAgent.invoke({
  messages: [{ role: "user", content: "연간 결제를 중간에 해지하면 환불받을 수 있나요?" }],
});
console.log(JSON.stringify(c1.structuredResponse, null, 2));

console.log("\nQ: Nimbus 서버는 어느 나라에 있나요?  ← 문서에 없는 내용");
const c2 = await citedAgent.invoke({
  messages: [{ role: "user", content: "Nimbus 서버는 어느 나라에 있나요?" }],
});
console.log(JSON.stringify(c2.structuredResponse, null, 2));
console.log("\n→ confident: false 와 빈 sources 가 '검색 실패'를 코드로 감지할 수 있게 해 줍니다.");

/* ===== [16-10] 종합 ===== */

printSection("[16-10] 종합 — 인덱싱은 한 번, 질의는 여러 번");

// 인덱싱을 함수로 묶어 두면 "한 번만 하고 재사용"이 구조적으로 드러납니다.
async function buildIndex(dir: string): Promise<MemoryVectorStore> {
  const l = new DirectoryLoader(dir, { ".md": (p) => new TextLoader(p) });
  const docs = await l.load();
  const s = new RecursiveCharacterTextSplitter({ chunkSize: 300, chunkOverlap: 60 });
  const chunks = await s.splitDocuments(docs);
  return MemoryVectorStore.fromDocuments(chunks, new OpenAIEmbeddings({ model: "text-embedding-3-small" }));
}

const store = await buildIndex(kbDir); // ← 임베딩 비용은 여기서 한 번
const finalAgent = createAgent({
  model,
  tools: [
    createRetrieverTool(store.asRetriever({ k: 3 }), {
      name: "search_nimbus_docs",
      description: "Nimbus 클라우드 공식 문서를 검색한다. 정책·가격·한도 질문에 사용하라.",
    }),
  ],
  systemPrompt: "Nimbus 고객 지원 담당자다. 사실 질문은 반드시 검색하고, 없으면 모른다고 답하라.",
});

for (const q of ["레이트 리밋은 API 키마다 따로인가요?", "Enterprise 는 응답이 얼마나 빠른가요?"]) {
  const r = await finalAgent.invoke({ messages: [{ role: "user", content: q }] });
  console.log(`\nQ: ${q}`);
  console.log(`A: ${r.messages.at(-1)?.text ?? ""}`);
}

console.log(`\n(실습용 지식 베이스 위치: ${kbDir})`);

/**
 * Step 16 — 검색과 RAG · 연습문제
 * 실행: npx tsx docs/reference/langchain/step-16-retrieval-rag/exercise.ts
 *
 * 필요한 환경변수: ANTHROPIC_API_KEY, OPENAI_API_KEY
 * 추가 설치: npm install @langchain/classic @langchain/textsplitters
 *
 * 각 [문제 N] 블록 아래에 코드를 채워 넣고 실행하세요.
 * 정답은 solution.ts 에 있습니다. 먼저 스스로 풀어 보세요.
 */
import "dotenv/config";
import { mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, basename } from "node:path";

import { DirectoryLoader } from "@langchain/classic/document_loaders/fs/directory";
import { TextLoader } from "@langchain/classic/document_loaders/fs/text";
import { MemoryVectorStore } from "@langchain/classic/vectorstores/memory";
import { createRetrieverTool } from "@langchain/classic/tools/retriever";
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";
import { OpenAIEmbeddings } from "@langchain/openai";
import type { BaseMessage } from "@langchain/core/messages";
import { createAgent, tool } from "langchain";
import * as z from "zod";

import { printSection, requireEnv } from "../project/src/lib/print.js";

requireEnv("ANTHROPIC_API_KEY");
requireEnv("OPENAI_API_KEY");

/* ===== 준비 — 이 부분은 이미 작성되어 있습니다 ===== */

const KB: Record<string, string> = {
  "refund.md": `# 환불 정책

Nimbus 클라우드의 유료 플랜은 결제일로부터 14일 이내에 환불을 요청할 수 있습니다. 환불은 요청 후 영업일 기준 5일 이내에 원결제 수단으로 처리됩니다. 단, 해당 기간에 누적 사용량이 무료 한도의 3배를 넘은 계정은 환불 대상에서 제외됩니다. 연간 결제 플랜은 잔여 기간을 일할 계산하여 부분 환불하며, 이 경우 이미 제공된 할인은 회수됩니다.

환불 요청은 대시보드의 결제 메뉴 또는 billing@nimbus.example 로 접수합니다. 환불이 완료되면 해당 계정은 즉시 Free 플랜으로 전환되며, 저장 공간이 Free 한도를 초과한 경우 30일 뒤 초과분이 삭제됩니다.`,

  "pricing.md": `# 요금제

Free 플랜은 월 5,000회 API 호출과 1GB 저장 공간을 무료로 제공합니다. Pro 플랜은 월 29달러이며 월 500,000회 API 호출과 100GB 저장 공간을 제공합니다. Enterprise 플랜은 별도 견적으로 운영되며 호출 한도가 없습니다.

Pro 플랜에서 월 한도를 초과하면 1,000회당 0.5달러가 추가 과금됩니다. 추가 과금은 다음 결제일에 합산 청구되며, 대시보드에서 상한선을 설정하면 그 금액에 도달했을 때 API 가 차단됩니다. 연간 결제를 선택하면 2개월치가 할인됩니다.`,

  "limits.md": `# 사용 한도와 레이트 리밋

모든 플랜에는 초당 100회의 레이트 리밋이 적용됩니다. 레이트 리밋을 초과하면 HTTP 429 응답과 함께 Retry-After 헤더가 반환되므로, 클라이언트는 그 값만큼 기다린 뒤 재시도해야 합니다. Enterprise 플랜은 요청 시 초당 1,000회까지 상향할 수 있습니다.

레이트 리밋은 API 키 단위가 아니라 계정 단위로 계산됩니다. 따라서 키를 여러 개 발급해도 한도가 늘어나지 않습니다. 초과 호출은 과금되지 않지만 429 응답도 월 호출 수에는 포함되지 않습니다.`,

  "support.md": `# 지원 정책

Free 플랜 사용자는 커뮤니티 포럼만 이용할 수 있으며 응답 시간을 보장하지 않습니다. Pro 플랜은 이메일 지원을 제공하며 첫 응답까지 영업일 기준 24시간이 소요됩니다. Enterprise 플랜은 전담 슬랙 채널과 1시간 이내 응답 SLA 를 제공합니다.

장애 신고는 플랜과 무관하게 status.nimbus.example 에서 확인할 수 있습니다. SLA 를 위반한 경우 Enterprise 고객은 해당 월 요금의 10%를 크레딧으로 보상받습니다.`,
};

const kbDir = mkdtempSync(join(tmpdir(), "nimbus-ex-"));
for (const [name, body] of Object.entries(KB)) {
  writeFileSync(join(kbDir, name), body, "utf8");
}

const embeddings = new OpenAIEmbeddings({ model: "text-embedding-3-small" });
const model = "anthropic:claude-sonnet-4-6";

/**
 * 지식 베이스를 인덱싱합니다.
 * [문제 1] 과 [문제 7] 에서 chunkSize / chunkOverlap 을 바꿔 가며 부를 수 있게
 * 파라미터로 열어 두었습니다. files 를 주면 그 파일만 인덱싱합니다([문제 8]).
 */
async function buildIndex(
  chunkSize = 300,
  chunkOverlap = 60,
  files?: string[],
): Promise<MemoryVectorStore> {
  const loader = new DirectoryLoader(kbDir, { ".md": (p) => new TextLoader(p) });
  let docs = await loader.load();
  if (files !== undefined) {
    docs = docs.filter((d) => files.includes(basename(String(d.metadata["source"]))));
  }
  const splitter = new RecursiveCharacterTextSplitter({ chunkSize, chunkOverlap });
  const chunks = await splitter.splitDocuments(docs);
  return MemoryVectorStore.fromDocuments(chunks, embeddings);
}

/* ===== [문제 1] 청킹이 검색을 망가뜨리는 것 보기 =====
 *
 * chunkSize: 300, chunkOverlap: 60 인덱스와
 * chunkSize: 60,  chunkOverlap: 0  인덱스를 각각 만들고,
 * 같은 질문 "환불은 며칠 만에 처리되나요?" 로 검색해 상위 2개 청크를 출력하세요.
 *
 * 후자에서 답("영업일 기준 5일")이 어떻게 쪼개지는지 확인하세요.
 * 검색된 청크에 답이 들어 있나요?
 */

printSection("[문제 1] 청킹이 검색을 망가뜨리는 것 보기");

// 여기에 코드를 작성하세요.

/* ===== [문제 2] 임계값을 데이터로 정하기 =====
 *
 * 기본 인덱스(300/60)에 아래 질문들을 던져 similaritySearchWithScore 로 최고 점수를
 * 각각 출력하세요.
 *
 *   무관한 질문: "김치찌개 레시피", "축구 경기 결과", "비트코인 시세"
 *   관련 질문:   "환불 기간", "Pro 플랜 가격", "레이트 리밋"
 *
 * 그리고 이 인덱스에 적절한 임계값을 정해 주석으로 근거와 함께 쓰세요.
 * (무관한 질문의 점수가 0이 아니라는 것에 주목하세요)
 */

printSection("[문제 2] 임계값을 데이터로 정하기");

// 여기에 코드를 작성하세요.

// → 내가 정한 임계값: ____ , 근거:

/* ===== [문제 3] MMR 이 정말 다른가 =====
 *
 * 같은 벡터 스토어에서 retriever 두 개를 만들어 "플랜별로 뭐가 다른가요?" 를 던지고
 * 반환된 source 목록을 비교하세요.
 *
 *   (A) 기본:  asRetriever({ k: 3 })
 *   (B) MMR:   asRetriever({ searchType: "mmr", k: 3, searchKwargs: { fetchK: ?, lambda: ? } })
 *
 * 힌트: 차이를 보려면 fetchK 가 k 보다 충분히 커야 합니다.
 *       fetchK 를 k 와 같게 두면 고를 후보가 없어 결과가 똑같이 나옵니다.
 */

printSection("[문제 3] MMR 이 정말 다른가");

// 여기에 코드를 작성하세요.

/* ===== [문제 4] 검색을 건너뛴 것을 감지하기 =====
 *
 * (a) createRetrieverTool 로 만든 도구 하나를 가진 에이전트를 만드세요.
 * (b) "안녕하세요" 와 "환불 정책 알려줘" 를 각각 던지고,
 *     tool_calls 가 있는 AI 메시지 수를 세어 출력하세요.
 * (c) assertSearched(messages) 를 작성하세요 — 검색 없이 답했으면 경고를 찍습니다.
 *
 * 힌트: instanceof AIMessage 대신 구조적 검사를 쓰세요.
 *       (m as { tool_calls?: unknown[] }).tool_calls
 *       @langchain/core 가 두 벌 설치되면 instanceof 가 조용히 false 가 됩니다.
 */

printSection("[문제 4] 검색을 건너뛴 것을 감지하기");

function assertSearched(_messages: BaseMessage[]): boolean {
  // 여기에 코드를 작성하세요.
  return false;
}

// 여기에 코드를 작성하세요.

/* ===== [문제 5] 줄 번호까지 인용하는 도구 =====
 *
 * metadata.loc.lines.from / .to 까지 포함하는 검색 도구를 직접 만드세요.
 *
 * 반환 형식:
 *   <document source="refund.md" lines="3-5">
 *   ...본문...
 *   </document>
 *
 * 힌트: splitDocuments 가 metadata.loc 를 넣어 줍니다. 구조는 이렇습니다.
 *       { loc: { lines: { from: 1, to: 5 } } }
 *       타입이 unknown 이므로 안전하게 좁혀서 읽어야 합니다.
 */

printSection("[문제 5] 줄 번호까지 인용하는 도구");

// 여기에 코드를 작성하세요.

/* ===== [문제 6] 인용 검증 =====
 *
 * 에이전트가 반환한 sources 중 실제로 검색되지 않은 파일명이 있으면 에러를 던지세요.
 *
 * (a) responseFormat 으로 { answer, sources } 를 받는 에이전트를 만드세요.
 * (b) 검색된 문서 집합을 따로 모아 두세요. (힌트: 도구 안에서 기록)
 * (c) sources ⊆ 검색된 집합 인지 검사하고, 아니면 에러를 던지세요.
 *
 * 그리고 이 검증이 왜 필요한지 주석으로 설명하세요.
 */

printSection("[문제 6] 인용 검증");

// 여기에 코드를 작성하세요.

// → 이 검증이 필요한 이유:

/* ===== [문제 7] 인덱싱에 캐시가 없다는 것 =====
 *
 * buildIndex() 를 두 번 호출하고 각각 걸린 시간을 측정해 출력하세요.
 * 두 번째도 첫 번째와 비슷하게 걸린다는 것을 확인하세요.
 *
 * 그리고 이것이 프로덕션에서 왜 문제인지 주석으로 쓰세요.
 * (힌트: 청크 5개 → 5만 개, 인스턴스 1개 → 10개일 때를 상상해 보세요)
 */

printSection("[문제 7] 인덱싱에 캐시가 없다는 것");

// 여기에 코드를 작성하세요.

// → 프로덕션에서 문제가 되는 이유:

/* ===== [문제 8] (심화) 도구를 소스별로 쪼개기 =====
 *
 * 지식 소스를 둘로 나눠 도구를 두 개 만드세요.
 *
 *   search_billing   → refund.md, pricing.md
 *   search_technical → limits.md, support.md
 *
 * (힌트: buildIndex 의 세 번째 인자 files 를 쓰세요)
 *
 * 에이전트에게 아래 둘을 던져 각각 어느 도구를 골랐는지 출력하세요.
 *   "Pro 플랜 환불되나요?"
 *   "레이트 리밋 얼마예요?"
 *
 * 도구 선택은 모델 판단이라 비결정적입니다. 기대와 다르게 골랐다면
 * description 을 고쳐 가며 선택이 어떻게 바뀌는지 관찰하세요.
 */

printSection("[문제 8] 도구를 소스별로 쪼개기");

// 여기에 코드를 작성하세요.

console.log(`\n(실습용 지식 베이스 위치: ${kbDir})`);

// 아래는 사용하지 않는 import 로 인한 오류를 막기 위한 것입니다.
// 문제를 풀면서 실제로 쓰게 되면 지워도 됩니다.
void createAgent;
void createRetrieverTool;
void tool;
void z;
void model;

/**
 * Step 16 — 검색과 RAG · 정답과 해설
 * 실행: npx tsx docs/reference/langchain/step-16-retrieval-rag/solution.ts
 *
 * 필요한 환경변수: ANTHROPIC_API_KEY, OPENAI_API_KEY
 * 추가 설치: npm install @langchain/classic @langchain/textsplitters
 *
 * exercise.ts 를 스스로 풀어본 뒤에 열어보세요.
 */
import "dotenv/config";
import { mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, basename } from "node:path";

import { DirectoryLoader } from "@langchain/classic/document_loaders/fs/directory";
import { TextLoader } from "@langchain/classic/document_loaders/fs/text";
import { MemoryVectorStore } from "@langchain/classic/vectorstores/memory";
import { createRetrieverTool } from "@langchain/classic/tools/retriever";
import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";
import { OpenAIEmbeddings } from "@langchain/openai";
import type { BaseMessage } from "@langchain/core/messages";
import { createAgent, tool } from "langchain";
import * as z from "zod";

import { printSection, requireEnv } from "../project/src/lib/print.js";

requireEnv("ANTHROPIC_API_KEY");
requireEnv("OPENAI_API_KEY");

/* ===== 준비 ===== */

const KB: Record<string, string> = {
  "refund.md": `# 환불 정책

Nimbus 클라우드의 유료 플랜은 결제일로부터 14일 이내에 환불을 요청할 수 있습니다. 환불은 요청 후 영업일 기준 5일 이내에 원결제 수단으로 처리됩니다. 단, 해당 기간에 누적 사용량이 무료 한도의 3배를 넘은 계정은 환불 대상에서 제외됩니다. 연간 결제 플랜은 잔여 기간을 일할 계산하여 부분 환불하며, 이 경우 이미 제공된 할인은 회수됩니다.

환불 요청은 대시보드의 결제 메뉴 또는 billing@nimbus.example 로 접수합니다. 환불이 완료되면 해당 계정은 즉시 Free 플랜으로 전환되며, 저장 공간이 Free 한도를 초과한 경우 30일 뒤 초과분이 삭제됩니다.`,

  "pricing.md": `# 요금제

Free 플랜은 월 5,000회 API 호출과 1GB 저장 공간을 무료로 제공합니다. Pro 플랜은 월 29달러이며 월 500,000회 API 호출과 100GB 저장 공간을 제공합니다. Enterprise 플랜은 별도 견적으로 운영되며 호출 한도가 없습니다.

Pro 플랜에서 월 한도를 초과하면 1,000회당 0.5달러가 추가 과금됩니다. 추가 과금은 다음 결제일에 합산 청구되며, 대시보드에서 상한선을 설정하면 그 금액에 도달했을 때 API 가 차단됩니다. 연간 결제를 선택하면 2개월치가 할인됩니다.`,

  "limits.md": `# 사용 한도와 레이트 리밋

모든 플랜에는 초당 100회의 레이트 리밋이 적용됩니다. 레이트 리밋을 초과하면 HTTP 429 응답과 함께 Retry-After 헤더가 반환되므로, 클라이언트는 그 값만큼 기다린 뒤 재시도해야 합니다. Enterprise 플랜은 요청 시 초당 1,000회까지 상향할 수 있습니다.

레이트 리밋은 API 키 단위가 아니라 계정 단위로 계산됩니다. 따라서 키를 여러 개 발급해도 한도가 늘어나지 않습니다. 초과 호출은 과금되지 않지만 429 응답도 월 호출 수에는 포함되지 않습니다.`,

  "support.md": `# 지원 정책

Free 플랜 사용자는 커뮤니티 포럼만 이용할 수 있으며 응답 시간을 보장하지 않습니다. Pro 플랜은 이메일 지원을 제공하며 첫 응답까지 영업일 기준 24시간이 소요됩니다. Enterprise 플랜은 전담 슬랙 채널과 1시간 이내 응답 SLA 를 제공합니다.

장애 신고는 플랜과 무관하게 status.nimbus.example 에서 확인할 수 있습니다. SLA 를 위반한 경우 Enterprise 고객은 해당 월 요금의 10%를 크레딧으로 보상받습니다.`,
};

const kbDir = mkdtempSync(join(tmpdir(), "nimbus-sol-"));
for (const [name, body] of Object.entries(KB)) {
  writeFileSync(join(kbDir, name), body, "utf8");
}

const embeddings = new OpenAIEmbeddings({ model: "text-embedding-3-small" });
const model = "anthropic:claude-sonnet-4-6";

async function buildIndex(
  chunkSize = 300,
  chunkOverlap = 60,
  files?: string[],
): Promise<MemoryVectorStore> {
  const loader = new DirectoryLoader(kbDir, { ".md": (p) => new TextLoader(p) });
  let docs = await loader.load();
  if (files !== undefined) {
    docs = docs.filter((d) => files.includes(basename(String(d.metadata["source"]))));
  }
  const splitter = new RecursiveCharacterTextSplitter({ chunkSize, chunkOverlap });
  const chunks = await splitter.splitDocuments(docs);
  return MemoryVectorStore.fromDocuments(chunks, embeddings);
}

const src = (d: { metadata: Record<string, unknown> }): string =>
  basename(String(d.metadata["source"]));

/* ===== [정답 1] 청킹이 검색을 망가뜨리는 것 보기 ===== */

printSection("[정답 1] 청킹이 검색을 망가뜨리는 것 보기");

const QUESTION_1 = "환불은 며칠 만에 처리되나요?";

// (A) 제대로 된 청킹
const goodIndex = await buildIndex(300, 60);
const goodHits = await goodIndex.similaritySearchWithScore(QUESTION_1, 2);

console.log("(A) chunkSize: 300, chunkOverlap: 60");
for (const [doc, score] of goodHits) {
  const hasAnswer = doc.pageContent.includes("5일");
  console.log(`  ${score.toFixed(4)}  ${src(doc)}  답 포함: ${hasAnswer ? "O" : "X"}`);
  console.log(`         ${doc.pageContent.slice(0, 60).replace(/\n/g, " ")}...`);
}

// (B) 망가진 청킹 — 문장이 두 동강 납니다.
const badIndex = await buildIndex(60, 0);
const badHits = await badIndex.similaritySearchWithScore(QUESTION_1, 2);

console.log("\n(B) chunkSize: 60, chunkOverlap: 0");
for (const [doc, score] of badHits) {
  const hasAnswer = doc.pageContent.includes("5일");
  console.log(`  ${score.toFixed(4)}  ${src(doc)}  답 포함: ${hasAnswer ? "O" : "X"}`);
  console.log(`         ${JSON.stringify(doc.pageContent)}`);
}

/* 해설:
 * (B) 에서 1위로 올라온 청크에는 "환불"이라는 단어가 있어 유사도가 높지만,
 * 정작 답인 "영업일 기준 5일"은 옆 청크에 있습니다. 즉 "답 포함: X" 입니다.
 *
 * 이것이 청킹 실패 → 검색 실패 → 환각으로 이어지는 사슬의 첫 고리입니다.
 * 모델은 검색된 청크를 근거로 삼는데 거기에 답이 없으니, 프롬프트가 약하면
 * "환불은 보통 7일 정도 걸립니다" 같은 걸 지어냅니다.
 *
 * 주의: 실제로 어떤 청크가 1위가 되는지는 임베딩 모델에 달려 있어
 * 매번 똑같지 않을 수 있습니다. 핵심은 "검색된 청크에 답이 있는가"를
 * 코드로 확인하는 습관(위의 hasAnswer)입니다. 이게 recall@k 측정의 씨앗입니다.
 */

/* ===== [정답 2] 임계값을 데이터로 정하기 ===== */

printSection("[정답 2] 임계값을 데이터로 정하기");

const store = await buildIndex(300, 60); // 이후 문제에서 계속 재사용합니다.

const offTopicQs = ["김치찌개 레시피", "축구 경기 결과", "비트코인 시세"];
const onTopicQs = ["환불 기간", "Pro 플랜 가격", "레이트 리밋"];

async function topScore(q: string): Promise<number> {
  const r = await store.similaritySearchWithScore(q, 1);
  return r[0]?.[1] ?? 0;
}

const offScores: number[] = [];
console.log("무관한 질문:");
for (const q of offTopicQs) {
  const s = await topScore(q);
  offScores.push(s);
  console.log(`  ${s.toFixed(4)}  "${q}"`);
}

const onScores: number[] = [];
console.log("\n관련 질문:");
for (const q of onTopicQs) {
  const s = await topScore(q);
  onScores.push(s);
  console.log(`  ${s.toFixed(4)}  "${q}"`);
}

const maxOff = Math.max(...offScores);
const minOn = Math.min(...onScores);
console.log(`\n무관 최고점: ${maxOff.toFixed(4)}`);
console.log(`관련 최저점: ${minOn.toFixed(4)}`);
console.log(
  maxOff < minOn
    ? `→ 두 구간이 분리됨. 임계값은 그 사이: ${((maxOff + minOn) / 2).toFixed(4)}`
    : "→ 두 구간이 겹침! 임계값만으로는 못 거릅니다. 리랭킹이 필요합니다.",
);

/* 해설:
 * 이 문제는 정답 숫자가 없습니다. 확인할 것은 두 가지입니다.
 *
 * 1. 무관한 질문의 점수가 0이 아닙니다. 대개 0.1~0.3 대가 나옵니다.
 *    "점수가 0보다 크면 관련 있다"는 직관은 틀렸습니다.
 *
 * 2. 임계값은 "관련 질문의 최저점"과 "무관 질문의 최고점" 사이에 있어야 합니다.
 *    그런데 이 둘이 겹치면 임계값으로는 절대 못 가릅니다 — 무관한 걸 버리려면
 *    관련 있는 것도 같이 버려야 하니까요. 그때가 리랭킹(cross-encoder)이
 *    필요해지는 지점입니다.
 *
 * 그래서 "0.7 이상이면 관련 있음" 같은 보편 상수는 존재하지 않습니다.
 * 반드시 여러분의 데이터에서 이 분포를 직접 찍어 보고 정하세요.
 */

/* ===== [정답 3] MMR 이 정말 다른가 ===== */

printSection("[정답 3] MMR 이 정말 다른가");

const QUESTION_3 = "플랜별로 뭐가 다른가요?";

const plainRetriever = store.asRetriever({ k: 3 });
const plainDocs = await plainRetriever.invoke(QUESTION_3);
console.log(`(A) 기본 k=3        → ${plainDocs.map(src).join(", ")}`);

// fetchK 를 k 의 3배 가까이 잡아야 MMR 이 고를 여지가 생깁니다.
const mmrRetriever = store.asRetriever({
  searchType: "mmr",
  k: 3,
  searchKwargs: { fetchK: 8, lambda: 0.5 },
});
const mmrDocs = await mmrRetriever.invoke(QUESTION_3);
console.log(`(B) MMR k=3 fetchK=8 → ${mmrDocs.map(src).join(", ")}`);

// fetchK 를 k 와 같게 두면 — 후보가 3개뿐이라 3개를 다 골라야 합니다.
const brokenMmr = store.asRetriever({
  searchType: "mmr",
  k: 3,
  searchKwargs: { fetchK: 3, lambda: 0.5 },
});
const brokenDocs = await brokenMmr.invoke(QUESTION_3);
console.log(`(C) MMR k=3 fetchK=3 → ${brokenDocs.map(src).join(", ")}  ← 기본과 같은 집합`);

/* 해설:
 * (C) 가 이 문제의 핵심입니다. fetchK === k 면 MMR 은 아무 일도 하지 않습니다.
 * 후보를 3개 가져와 3개를 골라야 하니 "고른다"는 행위 자체가 없습니다.
 * (순서만 바뀔 수 있습니다.)
 *
 * MMR 을 켜 놓고 "왜 똑같지?" 하는 경우의 대부분이 이것입니다.
 * fetchK 는 k 의 3~5배로 잡으세요.
 *
 * 이 실습의 지식 베이스는 문서가 4개뿐이라 (A)와 (B)의 차이가 작을 수 있습니다.
 * overlap 을 크게 준 큰 문서 집합일수록 MMR 의 효과가 커집니다 —
 * 거의 같은 내용의 청크가 상위를 도배하는 것을 막아 주니까요.
 */

/* ===== [정답 4] 검색을 건너뛴 것을 감지하기 ===== */

printSection("[정답 4] 검색을 건너뛴 것을 감지하기");

/**
 * tool_calls 가 있는 AI 메시지가 하나라도 있으면 true.
 *
 * instanceof AIMessage 를 쓰지 않은 이유:
 * @langchain/core 가 두 벌 설치되면 클래스 아이덴티티가 갈라져
 * instanceof 가 조용히 false 가 됩니다(Step 01 의 함정).
 * 그래서 "그 필드가 실제로 있는지"만 보는 구조적 검사를 씁니다.
 * project/src/lib/print.ts 도 같은 이유로 같은 방식을 씁니다.
 */
function countToolCalls(messages: BaseMessage[]): number {
  return messages.filter(
    (m) => ((m as { tool_calls?: unknown[] }).tool_calls?.length ?? 0) > 0,
  ).length;
}

function assertSearched(messages: BaseMessage[]): boolean {
  const n = countToolCalls(messages);
  if (n === 0) {
    console.warn("  ⚠️ 검색 없이 답변함 — 환각 가능성");
    return false;
  }
  return true;
}

const searchTool = createRetrieverTool(store.asRetriever({ k: 3 }), {
  name: "search_nimbus_docs",
  description:
    "Nimbus 클라우드의 공식 문서(요금제, 환불 정책, 사용 한도, 지원 정책)를 검색한다. " +
    "Nimbus 의 정책·가격·한도에 관한 질문에는 반드시 이 도구를 먼저 호출하라.",
});

const agent4 = createAgent({
  model,
  tools: [searchTool],
  systemPrompt:
    "너는 Nimbus 클라우드 고객 지원 담당자다. " +
    "사실 질문에는 반드시 search_nimbus_docs 를 호출하라. 없으면 모른다고 답하라.",
});

for (const q of ["안녕하세요", "환불 정책 알려줘"]) {
  const r = await agent4.invoke({ messages: [{ role: "user", content: q }] });
  console.log(`\nQ: ${q}`);
  console.log(`  메시지 ${r.messages.length}개 / 검색 호출 ${countToolCalls(r.messages)}회`);
  assertSearched(r.messages);
}

/* 해설:
 * "안녕하세요" 는 검색 0회가 정상입니다 — 그래서 경고가 찍힙니다.
 * 즉 assertSearched 를 무조건 에러로 만들면 안 됩니다. 인사에도 화를 내니까요.
 *
 * 실무에서는 "이 질문이 사실 질문인가"를 먼저 분류하고,
 * 사실 질문인데 검색을 안 했을 때만 문제 삼습니다.
 * 아니면 아예 고전 RAG 를 써서 재량 자체를 없애는 게 낫습니다.
 *
 * 결과는 비결정적입니다. 모델이 "환불 정책 알려줘"에 검색 없이 답할 수도 있고,
 * 그게 정확히 16-8 의 마지막 함정입니다.
 */

/* ===== [정답 5] 줄 번호까지 인용하는 도구 ===== */

printSection("[정답 5] 줄 번호까지 인용하는 도구");

/** metadata.loc 는 unknown 이므로 안전하게 좁혀서 읽습니다. */
function readLines(metadata: Record<string, unknown>): string {
  const loc = metadata["loc"];
  if (typeof loc !== "object" || loc === null) return "?";
  const lines = (loc as { lines?: unknown }).lines;
  if (typeof lines !== "object" || lines === null) return "?";
  const { from, to } = lines as { from?: unknown; to?: unknown };
  if (typeof from !== "number" || typeof to !== "number") return "?";
  return `${from}-${to}`;
}

const citedSearchWithLines = tool(
  async ({ query }) => {
    const results = await store.similaritySearchWithScore(query, 3);
    if (results.length === 0) return "검색 결과가 없습니다.";
    return results
      .map(
        ([doc, score]) =>
          `<document source="${src(doc)}" lines="${readLines(doc.metadata)}" score="${score.toFixed(3)}">\n` +
          `${doc.pageContent}\n</document>`,
      )
      .join("\n\n");
  },
  {
    name: "search_with_lines",
    description:
      "Nimbus 공식 문서를 검색한다. 각 결과에 source(파일명), lines(줄 범위), score(유사도)가 붙는다.",
    schema: z.object({
      query: z.string().describe("검색어. 핵심 키워드로 다듬어라."),
    }),
  },
);

console.log(await citedSearchWithLines.invoke({ query: "환불 기간" }));

/* 해설:
 * splitDocuments 가 넣어 주는 metadata.loc.lines 는 { from, to } 구조입니다.
 * 원본 문서에서 이 청크가 몇 번째 줄이었는지를 알려 줍니다.
 *
 * 이 값이 인용에서 값진 이유: 사용자가 "정말 그렇게 쓰여 있나?"를
 * refund.md 3~5줄로 바로 넘어가 확인할 수 있게 됩니다.
 * PDF 라면 같은 자리에 page 번호를 넣습니다(16-2 의 loadPdfPages 참고).
 *
 * metadata 를 unknown 으로 읽는 게 번거로워 보이지만, tsconfig 의
 * noUncheckedIndexedAccess 가 켜져 있으면 이렇게 좁혀야 통과합니다.
 * 그리고 이건 좋은 일입니다 — loc 가 없는 Document(로더가 직접 만든 것)를
 * 넣었을 때 조용히 "undefined-undefined" 가 찍히는 걸 막아 줍니다.
 */

/* ===== [정답 6] 인용 검증 ===== */

printSection("[정답 6] 인용 검증");

// 도구가 실제로 무엇을 반환했는지 기록해 둡니다.
// 이게 없으면 "모델이 지어낸 출처"와 "진짜 출처"를 구분할 방법이 없습니다.
const retrievedSources = new Set<string>();

const trackedSearch = tool(
  async ({ query }) => {
    const results = await store.similaritySearchWithScore(query, 3);
    for (const [doc] of results) retrievedSources.add(src(doc));
    return results
      .map(([doc, score]) => `<document source="${src(doc)}" score="${score.toFixed(3)}">\n${doc.pageContent}\n</document>`)
      .join("\n\n");
  },
  {
    name: "search_docs",
    description: "Nimbus 공식 문서를 검색한다. 결과에 source 와 score 가 붙는다.",
    schema: z.object({ query: z.string().describe("검색어") }),
  },
);

const agent6 = createAgent({
  model,
  tools: [trackedSearch],
  systemPrompt: [
    "너는 Nimbus 고객 지원 담당자다.",
    "사실 질문에는 반드시 search_docs 를 호출하라.",
    "근거로 쓴 문서의 파일명만 sources 에 담아라. 지어내지 마라.",
    "근거가 없으면 '문서에서 찾을 수 없습니다'라고 답하고 sources 는 빈 배열로 두라.",
  ].join("\n"),
  responseFormat: z.object({
    answer: z.string().describe("답변"),
    sources: z.array(z.string()).describe("근거로 사용한 문서의 파일명 목록"),
  }),
});

retrievedSources.clear();
const r6 = await agent6.invoke({
  messages: [{ role: "user", content: "연간 결제를 중간에 해지하면 환불받을 수 있나요?" }],
});

console.log(JSON.stringify(r6.structuredResponse, null, 2));
console.log(`실제로 검색된 문서: ${[...retrievedSources].join(", ") || "(없음)"}`);

const fake = r6.structuredResponse.sources.filter((s) => !retrievedSources.has(s));
if (fake.length > 0) {
  console.error(`  ❌ 존재하지 않는 출처를 인용함: ${fake.join(", ")}`);
} else {
  console.log("  ✅ 모든 인용이 실제 검색 결과에 존재합니다.");
}

/* 해설:
 * → 이 검증이 필요한 이유:
 *
 * "출처를 붙여라"라고 지시하면 모델은 출처를 붙입니다. 그런데 그게 진짜라는
 * 보장은 어디에도 없습니다. 컨텍스트에 없는 policy_2024.pdf 같은 파일명을
 * 그럴듯하게 지어낼 수 있습니다.
 *
 * 그리고 이건 인용이 아예 없는 것보다 더 위험합니다. 사용자는 인용이 붙어
 * 있으면 검증됐다고 믿기 때문입니다. 환각에 신뢰의 외피를 씌워 주는 셈입니다.
 *
 * 그래서 sources ⊆ 실제 검색된 집합 인지를 반드시 코드로 검사해야 합니다.
 * 이 검사는 LLM 없이 Set 하나로 됩니다 — 공짜입니다.
 *
 * 실무에서는 fake.length > 0 일 때 에러를 던져 응답을 막고 로그를 남깁니다.
 * 여기서는 실행이 멈추지 않게 console.error 로 두었습니다.
 */

/* ===== [정답 7] 인덱싱에 캐시가 없다는 것 ===== */

printSection("[정답 7] 인덱싱에 캐시가 없다는 것");

const t1 = Date.now();
await buildIndex();
const first = Date.now() - t1;

const t2 = Date.now();
await buildIndex();
const second = Date.now() - t2;

console.log(`1회차: ${first}ms`);
console.log(`2회차: ${second}ms`);
console.log(`→ 2회차가 1회차의 ${((second / first) * 100).toFixed(0)}% — 캐시가 없습니다.`);

/* 해설:
 * → 프로덕션에서 문제가 되는 이유:
 *
 * buildIndex() 는 매번 (1) 파일을 다시 읽고 (2) 다시 자르고 (3) 다시 임베딩합니다.
 * 두 번째 호출이 첫 번째와 비슷하게 걸리는 게 그 증거입니다.
 *
 * 여기선 청크 5개라 몇백 ms 입니다. 그런데 이 숫자에 곱셈을 해 보세요.
 *
 *   - 청크 5개 → 5만 개: 임베딩 API 를 5만 번(배치로 나눠서). 레이트 리밋에
 *     걸려 수십 분. 서버가 그동안 요청을 못 받습니다.
 *   - 인스턴스 1개 → 10개: 오토스케일링으로 뜨는 인스턴스마다 전부 다시.
 *     비용도 시간도 10배. 게다가 배포할 때마다 반복됩니다.
 *   - 최악: 인덱싱을 요청 핸들러 안에 두면 질문 한 번에 이게 다 돕니다.
 *
 * 처방은 두 가지입니다.
 *   1. 인덱싱을 요청 경로 밖으로 — 배치 잡(npm run reindex)이나 시작 시 1회.
 *   2. 인덱스를 프로세스 밖으로 — pgvector 같은 진짜 벡터 DB에 저장하면
 *      재시작해도 살아 있고, 인스턴스 10개가 하나를 공유합니다.
 *
 * MemoryVectorStore 는 학습용입니다. 이 측정이 그 이유입니다.
 */

/* ===== [정답 8] 도구를 소스별로 쪼개기 ===== */

printSection("[정답 8] 도구를 소스별로 쪼개기");

const billingStore = await buildIndex(300, 60, ["refund.md", "pricing.md"]);
const technicalStore = await buildIndex(300, 60, ["limits.md", "support.md"]);

// 어느 도구가 불렸는지 기록합니다.
const calledTools: string[] = [];

const searchBilling = tool(
  async ({ query }) => {
    calledTools.push("search_billing");
    const docs = await billingStore.similaritySearch(query, 3);
    return docs.map((d) => `[${src(d)}] ${d.pageContent}`).join("\n\n");
  },
  {
    name: "search_billing",
    // description 이 곧 라우팅 규칙입니다. "무엇이 들어 있는지"를 구체적으로.
    description:
      "결제 관련 문서를 검색한다: 환불 정책(환불 기간, 부분 환불, 환불 절차)과 " +
      "요금제(플랜별 가격, 추가 과금, 할인). 돈과 관련된 질문에 사용하라.",
    schema: z.object({ query: z.string().describe("검색어") }),
  },
);

const searchTechnical = tool(
  async ({ query }) => {
    calledTools.push("search_technical");
    const docs = await technicalStore.similaritySearch(query, 3);
    return docs.map((d) => `[${src(d)}] ${d.pageContent}`).join("\n\n");
  },
  {
    name: "search_technical",
    description:
      "기술 문서를 검색한다: 사용 한도와 레이트 리밋(429, Retry-After, 초당 호출 수)과 " +
      "지원 정책(응답 시간, SLA, 지원 채널). 기술적 제약이나 지원에 관한 질문에 사용하라.",
    schema: z.object({ query: z.string().describe("검색어") }),
  },
);

const routerAgent = createAgent({
  model,
  tools: [searchBilling, searchTechnical],
  systemPrompt:
    "너는 Nimbus 고객 지원 담당자다. 질문의 성격에 맞는 검색 도구를 골라 호출하라. " +
    "필요하면 둘 다 호출해도 된다. 근거가 없으면 모른다고 답하라.",
});

for (const q of ["Pro 플랜 환불되나요?", "레이트 리밋 얼마예요?"]) {
  calledTools.length = 0;
  const r = await routerAgent.invoke({ messages: [{ role: "user", content: q }] });
  console.log(`\nQ: ${q}`);
  console.log(`  고른 도구: ${calledTools.join(", ") || "(없음 — 검색을 건너뜀)"}`);
  console.log(`  A: ${(r.messages.at(-1)?.text ?? "").slice(0, 100)}...`);
}

/* 해설:
 * 기대: "Pro 플랜 환불되나요?" → search_billing
 *       "레이트 리밋 얼마예요?" → search_technical
 *
 * 도구를 쪼개서 얻는 것:
 *   1. 검색 공간이 줄어듭니다. search_billing 은 문서 2개만 뒤지므로
 *      k=3 이 훨씬 정확해집니다. 전체를 뒤질 때 상위 3개에 무관한 문서가
 *      끼어들 자리가 없습니다.
 *   2. 소스별로 다른 k, 다른 필터, 다른 권한을 걸 수 있습니다.
 *      (예: search_hr 은 인사팀만)
 *   3. 로그에 "어느 소스를 몇 번 뒤졌나"가 남습니다. 위의 calledTools 가 그것입니다.
 *
 * 다만 도구 선택은 모델 판단이라 비결정적입니다. 결과가 기대와 다르면
 * 모델을 탓하기 전에 description 을 보세요. 대부분 원인이 거기 있습니다.
 * description 에서 "환불 정책", "레이트 리밋" 같은 구체적 단어를 빼고
 * "결제 문서를 검색한다"로만 두면 선택이 눈에 띄게 나빠집니다 — 직접 해 보세요.
 *
 * "Pro 플랜 환불되나요?" 는 사실 경계에 있는 질문입니다("Pro 플랜"은 pricing,
 * "환불"은 refund). 둘 다 search_billing 안에 있어서 다행이지만,
 * 이런 경계 질문이 많다면 도구를 쪼갠 축이 잘못된 것일 수 있습니다.
 */

console.log(`\n(실습용 지식 베이스 위치: ${kbDir})`);