refs #737: move game query planning into ADB MCP tool

2026-07-27 16:39:58 +09:00
parent 5a3b03060d
commit 8298ecb511
6 changed files with 263 additions and 288 deletions
--- a/vpd-backoffice/src/main/java/com/cloudhandson/vpdbackoffice/service/GameCatalogVectorService.java
+++ b/vpd-backoffice/src/main/java/com/cloudhandson/vpdbackoffice/service/GameCatalogVectorService.java
@@ -3,6 +3,7 @@ package com.cloudhandson.vpdbackoffice.service;
 import com.cloudhandson.vpdbackoffice.config.BackofficeProperties;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
 import java.sql.CallableStatement;
 import java.sql.Clob;
 import java.sql.Connection;
@@ -11,15 +12,17 @@ import java.sql.ResultSet;
 import java.sql.SQLException;
 import java.sql.Types;
 import java.util.ArrayList;
-import java.util.Comparator;
-import java.util.LinkedHashMap;
 import java.util.List;
-import java.util.Locale;
-import java.util.Map;
-import java.util.Optional;
-import java.util.stream.Stream;
 import org.springframework.stereotype.Service;

+/**
+ * MCP database gateway for the ADB-owned game query planning functions.
+ *
+ * <p>Game mention extraction, vector candidate retrieval, and OCI GenAI
+ * candidate selection run inside {@code SG_GAME_QUERY_PLAN}. Java validates
+ * authentication and transports the structured JSON result without applying
+ * game-name matching rules.</p>
+ */
@Service
 public class GameCatalogVectorService {

@@ -37,76 +40,38 @@ public class GameCatalogVectorService {
    this.objectMapper = objectMapper;
  }

-  /**
-   * Resolves each extracted game mention independently.
-   *
-   * <p>Vector search supplies candidates. A candidate becomes executable only
-   * when the extracted mention also matches catalog identity text. This keeps
-   * an unknown mention from inheriting the nearest unrelated game while
-   * retaining the original mention for partial-result reporting.</p>
-   */
-  public Resolution resolve(String token, String question, int topK) {
+  public ObjectNode queryPlan(
+      String token, String question, int topK
+  ) {
    requireActiveToken(token);
-    JsonNode extracted;
-    try {
-      extracted = objectMapper.readTree(extractMentions(question));
-    } catch (Exception exception) {
-      throw new AppException(
-          "게임명 추출 결과 JSON 파싱 실패: " + exception.getMessage());
-    }
-
-    String scopeType = extracted.path("scope_hint").asText("UNKNOWN");
-    Map<String, MentionResolution> mentionsByNormalizedText =
-        new LinkedHashMap<>();
-    Map<String, GameCandidate> supportedByGameKey = new LinkedHashMap<>();
-
-    for (JsonNode item : extracted.path("game_mentions")) {
-      String mention = item.asText("").trim();
-      String normalizedMention = normalizeIdentity(mention);
-      if (normalizedMention.isEmpty()
-          || mentionsByNormalizedText.containsKey(normalizedMention)) {
-        continue;
-      }
-
-      List<GameCandidate> candidates = search(token, mention, topK);
-      Optional<GameCandidate> matched =
-          selectMatchedCandidate(mention, candidates);
-      MentionResolution resolution;
-      if (matched.isPresent()) {
-        GameCandidate game = matched.get();
-        supportedByGameKey.putIfAbsent(game.gameKey(), game);
-        resolution = new MentionResolution(
-            mention, "MATCHED", game, candidates);
-      } else {
-        resolution = new MentionResolution(
-            mention, "UNMATCHED", null, candidates);
-      }
-      mentionsByNormalizedText.put(normalizedMention, resolution);
-    }
-
-    return new Resolution(
-        scopeType,
-        List.copyOf(supportedByGameKey.values()),
-        List.copyOf(mentionsByNormalizedText.values())
-    );
-  }
-
-  private String extractMentions(String question) {
    BackofficeProperties.SelectAi database = requiredDatabase();
    try (Connection connection = DriverManager.getConnection(
        database.dbUrl(), database.dbUsername(), database.dbPassword());
         CallableStatement statement = connection.prepareCall(
-             "{ ? = call sg_game_extract_mentions(?) }")) {
+             "{ ? = call sg_game_query_plan(?, ?) }")) {
      statement.registerOutParameter(1, Types.CLOB);
      statement.setString(2, question);
+      statement.setInt(3, boundedTopK(topK));
      statement.execute();
      Clob value = (Clob) statement.getObject(1);
-      return value == null
-          ? "{\"game_mentions\":[],\"scope_hint\":\"UNKNOWN\"}"
-          : value.getSubString(1, (int) value.length());
+      String raw = value == null ? "" :
+          value.getSubString(1, (int) value.length());
+      JsonNode parsed = objectMapper.readTree(raw);
+      if (!(parsed instanceof ObjectNode plan)
+          || !plan.hasNonNull("status")
+          || !plan.path("supportedGames").isArray()
+          || !plan.path("unmatchedGames").isArray()) {
+        throw new AppException("ADB 게임 질의 계획 응답 형식이 올바르지 않습니다.");
+      }
+      return plan;
    } catch (SQLException exception) {
      throw new AppException(
-          "ADB 게임명 추출 실패: " + exception.getMessage());
+          "ADB 게임 질의 계획 실패: " + exception.getMessage());
+    } catch (AppException exception) {
+      throw exception;
+    } catch (Exception exception) {
+      throw new AppException(
+          "ADB 게임 질의 계획 JSON 파싱 실패: " + exception.getMessage());
    }
  }

