feat(coins): add optional seed param and label fields to sample-triples

- registry.sample_triples now accepts seed= for deterministic sampling
via random.Random(seed); omitted seed preserves prior random behaviour
- Each head/relation/tail gains a dataset-cleaned label alongside id and
name (NELL strips concept:, Freebase strips /m/, WordNet drops POS
suffix) so the frontend can show display-friendly strings without
duplicating the cleanup logic
- OpenAPI, Postman collection, and backend README updated in lockstep
- Enables a day-stable NELL Fact of the Day widget seeded by ISO date

docs/api.yaml

@@ -169,6 +169,17 @@ paths:
             maximum: 50
             default: 10
           description: Number of random triples to return
+        - name: seed
+          in: query
+          required: false
+          schema:
+            type: string
+          description: |
+            Optional sampling seed. When provided, sampling is deterministic —
+            the same `(dataset_id, count, seed)` always yields the same triples.
+            Useful for day-stable "fact of the day" widgets (e.g. seed by the
+            ISO date). When omitted, sampling is fully random.
+          example: "2026-04-15"
       responses:
         "200":
           description: Sample triples
@@ -844,6 +855,10 @@ components:
         name:
           type: string
           example: dog's_breakfast.n.01
+        label:
+          type: string
+          description: Dataset-specific short, display-friendly form of `name`. Only present on sample-triples responses.
+          example: dog's_breakfast
 
     CoinsRelationsResponse:
       type: object
@@ -872,6 +887,10 @@ components:
         name:
           type: string
           example: _hypernym
+        label:
+          type: string
+          description: Dataset-specific short, display-friendly form of `name`. Only present on sample-triples responses.
+          example: hypernym
 
     CoinsSampleTriplesResponse:
       type: object

docs/postman/collection.json

@@ -135,14 +135,15 @@
             "method": "GET",
             "header": [],
             "url": {
-              "raw": "{{base_url}}/coins/datasets/wordnet/sample-triples?count=5",
+              "raw": "{{base_url}}/coins/datasets/wordnet/sample-triples?count=5&seed=2026-04-15",
               "host": ["{{base_url}}"],
               "path": ["coins", "datasets", "wordnet", "sample-triples"],
               "query": [
-                { "key": "count", "value": "5" }
+                { "key": "count", "value": "5" },
+                { "key": "seed", "value": "2026-04-15", "description": "Optional. When provided, sampling is deterministic (same seed + count ⇒ same triples). Omit for random." }
               ]
             },
-            "description": "Random sample triples from the dataset."
+            "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."
           }
         },
         {

src/backend/README.md

@@ -77,7 +77,7 @@ All endpoints are prefixed with `/api/v1/`.
 | `GET` | `/coins/datasets` | List datasets with entity/relation counts |
 | `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`) |
+| `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/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

@@ -8,6 +8,7 @@ import yaml
 from django.conf import settings
 
 from api.services.constants import COINS_CONFIG_SUFFIX, COINS_DATASET_META
+from api.utils import clean_entity_name, clean_relation_name
 
 logger = logging.getLogger(__name__)
 
@@ -530,8 +531,13 @@ class ModelRegistry:
         start = (max(1, page) - 1) * page_size
         return items[start:start + page_size], total
 
-    def sample_triples(self, dataset_id, count=10):
-        """Return random triples with resolved entity/relation names."""
+    def sample_triples(self, dataset_id, count=10, seed=None):
+        """Return random triples with resolved entity/relation names.
+
+        When ``seed`` is provided, sampling is deterministic — the same
+        ``(dataset_id, count, seed)`` always yields the same triples. When
+        ``seed`` is None, uses the global RNG.
+        """
         loader = self.loaders.get(dataset_id)
         if loader is None:
             return []
@@ -539,16 +545,20 @@ class ModelRegistry:
         edge_data = loader.train_edge_data
         count = min(count, len(edge_data))
 
-        indices = random.sample(range(len(edge_data)), count)
+        rng = random.Random(seed) if seed is not None else random
+        indices = rng.sample(range(len(edge_data)), count)
 
         result = []
         for i in indices:
             row = edge_data.iloc[i]
             h, r, t = int(row.s), int(row.r), int(row.t)
+            h_name = str(inv_nodes.get(h, h))
+            r_name = str(inv_relations.get(r, r))
+            t_name = str(inv_nodes.get(t, t))
             result.append({
-                "head": {"id": h, "name": str(inv_nodes.get(h, h))},
-                "relation": {"id": r, "name": str(inv_relations.get(r, r))},
-                "tail": {"id": t, "name": str(inv_nodes.get(t, t))},
+                "head": {"id": h, "name": h_name, "label": clean_entity_name(h_name, dataset_id)},
+                "relation": {"id": r, "name": r_name, "label": clean_relation_name(r_name, dataset_id)},
+                "tail": {"id": t, "name": t_name, "label": clean_entity_name(t_name, dataset_id)},
             })
         return result
 

src/backend/api/views/coins.py

@@ -78,9 +78,12 @@ class CoinsSampleTriplesView(APIView):
         count = int(request.query_params.get("count", 10))
         count = max(1, min(50, count))
 
+        seed_raw = request.query_params.get("seed")
+        seed = seed_raw if seed_raw not in (None, "") else None
+
         return Response({
             "dataset_id": dataset_id,
-            "triples": registry.sample_triples(dataset_id, count),
+            "triples": registry.sample_triples(dataset_id, count, seed=seed),
         })