feat(coins): add sample-query endpoint and resolve Freebase MIDs to names

Add GET /coins/datasets/{id}/sample-query that produces structurally
valid KG queries for all 7 query structures by delegating to
Query.instantiate() from the research code rather than hand-rolling
graph walks. Returns anchors, variables, relations, and a known target
entity — guaranteed to form a real path/intersection in the training KG.

Also resolve Freebase MID identifiers (e.g. /m/06rf7) to human-readable
names (e.g. Schleswig Holstein) using the ent2name.txt lookup table:

- Entity and relation search endpoints now return a `label` field with
cleaned display names alongside the raw `name`
- Search filtering matches against both raw names and cleaned labels,
so searching "Chicago" finds /m/01yjl (Chicago Cubs)
- sample-query and sample-triples responses carry resolved labels

docs/api.yaml

@@ -190,6 +190,58 @@ paths:
         "404":
           $ref: "#/components/responses/NotFound"
 
+  /coins/datasets/{dataset_id}/sample-query:
+    get:
+      operationId: getCoinsSampleQuery
+      tags: [coins]
+      summary: Sample a valid KG query
+      description: |
+        Walks the training knowledge graph to produce a structurally valid query
+        for the given query structure. Each returned query contains anchor entities,
+        relations, and a known target entity — guaranteed to form a real path or
+        intersection in the KG. This is the recommended way to populate the query
+        builder UI with meaningful defaults. For simple 1p (single-hop) queries the
+        result is equivalent to a random triple; for multi-hop and intersection
+        structures (2p, 3p, 2i, 3i, ip, pi) the sampler walks backward from a
+        random target through actual KG edges.
+      parameters:
+        - $ref: "#/components/parameters/CoinsDatasetId"
+        - name: query_structure
+          in: query
+          required: true
+          schema:
+            $ref: "#/components/schemas/CoinsQueryStructureEnum"
+          description: The query structure to sample for.
+        - name: count
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 10
+            default: 1
+          description: Number of sample queries to return.
+        - name: seed
+          in: query
+          required: false
+          schema:
+            type: string
+          description: |
+            Optional sampling seed for deterministic results. Same
+            `(dataset_id, query_structure, count, seed)` always yields the
+            same queries. Useful for day-stable prefills (e.g. seed by ISO date).
+          example: "2026-04-17"
+      responses:
+        "200":
+          description: Sampled queries
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CoinsSampleQueryResponse"
+        "400":
+          $ref: "#/components/responses/InvalidRequest"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
   /coins/models:
     get:
       operationId: getCoinsModels
@@ -914,6 +966,50 @@ components:
         tail:
           $ref: "#/components/schemas/CoinsEntity"
 
+    CoinsSampleQueryResponse:
+      type: object
+      required: [dataset_id, query_structure, queries]
+      properties:
+        dataset_id:
+          $ref: "#/components/schemas/CoinsDatasetIdEnum"
+        query_structure:
+          $ref: "#/components/schemas/CoinsQueryStructureEnum"
+        queries:
+          type: array
+          description: |
+            Sampled queries. Each query is a valid walk through the training KG.
+            May return fewer than `count` if the graph is too sparse for the
+            requested structure (e.g. 3i requires a target with at least 3 in-edges).
+          items:
+            $ref: "#/components/schemas/CoinsSampledQuery"
+
+    CoinsSampledQuery:
+      type: object
+      required: [anchors, relations, target]
+      description: |
+        A structurally valid query instance. `anchors` and `relations` keys match the
+        node/edge IDs from `GET /coins/query-structures` for the given structure.
+        The `target` is the known answer entity.
+      properties:
+        anchors:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/CoinsEntity"
+          description: "Anchor entities keyed by node ID (e.g. `a`, `a1`, `a2`, `a3`)."
+          example:
+            a1: { id: 123, name: "/m/06thjt", label: "06thjt" }
+            a2: { id: 456, name: "/m/0d_kd", label: "0d_kd" }
+        relations:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/CoinsRelation"
+          description: "Relations keyed by edge ID (e.g. `r1`, `r2`, `r3`)."
+          example:
+            r1: { id: 7, name: "/people/person/nationality", label: "person nationality" }
+            r2: { id: 12, name: "/location/country/capital", label: "country capital" }
+        target:
+          $ref: "#/components/schemas/CoinsEntity"
+
     CoinsModelsResponse:
       type: object
       required: [models]

docs/postman/collection.json

