GraphRAG로 자연어 질의 풀기 — 자연어→Cypher→답변 합성

const SCHEMA = `
Labels:
- Post(slug, title, description, publishedAt, updatedAt)
- Tag(name)
- Series(name)
- Category(slug)
- Author(name, url)
- ExternalResource(url, title)

Relationships:
- (Post)-[:WRITTEN_BY]->(Author)
- (Post)-[:HAS_TAG]->(Tag)
- (Post)-[:IN_CATEGORY]->(Category)
- (Post)-[:BELONGS_TO_SERIES]->(Series)
- (Post)-[:CITES]->(ExternalResource)
- (Post)-[:RELATED_TO]->(Post)
- (Post)-[:PREREQUISITE_OF]->(Post)  // prereq -> 후속
`

const cypherTool = {
  name: "run_cypher",
  description: "Neo4j에서 Cypher를 실행한다. 읽기 전용 쿼리만 허용.",
  input_schema: {
    type: "object",
    properties: {
      cypher: { type: "string", description: "MATCH/WHERE/RETURN만 사용" },
      params: { type: "object", description: "$파라미터 바인딩 값" },
      explanation: {
        type: "string",
        description: "이 쿼리가 질의를 어떻게 푸는지 한 줄",
      },
    },
    required: ["cypher", "explanation"],
  },
}

async function naturalToCypher(question) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    system: [
      {
        type: "text",
        text: `당신은 Neo4j Cypher 쿼리 생성기입니다.\n\n스키마:\n${SCHEMA}\n\n규칙:\n- 위 라벨·관계만 사용\n- 쓰기 명령(CREATE/MERGE/DELETE/SET) 금지\n- 결과는 명시적으로 LIMIT 25 이하`,
        cache_control: { type: "ephemeral" },
      },
    ],
    tools: [cypherTool],
    tool_choice: { type: "tool", name: "run_cypher" },
    messages: [{ role: "user", content: question }],
  })

  return response.content.find(b => b.type === "tool_use").input
}

function isReadOnly(cypher) {
  const upper = cypher.toUpperCase()
  return !/\b(CREATE|MERGE|DELETE|SET|REMOVE|DROP|CALL\s+APOC\.PERIODIC)\b/.test(
    upper
  )
}

async function executeCypher(session, { cypher, params }) {
  if (!isReadOnly(cypher)) throw new Error("쓰기 쿼리 거부")
  const result = await session.executeRead(tx => tx.run(cypher, params ?? {}))
  return result.records.map(r => r.toObject())
}

CREATE VECTOR INDEX post_body_idx IF NOT EXISTS
FOR (p:Post) ON (p.embedding)
OPTIONS {indexConfig: {
  `vector.dimensions`: 1536,
  `vector.similarity_function`: 'cosine'
}};

async function vectorSearch(session, question, topK = 5) {
  const embedding = await embed(question) // 임베딩 함수
  const result = await session.executeRead(tx =>
    tx.run(
      `CALL db.index.vector.queryNodes('post_body_idx', $topK, $embedding)
       YIELD node, score
       RETURN node.slug AS slug, node.title AS title, score`,
      { embedding, topK }
    )
  )
  return result.records.map(r => r.toObject())
}

const routerTool = {
  name: "route_query",
  input_schema: {
    type: "object",
    properties: {
      mode: { type: "string", enum: ["graph", "vector", "hybrid"] },
      reason: { type: "string" },
    },
    required: ["mode", "reason"],
  },
}

mode 선택:
- graph: 명확한 엔티티/관계가 보이는 질의 (시리즈, 태그, 인용, 선수 글 등)
- vector: 의미적 유사성 기반 탐색 ("~한 글", "비슷한 내용")
- hybrid: 둘 다 필요할 때

async function synthesize(question, graphRows, vectorRows) {
  const context = JSON.stringify({ graphRows, vectorRows }, null, 2)
  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    system:
      "주어진 결과만으로 답하세요. 결과에 없는 사실은 만들지 마세요. 마지막에 근거가 된 글 slug 목록을 [refs: ...] 형태로 첨부합니다.",
    messages: [
      {
        role: "user",
        content: `질문: ${question}\n\n검색 결과:\n${context}`,
      },
    ],
  })
  return response.content[0].text
}

async function ask(session, question) {
  // 1) 라우팅
  const { mode } = await route(question)

  // 2) 채널별 검색
  let graphRows = [],
    vectorRows = []
  if (mode === "graph" || mode === "hybrid") {
    const { cypher, params } = await naturalToCypher(question)
    graphRows = await executeCypher(session, { cypher, params })
  }
  if (mode === "vector" || mode === "hybrid") {
    vectorRows = await vectorSearch(session, question)
  }

  // 3) 답변 합성
  return synthesize(question, graphRows, vectorRows)
}