fix(coins): score full hit community instead of only valid answers

Step 2 used to filter candidate entities to the set returned by
get_all_answers, so the link ranker only ever scored entities already
known to satisfy the query. Top-K therefore showed at most one row when
a community had a single valid answer, and the reported speedup hid the
fact that the model was not actually discriminating against negatives.

Now Step 2 mirrors rank_samples (experiments.py:782-786): the hit
community is the first one in step-1 order containing any valid answer,
and we score every entity in it minus the anchors. Predictions carry an
is_valid_answer flag so the UI can mark genuine hits with a check icon.
Scoring is mini-batched at 512 to bound CPU memory on large communities.

The OpenAPI CoinsPrediction schema gains the required is_valid_answer
boolean to keep clients in sync.

docs/api.yaml

@@ -1175,7 +1175,7 @@ components:
 
     CoinsPrediction:
       type: object
-      required: [rank, intra_community_rank, entity_id, entity_name, score]
+      required: [rank, intra_community_rank, entity_id, entity_name, score, is_valid_answer]
       properties:
         rank:
           type: integer
@@ -1200,6 +1200,14 @@ components:
           type: number
           format: float
           example: 0.923
+        is_valid_answer:
+          type: boolean
+          description: |
+            True if this entity actually satisfies the query in the KG (i.e. is a member of
+            `get_all_answers`). Step 2 scores every entity in the hit community, so any
+            prediction may be a non-answer the model surfaced — the flag lets the frontend
+            mark the genuine hits.
+          example: true
 
     CoinsTiming:
       type: object

src/backend/api/services/coins_inference.py

@@ -17,6 +17,11 @@ from api.utils import clean_entity_name, clean_relation_name
 from graph_completion.graphs.queries import Query, get_all_answers, get_node_cut_cache, query_edge_r_to_int
 from graph_completion.graphs.preprocess import QueryData
 
+# Step-2 mini-batch cap: the link-ranker runs a full forward pass per candidate,
+# and the hit community can hold thousands of nodes on Freebase. Splitting keeps
+# CPU memory bounded without changing results.
+SCORING_MINI_BATCH_SIZE = 512
+
 
 def coins_predict_inner(experiment, dataset_id, algorithm, query_structure_id,
                         anchors, variables, relations_map, top_k):