@@ -146,6 +146,24 @@
             "description": "Random sample triples from the dataset. Each triple has head/relation/tail entries with { id, name, label }; `label` is a dataset-specific display-friendly form of `name` (NELL strips `concept:` prefixes, Freebase strips `/m/`, WordNet drops the POS suffix). Pass an optional `seed` (any string) for deterministic sampling — e.g. seed by today's ISO date for a day-stable 'fact of the day' widget."
           }
         },
+        {
+          "name": "GET /coins/datasets/{id}/sample-query",
+          "request": {
+            "method": "GET",
+            "header": [],
+            "url": {
+              "raw": "{{base_url}}/coins/datasets/nell/sample-query?query_structure=2i&count=1&seed=2026-04-17",
+              "host": ["{{base_url}}"],
+              "path": ["coins", "datasets", "nell", "sample-query"],
+              "query": [
+                { "key": "query_structure", "value": "2i", "description": "Required. One of: 1p, 2p, 3p, 2i, 3i, ip, pi." },
+                { "key": "count", "value": "1", "description": "Number of sample queries (max 10)." },
+                { "key": "seed", "value": "2026-04-17", "description": "Optional. Deterministic sampling when provided." }
+              ]
+            },
+            "description": "Sample a structurally valid KG query by walking the training graph. Returns anchors, relations, and a known target entity that form a real path/intersection. Keys in `anchors` and `relations` match the node/edge IDs from GET /coins/query-structures. Preferred over sample-triples for multi-hop and intersection query prefills."
+          }
+        },
         {
           "name": "GET /coins/models",
           "request": {

src/backend/README.md

@@ -78,6 +78,7 @@ All endpoints are prefixed with `/api/v1/`.
 | `GET` | `/coins/datasets/{id}/entities` | Paginated entity search (`?q=&page=&page_size=`) |
 | `GET` | `/coins/datasets/{id}/relations` | Paginated relation search (`?q=&page=&page_size=`) |
 | `GET` | `/coins/datasets/{id}/sample-triples` | Random training triples (`?count=10&seed=...`); optional `seed` makes sampling deterministic (same `seed+count` ⇒ same triples, e.g. seed by ISO date for a day-stable widget). Head/relation/tail each carry a dataset-cleaned `label` alongside `id`, `name` |
+| `GET` | `/coins/datasets/{id}/sample-query` | Sample a structurally valid KG query (`?query_structure=2i&count=1&seed=...`). Walks the training graph to produce real paths/intersections. Returns `{anchors, relations, target}` keyed by node/edge IDs from `/coins/query-structures`. Preferred over `sample-triples` for multi-hop/intersection prefills |
 | `GET` | `/coins/models` | Available algorithms + supported query structures |
 | `GET` | `/coins/query-structures` | Query graph templates for frontend rendering |
 | `POST` | `/coins/predict` | Run link prediction / query answering |

src/backend/api/services/registry.py

@@ -263,6 +263,30 @@ class SubgraphInfo:
         self.subgraphs = subgraphs
 
 
+# ---------------------------------------------------------------------------
+# Query sampling — delegates to Query.instantiate() from the research code.
+#
+# _STRUCTURE_INFO maps frontend query structure IDs to:
+#   - research code structure string (e.g. "ip" -> "2i1p")
+#   - anchor_map: {query_tree_node_index: frontend_anchor_id}
+#   - variable_map: {query_tree_node_index: frontend_variable_id}
+#   - relation_map: {mapped_tree_edge_index: frontend_relation_id} for "p" edges
+#
+# After Query.instantiate() + map_to_tree(), entities live on vertices
+# and relation strings (like "p5") live on edges indexed by child node index.
+# ---------------------------------------------------------------------------
+#                    (structure,  anchor_map,                variable_map,       relation_map)
+_STRUCTURE_INFO = {
+    "1p": ("1p", {0: "a"}, {}, {0: "r1"}),
+    "2p": ("2p", {0: "a"}, {1: "v1"}, {0: "r1", 1: "r2"}),
+    "3p": ("3p", {0: "a"}, {1: "v1", 2: "v2"}, {0: "r1", 1: "r2", 2: "r3"}),
+    "2i": ("2i", {0: "a1", 2: "a2"}, {}, {0: "r1", 2: "r2"}),
+    "3i": ("3i", {0: "a1", 2: "a2", 4: "a3"}, {}, {0: "r1", 2: "r2", 4: "r3"}),
+    "ip": ("2i1p", {0: "a1", 2: "a2"}, {4: "v1"}, {0: "r1", 2: "r2", 4: "r3"}),
+    "pi": ("1p2i", {0: "a1", 3: "a2"}, {1: "v1"}, {0: "r1", 1: "r2", 3: "r3"}),
+}
+
+
 class ModelRegistry:
     _instance = None
 
@@ -523,7 +547,10 @@ class ModelRegistry:
         items = [(int(idx), str(name)) for idx, name in inv_nodes.items()]
         if query:
             q = query.lower()
-            items = [(eid, name) for eid, name in items if q in name.lower()]
+            items = [
+                (eid, name) for eid, name in items
+                if q in name.lower() or q in clean_entity_name(name, dataset_id).lower()
+            ]
         total = len(items)
         start = (max(1, page) - 1) * page_size
         return items[start:start + page_size], total
@@ -537,7 +564,10 @@ class ModelRegistry:
         items = [(int(idx), str(name)) for idx, name in inv_relations.items()]
         if query:
             q = query.lower()
-            items = [(rid, name) for rid, name in items if q in name.lower()]
+            items = [
+                (rid, name) for rid, name in items
+                if q in name.lower() or q in clean_relation_name(name, dataset_id).lower()
+            ]
         total = len(items)
         start = (max(1, page) - 1) * page_size
         return items[start:start + page_size], total
@@ -573,6 +603,94 @@ class ModelRegistry:
             })
         return result
 