@@ -122,7 +87,7 @@ public class GameCatalogVectorService {
             "{ ? = call sg_game_catalog_search(?, ?) }")) {
      statement.registerOutParameter(1, Types.REF_CURSOR);
      statement.setString(2, question);
-      statement.setInt(3, Math.min(Math.max(topK, 1), 20));
+      statement.setInt(3, boundedTopK(topK));
      statement.execute();
      try (ResultSet rows = (ResultSet) statement.getObject(1)) {
        while (rows.next()) {
@@ -143,40 +108,8 @@ public class GameCatalogVectorService {
    }
  }

-  static Optional<GameCandidate> selectMatchedCandidate(
-      String mention, List<GameCandidate> candidates
-  ) {
-    String normalizedMention = normalizeIdentity(mention);
-    if (normalizedMention.isEmpty()) {
-      return Optional.empty();
-    }
-    return candidates.stream()
-        .filter(candidate -> identityFields(candidate)
-            .map(GameCatalogVectorService::normalizeIdentity)
-            .anyMatch(field -> field.contains(normalizedMention)))
-        .min(Comparator.comparingDouble(GameCandidate::similarity));
-  }
-
-  private static Stream<String> identityFields(GameCandidate candidate) {
-    return Stream.of(
-        nullToEmpty(candidate.gameKey()),
-        nullToEmpty(candidate.gameId()),
-        nullToEmpty(candidate.gamePrefix()),
-        nullToEmpty(candidate.gameName()),
-        nullToEmpty(candidate.aliases())
-    );
-  }
-
-  private static String normalizeIdentity(String value) {
-    if (value == null) {
-      return "";
-    }
-    return value.toUpperCase(Locale.ROOT)
-        .replaceAll("[\\s\\p{Punct}]", "");
-  }
-
-  private static String nullToEmpty(String value) {
-    return value == null ? "" : value;
+  static int boundedTopK(int topK) {
+    return Math.min(Math.max(topK, 1), 20);
  }

  private BackofficeProperties.SelectAi requiredDatabase() {
@@ -204,23 +137,4 @@ public class GameCatalogVectorService {
      String aliases,
      double similarity
  ) {}
-
-  public record MentionResolution(
-      String mention,
-      String status,
-      GameCandidate matchedGame,
-      List<GameCandidate> candidates
-  ) {}
-
-  public record Resolution(
-      String scopeType,
-      List<GameCandidate> candidates,
-      List<MentionResolution> mentions
-  ) {
-    public Resolution(
-        String scopeType, List<GameCandidate> candidates
-    ) {
-      this(scopeType, candidates, List.of());
-    }
-  }
 }
--- a/vpd-backoffice/src/main/java/com/cloudhandson/vpdbackoffice/service/McpSseService.java
+++ b/vpd-backoffice/src/main/java/com/cloudhandson/vpdbackoffice/service/McpSseService.java
@@ -200,12 +200,12 @@ public class McpSseService {
      } else if (gameScopeTool) {
        response = gameScopeResponse(gameScopeService.resolve(
            token, arguments.path("question").asText("")));
-      } else if (gameCatalogTool) {
-        response = gameCatalogVectorResponse(gameCatalogVectorService.resolve(
-            token, arguments.path("question").asText(""), arguments.path("topK").asInt(5)));
-      } else if (gameQueryPlanTool) {
-        response = gameQueryPlanResponse(gameCatalogVectorService.resolve(
-            token, arguments.path("question").asText(""), arguments.path("topK").asInt(5)));
+      } else if (gameCatalogTool || gameQueryPlanTool) {
+        response = gameCatalogVectorService.queryPlan(
+            token,
+            arguments.path("question").asText(""),
+            arguments.path("topK").asInt(5)
+        );
      } else {
        String prompt = arguments.path("prompt").asText("");
        response = queryTool
@@ -258,50 +258,6 @@ public class McpSseService {
    return response;
  }

-  private ObjectNode gameCatalogVectorResponse(GameCatalogVectorService.Resolution resolution) {
-    ObjectNode response = objectMapper.createObjectNode();
-    response.put("scopeType", resolution.scopeType());
-    boolean hasUnmatched = resolution.mentions().stream()
-        .anyMatch(mention -> "UNMATCHED".equals(mention.status()));
-    response.put("status", resolution.candidates().isEmpty()
-        ? "NO_MATCH" : hasUnmatched ? "PARTIAL" : "CANDIDATES");
-    ArrayNode items = response.putArray("matchedGames");
-    for (GameCatalogVectorService.GameCandidate c : resolution.candidates()) {
-      addGameCandidate(items.addObject(), c, true);
-    }
-    ArrayNode mentionResults = response.putArray("mentionResults");
-    for (GameCatalogVectorService.MentionResolution mention
-        : resolution.mentions()) {
-      ObjectNode item = mentionResults.addObject();
-      item.put("mention", mention.mention());
-      item.put("status", mention.status());
-      if (mention.matchedGame() != null) {
-        item.put("matchedGameKey", mention.matchedGame().gameKey());
-      }
-      ArrayNode candidates = item.putArray("candidateGames");
-      for (GameCatalogVectorService.GameCandidate candidate
-          : mention.candidates()) {
-        addGameCandidate(candidates.addObject(), candidate, false);
-      }
-    }
-    return response;
-  }
-
-  private void addGameCandidate(
-      ObjectNode item,
-      GameCatalogVectorService.GameCandidate candidate,
-      boolean includeAliases
-  ) {
-    item.put("gameKey", candidate.gameKey());
-    item.put("gameId", candidate.gameId());
-    item.put("gamePrefix", candidate.gamePrefix());
-    item.put("gameName", candidate.gameName());
-    if (includeAliases) {
-      item.put("aliases", candidate.aliases());
-    }
-    item.put("cosineDistance", candidate.similarity());
-  }
-
  private ObjectNode qaVectorStoreResponse(QaVectorService.VectorStoreResult stored) {
    ObjectNode response = objectMapper.createObjectNode();
    response.put("status", "QA_VECTOR_STORED");
@@ -409,44 +365,6 @@ public class McpSseService {
        -1L, "게임 질의 계획", SELECT_AI_TOOL_PATH);
  }

-  private ObjectNode gameQueryPlanResponse(GameCatalogVectorService.Resolution resolution) {
-    ObjectNode response = gameCatalogVectorResponse(resolution);
-    List<GameCatalogVectorService.MentionResolution> unmatchedMentions =
-        resolution.mentions().stream()
-            .filter(mention -> "UNMATCHED".equals(mention.status()))
-            .toList();
-    response.put("status", resolution.candidates().isEmpty()
-        ? "NO_MATCH" : unmatchedMentions.isEmpty() ? "SUPPORTED" : "PARTIAL");
-    ArrayNode supported = response.putArray("supportedGames");
-    for (GameCatalogVectorService.GameCandidate c : resolution.candidates()) {
-      ObjectNode item = supported.addObject();
-      item.put("gameKey", c.gameKey());
-      item.put("gameId", c.gameId());
-      item.put("gameName", c.gameName());
-      item.put("gamePrefix", c.gamePrefix());
-      item.put("cosineDistance", c.similarity());
-    }
-    ArrayNode unmatched = response.putArray("unmatchedGames");
-    for (GameCatalogVectorService.MentionResolution mention
-        : unmatchedMentions) {
-      ObjectNode item = unmatched.addObject();
-      item.put("mention", mention.mention());
-      item.put("reasonCode", "NO_CATALOG_IDENTITY_MATCH");
-    }
-    response.put("nextAction", resolution.candidates().isEmpty()
-        ? "STOP_NO_MATCH"
-        : ("MULTI_GAME".equals(resolution.scopeType())
-            ? "CALL_FEWSHOT_PER_GAME" : "CALL_FEWSHOT"));
-    String mode = switch (resolution.scopeType()) {
-      case "SINGLE_GAME" -> "SINGLE";
-      case "MULTI_GAME" -> "FAN_OUT";
-      case "ALL_GAMES" -> "GROUPED";
-      default -> "BLOCKED";
-    };
-    response.put("executionMode", mode);
-    return response;
-  }
-
  private String selectAiProfile() {
    BackofficeProperties.SelectAi selectAi = properties == null ? null : properties.selectAi();
    if (selectAi == null || selectAi.profile() == null || selectAi.profile().isBlank()) {