@@ -104,8 +109,11 @@ def coins_predict_inner(experiment, dataset_id, algorithm, query_structure_id,
     community_order = community_scores.argsort(descending=True)  # [K]
     step1_ms = (time.perf_counter() - t1_start) * 1000.0
 
-    # ---- Step 2: Search communities in descending step-1 score order ----
-    # Mirrors rank_samples: get_all_answers pre-filters to KG-valid answers.
+    # ---- Step 2: Score every entity in the hit community ----
+    # Mirrors rank_samples (experiments.py:782-786): the hit community is the
+    # first one in step-1 order that contains *any* KG-valid answer; within it
+    # we score all entities (minus anchors) so the link ranker actually has to
+    # discriminate, instead of being handed only the known answers.
     t2_start = time.perf_counter()
 
     valid_answers = set(get_all_answers(qi_skeleton, query, adj_s_to_t))
@@ -114,68 +122,70 @@ def coins_predict_inner(experiment, dataset_id, algorithm, query_structure_id,
             "No entities in the knowledge graph satisfy this query"
         )
 
-    valid_qi_mappeds, valid_candidates = [], []
+    anchor_entity_ids = {
+        entities_skeleton[i] for i in query.query_anchors if entities_skeleton[i] != -1
+    }
+
     rank_c = 0           # 1-based rank of the hit community (0 = no hit)
     c_err = 0            # sum of sizes of communities with better step-1 score than the hit
     community_size = 0   # size of the hit community
+    candidates = []
 
     for rank_0indexed in range(num_communities):
         cid = int(community_order[rank_0indexed].item())
         c_entities_tensor = (community_membership == cid).nonzero(as_tuple=True)[0]
         c_size = int(c_entities_tensor.shape[0])
-
         c_entities = [int(e.item()) for e in c_entities_tensor]
-        scored_candidates = [e for e in c_entities if e in valid_answers]
-
-        for candidate in scored_candidates:
-            # Build qi_m directly: anchor + resolved-variable positions stay fixed;
-            # answer and phantom intersection nodes receive the candidate entity.
-            qi_m = qi_skeleton.copy()
-            qi_m.vs["e"] = [
-                entities_skeleton[i] if entities_skeleton[i] != -1 else candidate
-                for i in range(num_tree_nodes)
-            ]
-            valid_qi_mappeds.append(qi_m)
-            valid_candidates.append(candidate)
-
-        if valid_qi_mappeds:
+
+        if any(e in valid_answers for e in c_entities):
             rank_c = rank_0indexed + 1
             community_size = c_size
+            candidates = [e for e in c_entities if e not in anchor_entity_ids]
             break
 
         c_err += c_size
 
-    if not valid_qi_mappeds:
+    if not candidates:
         raise InvalidRequestError(
             "No entities in the knowledge graph satisfy this query"
         )
 
-    # Build batched QueryData and score in one forward pass
-    n_valid = len(valid_qi_mappeds)
+    n_candidates = len(candidates)
+    candidates_tensor = pt.tensor(candidates, dtype=pt.long, device=device)
+
+    # Build per-tree-node entity columns. Anchor / resolved-variable positions
+    # repeat the same id across the batch; the answer and phantom-i positions
+    # take each candidate.
     e_batch, x_batch, c_batch, edge_attr_batch = [], [], [], []
     for i in range(num_tree_nodes):
-        entities_i = pt.tensor([qm.vs[i]["e"] for qm in valid_qi_mappeds], dtype=pt.long, device=device)
+        if entities_skeleton[i] == -1:
+            entities_i = candidates_tensor
+        else:
+            entities_i = pt.full([n_candidates], entities_skeleton[i], dtype=pt.long, device=device)
         e_batch.append(entities_i)
         x_batch.append(one_hot(node_types_tensor[entities_i], num_node_types).float())
         c_batch.append(community_membership[entities_i])
     for j in range(num_tree_edges):
-        r_label = valid_qi_mappeds[0].es[j]["r"]
+        r_label = qi_skeleton.es[j]["r"]
         if "p" in r_label:
             r_id = int(r_label[1:])
             edge_attr_batch.append(
-                one_hot(pt.full([n_valid], r_id, dtype=pt.long, device=device), num_relations + 1).float()
+                one_hot(pt.full([n_candidates], r_id, dtype=pt.long, device=device), num_relations + 1).float()
             )
         else:
             edge_attr_batch.append(
-                one_hot(pt.full([n_valid], num_relations, dtype=pt.long, device=device), num_relations + 1).float()
+                one_hot(pt.full([n_candidates], num_relations, dtype=pt.long, device=device), num_relations + 1).float()
             )
 
     with pt.no_grad():
         batched_query = QueryData(query, e=e_batch, x=x_batch, c=c_batch, edge_attr=edge_attr_batch)
-        q_emb, a_emb = embedder(batched_query)
-        scores = link_ranker(q_emb, a_emb).view(-1)  # ensure 1D even for batch_size=1
+        score_chunks = []
+        for chunk in batched_query.batch_split(SCORING_MINI_BATCH_SIZE):
+            q_emb, a_emb = embedder(chunk)
+            score_chunks.append(link_ranker(q_emb, a_emb).view(-1))
+        scores = pt.cat(score_chunks)
 
-    k = min(top_k, n_valid)
+    k = min(top_k, n_candidates)
     top_scores, top_indices = scores.topk(k)
     step2_ms = (time.perf_counter() - t2_start) * 1000.0
 
@@ -183,7 +193,7 @@ def coins_predict_inner(experiment, dataset_id, algorithm, query_structure_id,
     inv_nodes, _, _ = loader.dataset.get_inverted_name_maps()
     predictions = []
     for intra_community_rank, (idx, score) in enumerate(zip(top_indices.tolist(), top_scores.tolist()), 1):
-        entity_id = valid_candidates[idx]
+        entity_id = candidates[idx]
         raw_name = str(inv_nodes.get(entity_id, entity_id))
         predictions.append({
             "intra_community_rank": intra_community_rank,
@@ -191,6 +201,7 @@ def coins_predict_inner(experiment, dataset_id, algorithm, query_structure_id,
             "entity_id": entity_id,
             "entity_name": clean_entity_name(raw_name, dataset_id),
             "score": round(float(score), 4),
+            "is_valid_answer": entity_id in valid_answers,
         })
 
     total_ms = step1_ms + step2_ms

src/frontend/src/components/coins/PredictionList.vue

@@ -19,7 +19,14 @@ function barWidth(score) {
           #{{ p.rank }}
         </div>
         <div class="pred-body">
-          <div class="pred-name" :title="`entity id ${p.entity_id}`">{{ p.entity_name }}</div>
+          <div class="pred-name" :title="`entity id ${p.entity_id}`">
+            {{ p.entity_name }}
+            <i
+              v-if="p.is_valid_answer"
+              class="check circle icon valid-flag"
+              title="Known KG answer — this entity actually satisfies the query"
+            ></i>
+          </div>
           <div class="pred-bar">
             <div class="pred-bar-fill" :style="{ width: barWidth(p.score) }"></div>
           </div>
@@ -55,6 +62,7 @@ function barWidth(score) {
 }
 .pred-body { min-width: 0; }
 .pred-name { font-weight: 600; word-break: break-word; }
+.pred-name .valid-flag { color: var(--primary-strong); margin-left: 0.35rem; font-size: 0.95em; }
 .pred-bar {
   width: 100%;
   height: 6px;