+    # ---- Query sampling ---------------------------------------------------
+
+    def sample_query(self, dataset_id, query_structure, count=1, seed=None):
+        """Sample structurally valid queries using Query.instantiate() from the research code.
+
+        Picks random answer entities, walks the training graph backward via
+        adj_t_to_s to produce fully-instantiated query trees, then extracts
+        anchor entities and relation IDs mapped to frontend slot names.
+        """
+        import numpy as np
+
+        loader = self.loaders.get(dataset_id)
+        if loader is None:
+            return []
+
+        info = _STRUCTURE_INFO.get(query_structure)
+        if info is None:
+            return []
+        structure_str, anchor_map, variable_map, relation_map = info
+
+        adj_t_to_s = loader.graph_indexes[2]
+        inv_nodes, _, inv_relations = loader.dataset.get_inverted_name_maps()
+
+        coins_root = str(Path(settings.COINS_DATA_DIR).parent)
+        original_cwd = os.getcwd()
+        try:
+            os.chdir(coins_root)
+            from graph_completion.graphs.queries import Query, query_edge_r_to_int
+        finally:
+            os.chdir(original_cwd)
+
+        query = Query(structure_str)
+        query.build_query_tree()
+
+        answer_candidates = list(adj_t_to_s.keys())
+        rng = random.Random(seed) if seed is not None else random
+
+        np_state = np.random.get_state()
+        if seed is not None:
+            np.random.seed(hash(seed) % (2**32))
+
+        def ent(eid):
+            name = str(inv_nodes.get(eid, eid))
+            return {"id": eid, "name": name, "label": clean_entity_name(name, dataset_id)}
+
+        def rel(rid):
+            name = str(inv_relations.get(rid, rid))
+            return {"id": rid, "name": name, "label": clean_relation_name(name, dataset_id)}
+
+        results = []
+        max_attempts = count * 200
+        try:
+            for _ in range(max_attempts):
+                if len(results) >= count:
+                    break
+                answer = rng.choice(answer_candidates)
+                qi = next(
+                    query.instantiate(adj_t_to_s, loader.num_nodes, loader.num_relations, answer, sample=True),
+                    None,
+                )
+                if qi is None:
+                    continue
+
+                qi_mapped = qi.map_to_tree(query.query_tree)
+
+                anchors = {}
+                for tree_idx, frontend_id in anchor_map.items():
+                    anchors[frontend_id] = ent(int(qi_mapped.vs[tree_idx]["e"]))
+
+                variables = {}
+                for tree_idx, frontend_id in variable_map.items():
+                    variables[frontend_id] = ent(int(qi_mapped.vs[tree_idx]["e"]))
+
+                relations = {}
+                for edge_idx, frontend_id in relation_map.items():
+                    rel_id = query_edge_r_to_int(qi_mapped.es[edge_idx]["r"])
+                    relations[frontend_id] = rel(rel_id)
+
+                target_id = int(qi_mapped.vs[query.query_answer]["e"])
+                q = {"anchors": anchors, "relations": relations, "target": ent(target_id)}
+                if variables:
+                    q["variables"] = variables
+                results.append(q)
+        finally:
+            np.random.set_state(np_state)
+
+        return results
+
     # ---- Sample subgraph generation ------------------------------------
 
     def _generate_sample_subgraphs(self):

src/backend/api/urls.py

@@ -7,6 +7,7 @@ from api.views.coins import (
     CoinsPredictView,
     CoinsQueryStructuresView,
     CoinsRelationsView,
+    CoinsSampleQueryView,
     CoinsSampleTriplesView,
 )
 from api.views.graph_generation import (
@@ -31,6 +32,7 @@ urlpatterns = [
     path("coins/datasets/<str:dataset_id>/entities", CoinsEntitiesView.as_view()),
     path("coins/datasets/<str:dataset_id>/relations", CoinsRelationsView.as_view()),
     path("coins/datasets/<str:dataset_id>/sample-triples", CoinsSampleTriplesView.as_view()),
+    path("coins/datasets/<str:dataset_id>/sample-query", CoinsSampleQueryView.as_view()),
     path("coins/models", CoinsModelsView.as_view()),
     path("coins/query-structures", CoinsQueryStructuresView.as_view()),
     path("coins/predict", CoinsPredictView.as_view()),

src/backend/api/utils.py

@@ -1,6 +1,31 @@
+from pathlib import Path
+
+from django.conf import settings
+
+_freebase_ent2name = None
+
+
+def _get_freebase_ent2name():
+    global _freebase_ent2name
+    if _freebase_ent2name is None:
+        path = Path(settings.COINS_DATA_DIR) / "FB15k-237" / "ent2name.txt"
+        mapping = {}
+        if path.exists():
+            with open(path, encoding="utf-8") as f:
+                for line in f:
+                    parts = line.rstrip("\n").split(None, 1)
+                    if len(parts) == 2:
+                        mapping[parts[0]] = parts[1].replace("_", " ")
+        _freebase_ent2name = mapping
+    return _freebase_ent2name
+
+
 def clean_entity_name(name: str, dataset_id: str) -> str:
-    """Apply dataset-specific entity name cleaning for display (from graph_generation/src/main.py)."""
+    """Apply dataset-specific entity name cleaning for display."""
     if dataset_id == "freebase":
+        resolved = _get_freebase_ent2name().get(name)
+        if resolved:
+            return resolved
         return name.replace("/m/", "")
     elif dataset_id == "wordnet":
         return name.split(".")[0]

src/backend/api/views/coins.py

@@ -7,6 +7,7 @@ from api.services.constants import (
     QUERY_STRUCTURE_INTERNAL, QUERY_TREE_MAPPINGS,
 )
 from api.services.registry import ModelRegistry
+from api.utils import clean_entity_name, clean_relation_name
 
 
 def _require_loader(dataset_id):
@@ -49,7 +50,10 @@ class CoinsEntitiesView(APIView):
             "total": total,
             "page": page,
             "page_size": page_size,
-            "entities": [{"id": eid, "name": name} for eid, name in page_items],
+            "entities": [
+                {"id": eid, "name": name, "label": clean_entity_name(name, dataset_id)}
+                for eid, name in page_items
+            ],
         })
 
 
@@ -68,7 +72,10 @@ class CoinsRelationsView(APIView):
             "total": total,
             "page": page,
             "page_size": page_size,
-            "relations": [{"id": rid, "name": name} for rid, name in page_items],
+            "relations": [
+                {"id": rid, "name": name, "label": clean_relation_name(name, dataset_id)}
+                for rid, name in page_items
+            ],
         })
 
 
@@ -87,6 +94,30 @@ class CoinsSampleTriplesView(APIView):
         })
 
 
+class CoinsSampleQueryView(APIView):
+    def get(self, request, dataset_id):
+        registry = _require_loader(dataset_id)
+        query_structure = request.query_params.get("query_structure")
+        if not query_structure:
+            raise InvalidRequestError("Missing required parameter: query_structure")
+        valid_qs = {qs["id"] for qs in QUERY_STRUCTURES}
+        if query_structure not in valid_qs:
+            raise InvalidRequestError(
+                f"Unknown query_structure '{query_structure}'. Must be one of: {sorted(valid_qs)}"
+            )
+        count = int(request.query_params.get("count", 1))
+        count = max(1, min(10, count))
+        seed_raw = request.query_params.get("seed")
+        seed = seed_raw if seed_raw not in (None, "") else None
+
+        queries = registry.sample_query(dataset_id, query_structure, count, seed=seed)
+        return Response({
+            "dataset_id": dataset_id,
+            "query_structure": query_structure,
+            "queries": queries,
+        })
+
+
 class CoinsModelsView(APIView):
     def get(self, request):
         registry = ModelRegistry.get()