model final final final final

.dockerignore

@@ -0,0 +1,19 @@
+# Python caches
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+
+# Duplicate ~950 MB backup copy of the artifacts — the API loads from
+# artifacts_improved8/ root, not this directory.
+artifacts_improved8/_backup_pretrained/
+
+# Notebooks, docs, and the offline catalog-build script (not needed to serve).
+*.ipynb
+*.md
+build_full_catalog.py
+
+# Git / editor
+.git/
+.gitignore
+.vscode/

.gitattributes

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+artifacts_improved8/* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,55 @@
+# syntax=docker/dockerfile:1
+
+# CL-EPIDTN recommender model API (improved_8) — CPU-only FastAPI/Uvicorn image.
+FROM python:3.11-slim
+
+# --- Environment ---------------------------------------------------------
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PORT=7749 \
+    ARTIFACTS_DIR=artifacts_improved8 \
+    # Bake the Hugging Face cache into the image so the text encoder used by
+    # /catalog/add is available offline and without a runtime download.
+    HF_HOME=/app/hf_cache
+
+WORKDIR /app
+
+# --- System dependencies -------------------------------------------------
+# build-essential covers any package without a prebuilt wheel; curl powers the healthcheck.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# --- Python dependencies -------------------------------------------------
+# CPU-only torch first (the GPU build is huge and unnecessary for serving),
+# then the rest of the dependencies from PyPI.
+RUN pip install --index-url https://download.pytorch.org/whl/cpu torch==2.6.0
+
+COPY requirements.docker.txt ./
+RUN pip install -r requirements.docker.txt
+
+# Pre-download the text encoder used for catalog hot-add so the container does
+# not need to fetch it from Hugging Face at runtime.
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')"
+
+# --- Model artifacts -----------------------------------------------------
+# The ~1.2 GB artifacts exceed the Space repo storage limit, so they are NOT
+# bundled. Pull them from the public model repo at build time instead. This
+# layer is placed before COPY so code changes don't re-trigger the download.
+ENV MODEL_REPO=zeyadgamal00/CL-EPIDTN
+RUN python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='$MODEL_REPO', repo_type='model', allow_patterns=['artifacts_improved8/**'], local_dir='/app')"
+
+# --- Application ---------------------------------------------------------
+# Copies the API + model code only (artifacts already downloaded above; the
+# artifacts dir is excluded from the build context via .dockerignore).
+COPY . .
+
+EXPOSE 7749
+
+# /health reports model_loaded once artifacts finish loading at startup.
+HEALTHCHECK --interval=30s --timeout=10s --start-period=180s --retries=3 \
+    CMD curl -fsS http://localhost:${PORT}/health || exit 1
+
+CMD ["sh", "-c", "uvicorn recommender_api_improved8:app --host 0.0.0.0 --port ${PORT}"]

README.md

@@ -0,0 +1,20 @@
+---
+title: Questro Recommender Model API
+emoji: 🎬
+colorFrom: indigo
+colorTo: purple
+sdk: docker
+app_port: 7749
+pinned: false
+---
+
+# Questro Recommender Model API (CL-EPIDTN, improved_8)
+
+FastAPI service that scores and re-ranks movie/game candidates for the Questro
+RAG pipeline. It exposes `/recommend`, `/recommend/rerank`, `/catalog/add`,
+`/genres`, and `/health` on port **7749**.
+
+The full catalog (189,753 items) is baked into the artifacts in
+`artifacts_improved8/`, so the model never needs to hot-add items at runtime.
+See [RECOMMENDER_API_IMPROVED8_DOCS.md](RECOMMENDER_API_IMPROVED8_DOCS.md) for
+the API reference and `build_full_catalog.py` for how the catalog is rebuilt.

RECOMMENDER_API_IMPROVED8_DOCS.md

@@ -0,0 +1,646 @@
+# Questro Recommender API — Integration Guide (improved_8)
+
+> **Engine generation**: `improved_8` (architecture file `cl_epidtn_recommender_improved_8.py`, artifacts dir `artifacts_improved8/`, checkpoint `improved_8epochs.pt`)
+> **Runtime `model_version`**: `improved_8` (echoed in every response)
+> **Base URL**: `http://<ML_HOST>:7749`
+> **Protocol**: REST / JSON (FastAPI)
+> **Auth**: None (internal network only)
+
+---
+
+## Quick Start
+
+```bash
+# Start the server
+uvicorn recommender_api_improved8:app --host 0.0.0.0 --port 7749
+
+# Health check
+curl http://localhost:7749/health
+
+# Get recommendations (star ratings)
+curl -X POST http://localhost:7749/recommend \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user": {
+      "ratings": [
+        {"item_id": "game_271590", "title": "Grand Theft Auto V", "stars": 5.0},
+        {"item_id": "movie_155", "title": "The Dark Knight", "stars": 4.5}
+      ]
+    },
+    "k": 10,
+    "domain": "game",
+    "blocked_genres": ["Horror", "War"]
+  }'
+```
+
+---
+
+## Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/health` | Liveness + model-loaded status |
+| `GET` | `/genres` | List blockable genres/tags (for the parental-controls UI) |
+| `POST` | `/recommend` | Personalised recommendations with pagination + genre blocking |
+| `POST` | `/recommend/rerank` | Re-rank a RAG-fetched candidate list (RAG tool) |
+| `POST` | `/catalog/add` | Hot-add cold-start items at runtime |
+| `POST` | `/admin/reload` | Reload artifacts from disk (clears hot-added items) |
+
+---
+
+### 1. `GET /health`
+
+Health check — verify the model is loaded before sending requests.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "model_loaded": true,
+  "n_items": 138541,
+  "n_genres_tracked": 138541,
+  "text_index_loaded": true,
+  "model_version": "improved_8",
+  "hot_added_count": 0
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `string` | Always `"ok"` when the server responds |
+| `model_loaded` | `bool` | `false` during startup — wait until `true` |
+| `n_items` | `int` | Total items in catalog (movies + games) |
+| `n_genres_tracked` | `int` | Items with genre/tag data for blocking |
+| `text_index_loaded` | `bool` | Whether text embeddings are available (enhances quality) |
+| `model_version` | `string` | Engine version string (`"improved_8"`) |
+| `hot_added_count` | `int` | Items added at runtime via `/catalog/add` since the last load |
+
+---
+
+### 2. `POST /recommend`
+
+**The main endpoint.** Send a user profile and get personalised, genre-filtered recommendations with pagination.
+
+#### Request Body
+
+```json
+{
+  "user": {
+    "age": 21,
+    "gender": "Male",
+    "profession": "Student",
+    "country": "Egypt",
+    "movie_genres_fav": "Action|Adventure|Comedy",
+    "movie_genres_disliked": "Horror|War",
+    "game_genres_fav": "Action|RPG|Shooter",
+    "game_genres_disliked": "Card|Educational",
+    "ratings": [
+      {"item_id": "game_271590", "title": "Grand Theft Auto V", "type": "game", "rating": "5 Stars"},
+      {"item_id": "movie_155", "title": "The Dark Knight", "stars": 4.5},
+      {"item_id": "movie_680", "source": "wishlist"},
+      {"item_id": "game_99999", "source": "ignore"}
+    ]
+  },
+  "k": 10,
+  "offset": 0,
+  "domain": "movie",
+  "blocked_genres": ["Horror", "Crime"]
+}
+```
+
+#### User Profile Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `age` | `int` | No | User's age (1–120) |
+| `gender` | `string` | No | Gender |
+| `profession` | `string` | No | Profession / occupation |
+| `country` | `string` | No | Country |
+| `movie_genres_fav` | `string` | No | Pipe-separated favourite movie genres |
+| `movie_genres_disliked` | `string` | No | Pipe-separated disliked movie genres |
+| `game_genres_fav` | `string` | No | Pipe-separated favourite game genres |
+| `game_genres_disliked` | `string` | No | Pipe-separated disliked game genres |
+| `ratings` | `RatingItem[]` | ✅ Yes | At least 1 rating (see below) |
+
+#### Rating Item Fields
+
+Each item in `ratings` supports **three input modes** — use whichever is convenient:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `item_id` | `string` | **Required.** Format: `"movie_{id}"`, `"movie:{id}"`, `"game_{id}"`, or `"game:{id}"` |
+| `title` | `string` | Optional, for logging |
+| `type` | `"movie" \| "game"` | Optional domain hint (inferred from `item_id` prefix if omitted) |
+| `rating` | `string` | **Mode 1**: Survey label (see table below) |
+| `stars` | `float` | **Mode 2**: Numeric rating 1.0–5.0 |
+| `source` | `string` | **Mode 3**: `"rating"`, `"wishlist"`, or `"ignore"` |
+
+#### Rating Labels Reference
+
+| Label | Numeric Equivalent | Weight |
+|-------|--------------------|--------|
+| `"5 Stars"` | 5.0 | +1.0 |
+| `"4 Stars"` | 4.0 | +0.5 |
+| `"Didn't watch but would watch"` | 3.5 | +0.25 |
+| `"Didn't play but would play"` | 3.5 | +0.25 |
+| `"3 Stars"` | 3.0 | 0.0 |
+| `"2 Stars"` | 2.0 | −0.5 |
+| `"Didn't watch and wouldn't watch"` | 1.5 | −0.75 |
+| `"Didn't play and wouldn't play"` | 1.5 | −0.75 |
+| `"1 Star"` | 1.0 | −1.0 |
+
+> Numeric `stars` are mapped with `weight = clamp((stars − 3) / 2, −1, 1)`. An item with no `rating`, `stars`, or `source` defaults to a mild positive (+0.25).
+
+#### Source Signals
+
+| `source` value | Meaning | Equivalent Label |
+|---|---|---|
+| `"wishlist"` | User saved / wishlisted the item | "Didn't watch but would watch" (+0.25) |
+| `"ignore"` | User blocked / ignored the item | "Didn't watch and wouldn't watch" (−0.75) |
+| `"rating"` or `null` | Normal rating — uses `rating` or `stars` field | — |
+
+#### Request Parameters
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `k` | `int` | No | `10` | Results per page (1–100) |
+| `offset` | `int` | No | `0` | Pagination offset. Page 1 = 0, page 2 = k, etc. |
+| `domain` | `string \| null` | No | `null` | `"movie"`, `"game"`, or `null` for cross-domain |
+| `blocked_genres` | `string[] \| null` | No | `null` | Genres/tags to exclude (case-insensitive) |
+
+#### Response Body
+
+```json
+{
+  "count": 10,
+  "total_available": 85,
+  "domain": "movie",
+  "offset": 0,
+  "k": 10,
+  "recommendations": [
+    {
+      "item_id": 157336,
+      "item_key": "movie:157336",
+      "title": "Interstellar (2014)",
+      "domain": "movie",
+      "score": 0.872451
+    }
+  ],
+  "signals_used": 3,
+  "blocked_genres": ["crime", "horror"],
+  "model_version": "improved_8",
+  "has_more": true
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `count` | `int` | Items in this page |
+| `total_available` | `int` | Total results available (after genre filtering) |
+| `domain` | `string \| null` | Echoes the requested domain filter |
+| `offset` | `int` | Current offset |
+| `k` | `int` | Requested page size |
+| `has_more` | `bool` | `true` if more pages exist beyond this one |
+| `recommendations[].item_id` | `int \| null` | **Backend provider ID: TMDB ID for movies, RAWG ID for games.** `null` if the catalog row has no provider ID. |
+| `recommendations[].item_key` | `string` | Internal key: `movie:{id}` or `game:{id}` |
+| `recommendations[].title` | `string` | Human-readable title |
+| `recommendations[].domain` | `string` | `"movie"` or `"game"` |
+| `recommendations[].score` | `float` | Relevance score, rounded to 6 dp (higher = better) |
+| `signals_used` | `int` | How many submitted ratings mapped to the catalog |
+| `blocked_genres` | `string[]` | Genres that were blocked (lowercased) |
+| `model_version` | `string` | `"improved_8"` |
+
+> **Resolve display data from `item_id`** (the TMDB/RAWG provider ID) against your own Movies/Games tables. Use `item_key` only when you need the model's internal identifier.
+
+> **Pagination example:**
+> - Page 1: `{"k": 10, "offset": 0}` → items 1–10
+> - Page 2: `{"k": 10, "offset": 10}` → items 11–20
+> - Stop when `has_more` is `false`
+
+---
+
+### 3. `POST /recommend/rerank` — RAG Tool
+
+**Re-rank a pre-fetched candidate list** using the recommender model. Use this as a tool in your RAG pipeline.
+
+#### Workflow
+
+```
+1. RAG retrieves a broad list of candidate items (e.g. "top 50 sci-fi games")
+2. POST them to /recommend/rerank with the user's profile
+3. The recommender scores each candidate against the user's taste
+4. Items are returned ranked by personalised relevance
+5. Blocked genres are filtered out; the user's own history items are removed
+```
+
+#### Request Body
+
+```json
+{
+  "user": {
+    "ratings": [
+      {"item_id": "game_271590", "stars": 5.0},
+      {"item_id": "movie_155", "stars": 4.0}
+    ]
+  },
+  "candidate_items": [
+    {"item_id": "game_1091500", "title": "Cyberpunk 2077"},
+    {"item_id": "game_292030", "title": "The Witcher 3"},
+    {"item_id": "game_374320", "title": "Dark Souls III"},
+    {"item_id": "movie_27205", "title": "Inception"}
+  ],
+  "blocked_genres": ["Horror"],
+  "k": 3
+}
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `user` | `UserProfile` | ✅ Yes | — | Same user profile as `/recommend` |
+| `candidate_items` | `CandidateItem[]` | ✅ Yes | — | Items to score (at least 1) |
+| `candidate_items[].item_id` | `string` | ✅ Yes | — | `"movie_{id}"` / `"movie:{id}"` / `"game_{id}"` / `"game:{id}"` |
+| `candidate_items[].title` | `string` | No | — | Optional title |
+| `blocked_genres` | `string[] \| null` | No | `null` | Genres/tags to block |
+| `k` | `int \| null` | No | `null` | Max results. `null` = return all ranked |
+
+#### Response Body
+
+```json
+{
+  "count": 3,
+  "recommendations": [
+    {"item_id": 1091500, "item_key": "game:1091500", "title": "Cyberpunk 2077", "domain": "game", "score": 0.91},
+    {"item_id": 292030, "item_key": "game:292030", "title": "The Witcher 3", "domain": "game", "score": 0.87},
+    {"item_id": 27205, "item_key": "movie:27205", "title": "Inception", "domain": "movie", "score": 0.83}
+  ],
+  "signals_used": 2,
+  "candidates_submitted": 4,
+  "candidates_matched": 4,
+  "blocked_genres": ["horror"],
+  "model_version": "improved_8"
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `count` | `int` | Final results after filtering |
+| `recommendations[]` | `object[]` | Same shape as `/recommend` (`item_id`, `item_key`, `title`, `domain`, `score`) |
+| `signals_used` | `int` | User ratings that mapped to the catalog |
+| `candidates_submitted` | `int` | How many candidates you sent |
+| `candidates_matched` | `int` | How many were found in the model catalog |
+| `blocked_genres` | `string[]` | Genres that were blocked (lowercased) |
+| `model_version` | `string` | `"improved_8"` |
+
+> **Graceful FAISS fallback.** If none of the candidates can be scored by the model — e.g. they are all hot-added items whose indices fall outside the trained embedding range, or a transient CUDA error occurs during scoring — the endpoint returns `count: 0` with an empty `recommendations` list **instead of erroring**. The RAG pipeline should treat an empty rerank result as "fall back to the original FAISS similarity order."
+
+---
+
+### 4. `POST /catalog/add` — Hot-Add Items
+
+**Register new items into the running catalog dynamically**, so the recommender can score items it has never been trained on. Ideal for newly released titles or dynamic RAG pipelines.
+
+#### Workflow
+
+```
+1. RAG retrieves items from an external DB the ML model wasn't trained on
+2. POST the missing items to /catalog/add with metadata/text
+3. The server expands its tensors and (if sentence-transformers is installed and a
+   text index is loaded) computes text embeddings so the items can be scored (0-shot)
+4. The items can now be returned by /recommend or /recommend/rerank
+```
+
+#### Request Body
+
+```json
+{
+  "items": [
+    {
+      "item_id": "game_1091500",
+      "title": "Cyberpunk 2077",
+      "domain": "game",
+      "description": "An open-world, action-adventure story set in Night City...",
+      "genres": "Action|RPG",
+      "tags": "sci-fi|open world|cyberpunk",
+      "provider_id": 1091500
+    }
+  ]
+}
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `items` | `CatalogNewItem[]` | ✅ Yes | — | 1–500 items per request |
+| `items[].item_id` | `string` | ✅ Yes | — | `"movie_{id}"` / `"movie:{id}"` / `"game_{id}"` / `"game:{id}"` |
+| `items[].title` | `string` | ✅ Yes | — | Human-readable title |
+| `items[].domain` | `"movie" \| "game" \| null` | No | inferred from `item_id` | Optional domain override |
+| `items[].description` | `string` | No | `""` | Synopsis (used for text embedding) |
+| `items[].genres` | `string` | No | `""` | Pipe- or comma-separated genres, e.g. `"Action\|RPG"` |
+| `items[].tags` | `string` | No | `""` | Pipe- or comma-separated tags |
+| `items[].provider_id` | `int \| null` | No | `null` | TMDB ID for movies, RAWG ID for games — surfaced as `item_id` in later responses |
+
+#### Response Body
+
+```json
+{
+  "added": ["game:1091500"],
+  "already_exists": [],
+  "failed": {},
+  "n_items": 138542,
+  "text_index_updated": true
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `added` | `string[]` | Internal keys (`domain:id`) that were registered this call |
+| `already_exists` | `string[]` | Keys that were already in the catalog (skipped) |
+| `failed` | `object` | Map of `item_id` → error reason for items that could not be added |
+| `n_items` | `int` | Total catalog size after the operation |
+| `text_index_updated` | `bool` | `true` if text embeddings were computed and written for the new items |
+
+> **Notes.** Hot-added items are **runtime-only** — they are cleared on `/admin/reload` or a server restart. They start with zero *learned* collaborative embeddings and rank primarily through text similarity, which requires `sentence-transformers` to be installed and a text index to be loaded; otherwise `text_index_updated` is `false`. Items whose new index exceeds the model's trained embedding bounds are kept in the catalog (and still visible to FAISS/RAG) but are skipped by the model's scoring path in `/recommend/rerank`.
+
+---
+
+### 5. `GET /genres`
+
+List all genres/tags available for blocking. Use this to populate the parental-controls UI.
+
+**Response:**
+
+```json
+{
+  "genres": ["action", "adventure", "animation", "comedy", "crime", "documentary", "drama", "fantasy", "horror", "indie", "mystery", "rpg", "racing", "romance", "sci-fi", "shooter", "simulation", "sports", "strategy", "thriller", "war", "western"]
+}
+```
+
+> All genres are **lowercased** and limited to tokens longer than 2 characters. When sending `blocked_genres`, any casing works — the API normalises everything to lowercase.
+
+---
+
+### 6. `POST /admin/reload`
+
+Reload all on-disk artifacts (model, indices, metadata). **Runtime hot-added items are intentionally cleared** so the server returns to the persisted artifact state.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "n_items": 138541,
+  "text_index_loaded": true,
+  "hot_added_count": 0
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `string` | `"ok"` on success |
+| `n_items` | `int` | Catalog size after reload |
+| `text_index_loaded` | `bool` | Whether text embeddings were reloaded |
+| `hot_added_count` | `int` | Reset to `0` after reload |
+
+---
+
+## How Recommendations Are Scored
+
+A few behaviours are worth knowing when integrating:
+
+- **Over-fetch before filtering.** When `blocked_genres` is set, the engine fetches `OVERFETCH_MULTIPLIER` × more candidates (default **5×**) before applying genre filtering, so a full page of `k` results is still returned after blocked items are removed.
+- **Title-family franchise boost.** For profiles seeded with a clear franchise (e.g. *Grand Theft Auto V*), the engine adds extra same-franchise candidates and applies a score boost (`TITLE_FAMILY_BOOST`, default **0.40**) so obvious franchise neighbours rank ahead of generic genre matches. Version/edition words ("Remastered", "GOTY", roman numerals, …) are stripped so sequels still match.
+- **History exclusion.** In `/recommend/rerank`, candidates already present in the user's rating history are dropped before scoring.
+- **Cold-start text scoring.** Hot-added items are embedded with a lightweight sentence encoder (`all-MiniLM-L6-v2`) so they can be scored by content similarity even though they have no learned collaborative vector.
+
+---
+
+## Integration Guide
+
+### Mapping Your IDs to the API
+
+| Your Database | API `item_id` format | Example |
+|---|---|---|
+| Movie (TMDB ID) | `"movie_{TMDB_Id}"` | `"movie_155"` |
+| Movie (MovieLens ID) | `"movie_{movieId}"` | `"movie_1199"` |
+| Game (Steam App ID) | `"game_{app_id}"` | `"game_271590"` |
+
+> Responses return the provider ID in the `item_id` field — **TMDB ID for movies, RAWG ID for games** — alongside the internal `item_key`.
+
+### Converting Your Signals to API Ratings
+
+| User Action in Your App | API Rating |
+|---|---|
+| Rated 1–5 stars | `{"item_id": "...", "stars": 4.0}` |
+| Liked | `{"item_id": "...", "stars": 4.0}` |
+| Watched / Played | `{"item_id": "...", "stars": 4.0}` |
+| Wishlisted / Saved | `{"item_id": "...", "source": "wishlist"}` |
+| Ignored / Blocked | `{"item_id": "...", "source": "ignore"}` |
+| Disliked | `{"item_id": "...", "stars": 1.0}` |
+
+### Parental Controls
+
+Send `blocked_genres` with every request for child accounts. Populate the picker from `GET /genres`.
+
+| Restriction Level | `blocked_genres` |
+|---|---|
+| Child-safe | `["horror", "crime", "war", "thriller"]` |
+| Teen-safe | `["horror"]` |
+| No restrictions | `null` or `[]` |
+
+The API guarantees:
+- **No item with a blocked genre/tag will appear** in results.
+- The **requested `k` items are returned** after filtering (the model over-fetches internally).
+- **Case-insensitive** matching: `"Horror"`, `"HORROR"`, `"horror"` are all equivalent.
+
+### Typical Backend Flow
+
+```
+1. User opens "For You" page
+2. Backend queries its own DB for user's ratings/likes/watches/wishlists/ignores
+3. Backend maps each item to {item_id, stars/source}
+4. Backend reads the user's parental control settings → blocked_genres
+5. Backend POSTs to /recommend with offset=0, k=20
+6. Backend receives item_id values (TMDB/RAWG provider IDs)
+7. Backend looks up those IDs in its own Movies/Games table
+8. Backend returns rich item data (posters, descriptions) to frontend
+9. On scroll / "Load More", backend POSTs again with offset=20
+```
+
+### RAG Tool Integration
+
+```
+1. User asks chatbot: "Recommend me games like Skyrim"
+2. RAG retrieves top 50 RPG games from your vector DB
+3. (Optional) RAG hot-adds any items missing from the model via /catalog/add
+4. RAG calls POST /recommend/rerank with the user profile + 50 candidates
+5. API returns the items re-ranked by the user's personal taste
+   (empty list ⇒ fall back to the original FAISS order)
+6. RAG picks top 5 and formats the response
+```
+
+---
+
+## C# Backend Integration Example
+
+```csharp
+public class RecommenderClient
+{
+    private readonly HttpClient _http;
+    private readonly string _baseUrl;
+
+    public RecommenderClient(string baseUrl)
+    {
+        _baseUrl = baseUrl.TrimEnd('/');
+        _http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
+    }
+
+    public async Task<RecommendResponse?> GetRecommendationsAsync(
+        UserProfile user,
+        int k = 10,
+        int offset = 0,
+        string? domain = null,
+        List<string>? blockedGenres = null)
+    {
+        var request = new
+        {
+            user,
+            k,
+            offset,
+            domain,
+            blocked_genres = blockedGenres
+        };
+
+        var json = JsonSerializer.Serialize(request,
+            new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower });
+
+        var response = await _http.PostAsync(
+            $"{_baseUrl}/recommend",
+            new StringContent(json, Encoding.UTF8, "application/json"));
+
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<RecommendResponse>();
+    }
+
+    public async Task<RerankResponse?> RerankAsync(
+        UserProfile user,
+        List<CandidateItem> candidates,
+        int? k = null,
+        List<string>? blockedGenres = null)
+    {
+        var request = new
+        {
+            user,
+            candidate_items = candidates,
+            k,
+            blocked_genres = blockedGenres
+        };
+
+        var json = JsonSerializer.Serialize(request,
+            new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower });
+
+        var response = await _http.PostAsync(
+            $"{_baseUrl}/recommend/rerank",
+            new StringContent(json, Encoding.UTF8, "application/json"));
+
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<RerankResponse>();
+    }
+}
+
+// Each recommendation exposes item_id (TMDB/RAWG provider id), item_key, title, domain, score.
+// Usage — recommendations with pagination:
+var user = BuildUserProfile(userId);  // your helper
+var page1 = await _recommender.GetRecommendationsAsync(
+    user, k: 20, offset: 0,
+    domain: "movie",
+    blockedGenres: userSettings.BlockedGenres);
+
+// Show page1.Recommendations to user...
+
+if (page1.HasMore)
+{
+    var page2 = await _recommender.GetRecommendationsAsync(
+        user, k: 20, offset: 20,
+        domain: "movie",
+        blockedGenres: userSettings.BlockedGenres);
+}
+
+// Usage — RAG reranking:
+var ragResults = await _vectorDb.SearchAsync("sci-fi games", top: 50);
+var candidates = ragResults.Select(r => new CandidateItem
+{
+    ItemId = $"game_{r.SteamAppId}",
+    Title = r.Title
+}).ToList();
+
+var reranked = await _recommender.RerankAsync(
+    user, candidates, k: 5,
+    blockedGenres: userSettings.BlockedGenres);
+```
+
+---
+
+## Error Responses
+
+| Code | When |
+|------|------|
+| `422` | No ratings provided, all items unmapped, all candidates already in history, invalid rating label, stars out of range |
+| `503` | Model / catalog still loading (check `/health` first) |
+
+> Note: an all-unscoreable `/recommend/rerank` request is **not** an error — it returns `200` with `count: 0` so the caller can fall back to FAISS scores.
+
+---
+
+## Deployment Notes
+
+| Item | Value |
+|------|-------|
+| **Server start** | `uvicorn recommender_api_improved8:app --host 0.0.0.0 --port 7749` |
+| **Required files** | `recommender_api_improved8.py`, `cl_epidtn_recommender_improved_8.py` |
+| **Artifacts dir** | `./artifacts_improved8/` containing: `improved_8epochs.pt`, `item_index.pt`, `item_to_idx.pkl`, `item_meta.pkl`, `title_lookup.pkl`, `improved_item_text_embeddings.pt` |
+| **Dependencies** | `pip install torch fastapi uvicorn pydantic pandas` (plus `sentence-transformers` for cold-start text scoring) |
+| **Text encoder** | `sentence-transformers/all-MiniLM-L6-v2` (cold-start hot-add embeddings) |
+| **Swagger docs** | `http://<HOST>:7749/docs` (auto-generated) |
+| **Cold start time** | ~15–30 seconds (model + text embeddings loading) |
+| **Avg response time** | ~50–150ms per request |
+
+### Configurable Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `ARTIFACTS_DIR` | `artifacts_improved8` | Base directory for artifacts |
+| `MODEL_CHECKPOINT` | `<dir>/improved_8epochs.pt` | Trained model checkpoint |
+| `TEXT_EMBEDDINGS_PATH` | `<dir>/improved_item_text_embeddings.pt` | Optional content embeddings |
+| `TEXT_ENCODER_MODEL` | `sentence-transformers/all-MiniLM-L6-v2` | Cold-start text encoder |
+| `MAX_RECS` | `100` | Hard cap on internal fetch size |
+| `OVERFETCH_MULTIPLIER` | `5` | Extra candidates fetched before genre filtering |
+| `TITLE_FAMILY_BOOST` | `0.40` | Score boost for same-franchise neighbours |
+| `TITLE_FAMILY_EXTRA_CANDIDATES` | `50` | Max extra franchise candidates injected |
+
+---
+
+## FAQ
+
+**Q: What if a user has no ratings yet?**
+A: The API requires at least 1 rating. For new users, show popular/trending items until they interact with something, then call `/recommend`.
+
+**Q: What if a submitted item_id isn't in the model catalog?**
+A: It's silently skipped. Check `signals_used` in the response — if it's 0, none of the items were found (the endpoint returns `422`).
+
+**Q: Can I mix stars and survey labels in the same request?**
+A: Yes. Each rating item is independent. You can use `stars` for some, `rating` labels for others, and `source: "wishlist"/"ignore"` for others.
+
+**Q: How does pagination work?**
+A: Set `offset` and `k`. Page 1 = `offset: 0, k: 20`, page 2 = `offset: 20, k: 20`. The `has_more` field tells you if another page exists. `total_available` gives the total count after filtering.
+
+**Q: Are blocked genres guaranteed to be excluded?**
+A: Yes. The API over-fetches internally and filters BEFORE paginating, so you always get `k` results (or fewer only if the entire filtered catalog is exhausted).
+
+**Q: Why does `/recommend/rerank` sometimes return an empty list?**
+A: When none of the candidates can be scored by the model (all hot-added/out-of-range, or a transient CUDA error). This is intentional — treat it as a signal to keep the RAG's original FAISS ordering.
+
+**Q: Is the API stateless?**
+A: User data is stateless — no per-user data is stored server-side. The **catalog** is mutable, though: `/catalog/add` mutates in-memory state until `/admin/reload` or a restart.
+
+**Q: What's the rerank endpoint for?**
+A: It's designed as a tool for your RAG/chatbot pipeline. Your RAG retrieves a broad candidate list (e.g. "top 50 RPG games"), and the recommender personalises the ranking for the specific user.

artifacts_improved8/improved_8epochs.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0bdceb5b545ce6bfeda28be97f93769d0957842eee4a51209ba6017fac32b319
+size 690839178

artifacts_improved8/improved_item_text_embeddings.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a9f09e5470a8246f26f411fea490387e45159626d27848a5933bb3767800696b
+size 228876170

artifacts_improved8/item_index.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:40747a1d12d31021d0e6bd0e8f1cf4c1cb7c8a3109227bcb01db92c347eecd96
+size 76292779

artifacts_improved8/item_meta.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2ab33ead574f9e43dced91fdae3beba8823dee31f3d2df796ea65ef072aa05be
+size 211305749

artifacts_improved8/item_to_idx.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1135db845f3a67af749339d760c3c91eebdd3bed2af4627353893cca0d6623d5
+size 2774245

artifacts_improved8/title_lookup.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:351cc07b4eb6aa519df088b5c6467ed9bbf9d8ec2bb0920b6ae253478a5bb8b1
+size 4378344

cl_epidtn_recommender_improved_8.py

@@ -0,0 +1,2299 @@
+from __future__ import annotations
+
+import math
+import os
+import random
+import re
+import time
+import zipfile
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Sequence
+
+import numpy as np
+import pandas as pd
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch.utils.data import DataLoader, Dataset
+from tqdm.auto import tqdm
+
+
+PAD = 0
+
+_METADATA_STOP_WORDS = frozenset({
+    "the", "and", "for", "with", "from", "that", "this", "your", "you",
+    "game", "movie", "film", "very", "positive", "mostly", "mixed",
+    "win", "steam", "deck",
+})
+
+
+@dataclass
+class RecConfig:
+    movielens_zip: str = "ml-32m.zip"
+    steam_zip: str = "archive (11).zip"
+    max_seq_len: int = 30
+    min_movie_rating: float = 3.5
+    min_steam_hours: float = 1.0
+    max_movielens_rows: int | None = 2_000_000
+    max_steam_rows: int | None = 2_000_000
+    max_train_samples: int = 1_000_000
+    min_user_events: int = 4
+    min_item_interactions: int = 5
+    embedding_dim: int = 128
+    transformer_layers: int = 5
+    attention_heads: int = 4
+    dropout: float = 0.15
+    batch_size: int = 512
+    epochs: int = 10
+    lr: float = 2e-3
+    temperature: float = 0.07
+    contrastive_weight: float = 0.15
+    amm_weight: float = 0.01
+    gradient_clip_norm: float = 1.0
+    use_causal_attention: bool = False
+    hf_cache_dir: str = "hf_cache"
+    hf_home_dir: str = "hf_home"
+    survey_csv: str = "users_ratings.csv"
+    device: str = "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def set_seed(seed: int = 42) -> None:
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)
+
+
+def _read_csv_from_zip(zip_path: str | Path, member: str, **kwargs) -> pd.DataFrame:
+    with zipfile.ZipFile(zip_path) as zf:
+        with zf.open(member) as fh:
+            return pd.read_csv(fh, **kwargs)
+
+
+def load_movielens(cfg: RecConfig) -> tuple[pd.DataFrame, pd.DataFrame]:
+    ratings = _read_csv_from_zip(
+        cfg.movielens_zip,
+        "ml-32m/ratings.csv",
+        usecols=["userId", "movieId", "rating", "timestamp"],
+        nrows=cfg.max_movielens_rows,
+    )
+    ratings = ratings.loc[ratings["rating"] >= cfg.min_movie_rating].copy()
+    ratings["user_key"] = "ml:" + ratings["userId"].astype(str)
+    ratings["item_key"] = "movie:" + ratings["movieId"].astype(str)
+    ratings["domain"] = "movie"
+    interactions = ratings[["user_key", "item_key", "timestamp", "domain"]]
+
+    movies = _read_csv_from_zip(cfg.movielens_zip, "ml-32m/movies.csv")
+    links = _read_csv_from_zip(cfg.movielens_zip, "ml-32m/links.csv", usecols=["movieId", "tmdbId"])
+    movies = movies.merge(links, on="movieId", how="left")
+    tags = _read_movielens_tags(cfg.movielens_zip)
+    movies = movies.merge(tags, on="movieId", how="left")
+    movies["item_key"] = "movie:" + movies["movieId"].astype(str)
+    movies["domain"] = "movie"
+    movies["user_reviews"] = np.nan
+    movies["tmdb_id"] = movies["tmdbId"].astype("Int64")
+    if "is_adult" not in movies.columns:
+        movies["is_adult"] = False
+    movies["is_adult"] = movies["is_adult"].fillna(False).astype(bool)
+    movies["tokens"] = (
+        movies["genres"].fillna("").str.replace("|", " ", regex=False)
+        + " "
+        + movies["genres"].fillna("").map(_movie_genre_bridge_tokens)
+        + " "
+        + movies["tag_tokens"].fillna("")
+        + " "
+        + movies["title"].fillna("").map(_title_tokens)
+    )
+    movies["description"] = ""
+    items = movies[["item_key", "title", "domain", "tokens", "user_reviews", "description", "tmdb_id", "is_adult"]]
+    return interactions, items
+
+
+def load_steam(cfg: RecConfig) -> tuple[pd.DataFrame, pd.DataFrame]:
+    recs = _read_csv_from_zip(
+        cfg.steam_zip,
+        "recommendations.csv",
+        usecols=["app_id", "is_recommended", "hours", "user_id", "date"],
+        nrows=cfg.max_steam_rows,
+    )
+    recs = recs.loc[recs["is_recommended"].astype(str).str.lower().eq("true")].copy()
+    # Filter out low-engagement recommendations (< min_steam_hours played)
+    recs["hours"] = pd.to_numeric(recs["hours"], errors="coerce").fillna(0)
+    recs = recs.loc[recs["hours"] >= cfg.min_steam_hours]
+    recs["timestamp"] = pd.to_datetime(recs["date"], errors="coerce").astype("int64") // 10**9
+    recs["timestamp"] = recs["timestamp"].fillna(0).astype("int64")
+    recs["user_key"] = "steam:" + recs["user_id"].astype(str)
+    recs["item_key"] = "game:" + recs["app_id"].astype(str)
+    recs["domain"] = "game"
+    interactions = recs[["user_key", "item_key", "timestamp", "domain"]]
+
+    games = _read_csv_from_zip(cfg.steam_zip, "games.csv")
+    if 'positive' in games.columns and 'negative' in games.columns:
+        total_reviews = pd.to_numeric(games['positive'], errors='coerce').fillna(0) + pd.to_numeric(games['negative'], errors='coerce').fillna(0)
+        games = games[total_reviews >= 5]
+    elif 'recommendations' in games.columns:
+        games = games[pd.to_numeric(games['recommendations'], errors='coerce').fillna(0) >= 5]
+
+    game_meta = _read_steam_metadata(cfg.steam_zip)
+    if not game_meta.empty:
+        games = games.merge(game_meta, on="app_id", how="left")
+    else:
+        games["tag_tokens"] = ""
+        games["description"] = ""
+    games["item_key"] = "game:" + games["app_id"].astype(str)
+    games["domain"] = "game"
+    games["tmdb_id"] = pd.NA
+    for _col in ("win", "mac", "linux", "steam_deck"):
+        if _col not in games.columns:
+            games[_col] = False
+    if "user_reviews" not in games.columns:
+        games["user_reviews"] = np.nan
+    if "is_adult" not in games.columns:
+        games["is_adult"] = False
+    games["is_adult"] = games["is_adult"].fillna(False).astype(bool)
+    platform_tokens = (
+        pd.Series(np.where(games["win"].fillna(False).astype(bool), " win", ""), index=games.index)
+        + np.where(games["mac"].fillna(False).astype(bool), " mac", "")
+        + np.where(games["linux"].fillna(False).astype(bool), " linux", "")
+        + np.where(games["steam_deck"].fillna(False).astype(bool), " steam_deck", "")
+    )
+    games["tokens"] = (
+        games["tag_tokens"].fillna("")
+        + " "
+        + games["description"].fillna("").map(lambda x: _text_tokens(x, limit=60))
+        + " "
+        + games["rating"].fillna("").astype(str).map(_text_tokens)
+        + " "
+        + games["positive_ratio"].fillna(0).astype(int).map(lambda x: f"posratio_{x // 10}")
+        + platform_tokens
+        + " "
+        + games["title"].fillna("").map(_title_tokens)
+    )
+    items = games[["item_key", "title", "domain", "tokens", "user_reviews", "description", "tmdb_id", "is_adult"]]
+    return interactions, items
+
+
+def configure_hf_cache(hf_cache_dir: str | Path = "hf_cache", hf_home_dir: str | Path = "hf_home") -> None:
+    """Point Hugging Face libraries at the project-local caches."""
+    os.environ["HF_DATASETS_CACHE"] = str(Path(hf_cache_dir).resolve())
+    os.environ["HF_HOME"] = str(Path(hf_home_dir).resolve())
+
+
+def _find_cached_arrow(cache_dir: str | Path, dataset_fragment: str, filename: str) -> Path:
+    cache = Path(cache_dir)
+    # Try exact filename under the dataset directory first
+    matches = list(cache.glob(f"**/*{dataset_fragment}*/**/{filename}"))
+    if not matches:
+        matches = list(cache.glob(f"**/{filename}"))
+    if not matches:
+        # Fallback: find any train arrow file under a directory matching the dataset
+        matches = list(cache.glob(f"**/*{dataset_fragment}*/**/*train*.arrow"))
+    if not matches:
+        raise FileNotFoundError(
+            f"Could not find {filename!r} (or any train arrow) for "
+            f"{dataset_fragment!r} under {cache_dir!s}. "
+            f"Run download_tmdb_hf_dataset() first."
+        )
+    return matches[0]
+
+
+def _normalize_catalog_title(value: str) -> str:
+    value = re.sub(r"\((?:19|20)\d{2}\)\s*$", "", str(value))
+    return re.sub(r"[^a-z0-9]+", " ", value.lower()).strip()
+
+
+def _title_year(value: str) -> int | None:
+    match = re.search(r"\((19\d{2}|20\d{2})\)\s*$", str(value))
+    return int(match.group(1)) if match else None
+
+
+def _pipe_text(value) -> str:
+    if value is None or (isinstance(value, float) and math.isnan(value)):
+        return ""
+    return _text_tokens(str(value).replace("|", " ").replace(",", " "))
+
+
+def download_tmdb_hf_dataset(cache_dir: str | Path = "hf_cache") -> None:
+    """Download ada-datadruids/full_tmdb_movies_dataset to the local HF cache.
+
+    Only needs to run once.  Safe to call again — HF caching is idempotent.
+
+    Requires: ``pip install datasets``
+    """
+    try:
+        from datasets import load_dataset
+    except ImportError as exc:
+        raise RuntimeError("Install `datasets` first: pip install datasets") from exc
+
+    cache_dir = Path(cache_dir).resolve()
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    os.environ["HF_DATASETS_CACHE"] = str(cache_dir)
+    os.environ["HF_HOME"] = str(cache_dir)
+
+    print("[tmdb] downloading ada-datadruids/full_tmdb_movies_dataset …")
+    load_dataset("ada-datadruids/full_tmdb_movies_dataset", split="train", cache_dir=str(cache_dir))
+    print("[tmdb] download complete.")
+
+
+def load_cached_hf_movies(cfg: RecConfig) -> pd.DataFrame:
+    """Load the cached ada-datadruids/full_tmdb_movies_dataset Arrow file.
+
+    Columns used from the dataset
+    -----------------------------
+    id              - TMDB movie ID (int64)
+    title           - movie title
+    overview        - plot description
+    genres          - pipe- or comma-separated genre string
+    keywords        - comma-separated keyword string
+    tagline         - short marketing tagline
+    vote_count      - number of votes
+    vote_average    - average rating (0-10)
+    popularity      - TMDB popularity score
+    poster_path     - relative poster URL path
+    release_date    - release date string (YYYY-MM-DD)
+    """
+    configure_hf_cache(cfg.hf_cache_dir, cfg.hf_home_dir)
+    try:
+        from datasets import Dataset
+    except ImportError as exc:
+        raise RuntimeError("Install `datasets` to read the local Hugging Face Arrow cache.") from exc
+    arrow = _find_cached_arrow(
+        cfg.hf_cache_dir,
+        "ada-datadruids___full_tmdb_movies_dataset",
+        "full_tmdb_movies_dataset-train.arrow",
+    )
+    columns = [
+        "id",
+        "title",
+        "overview",
+        "genres",
+        "keywords",
+        "tagline",
+        "vote_count",
+        "vote_average",
+        "popularity",
+        "poster_path",
+        "release_date",
+        "original_language",
+        "adult",
+    ]
+    ds = Dataset.from_file(str(arrow))
+    fetch_cols = [c for c in columns if c in ds.column_names]
+    frame = ds.select_columns(fetch_cols).to_pandas()
+    frame["tmdb_id"] = pd.to_numeric(frame["id"], errors="coerce").astype("Int64")
+    frame["match_title"] = frame["title"].map(_normalize_catalog_title)
+    frame["match_year"] = pd.to_datetime(frame["release_date"], errors="coerce").dt.year.astype("Int64")
+    frame["vote_count"] = pd.to_numeric(frame.get("vote_count"), errors="coerce")
+    frame = frame[frame["vote_count"].fillna(0) >= 5]
+    frame["vote_average"] = pd.to_numeric(frame.get("vote_average"), errors="coerce")
+
+    adult_themes = frame.get('genres', '').astype(str).fillna('') + ", " + frame.get('keywords', '').astype(str).fillna('')
+    adult_themes = adult_themes.str.contains(r'\b(NSFW|Nudity|Sexual Content|Adult|sex)\b', case=False, na=False)
+    frame["hf_is_adult"] = frame.get("adult", pd.Series(False, index=frame.index)).fillna(False).astype(bool) | adult_themes
+
+    frame = frame.sort_values(["vote_count", "popularity"], ascending=False, na_position="last")
+    return frame.drop_duplicates(["match_title", "match_year"])
+
+
+def load_cached_hf_rawg(cfg: RecConfig) -> pd.DataFrame:
+    """Load useful RAWG fields from the cached Arrow file using memory mapping."""
+    configure_hf_cache(cfg.hf_cache_dir, cfg.hf_home_dir)
+    try:
+        from datasets import Dataset
+    except ImportError as exc:
+        raise RuntimeError("Install `datasets` to read the local Hugging Face Arrow cache.") from exc
+    arrow = _find_cached_arrow(
+        cfg.hf_cache_dir,
+        "atalaydenknalbant___rawg-games-dataset",
+        "rawg-games-dataset-train.arrow",
+    )
+    columns = [
+        "id",
+        "name",
+        "released",
+        "rating",
+        "ratings_count",
+        "reviews_count",
+        "metacritic",
+        "platforms",
+        "developers",
+        "genres",
+        "tags",
+        "publishers",
+        "description_raw",
+        "background_image",
+        "stores",
+        "esrb_rating",
+    ]
+    ds = Dataset.from_file(str(arrow))
+    fetch_cols = [c for c in columns if c in ds.column_names]
+    frame = ds.select_columns(fetch_cols).to_pandas()
+    
+    if "stores" in frame.columns:
+        frame = frame[~frame["stores"].astype(str).str.contains("itch.io", case=False, na=False)]
+        
+    if "ratings_count" in frame.columns:
+        frame["ratings_count"] = pd.to_numeric(frame["ratings_count"], errors="coerce")
+        frame = frame[frame["ratings_count"].fillna(0) >= 5]
+    elif "reviews_count" in frame.columns:
+        frame["reviews_count"] = pd.to_numeric(frame["reviews_count"], errors="coerce")
+        frame = frame[frame["reviews_count"].fillna(0) >= 5]
+
+    adult_tags = frame.get("tags", "").astype(str).str.contains(r'\b(NSFW|Nudity|Sexual Content|Adult|sex)\b', case=False, na=False)
+    mature_esrb = frame.get("esrb_rating", "").astype(str).str.contains(r'\b(Adults Only|Mature)\b', case=False, na=False)
+    frame["hf_is_adult"] = mature_esrb | adult_tags
+
+    frame["match_title"] = frame["name"].map(_normalize_catalog_title)
+    frame["match_year"] = pd.to_datetime(frame["released"], errors="coerce").dt.year.astype("Int64")
+    if "ratings_count" in frame.columns:
+        frame = frame.sort_values("ratings_count", ascending=False, na_position="last")
+    return frame.drop_duplicates("match_title")
+
+
+def enrich_item_metadata_from_hf_cache(
+    item_meta: pd.DataFrame,
+    cfg: RecConfig,
+) -> tuple[pd.DataFrame, dict[str, int]]:
+    """Enrich MovieLens and Steam metadata from the two local HF datasets.
+
+    Movie rows are joined on normalized title and release year. RAWG does not
+    expose Steam app IDs in this cache, so games use a conservative exact
+    normalized-title join and retain Steam's interaction/popularity fields.
+    """
+    out = item_meta.copy()
+    out["match_title"] = out["title"].map(_normalize_catalog_title)
+    out["match_year"] = out["title"].map(_title_year).astype("Int64")
+
+    movies = load_cached_hf_movies(cfg).rename(
+        columns={
+            "overview":      "hf_description",
+            "genres":        "hf_genres",
+            "keywords":      "hf_keywords",
+            "tagline":       "hf_tagline",
+            "vote_count":    "hf_vote_count",
+            "vote_average":  "hf_vote_average",
+            "poster_path":   "poster_url",
+            "tmdb_id":       "hf_tmdb_id",
+        }
+    )
+    movie_columns = [
+        "match_title",
+        "match_year",
+        "hf_description",
+        "hf_genres",
+        "hf_keywords",
+        "hf_tagline",
+        "hf_vote_count",
+        "hf_vote_average",
+        "poster_url",
+        "hf_tmdb_id",
+        "hf_is_adult",
+    ]
+    movie_rows = out["domain"].eq("movie")
+    enriched_movies = out.loc[movie_rows].merge(movies[movie_columns], on=["match_title", "match_year"], how="left")
+    # Back-fill tmdb_id from HF dataset where MovieLens links.csv had no entry
+    if "hf_tmdb_id" in enriched_movies.columns:
+        enriched_movies["tmdb_id"] = enriched_movies["tmdb_id"].where(
+            enriched_movies["tmdb_id"].notna(), enriched_movies["hf_tmdb_id"]
+        )
+        enriched_movies = enriched_movies.drop(columns=["hf_tmdb_id"], errors="ignore")
+
+    rawg = load_cached_hf_rawg(cfg).rename(
+        columns={
+            "id": "rawg_id",
+            "description_raw": "hf_description",
+            "genres": "hf_genres",
+            "tags": "hf_tags",
+            "developers": "hf_developers",
+            "publishers": "hf_publishers",
+            "platforms": "hf_platforms",
+            "rating": "rawg_rating",
+            "ratings_count": "rawg_ratings_count",
+            "reviews_count": "rawg_reviews_count",
+        }
+    )
+    rawg_columns = [
+        "match_title",
+        "rawg_id",
+        "hf_description",
+        "hf_genres",
+        "hf_tags",
+        "hf_developers",
+        "hf_publishers",
+        "hf_platforms",
+        "rawg_rating",
+        "rawg_ratings_count",
+        "rawg_reviews_count",
+        "metacritic",
+        "background_image",
+        "hf_is_adult",
+    ]
+    game_rows = out["domain"].eq("game")
+    enriched_games = out.loc[game_rows].merge(rawg[rawg_columns], on="match_title", how="left")
+
+    other_rows = out.loc[~(movie_rows | game_rows)]
+    out = pd.concat([enriched_movies, enriched_games, other_rows], ignore_index=True, sort=False)
+    existing_description = out["description"].fillna("").astype(str)
+    hf_description = out["hf_description"].fillna("").astype(str)
+    out["description"] = existing_description.where(existing_description.str.len() >= hf_description.str.len(), hf_description)
+    extra_tokens = (
+        out.get("hf_genres",   pd.Series("", index=out.index)).fillna("").map(_pipe_text)
+        + " "
+        + out.get("hf_keywords", pd.Series("", index=out.index)).fillna("").map(_pipe_text)
+        + " "
+        + out.get("hf_tags",    pd.Series("", index=out.index)).fillna("").map(_pipe_text)
+        + " "
+        + out.get("hf_tagline", pd.Series("", index=out.index)).fillna("").map(_pipe_text)
+        + " "
+        + out.get("hf_developers",  pd.Series("", index=out.index)).fillna("").map(_pipe_text)
+        + " "
+        + out.get("hf_publishers",  pd.Series("", index=out.index)).fillna("").map(_pipe_text)
+        + " "
+        + out["description"].map(lambda value: _text_tokens(value, limit=100))
+    )
+    out["tokens"] = (out["tokens"].fillna("") + " " + extra_tokens).str.strip()
+    
+    hf_adult = out.get("hf_is_adult", pd.Series(False, index=out.index)).fillna(False).astype(bool)
+    if "is_adult" in out.columns:
+        out["is_adult"] = out["is_adult"].astype(bool) | hf_adult
+    else:
+        out["is_adult"] = hf_adult
+    out = out.drop(columns=["hf_is_adult"], errors="ignore")
+
+    stats = {
+        "movie_rows": int(movie_rows.sum()),
+        "movie_matches": int(enriched_movies["hf_description"].notna().sum()),
+        "game_rows": int(game_rows.sum()),
+        "game_matches": int(enriched_games["rawg_id"].notna().sum()),
+    }
+    return out.drop(columns=["match_title", "match_year"], errors="ignore"), stats
+
+
+def _title_tokens(title: str) -> str:
+    title = re.sub(r"\(\d{4}\)", "", str(title).lower())
+    return " ".join(t for t in re.findall(r"[a-z0-9]+", title) if len(t) > 2)
+
+
+def _text_tokens(text: str, limit: int | None = None) -> str:
+    tokens = [t for t in re.findall(r"[a-z0-9]+", str(text).lower()) if len(t) > 2]
+    if limit is not None:
+        tokens = tokens[:limit]
+    return " ".join(tokens)
+
+
+def _tag_tokens(tags) -> str:
+    if not isinstance(tags, list):
+        return ""
+    return " ".join(_text_tokens(tag) for tag in tags)
+
+
+def _read_movielens_tags(zip_path: str | Path, max_tags_per_movie: int = 40) -> pd.DataFrame:
+    try:
+        tags = _read_csv_from_zip(zip_path, "ml-32m/tags.csv", usecols=["movieId", "tag"])
+    except (KeyError, FileNotFoundError):
+        return pd.DataFrame(columns=["movieId", "tag_tokens", "is_adult"])
+    
+    adult_tags = tags["tag"].astype(str).str.contains(r'\b(NSFW|Nudity|Sexual Content|Adult|sex)\b', case=False, na=False)
+    is_adult_df = adult_tags.groupby(tags["movieId"]).any().reset_index(name="is_adult")
+
+    tags["tag"] = tags["tag"].fillna("").astype(str).map(_text_tokens)
+    tags = tags.loc[tags["tag"].ne("")]
+    tags = tags.drop_duplicates(["movieId", "tag"])
+    tag_tokens = (
+        tags.groupby("movieId")["tag"]
+        .apply(lambda values: " ".join(list(values)[:max_tags_per_movie]))
+        .reset_index(name="tag_tokens")
+    )
+    return tag_tokens.merge(is_adult_df, on="movieId", how="left")
+
+
+def _read_steam_metadata(zip_path: str | Path) -> pd.DataFrame:
+    try:
+        with zipfile.ZipFile(zip_path) as zf:
+            with zf.open("games_metadata.json") as fh:
+                meta = pd.read_json(fh, lines=True)
+    except (KeyError, FileNotFoundError):
+        return pd.DataFrame(columns=["app_id", "tag_tokens", "description", "is_adult"])
+    
+    adult_tags = meta["tags"].astype(str).str.contains(r'\b(NSFW|Nudity|Sexual Content|Hentai|Adult|sex)\b', case=False, na=False)
+    meta["is_adult"] = adult_tags
+    
+    meta["tag_tokens"] = meta["tags"].map(_tag_tokens).fillna("")
+    meta["description"] = meta["description"].fillna("").astype(str)
+    return meta[["app_id", "tag_tokens", "description", "is_adult"]]
+
+
+def _movie_genre_bridge_tokens(genres: str) -> str:
+    bridge = {
+        "Action": "action combat fast shooter fighting",
+        "Adventure": "adventure exploration quest puzzle platformer",
+        "Animation": "animation animated cartoony colorful cute family",
+        "Children": "family friendly casual cute cozy",
+        "Comedy": "funny comedy humorous casual party",
+        "Crime": "crime detective mystery noir stealth",
+        "Documentary": "documentary educational simulation realistic",
+        "Drama": "story rich narrative emotional choices",
+        "Fantasy": "fantasy magic rpg adventure mythical",
+        "Film-Noir": "noir detective mystery dark",
+        "Horror": "horror survival dark atmospheric",
+        "Musical": "music rhythm soundtrack",
+        "Mystery": "mystery detective puzzle investigation",
+        "Romance": "romance emotional story rich dating",
+        "Sci-Fi": "sci fi science fiction space futuristic",
+        "Thriller": "thriller suspense stealth action",
+        "War": "war military strategy tactical",
+        "Western": "western open world adventure",
+        "IMAX": "cinematic immersive",
+    }
+    out = []
+    for genre in str(genres).split("|"):
+        out.append(bridge.get(genre, _text_tokens(genre)))
+    return " ".join(out)
+
+
+def build_public_pretraining_data(
+    cfg: RecConfig,
+    enrich_from_hf: bool = True,
+) -> tuple[pd.DataFrame, pd.DataFrame]:
+    ml_inter, ml_items = load_movielens(cfg)
+    st_inter, st_items = load_steam(cfg)
+    interactions = pd.concat([ml_inter, st_inter], ignore_index=True)
+    interactions = interactions.dropna().drop_duplicates()
+    # Keep only the most recent interaction per (user, item) pair
+    interactions = (
+        interactions.sort_values("timestamp")
+        .drop_duplicates(subset=["user_key", "item_key"], keep="last")
+        .reset_index(drop=True)
+    )
+    # Remove items with too few interactions (noisy, unlearnable)
+    item_counts = interactions["item_key"].value_counts()
+    keep_items = set(item_counts[item_counts >= cfg.min_item_interactions].index)
+    interactions = interactions.loc[interactions["item_key"].isin(keep_items)]
+    item_meta = (
+        pd.concat([ml_items, st_items], ignore_index=True)
+        .drop_duplicates("item_key")
+        .reset_index(drop=True)
+    )
+    if enrich_from_hf:
+        item_meta, stats = enrich_item_metadata_from_hf_cache(item_meta, cfg)
+        item_meta.attrs["hf_enrichment_stats"] = stats
+    return interactions, item_meta
+
+
+def enrich_movie_descriptions_from_tmdb(
+    item_meta: pd.DataFrame,
+    api_key: str | None = None,
+    cache_path: str | Path = "artifacts/tmdb_movie_descriptions.csv",
+    limit: int | None = None,
+    sleep_s: float = 0.03,
+) -> pd.DataFrame:
+    import requests
+
+    api_key = api_key or os.getenv("TMDB_API_KEY")
+    if not api_key:
+        raise RuntimeError("Set TMDB_API_KEY or pass api_key=... before fetching TMDB descriptions.")
+    if "tmdb_id" not in item_meta.columns:
+        raise ValueError("item_meta has no tmdb_id column. Rebuild item_meta with the current loader first.")
+
+    cache_path = Path(cache_path)
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    if cache_path.exists():
+        cache = pd.read_csv(cache_path)
+    else:
+        cache = pd.DataFrame(columns=["tmdb_id", "description"])
+    cached = set(cache["tmdb_id"].dropna().astype(int).tolist())
+
+    movie_ids = (
+        item_meta.loc[item_meta["domain"].eq("movie"), "tmdb_id"]
+        .dropna()
+        .astype(int)
+        .drop_duplicates()
+        .tolist()
+    )
+    missing = [tmdb_id for tmdb_id in movie_ids if tmdb_id not in cached]
+    if limit is not None:
+        missing = missing[:limit]
+
+    rows = []
+    for tmdb_id in tqdm(missing, desc="fetch TMDB overviews"):
+        url = f"https://api.themoviedb.org/3/movie/{tmdb_id}"
+        try:
+            r = requests.get(url, params={"api_key": api_key, "language": "en-US"}, timeout=20)
+            if r.status_code == 404:
+                continue
+            r.raise_for_status()
+            rows.append({"tmdb_id": tmdb_id, "description": r.json().get("overview", "") or ""})
+            if len(rows) % 100 == 0:
+                cache = pd.concat([cache, pd.DataFrame(rows)], ignore_index=True).drop_duplicates("tmdb_id", keep="last")
+                cache.to_csv(cache_path, index=False)
+                rows = []
+            if sleep_s:
+                time.sleep(sleep_s)
+        except requests.RequestException:
+            continue
+
+    if rows:
+        cache = pd.concat([cache, pd.DataFrame(rows)], ignore_index=True).drop_duplicates("tmdb_id", keep="last")
+        cache.to_csv(cache_path, index=False)
+
+    out = item_meta.copy()
+    cache["tmdb_id"] = cache["tmdb_id"].astype("Int64")
+    out = out.merge(cache, on="tmdb_id", how="left", suffixes=("", "_tmdb"))
+    out["description"] = out["description_tmdb"].fillna(out.get("description", ""))
+    out = out.drop(columns=[c for c in ["description_tmdb"] if c in out.columns])
+    out["tokens"] = out["tokens"].fillna("") + " " + out["description"].fillna("").map(lambda x: _text_tokens(x, limit=80))
+    return out
+
+
+def build_text_embedding_tensor(
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+    model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+    cache_path: str | Path = "artifacts/item_text_embeddings.pt",
+    batch_size: int = 128,
+    force_recompute: bool = False,
+) -> torch.Tensor:
+    cache_path = Path(cache_path)
+    n_items = max(item_to_idx.values()) + 1
+    ordered = item_meta.loc[item_meta["item_key"].isin(item_to_idx)].copy()
+    ordered["idx"] = ordered["item_key"].map(item_to_idx)
+    ordered = ordered.sort_values("idx")
+    signature = {
+        "model_name": model_name,
+        "item_keys": ordered["item_key"].tolist(),
+        "descriptions": ordered["description"].fillna("").tolist(),
+        "tokens": ordered["tokens"].fillna("").tolist(),
+    }
+
+    if cache_path.exists() and not force_recompute:
+        cached = torch.load(cache_path, map_location="cpu", weights_only=False)
+        if cached.get("signature") == signature:
+            return cached["tensor"]
+
+    try:
+        from sentence_transformers import SentenceTransformer
+    except ImportError as exc:
+        raise RuntimeError("Install sentence-transformers first: %pip install -q sentence-transformers") from exc
+
+    texts = (
+        ordered["title"].fillna("")
+        + ". "
+        + ordered["description"].fillna("")
+        + " "
+        + ordered["tokens"].fillna("")
+    ).tolist()
+    encoder = SentenceTransformer(model_name)
+    embeddings = encoder.encode(
+        texts,
+        batch_size=batch_size,
+        show_progress_bar=True,
+        normalize_embeddings=True,
+        convert_to_numpy=True,
+    )
+
+    tensor = torch.zeros((n_items, embeddings.shape[1]), dtype=torch.float32)
+    tensor[torch.tensor(ordered["idx"].to_numpy(), dtype=torch.long)] = torch.tensor(embeddings, dtype=torch.float32)
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    torch.save({"signature": signature, "tensor": tensor}, cache_path)
+    return tensor
+
+
+def make_vocab(values: Iterable[str], add_pad: bool = True) -> dict[str, int]:
+    start = 1 if add_pad else 0
+    vocab = {v: i + start for i, v in enumerate(sorted(set(map(str, values))))}
+    if add_pad:
+        vocab["<PAD>"] = PAD
+    return vocab
+
+
+SURVEY_RATING_VALUES = {
+    "5 Stars": 5.0,
+    "4 Stars": 4.0,
+    "Didn't watch but would watch": 3.5,
+    "Didn't play but would play": 3.5,
+    "3 Stars": 3.0,
+    "2 Stars": 2.0,
+    "Didn't watch and wouldn't watch": 1.5,
+    "Didn't play and wouldn't play": 1.5,
+    "1 Star": 1.0,
+}
+
+
+def parse_survey_item_id(value: str) -> str:
+    domain, item_id = str(value).split("_", 1)
+    if domain not in {"movie", "game"} or not item_id:
+        raise ValueError(f"Unsupported survey item id: {value!r}")
+    return f"{domain}:{item_id}"
+
+
+def survey_rating_value(value: str) -> float:
+    if value not in SURVEY_RATING_VALUES:
+        raise ValueError(f"Unknown survey rating label: {value!r}")
+    return SURVEY_RATING_VALUES[value]
+
+
+def survey_rating_weight(value: str) -> float:
+    return max(-1.0, min((survey_rating_value(value) - 3.0) / 2.0, 1.0))
+
+
+def _split_genres(value) -> list[str]:
+    if pd.isna(value):
+        return []
+    return [part.strip().lower() for part in str(value).split("|") if part.strip()]
+
+
+def build_genre_vocab(survey: pd.DataFrame) -> dict[str, int]:
+    columns = [
+        "movie_genres_fav",
+        "movie_genres_disliked",
+        "game_genres_fav",
+        "game_genres_disliked",
+    ]
+    values = {genre for column in columns for value in survey[column] for genre in _split_genres(value)}
+    return {genre: idx for idx, genre in enumerate(sorted(values))}
+
+
+def genre_preference_vector(row: pd.Series, genre_vocab: dict[str, int]) -> torch.Tensor:
+    vector = torch.zeros(len(genre_vocab), dtype=torch.float32)
+    for column in ["movie_genres_fav", "game_genres_fav"]:
+        for genre in _split_genres(row[column]):
+            if genre in genre_vocab:
+                vector[genre_vocab[genre]] = 1.0
+    for column in ["movie_genres_disliked", "game_genres_disliked"]:
+        for genre in _split_genres(row[column]):
+            if genre in genre_vocab:
+                vector[genre_vocab[genre]] = -1.0
+    return vector
+
+
+def load_survey_user_profiles(
+    csv_path: str | Path,
+    item_to_idx: dict[str, int] | None = None,
+) -> tuple[list[dict], dict[str, int]]:
+    survey = pd.read_csv(csv_path)
+    genre_vocab = build_genre_vocab(survey)
+    profiles = []
+    for user_number, row in survey.iterrows():
+        ratings = json.loads(row["ratings"])
+        profile_ratings = []
+        for rating in ratings:
+            item_key = parse_survey_item_id(rating["item_id"])
+            item_id = None if item_to_idx is None else item_to_idx.get(item_key)
+            profile_ratings.append(
+                {
+                    "item_key": item_key,
+                    "item_id": item_id,
+                    "title": rating.get("title", ""),
+                    "domain": rating.get("type", item_key.split(":", 1)[0]),
+                    "label": rating["rating"],
+                    "value": survey_rating_value(rating["rating"]),
+                    "weight": survey_rating_weight(rating["rating"]),
+                }
+            )
+        profiles.append(
+            {
+                "user_key": f"survey:{user_number}",
+                "age": int(row["age"]),
+                "gender": str(row["gender"]).strip().lower(),
+                "profession": str(row["profession"]).strip().lower(),
+                "country": str(row["country"]).strip().lower(),
+                "movie_genres_fav": _split_genres(row["movie_genres_fav"]),
+                "movie_genres_disliked": _split_genres(row["movie_genres_disliked"]),
+                "game_genres_fav": _split_genres(row["game_genres_fav"]),
+                "game_genres_disliked": _split_genres(row["game_genres_disliked"]),
+                "genre_preferences": genre_preference_vector(row, genre_vocab),
+                "ratings": profile_ratings,
+            }
+        )
+    return profiles, genre_vocab
+
+
+def build_survey_interactions(
+    csv_path: str | Path,
+    positive_threshold: float = 3.5,
+) -> pd.DataFrame:
+    """Convert explicit survey labels into ordered positive pretraining events."""
+    profiles, _ = load_survey_user_profiles(csv_path)
+    rows = []
+    for profile in profiles:
+        for position, rating in enumerate(profile["ratings"]):
+            if rating["value"] < positive_threshold:
+                continue
+            rows.append(
+                {
+                    "user_key": profile["user_key"],
+                    "item_key": rating["item_key"],
+                    "timestamp": position,
+                    "domain": rating["domain"],
+                    "rating_value": rating["value"],
+                    "rating_weight": rating["weight"],
+                }
+            )
+    return pd.DataFrame(rows)
+
+
+def survey_catalog_coverage(profiles: Sequence[dict]) -> dict[str, int | float]:
+    ratings = [rating for profile in profiles for rating in profile["ratings"]]
+    mapped = [rating for rating in ratings if rating.get("item_id") is not None]
+    return {
+        "ratings": len(ratings),
+        "mapped_ratings": len(mapped),
+        "unique_items": len({rating["item_key"] for rating in ratings}),
+        "mapped_unique_items": len({rating["item_key"] for rating in mapped}),
+        "coverage": len(mapped) / max(len(ratings), 1),
+    }
+
+
+def _profile_rating_map(profile: dict) -> dict[int, float]:
+    return {
+        int(rating["item_id"]): float(rating["weight"])
+        for rating in profile["ratings"]
+        if rating.get("item_id") is not None
+    }
+
+
+def survey_user_similarity(
+    target_profile: dict,
+    other_profile: dict,
+    rating_weight: float = 0.7,
+    genre_weight: float = 0.3,
+    overlap_shrinkage: float = 3.0,
+) -> dict[str, float]:
+    """Blend shared-rating cosine similarity with explicit genre preferences."""
+    target_ratings = _profile_rating_map(target_profile)
+    other_ratings = _profile_rating_map(other_profile)
+    shared = sorted(set(target_ratings) & set(other_ratings))
+
+    rating_similarity = 0.0
+    if shared:
+        target_values = np.array([target_ratings[item_id] for item_id in shared], dtype=np.float32)
+        other_values = np.array([other_ratings[item_id] for item_id in shared], dtype=np.float32)
+        denominator = float(np.linalg.norm(target_values) * np.linalg.norm(other_values))
+        if denominator > 0:
+            raw_similarity = float(target_values @ other_values / denominator)
+            shrinkage = len(shared) / (len(shared) + max(float(overlap_shrinkage), 0.0))
+            rating_similarity = raw_similarity * shrinkage
+
+    target_genres = torch.as_tensor(target_profile["genre_preferences"], dtype=torch.float32)
+    other_genres = torch.as_tensor(other_profile["genre_preferences"], dtype=torch.float32)
+    genre_denominator = float(target_genres.norm() * other_genres.norm())
+    genre_similarity = (
+        float(torch.dot(target_genres, other_genres) / genre_denominator)
+        if genre_denominator > 0
+        else 0.0
+    )
+
+    available_rating_weight = float(rating_weight) if shared else 0.0
+    available_genre_weight = float(genre_weight) if genre_denominator > 0 else 0.0
+    total_weight = available_rating_weight + available_genre_weight
+    similarity = 0.0
+    if total_weight > 0:
+        similarity = (
+            available_rating_weight * rating_similarity
+            + available_genre_weight * genre_similarity
+        ) / total_weight
+    return {
+        "similarity": float(similarity),
+        "rating_similarity": float(rating_similarity),
+        "genre_similarity": float(genre_similarity),
+        "shared_items": float(len(shared)),
+    }
+
+
+def find_similar_survey_users(
+    target_profile: dict,
+    profiles: Sequence[dict],
+    k: int = 15,
+    min_similarity: float = 0.0,
+    rating_weight: float = 0.7,
+    genre_weight: float = 0.3,
+    overlap_shrinkage: float = 3.0,
+) -> list[dict]:
+    neighbors = []
+    for other in profiles:
+        if other.get("user_key") == target_profile.get("user_key"):
+            continue
+        similarity = survey_user_similarity(
+            target_profile,
+            other,
+            rating_weight=rating_weight,
+            genre_weight=genre_weight,
+            overlap_shrinkage=overlap_shrinkage,
+        )
+        if similarity["similarity"] < min_similarity:
+            continue
+        neighbors.append(
+            {
+                "user_key": other["user_key"],
+                "profile": other,
+                **similarity,
+            }
+        )
+    neighbors.sort(
+        key=lambda row: (row["similarity"], row["shared_items"]),
+        reverse=True,
+    )
+    return neighbors[:k]
+
+
+def recommend_user_cf(
+    target_profile: dict,
+    profiles: Sequence[dict],
+    k: int = 10,
+    neighbor_count: int = 15,
+    domain: str | None = None,
+    min_similarity: float = 0.05,
+    min_score: float = 0.0,
+    rating_weight: float = 0.7,
+    genre_weight: float = 0.3,
+    overlap_shrinkage: float = 3.0,
+) -> tuple[list[tuple[int, float]], list[dict]]:
+    """Recommend unseen survey items from the target user's nearest neighbors."""
+    if domain not in {None, "movie", "game"}:
+        raise ValueError("domain must be None, 'movie', or 'game'.")
+    neighbors = find_similar_survey_users(
+        target_profile,
+        profiles,
+        k=neighbor_count,
+        min_similarity=min_similarity,
+        rating_weight=rating_weight,
+        genre_weight=genre_weight,
+        overlap_shrinkage=overlap_shrinkage,
+    )
+    seen = set(_profile_rating_map(target_profile))
+    weighted_scores: dict[int, float] = {}
+    similarity_sums: dict[int, float] = {}
+    support: dict[int, int] = {}
+    for neighbor in neighbors:
+        similarity = float(neighbor["similarity"])
+        for rating in neighbor["profile"]["ratings"]:
+            item_id = rating.get("item_id")
+            if item_id is None or item_id in seen:
+                continue
+            if domain is not None and rating["domain"] != domain:
+                continue
+            weighted_scores[item_id] = weighted_scores.get(item_id, 0.0) + similarity * float(rating["weight"])
+            similarity_sums[item_id] = similarity_sums.get(item_id, 0.0) + abs(similarity)
+            support[item_id] = support.get(item_id, 0) + 1
+
+    rows = []
+    for item_id, numerator in weighted_scores.items():
+        score = numerator / max(similarity_sums[item_id], 1e-8)
+        # A small support adjustment prevents single-neighbor items from
+        # dominating equally scored items with broader agreement.
+        score *= support[item_id] / (support[item_id] + 1.0)
+        if score >= min_score:
+            rows.append((int(item_id), float(score)))
+    rows.sort(key=lambda row: (row[1], support[row[0]]), reverse=True)
+    return rows[:k], neighbors
+
+
+def evaluate_user_cf_leave_one_out(
+    profiles: Sequence[dict],
+    k: int = 10,
+    neighbor_count: int = 15,
+    domain: str | None = None,
+    min_similarity: float = 0.05,
+) -> dict[str, float]:
+    """Evaluate user-CF by hiding each survey user's final positive item."""
+    hits, reciprocal_rank, total, users_with_recommendations = 0, 0.0, 0, 0
+    for profile in tqdm(profiles, total=len(profiles), desc="evaluate user CF", leave=False):
+        positive_indices = [
+            index
+            for index, rating in enumerate(profile["ratings"])
+            if rating.get("item_id") is not None
+            and rating["weight"] > 0
+            and (domain is None or rating["domain"] == domain)
+        ]
+        if len(positive_indices) < 2:
+            continue
+        held_out_index = positive_indices[-1]
+        target = int(profile["ratings"][held_out_index]["item_id"])
+        target_profile = {
+            **profile,
+            "ratings": [
+                rating
+                for index, rating in enumerate(profile["ratings"])
+                if index != held_out_index
+            ],
+        }
+        recommendations, _ = recommend_user_cf(
+            target_profile,
+            profiles,
+            k=k,
+            neighbor_count=neighbor_count,
+            domain=domain,
+            min_similarity=min_similarity,
+        )
+        ranked = [item_id for item_id, _ in recommendations]
+        total += 1
+        users_with_recommendations += int(bool(ranked))
+        if target in ranked:
+            rank = ranked.index(target) + 1
+            hits += 1
+            reciprocal_rank += 1.0 / rank
+    return {
+        f"UserCF_HR@{k}": hits / max(total, 1),
+        f"UserCF_MRR@{k}": reciprocal_rank / max(total, 1),
+        "user_cf_users": float(total),
+        "user_cf_coverage": users_with_recommendations / max(total, 1),
+    }
+
+
+def recommend_hybrid_survey_user(
+    target_profile: dict,
+    profiles: Sequence[dict],
+    model: CLEPIDTN,
+    item_index: torch.Tensor,
+    cfg: RecConfig,
+    k: int = 10,
+    domain: str | None = None,
+    neural_weight: float = 0.75,
+    user_cf_weight: float = 0.25,
+    candidate_multiplier: int = 5,
+    text_index: torch.Tensor | None = None,
+    neighbor_count: int = 15,
+) -> tuple[list[tuple[int, float]], dict]:
+    """Fuse neural and survey user-CF rankings with reciprocal-rank fusion."""
+    mapped_ratings = [
+        rating for rating in target_profile["ratings"] if rating.get("item_id") is not None
+    ]
+    if not mapped_ratings:
+        raise ValueError("The survey profile has no items mapped to the model catalog.")
+    history_ids = [int(rating["item_id"]) for rating in mapped_ratings]
+    history_weights = [float(rating["weight"]) for rating in mapped_ratings]
+    pool_size = max(k, k * max(int(candidate_multiplier), 1))
+    neural = recommend_from_history(
+        model,
+        item_index,
+        history_ids,
+        user_id=None,
+        activity=len(history_ids),
+        cfg=cfg,
+        k=pool_size,
+        domain=domain,
+        text_index=text_index,
+        history_weights=history_weights,
+    )
+    user_cf, neighbors = recommend_user_cf(
+        target_profile,
+        profiles,
+        k=pool_size,
+        neighbor_count=neighbor_count,
+        domain=domain,
+    )
+
+    fused: dict[int, float] = {}
+    rank_constant = 20.0
+    for rank, (item_id, _) in enumerate(neural, start=1):
+        fused[item_id] = fused.get(item_id, 0.0) + float(neural_weight) / (rank_constant + rank)
+    for rank, (item_id, _) in enumerate(user_cf, start=1):
+        fused[item_id] = fused.get(item_id, 0.0) + float(user_cf_weight) / (rank_constant + rank)
+    rows = sorted(fused.items(), key=lambda row: row[1], reverse=True)[:k]
+    return rows, {
+        "neural_recommendations": neural,
+        "user_cf_recommendations": user_cf,
+        "neighbors": neighbors,
+    }
+
+
+def encode_item_metadata(item_meta: pd.DataFrame, item_to_idx: dict[str, int], max_tokens: int = 80):
+    token_counts: dict[str, int] = {}
+    for text in tqdm(
+        item_meta["tokens"].fillna(""),
+        total=len(item_meta),
+        desc="count metadata tokens",
+        leave=False,
+    ):
+        for token in str(text).split():
+            token_counts[token] = token_counts.get(token, 0) + 1
+    kept = [t for t, c in token_counts.items() if c >= 3]
+    token_to_idx = {"<PAD>": PAD, "<UNK>": 1, **{t: i + 2 for i, t in enumerate(sorted(kept))}}
+    domain_to_idx = {"movie": 0, "game": 1}
+
+    n_items = max(item_to_idx.values()) + 1
+    token_ids = np.zeros((n_items, max_tokens), dtype=np.int64)
+    domain_ids = np.zeros(n_items, dtype=np.int64)
+    title_lookup = {}
+
+    for row in tqdm(
+        item_meta.itertuples(index=False),
+        total=len(item_meta),
+        desc="encode item metadata",
+        leave=False,
+    ):
+        idx = item_to_idx.get(row.item_key)
+        if idx is None:
+            continue
+        toks = [token_to_idx.get(t, 1) for t in str(row.tokens).split()[:max_tokens]]
+        token_ids[idx, : len(toks)] = toks
+        domain_ids[idx] = domain_to_idx.get(row.domain, 0)
+        title_lookup[idx] = row.title
+    return token_to_idx, torch.tensor(token_ids), torch.tensor(domain_ids), title_lookup
+
+
+def make_sequence_samples(interactions: pd.DataFrame, cfg: RecConfig, all_item_keys: Iterable[str] | None = None):
+    user_counts = interactions.groupby("user_key").size()
+    keep_users = set(user_counts[user_counts >= cfg.min_user_events].index)
+    interactions = interactions.loc[interactions["user_key"].isin(keep_users)].copy()
+
+    user_to_idx = make_vocab(interactions["user_key"], add_pad=False)
+    if all_item_keys is None:
+        item_values = interactions["item_key"]
+    else:
+        item_values = pd.concat(
+            [interactions["item_key"], pd.Series(list(all_item_keys), dtype="object")],
+            ignore_index=True,
+        )
+    item_to_idx = make_vocab(item_values, add_pad=True)
+    interactions["u"] = interactions["user_key"].map(user_to_idx).astype(np.int64)
+    interactions["i"] = interactions["item_key"].map(item_to_idx).astype(np.int64)
+    interactions = interactions.sort_values(["u", "timestamp"])
+
+    histories, targets, users, activity = [], [], [], []
+    eval_rows = []
+    grouped = interactions.groupby("u", sort=False)
+    for u, g in tqdm(grouped, total=grouped.ngroups, desc="build sequences", leave=False):
+        seq = g["i"].tolist()
+        if len(seq) < cfg.min_user_events:
+            continue
+        eval_rows.append((u, seq[:-1][-cfg.max_seq_len :], seq[-1]))
+        for pos in range(1, len(seq) - 1):
+            histories.append(seq[:pos][-cfg.max_seq_len :])
+            targets.append(seq[pos])
+            users.append(u)
+            activity.append(min(int(math.log2(len(seq))), 8))
+            if len(targets) >= cfg.max_train_samples:
+                break
+        if len(targets) >= cfg.max_train_samples:
+            break
+
+    return {
+        "user_to_idx": user_to_idx,
+        "item_to_idx": item_to_idx,
+        "histories": histories,
+        "targets": targets,
+        "users": users,
+        "activity": activity,
+        "eval_rows": eval_rows,
+    }
+
+
+def make_temporal_sequence_splits(
+    interactions: pd.DataFrame,
+    cfg: RecConfig,
+    all_item_keys: Iterable[str] | None = None,
+) -> dict:
+    """Create leakage-resistant train/validation/test next-item splits.
+
+    The last event is test, the penultimate event is validation, and training
+    targets come only from earlier events. Users need at least four events for
+    all three partitions.
+    """
+    user_counts = interactions.groupby("user_key").size()
+    keep_users = set(user_counts[user_counts >= cfg.min_user_events].index)
+    frame = interactions.loc[interactions["user_key"].isin(keep_users)].copy()
+    user_to_idx = make_vocab(frame["user_key"], add_pad=False)
+    item_values = frame["item_key"]
+    if all_item_keys is not None:
+        item_values = pd.concat([item_values, pd.Series(list(all_item_keys), dtype="object")], ignore_index=True)
+    item_to_idx = make_vocab(item_values, add_pad=True)
+    frame["u"] = frame["user_key"].map(user_to_idx).astype(np.int64)
+    frame["i"] = frame["item_key"].map(item_to_idx).astype(np.int64)
+    frame = frame.sort_values(["u", "timestamp"])
+
+    histories, targets, users, activity = [], [], [], []
+    validation_rows, test_rows = [], []
+    grouped = frame.groupby("u", sort=False)
+    for u, group in tqdm(grouped, total=grouped.ngroups, desc="build temporal splits", leave=False):
+        sequence = group["i"].tolist()
+        if len(sequence) < 4:
+            continue
+        validation_rows.append((u, sequence[:-2][-cfg.max_seq_len :], sequence[-2]))
+        test_rows.append((u, sequence[:-1][-cfg.max_seq_len :], sequence[-1]))
+        if len(targets) >= cfg.max_train_samples:
+            continue
+        for position in range(1, len(sequence) - 2):
+            histories.append(sequence[:position][-cfg.max_seq_len :])
+            targets.append(sequence[position])
+            users.append(u)
+            activity.append(min(int(math.log2(len(sequence))), 8))
+            if len(targets) >= cfg.max_train_samples:
+                break
+
+    return {
+        "user_to_idx": user_to_idx,
+        "item_to_idx": item_to_idx,
+        "histories": histories,
+        "targets": targets,
+        "users": users,
+        "activity": activity,
+        "validation_rows": validation_rows,
+        "test_rows": test_rows,
+        "eval_rows": validation_rows,
+    }
+
+
+class SequenceDataset(Dataset):
+    def __init__(self, histories, targets, users, activity, max_seq_len: int):
+        self.histories = histories
+        self.targets = targets
+        self.users = users
+        self.activity = activity
+        self.max_seq_len = max_seq_len
+
+    def __len__(self) -> int:
+        return len(self.targets)
+
+    def __getitem__(self, idx: int):
+        hist = self.histories[idx]
+        padded = [PAD] * (self.max_seq_len - len(hist)) + hist[-self.max_seq_len :]
+        mask = [0] * (self.max_seq_len - len(hist)) + [1] * min(len(hist), self.max_seq_len)
+        return {
+            "history": torch.tensor(padded, dtype=torch.long),
+            "mask": torch.tensor(mask, dtype=torch.bool),
+            "target": torch.tensor(self.targets[idx], dtype=torch.long),
+            "user": torch.tensor(self.users[idx], dtype=torch.long),
+            "activity": torch.tensor(self.activity[idx], dtype=torch.long),
+        }
+
+
+class CLEPIDTN(nn.Module):
+    def __init__(
+        self,
+        n_items: int,
+        n_users: int,
+        n_tokens: int,
+        item_token_ids: torch.Tensor,
+        item_domain_ids: torch.Tensor,
+        cfg: RecConfig,
+        item_text_embeddings: torch.Tensor | None = None,
+    ):
+        super().__init__()
+        d = cfg.embedding_dim
+        self.cfg = cfg
+        self.item_token_ids = item_token_ids
+        self.item_domain_ids = item_domain_ids
+        self.item_text_embeddings = item_text_embeddings
+        self.item_id = nn.Embedding(n_items, d, padding_idx=PAD)
+        self.user_id = nn.Embedding(n_users, d)
+        self.activity = nn.Embedding(9, d)
+        self.token = nn.Embedding(n_tokens, d, padding_idx=PAD)
+        self.domain = nn.Embedding(2, d)
+        self.pos = nn.Embedding(cfg.max_seq_len, d)
+        text_dim = 0 if item_text_embeddings is None else int(item_text_embeddings.shape[1])
+        self.text_proj = nn.Linear(text_dim, d) if text_dim else None
+
+        enc_layer = nn.TransformerEncoderLayer(
+            d_model=d,
+            nhead=cfg.attention_heads,
+            dim_feedforward=d * 4,
+            dropout=cfg.dropout,
+            batch_first=True,
+            activation="gelu",
+        )
+        # Nested tensors can fail when stochastic augmentation produces heavily
+        # padded batches. Dense tensors are more predictable for our fixed,
+        # left-padded sequence layout.
+        self.sequence_encoder = nn.TransformerEncoder(
+            enc_layer,
+            num_layers=cfg.transformer_layers,
+            enable_nested_tensor=False,
+        )
+        self.user_aug = nn.Sequential(nn.Linear(d * 2, d), nn.GELU(), nn.Linear(d, d))
+        self.item_aug = nn.Sequential(nn.Linear(d * 2, d), nn.GELU(), nn.Linear(d, d))
+        self.user_proj = nn.Sequential(nn.Linear(d * 4, d), nn.GELU(), nn.Dropout(cfg.dropout), nn.Linear(d, d))
+        item_input_dim = d * 4 if self.text_proj is not None else d * 3
+        self.item_proj = nn.Sequential(nn.Linear(item_input_dim, d), nn.GELU(), nn.Dropout(cfg.dropout), nn.Linear(d, d))
+
+    def item_features(
+        self,
+        item_ids: torch.Tensor,
+        mask_tokens: bool = False,
+        return_aux: bool = False,
+    ) -> torch.Tensor | tuple[torch.Tensor, dict[str, torch.Tensor]]:
+        token_ids = self.item_token_ids.to(item_ids.device)[item_ids]
+        if self.training and mask_tokens:
+            keep = torch.rand_like(token_ids.float()) > self.cfg.dropout
+            token_ids = token_ids * keep.long()
+        token_mask = token_ids.ne(PAD).unsqueeze(-1)
+        token_sum = (self.token(token_ids) * token_mask).sum(dim=1)
+        tok = token_sum / token_mask.sum(dim=1).clamp_min(1)
+        dom = self.domain(self.item_domain_ids.to(item_ids.device)[item_ids])
+        iid = self.item_id(item_ids)
+        pav = self.item_aug(torch.cat([iid, tok], dim=-1))
+        parts = [iid, tok + pav, dom]
+        if self.text_proj is not None and self.item_text_embeddings is not None:
+            text = self.item_text_embeddings.to(item_ids.device)[item_ids].float()
+            parts.append(self.text_proj(text))
+        out = F.normalize(self.item_proj(torch.cat(parts, dim=-1)), dim=-1)
+        if return_aux:
+            return out, {"pav": F.normalize(pav, dim=-1)}
+        return out
+
+    def user_features(
+        self,
+        history: torch.Tensor,
+        mask: torch.Tensor,
+        user: torch.Tensor | None,
+        activity: torch.Tensor,
+        augment: bool = False,
+        anonymous: bool = False,
+        return_aux: bool = False,
+    ):
+        hist = history
+        hist_mask = mask
+        if not hist_mask.any(dim=1).all():
+            raise ValueError("Every user history must contain at least one non-padding item.")
+        if self.training and augment:
+            keep = (torch.rand_like(hist.float()) > self.cfg.dropout) & hist_mask
+            emptied = ~keep.any(dim=1)
+            if emptied.any():
+                positions = torch.arange(hist.size(1), device=hist.device).unsqueeze(0)
+                recent_original = positions.masked_fill(~hist_mask, -1).max(dim=1).values
+                empty_rows = torch.nonzero(emptied, as_tuple=False).squeeze(1)
+                keep[empty_rows, recent_original[empty_rows]] = True
+            hist = hist * keep.long()
+            hist_mask = keep
+        x = self.item_id(hist)
+        positions = torch.arange(hist.size(1), device=hist.device).unsqueeze(0)
+        x = x + self.pos(positions)
+        causal_mask = None
+        if self.cfg.use_causal_attention:
+            causal_mask = torch.triu(
+                torch.ones(hist.size(1), hist.size(1), dtype=torch.bool, device=hist.device),
+                diagonal=1,
+            )
+        encoded = self.sequence_encoder(x, mask=causal_mask, src_key_padding_mask=~hist_mask)
+        denom = hist_mask.sum(dim=1).clamp_min(1).unsqueeze(-1)
+        pooled = (encoded * hist_mask.unsqueeze(-1)).sum(dim=1) / denom
+        sequence_positions = torch.arange(hist.size(1), device=hist.device).unsqueeze(0)
+        recent_idx = sequence_positions.masked_fill(~hist_mask, -1).max(dim=1).values.clamp_min(0)
+        recent = encoded[torch.arange(hist.size(0), device=hist.device), recent_idx]
+        if anonymous or user is None:
+            uattr = torch.zeros_like(pooled)
+            activity_vec = torch.zeros_like(pooled)
+        else:
+            activity_vec = self.activity(activity)
+            uattr = self.user_id(user) + activity_vec
+        pav = self.user_aug(torch.cat([uattr, pooled], dim=-1))
+        out = self.user_proj(torch.cat([uattr + pav, pooled, recent, activity_vec], dim=-1))
+        result = F.normalize(out, dim=-1), F.normalize(pooled, dim=-1), F.normalize(uattr, dim=-1)
+        if return_aux:
+            return (*result, {"pav": F.normalize(pav, dim=-1)})
+        return result
+
+    def forward(self, batch):
+        user_vec, seq_vec, attr_vec, user_aux = self.user_features(
+            batch["history"],
+            batch["mask"],
+            batch["user"],
+            batch["activity"],
+            augment=False,
+            return_aux=True,
+        )
+        item_vec, item_aux = self.item_features(batch["target"], mask_tokens=False, return_aux=True)
+        return user_vec, item_vec, seq_vec, attr_vec, user_aux, item_aux
+
+
+def info_nce(a: torch.Tensor, b: torch.Tensor, temperature: torch.Tensor | float) -> torch.Tensor:
+    logits = a @ b.T / temperature
+    labels = torch.arange(a.size(0), device=a.device)
+    return F.cross_entropy(logits, labels)
+
+
+def build_training_scheduler(optimizer, loader: DataLoader, cfg: RecConfig):
+    """Create a OneCycleLR scheduler spanning all epochs.
+
+    Linear warmup for the first 5% of steps, then cosine decay to 0.
+    """
+    return torch.optim.lr_scheduler.OneCycleLR(
+        optimizer,
+        max_lr=cfg.lr,
+        total_steps=len(loader) * cfg.epochs,
+        pct_start=0.05,
+        anneal_strategy="cos",
+    )
+
+
+def train_one_epoch(
+    model: CLEPIDTN,
+    loader: DataLoader,
+    optimizer,
+    cfg: RecConfig,
+    desc: str | None = None,
+    scheduler=None,
+) -> float:
+    model.train()
+    total, steps = 0.0, 0
+    progress = tqdm(loader, desc=desc or "train", leave=False)
+    for batch in progress:
+        batch = {k: v.to(cfg.device) for k, v in batch.items()}
+
+        # View 1 (clean): main InfoNCE loss + auxiliary vectors
+        user_vec, item_vec, _, _, user_aux, item_aux = model(batch)
+        main_loss = info_nce(user_vec, item_vec, cfg.temperature)
+
+        # View 2 (augmented): contrastive SSL pairs
+        _, seq_a, attr_a = model.user_features(
+            batch["history"], batch["mask"], batch["user"], batch["activity"],
+            augment=True,
+        )
+        _, seq_b, attr_b = model.user_features(
+            batch["history"], batch["mask"], batch["user"], batch["activity"],
+            augment=True,
+        )
+        item_a = model.item_features(batch["target"], mask_tokens=True)
+        item_b = model.item_features(batch["target"], mask_tokens=True)
+
+        ssl = (
+            info_nce(seq_a, seq_b, cfg.temperature)
+            + info_nce(attr_a, attr_b, cfg.temperature)
+            + info_nce(item_a, item_b, cfg.temperature)
+        ) / 3
+
+        # AMM loss: cosine similarity instead of MSE to avoid collapse
+        amm_loss = (
+            1.0 - F.cosine_similarity(user_aux["pav"], item_vec.detach(), dim=-1).mean()
+            + 1.0 - F.cosine_similarity(item_aux["pav"], user_vec.detach(), dim=-1).mean()
+        )
+
+        loss = main_loss + cfg.contrastive_weight * ssl + cfg.amm_weight * amm_loss
+        optimizer.zero_grad(set_to_none=True)
+        loss.backward()
+        if cfg.gradient_clip_norm > 0:
+            torch.nn.utils.clip_grad_norm_(model.parameters(), cfg.gradient_clip_norm)
+        optimizer.step()
+        if scheduler is not None:
+            scheduler.step()
+        total += loss.item()
+        steps += 1
+        progress.set_postfix(loss=f"{total / steps:.4f}")
+    return total / max(steps, 1)
+
+
+@torch.no_grad()
+def build_item_index(model: CLEPIDTN, batch_size: int = 4096) -> torch.Tensor:
+    """Build a full item index tensor of shape ``(n_items, d)``.
+
+    Position 0 (PAD) is a zero vector.  Every other position stores the
+    normalized item-tower output so that ``item_index[item_id]`` gives the
+    correct vector without any offset arithmetic.
+    """
+    model.eval()
+    n_items = model.item_id.num_embeddings
+    device = next(model.parameters()).device
+    vecs = []
+    starts = range(1, n_items, batch_size)
+    for start in tqdm(starts, desc="index items", leave=False):
+        ids = torch.arange(start, min(start + batch_size, n_items), device=device)
+        vecs.append(model.item_features(ids).cpu())
+    item_vecs = torch.cat(vecs, dim=0)
+    # Prepend a zero vector for PAD (index 0) so item_index[item_id] works directly.
+    pad_vec = torch.zeros(1, item_vecs.size(1), dtype=item_vecs.dtype)
+    return torch.cat([pad_vec, item_vecs], dim=0)
+
+
+def item_index_ids(model: CLEPIDTN) -> torch.Tensor:
+    return torch.arange(1, model.item_id.num_embeddings)
+
+
+def candidate_item_ids_from_metadata(
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+    domain: str | None = None,
+    min_reviews: int | None = None,
+) -> torch.Tensor:
+    candidates = item_meta.copy()
+    if domain is not None:
+        candidates = candidates.loc[candidates["domain"].eq(domain)]
+    if min_reviews is not None and "user_reviews" in candidates.columns:
+        candidates = candidates.loc[candidates["user_reviews"].fillna(0) >= min_reviews]
+    ids = [item_to_idx[k] for k in candidates["item_key"] if k in item_to_idx]
+    if not ids:
+        raise ValueError("No candidates matched the requested metadata filters.")
+    return torch.tensor(sorted(set(ids)), dtype=torch.long)
+
+
+def recommend_cross_domain_content(
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+    history_ids: list[int],
+    target_domain: str,
+    k: int = 10,
+    text_index: torch.Tensor | None = None,
+    min_reviews: int | None = 500,
+    exclude_addons: bool = True,
+    semantic_weight: float = 0.35,
+    token_weight: float = 0.30,
+    title_weight: float = 0.25,
+    popularity_weight: float = 0.10,
+    history_weights: list[float] | None = None,
+) -> list[tuple[int, float]]:
+    """Content-first cross-domain retrieval for cold-start recommendations.
+
+    This is intentionally separate from the trained interaction model. Public
+    MovieLens users and public Steam users are not the same people, so
+    cross-domain recommendations are more reliable when ranked by shared
+    language, tags, descriptions, franchise/entity overlap, and catalog quality.
+    """
+    idx_to_key = {idx: key for key, idx in item_to_idx.items()}
+    meta = item_meta.loc[item_meta["item_key"].isin(item_to_idx)].copy()
+    meta["idx"] = meta["item_key"].map(item_to_idx)
+
+    source_ids, source_weights = _normalize_history_weights(history_ids, history_weights)
+    positive_ids = [idx for idx, weight in zip(source_ids, source_weights) if weight > 0]
+    negative_ids = [idx for idx, weight in zip(source_ids, source_weights) if weight < 0]
+
+    source = meta.loc[meta["idx"].isin(positive_ids)]
+    if source.empty:
+        raise ValueError("No positive source items found. Ratings of 4-5 are needed to build a profile.")
+    negative_source = meta.loc[meta["idx"].isin(negative_ids)]
+
+    candidates = meta.loc[meta["domain"].eq(target_domain)].copy()
+    if min_reviews is not None and "user_reviews" in candidates.columns:
+        candidates = candidates.loc[candidates["user_reviews"].fillna(0) >= min_reviews]
+    if exclude_addons:
+        addon_pattern = r"\b(?:dlc|demo|pack|skin|skins|season pass|expansion|challenge pack|batmobile|soundtrack)\b"
+        candidates = candidates.loc[~candidates["title"].fillna("").str.contains(addon_pattern, case=False, regex=True)]
+    if candidates.empty:
+        raise ValueError("No target-domain candidates remain after filtering.")
+
+    source_tokens = _weighted_metadata_token_scores(source, source_ids, source_weights, positive_only=True)
+    negative_tokens = _weighted_metadata_token_scores(negative_source, source_ids, source_weights, positive_only=False)
+    source_title_tokens = _important_title_tokens(source["title"].fillna("").tolist())
+    if not source_tokens:
+        raise ValueError("Source items have no usable metadata tokens.")
+
+    rows = []
+    candidate_indices = torch.tensor(candidates["idx"].to_numpy(), dtype=torch.long)
+
+    semantic_scores = torch.zeros(len(candidates), dtype=torch.float32)
+    if text_index is not None:
+        hist_indices = torch.tensor(source_ids, dtype=torch.long)
+        hist_weights = torch.tensor(source_weights, dtype=torch.float32).unsqueeze(1)
+        hist_vec = text_index[hist_indices] * hist_weights
+        hist_vec = F.normalize(hist_vec.sum(dim=0, keepdim=True), dim=-1)
+        cand_vec = F.normalize(text_index[candidate_indices], dim=-1)
+        semantic_scores = (hist_vec @ cand_vec.T).squeeze(0).cpu()
+
+    max_reviews = float(np.log1p(candidates["user_reviews"].fillna(0).astype(float)).max() or 1.0)
+    candidate_rows = candidates.itertuples(index=False)
+    for pos, row in enumerate(
+        tqdm(candidate_rows, total=len(candidates), desc="rank cross-domain candidates", leave=False)
+    ):
+        candidate_tokens = set(str(row.tokens).split())
+        token_score = sum(source_tokens.get(t, 0.0) for t in candidate_tokens)
+        token_score -= sum(abs(negative_tokens.get(t, 0.0)) for t in candidate_tokens)
+        token_score = token_score / max(sum(abs(v) for v in source_tokens.values()) ** 0.5, 1.0)
+
+        title_tokens = set(_title_tokens(row.title).split())
+        title_score = min(len(source_title_tokens & title_tokens), 3) / 3.0
+        if source_title_tokens and source_title_tokens.issubset(title_tokens):
+            title_score = 1.0
+
+        reviews = getattr(row, "user_reviews", 0) or 0
+        popularity_score = float(np.log1p(reviews)) / max_reviews
+        score = (
+            semantic_weight * float(semantic_scores[pos])
+            + token_weight * float(token_score)
+            + title_weight * float(title_score)
+            + popularity_weight * popularity_score
+        )
+        rows.append((int(row.idx), float(score)))
+
+    rows.sort(key=lambda x: x[1], reverse=True)
+    return rows[:k]
+
+
+
+def _normalize_history_weights(
+    history_ids: list[int],
+    history_weights: list[float] | None = None,
+    star_rating_scale: bool = False,
+) -> tuple[list[int], list[float]]:
+    """Pair item IDs with normalized weights in [-1, 1].
+
+    Parameters
+    ----------
+    star_rating_scale : bool
+        When *True*, weights are treated as 1-5 star ratings and linearly
+        mapped to [-1, 1] via ``(w - 3) / 2``.  When *False* (default),
+        weights are assumed to already be in [-1, 1] and are only clamped.
+    """
+    ids = [int(i) for i in history_ids if i > 0]
+    if history_weights is None:
+        return ids, [1.0] * len(ids)
+    if len(history_weights) != len(history_ids):
+        raise ValueError("history_weights must have the same length as history_ids.")
+    out_ids, out_weights = [], []
+    for item_id, raw_weight in zip(history_ids, history_weights):
+        if item_id <= 0:
+            continue
+        weight = float(raw_weight)
+        if star_rating_scale:
+            weight = (weight - 3.0) / 2.0
+        out_ids.append(int(item_id))
+        out_weights.append(max(-1.0, min(weight, 1.0)))
+    return out_ids, out_weights
+
+
+def _weighted_metadata_token_scores(
+    rows: pd.DataFrame,
+    history_ids: list[int],
+    history_weights: list[float],
+    positive_only: bool,
+) -> dict[str, float]:
+    weight_by_idx = dict(zip(history_ids, history_weights))
+    scores: dict[str, float] = {}
+    for row in rows.itertuples(index=False):
+        weight = float(weight_by_idx.get(int(row.idx), 0.0))
+        if positive_only and weight <= 0:
+            continue
+        if not positive_only and weight >= 0:
+            continue
+        for token in str(row.tokens).split():
+            if len(token) <= 2 or token in _METADATA_STOP_WORDS or token.startswith("posratio_"):
+                continue
+            scores[token] = scores.get(token, 0.0) + weight
+    return scores
+
+
+def _important_title_tokens(titles: list[str]) -> set[str]:
+    stop = {"the", "and", "part", "movie", "film", "edition", "year"}
+    tokens = set()
+    for title in titles:
+        tokens.update(t for t in _title_tokens(title).split() if len(t) > 2 and t not in stop)
+    return tokens
+
+
+def add_tmdb_movie_descriptions(
+    cfg: RecConfig,
+    item_meta: pd.DataFrame,
+    cache_path: str | Path = "artifacts/tmdb_movie_descriptions.csv",
+    bearer_token: str | None = None,
+    limit: int | None = None,
+    sleep_seconds: float = 0.025,
+) -> pd.DataFrame:
+    import requests
+
+    bearer_token = bearer_token or os.getenv("TMDB_BEARER_TOKEN")
+    if not bearer_token:
+        raise RuntimeError("Set TMDB_BEARER_TOKEN or pass bearer_token=... before fetching TMDB descriptions.")
+
+    cache_path = Path(cache_path)
+    cache_path.parent.mkdir(parents=True, exist_ok=True)
+    if cache_path.exists():
+        cached = pd.read_csv(cache_path)
+    else:
+        cached = pd.DataFrame(columns=["item_key", "tmdbId", "description"])
+
+    cached_keys = set(cached["item_key"].astype(str))
+    links = _read_csv_from_zip(cfg.movielens_zip, "ml-32m/links.csv", usecols=["movieId", "tmdbId"])
+    links = links.dropna(subset=["tmdbId"]).copy()
+    links["tmdbId"] = links["tmdbId"].astype(int)
+    links["item_key"] = "movie:" + links["movieId"].astype(str)
+    links = links.loc[links["item_key"].isin(set(item_meta["item_key"]))]
+    links = links.loc[~links["item_key"].isin(cached_keys)]
+    if limit is not None:
+        links = links.head(limit)
+
+    rows = []
+    headers = {"Authorization": f"Bearer {bearer_token}"}
+    for row in tqdm(links.itertuples(index=False), total=len(links), desc="fetch tmdb descriptions"):
+        try:
+            r = requests.get(
+                f"https://api.themoviedb.org/3/movie/{row.tmdbId}",
+                headers=headers,
+                timeout=20,
+            )
+            if r.status_code == 404:
+                continue
+            r.raise_for_status()
+            data = r.json()
+            rows.append(
+                {
+                    "item_key": row.item_key,
+                    "tmdbId": row.tmdbId,
+                    "description": data.get("overview") or "",
+                }
+            )
+            if sleep_seconds:
+                time.sleep(sleep_seconds)
+        except requests.RequestException:
+            continue
+
+    if rows:
+        cached = pd.concat([cached, pd.DataFrame(rows)], ignore_index=True)
+        cached = cached.drop_duplicates("item_key", keep="last")
+        cached.to_csv(cache_path, index=False)
+
+    enriched = item_meta.copy()
+    enriched = enriched.merge(cached[["item_key", "description"]], on="item_key", how="left", suffixes=("", "_tmdb"))
+    if "description_tmdb" in enriched.columns:
+        enriched["description"] = enriched["description_tmdb"].fillna(enriched.get("description", ""))
+        enriched = enriched.drop(columns=["description_tmdb"])
+    enriched["description"] = enriched["description"].fillna("")
+    enriched["tokens"] = (
+        enriched["tokens"].fillna("")
+        + " "
+        + enriched["description"].map(lambda x: _text_tokens(x, limit=80))
+    )
+    return enriched
+
+
+def build_text_embedding_index(
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+    model_name: str = "sentence-transformers/all-MiniLM-L6-v2",
+    batch_size: int = 128,
+    device: str | None = None,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    try:
+        from sentence_transformers import SentenceTransformer
+    except ImportError as exc:
+        raise ImportError("Install sentence-transformers first: %pip install -q sentence-transformers") from exc
+
+    n_items = max(item_to_idx.values()) + 1
+    rows = []
+    for row in tqdm(
+        item_meta.itertuples(index=False),
+        total=len(item_meta),
+        desc="prepare text index",
+        leave=False,
+    ):
+        item_id = item_to_idx.get(row.item_key)
+        if item_id is None:
+            continue
+        description = getattr(row, "description", "") or ""
+        text = f"{row.title}. {description} {getattr(row, 'tokens', '')}"
+        rows.append((item_id, text))
+
+    rows.sort(key=lambda x: x[0])
+    ids = torch.tensor([r[0] for r in rows], dtype=torch.long)
+    texts = [r[1] for r in rows]
+    encoder = SentenceTransformer(model_name, device=device)
+    emb = encoder.encode(
+        texts,
+        batch_size=batch_size,
+        show_progress_bar=True,
+        convert_to_tensor=True,
+        normalize_embeddings=True,
+    ).cpu()
+
+    index = torch.zeros((n_items, emb.size(1)), dtype=torch.float32)
+    index[ids] = emb
+    return index, ids
+
+
+@torch.no_grad()
+def recommend_from_history(
+    model: CLEPIDTN,
+    item_index: torch.Tensor,
+    history_ids: list[int],
+    user_id: int | None,
+    activity: int,
+    cfg: RecConfig,
+    k: int = 10,
+    domain: str | None = None,
+    anonymous_item_weight: float = 0.65,
+    content_boost: float = 0.20,
+    candidate_item_ids: torch.Tensor | None = None,
+    text_index: torch.Tensor | None = None,
+    text_weight: float = 0.25,
+    title_boost: float = 0.25,
+    history_weights: list[float] | None = None,
+):
+    model.eval()
+    if candidate_item_ids is None:
+        candidate_item_ids = item_index_ids(model)
+    else:
+        candidate_item_ids = candidate_item_ids.cpu().long()
+    weighted_ids, weighted_values = _normalize_history_weights(history_ids, history_weights)
+    positive_weighted_ids = [idx for idx, weight in zip(weighted_ids, weighted_values) if weight > 0]
+    hist = positive_weighted_ids[-cfg.max_seq_len :]
+    if not hist:
+        # Fall back to all items when no positives exist (e.g. all neutral/negative).
+        hist = weighted_ids[-cfg.max_seq_len :]
+    if not hist:
+        return []
+    padded = [PAD] * (cfg.max_seq_len - len(hist)) + hist
+    mask = [0] * (cfg.max_seq_len - len(hist)) + [1] * len(hist)
+    user_tensor = None if user_id is None else torch.tensor([user_id], device=cfg.device)
+    batch = {
+        "history": torch.tensor([padded], device=cfg.device),
+        "mask": torch.tensor([mask], dtype=torch.bool, device=cfg.device),
+        "user": user_tensor,
+        "activity": torch.tensor([min(activity, 8)], device=cfg.device),
+    }
+    user_vec, _, _ = model.user_features(
+        batch["history"],
+        batch["mask"],
+        batch["user"],
+        batch["activity"],
+        anonymous=user_id is None,
+    )
+    if user_id is None and weighted_ids:
+        hist_ids = torch.tensor(weighted_ids, device=cfg.device)
+        hist_weights = torch.tensor(weighted_values, device=cfg.device, dtype=torch.float32).unsqueeze(1)
+        hist_vec = model.item_features(hist_ids) * hist_weights
+        hist_vec = hist_vec.sum(dim=0, keepdim=True)
+        hist_vec = F.normalize(hist_vec, dim=-1)
+        w = max(0.0, min(float(anonymous_item_weight), 1.0))
+        user_vec = F.normalize((1.0 - w) * user_vec + w * hist_vec, dim=-1)
+    # item_index now has shape (n_items, d) with PAD at index 0 — no offset needed.
+    scores = (user_vec.cpu() @ item_index[candidate_item_ids].T).squeeze(0)
+    if user_id is None and weighted_ids and content_boost > 0:
+        item_tokens = model.item_token_ids[candidate_item_ids].cpu()
+        pos_tokens = model.item_token_ids[[i for i, weight in zip(weighted_ids, weighted_values) if weight > 0]].cpu().flatten()
+        neg_tokens = model.item_token_ids[[i for i, weight in zip(weighted_ids, weighted_values) if weight < 0]].cpu().flatten()
+        pos_tokens = pos_tokens[(pos_tokens != PAD) & (pos_tokens != 1)].unique()
+        neg_tokens = neg_tokens[(neg_tokens != PAD) & (neg_tokens != 1)].unique()
+        if len(pos_tokens) > 0:
+            overlap = torch.isin(item_tokens, pos_tokens).float().sum(dim=1)
+            if len(neg_tokens) > 0:
+                # Only penalize tokens that are exclusive to disliked items,
+                # so shared tokens like "action" don't suppress liked genres.
+                neg_only_tokens = neg_tokens[~torch.isin(neg_tokens, pos_tokens)]
+                if len(neg_only_tokens) > 0:
+                    overlap = overlap - torch.isin(item_tokens, neg_only_tokens).float().sum(dim=1)
+            lengths = (item_tokens > 1).float().sum(dim=1).clamp_min(1.0)
+            overlap = overlap / lengths.sqrt()
+            scores = scores + float(content_boost) * overlap
+    if text_index is None and getattr(model, "item_text_embeddings", None) is not None:
+        text_index = model.item_text_embeddings.cpu()
+    if text_index is not None and weighted_ids and text_weight > 0:
+        hist_ids = torch.tensor(weighted_ids, dtype=torch.long)
+        hist_weights = torch.tensor(weighted_values, dtype=torch.float32).unsqueeze(1)
+        hist_text = (text_index[hist_ids] * hist_weights).sum(dim=0, keepdim=True)
+        hist_text = F.normalize(hist_text, dim=-1)
+        candidate_text = F.normalize(text_index[candidate_item_ids], dim=-1)
+        text_scores = (hist_text @ candidate_text.T).squeeze(0)
+        scores = scores + float(text_weight) * text_scores
+    if user_id is None and positive_weighted_ids and title_boost > 0:
+        hist_tokens = model.item_token_ids[positive_weighted_ids].cpu().flatten()
+        item_tokens = model.item_token_ids[candidate_item_ids].cpu()
+        hist_tokens = hist_tokens[(hist_tokens != PAD) & (hist_tokens != 1)].unique()
+        if len(hist_tokens) > 0:
+            # Title tokens are appended *last* in the token string, so use
+            # the tail of the token tensor (the head contains genre/tag tokens).
+            titleish = torch.isin(item_tokens[:, -12:], hist_tokens).float().sum(dim=1).clamp(max=3.0) / 3.0
+            scores = scores + float(title_boost) * titleish
+    if weighted_ids:
+        blocked_items = torch.tensor(weighted_ids, dtype=torch.long)
+        blocked = torch.isin(candidate_item_ids, blocked_items)
+        scores[blocked] = -1e9
+    if domain is not None:
+        domain_to_idx = {"movie": 0, "game": 1}
+        if domain not in domain_to_idx:
+            raise ValueError(f"domain must be one of {sorted(domain_to_idx)}, got {domain!r}")
+        item_domains = model.item_domain_ids[candidate_item_ids].cpu()
+        domain_mask = item_domains == domain_to_idx[domain]
+        if not domain_mask.any():
+            raise ValueError(f"No {domain!r} candidates are available in this item index.")
+        scores[~domain_mask] = -1e9
+    valid_count = int((scores > -1e8).sum().item())
+    if valid_count == 0:
+        raise ValueError("No valid recommendation candidates remain after filtering.")
+    k = min(k, valid_count)
+    values, offsets = torch.topk(scores, k)
+    item_ids = candidate_item_ids[offsets].tolist()
+    return list(zip(item_ids, values.tolist()))
+
+
+@torch.no_grad()
+def evaluate_retrieval(
+    model: CLEPIDTN,
+    item_index: torch.Tensor,
+    eval_rows: Sequence[tuple[int, list[int], int]],
+    cfg: RecConfig,
+    ks: Sequence[int] = (10, 50),
+    candidate_item_ids: torch.Tensor | None = None,
+    max_users: int | None = None,
+    eval_batch_size: int = 256,
+) -> dict[str, float]:
+    """Batched evaluation — encodes users in GPU batches and scores with one matmul."""
+    model.eval()
+    max_k = max(ks)
+    rows = eval_rows if max_users is None else eval_rows[:max_users]
+
+    # Filter valid rows
+    valid = [(u, h, t) for u, h, t in rows if h and t > 0]
+    if not valid:
+        return {"users": 0.0, "MRR": 0.0, **{f"HR@{k}": 0.0 for k in ks},
+                **{f"Recall@{k}": 0.0 for k in ks}, **{f"NDCG@{k}": 0.0 for k in ks}}
+
+    # Build candidate index on CPU
+    if candidate_item_ids is None:
+        candidate_item_ids = torch.arange(1, item_index.size(0))
+    cand_vecs = item_index[candidate_item_ids]  # (n_cand, d)
+
+    # Map targets to candidate offsets for fast lookup
+    cand_id_to_offset = {int(cid): off for off, cid in enumerate(candidate_item_ids.tolist())}
+
+    hits = {k: 0.0 for k in ks}
+    ndcg = {k: 0.0 for k in ks}
+    reciprocal_rank = 0.0
+    total = 0
+
+    for batch_start in range(0, len(valid), eval_batch_size):
+        batch_rows = valid[batch_start : batch_start + eval_batch_size]
+        B = len(batch_rows)
+
+        # Pad histories and build masks
+        padded_batch = []
+        mask_batch = []
+        user_batch = []
+        activity_batch = []
+        target_offsets = []  # offset in candidate_item_ids, or -1
+
+        for user_id, history, target in batch_rows:
+            h = history[-cfg.max_seq_len:]
+            pad_len = cfg.max_seq_len - len(h)
+            padded_batch.append([PAD] * pad_len + h)
+            mask_batch.append([0] * pad_len + [1] * len(h))
+            user_batch.append(user_id)
+            activity_batch.append(min(len(history), 8))
+            target_offsets.append(cand_id_to_offset.get(target, -1))
+
+        # Encode users on GPU
+        hist_t = torch.tensor(padded_batch, dtype=torch.long, device=cfg.device)
+        mask_t = torch.tensor(mask_batch, dtype=torch.bool, device=cfg.device)
+        user_t = torch.tensor(user_batch, dtype=torch.long, device=cfg.device)
+        act_t = torch.tensor(activity_batch, dtype=torch.long, device=cfg.device)
+
+        with torch.no_grad():
+            user_vecs, _, _ = model.user_features(hist_t, mask_t, user_t, act_t)
+            user_vecs = user_vecs.cpu()  # (B, d)
+
+        # Score all candidates at once: (B, d) @ (d, n_cand) -> (B, n_cand)
+        scores = user_vecs @ cand_vecs.T
+
+        # Get top-k per user
+        topk_vals, topk_idx = torch.topk(scores, min(max_k, scores.size(1)), dim=1)
+
+        for i in range(B):
+            target_off = target_offsets[i]
+            if target_off < 0:
+                continue  # target not in candidates
+            total += 1
+            ranked_offsets = topk_idx[i].tolist()
+            if target_off in ranked_offsets:
+                rank = ranked_offsets.index(target_off) + 1
+                reciprocal_rank += 1.0 / rank
+                for k in ks:
+                    if rank <= k:
+                        hits[k] += 1.0
+                        ndcg[k] += 1.0 / math.log2(rank + 1)
+
+    metrics = {"users": float(total), "MRR": reciprocal_rank / max(total, 1)}
+    for k in ks:
+        metrics[f"HR@{k}"] = hits[k] / max(total, 1)
+        metrics[f"Recall@{k}"] = hits[k] / max(total, 1)
+        metrics[f"NDCG@{k}"] = ndcg[k] / max(total, 1)
+    return metrics
+
+
+def build_popularity_rankings(
+    interactions: pd.DataFrame,
+    item_to_idx: dict[str, int],
+    domain_by_item_key: dict[str, str] | None = None,
+) -> dict[str | None, list[int]]:
+    counts = interactions["item_key"].value_counts()
+    rows = [(item_to_idx[key], int(count)) for key, count in counts.items() if key in item_to_idx]
+    rows.sort(key=lambda value: value[1], reverse=True)
+    rankings: dict[str | None, list[int]] = {None: [item_id for item_id, _ in rows]}
+    if domain_by_item_key is not None:
+        for domain in sorted(set(domain_by_item_key.values())):
+            rankings[domain] = [
+                item_to_idx[key]
+                for key in counts.index
+                if key in item_to_idx and domain_by_item_key.get(key) == domain
+            ]
+    return rankings
+
+
+def evaluate_popularity_baseline(
+    rankings: dict[str | None, list[int]] | list[int],
+    eval_rows: Sequence[tuple[int, list[int], int]],
+    ks: Sequence[int] = (10, 50),
+) -> dict[str, float]:
+    ranking = rankings[None] if isinstance(rankings, dict) else rankings
+    max_k = max(ks)
+    hits = {k: 0.0 for k in ks}
+    ndcg = {k: 0.0 for k in ks}
+    total = 0
+    for _, history, target in tqdm(
+        eval_rows,
+        total=len(eval_rows),
+        desc="evaluate popularity",
+        leave=False,
+    ):
+        seen = set(history)
+        candidates = [item_id for item_id in ranking if item_id not in seen][:max_k]
+        total += 1
+        if target in candidates:
+            rank = candidates.index(target) + 1
+            for k in ks:
+                if rank <= k:
+                    hits[k] += 1.0
+                    ndcg[k] += 1.0 / math.log2(rank + 1)
+    metrics = {"users": float(total)}
+    for k in ks:
+        metrics[f"Popularity_HR@{k}"] = hits[k] / max(total, 1)
+        metrics[f"Popularity_NDCG@{k}"] = ndcg[k] / max(total, 1)
+    return metrics
+
+
+def build_token_knn_index(
+    item_token_ids: torch.Tensor,
+    candidate_item_ids: torch.Tensor | None = None,
+) -> dict[int, set[int]]:
+    if candidate_item_ids is None:
+        candidate_item_ids = torch.arange(1, item_token_ids.size(0))
+    index = {}
+    candidate_ids = candidate_item_ids.tolist()
+    for item_id in tqdm(candidate_ids, total=len(candidate_ids), desc="build token KNN", leave=False):
+        tokens = item_token_ids[item_id]
+        index[int(item_id)] = set(tokens[(tokens != PAD) & (tokens != 1)].tolist())
+    return index
+
+
+def recommend_item_knn(
+    history_ids: list[int],
+    token_index: dict[int, set[int]],
+    k: int = 10,
+    history_weights: list[float] | None = None,
+) -> list[tuple[int, float]]:
+    source_ids, weights = _normalize_history_weights(history_ids, history_weights)
+    profile_scores: dict[int, float] = {}
+    for item_id, weight in zip(source_ids, weights):
+        if weight <= 0:
+            continue
+        for token in token_index.get(item_id, set()):
+            profile_scores[token] = profile_scores.get(token, 0.0) + weight
+    blocked = set(source_ids)
+    rows = []
+    denom = max(sum(abs(value) for value in profile_scores.values()) ** 0.5, 1.0)
+    for item_id, tokens in tqdm(
+        token_index.items(),
+        total=len(token_index),
+        desc="score token KNN",
+        leave=False,
+    ):
+        if item_id in blocked:
+            continue
+        score = sum(profile_scores.get(token, 0.0) for token in tokens) / denom
+        rows.append((item_id, float(score)))
+    rows.sort(key=lambda value: value[1], reverse=True)
+    return rows[:k]
+
+
+def evaluate_survey_leave_one_out(
+    profiles: Sequence[dict],
+    model: CLEPIDTN,
+    item_index: torch.Tensor,
+    cfg: RecConfig,
+    k: int = 10,
+) -> dict[str, float]:
+    hits, total = 0, 0
+    for profile in tqdm(profiles, total=len(profiles), desc="evaluate survey", leave=False):
+        positives = [
+            rating
+            for rating in profile["ratings"]
+            if rating.get("item_id") is not None and rating["weight"] > 0
+        ]
+        if len(positives) < 2:
+            continue
+        target = positives[-1]["item_id"]
+        history = [rating["item_id"] for rating in positives[:-1]]
+        weights = [rating["weight"] for rating in positives[:-1]]
+        try:
+            recs = recommend_from_history(
+                model,
+                item_index,
+                history,
+                user_id=None,
+                activity=len(history),
+                cfg=cfg,
+                k=k,
+                history_weights=weights,
+            )
+        except (ValueError, RuntimeError):
+            # Skip users whose history is too sparse or entirely negative
+            # after weight normalization.
+            continue
+        if not recs:
+            total += 1
+            continue
+        hits += int(target in [item_id for item_id, _ in recs])
+        total += 1
+    return {f"Survey_HR@{k}": hits / max(total, 1), "survey_users": float(total)}
+
+
+def anonymous_history_from_titles(query_titles: list[str], item_meta: pd.DataFrame, item_to_idx: dict[str, int]) -> list[int]:
+    out = []
+    titles = item_meta[["item_key", "title"]].copy()
+    titles["norm"] = titles["title"].fillna("").map(lambda x: re.sub(r"[^a-z0-9]+", " ", str(x).lower()).strip())
+    for q in query_titles:
+        qn = re.sub(r"[^a-z0-9]+", " ", q.lower()).strip()
+        hit = titles.loc[titles["norm"].str.contains(re.escape(qn), na=False)].head(1)
+        if not hit.empty:
+            out.append(item_to_idx[hit.iloc[0]["item_key"]])
+    return out
+
+
+def anonymous_history_from_ratings(
+    title_ratings: dict[str, float] | list[tuple[str, float]],
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+) -> tuple[list[int], list[float]]:
+    pairs = title_ratings.items() if isinstance(title_ratings, dict) else title_ratings
+    history_ids, ratings = [], []
+    for title, rating in pairs:
+        matched = anonymous_history_from_titles([title], item_meta, item_to_idx)
+        if matched:
+            history_ids.append(matched[0])
+            ratings.append(float(rating))
+    return history_ids, ratings
+
+
+def item_from_external_id(
+    source: str,
+    external_id: int,
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+) -> dict:
+    """Resolve a TMDB, RAWG, MovieLens, or Steam ID into the model catalog."""
+    source = source.strip().lower()
+    column_by_source = {
+        "tmdb": "tmdb_id",
+        "rawg": "rawg_id",
+        "movielens": "item_key",
+        "movie": "item_key",
+        "steam": "item_key",
+        "game": "item_key",
+    }
+    if source not in column_by_source:
+        raise ValueError(f"source must be one of {sorted(column_by_source)}, got {source!r}")
+
+    if source in {"movielens", "movie"}:
+        matches = item_meta.loc[item_meta["item_key"].eq(f"movie:{int(external_id)}")]
+    elif source in {"steam", "game"}:
+        matches = item_meta.loc[item_meta["item_key"].eq(f"game:{int(external_id)}")]
+    else:
+        column = column_by_source[source]
+        if column not in item_meta.columns:
+            raise ValueError(
+                f"{column!r} is unavailable. Build metadata with HF enrichment for RAWG "
+                "or MovieLens links for TMDB."
+            )
+        numeric_ids = pd.to_numeric(item_meta[column], errors="coerce")
+        matches = item_meta.loc[numeric_ids.eq(int(external_id))]
+
+    matches = matches.loc[matches["item_key"].isin(item_to_idx)].copy()
+    if matches.empty:
+        raise KeyError(f"No catalog item mapped from {source} id {external_id}.")
+    if len(matches) > 1:
+        popularity = pd.to_numeric(matches.get("user_reviews"), errors="coerce").fillna(0)
+        matches = matches.loc[[popularity.idxmax()]]
+    row = matches.iloc[0]
+    return {
+        "item_id": int(item_to_idx[row["item_key"]]),
+        "item_key": row["item_key"],
+        "title": row["title"],
+        "domain": row["domain"],
+        "source": source,
+        "external_id": int(external_id),
+    }
+
+
+def history_from_external_ratings(
+    external_ratings: Sequence[tuple[str, int, float]],
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+    ignore_missing: bool = False,
+) -> tuple[list[int], list[float], list[dict]]:
+    """Resolve `(source, external_id, rating)` triples for anonymous inference."""
+    history_ids, ratings, resolved = [], [], []
+    for source, external_id, rating in external_ratings:
+        try:
+            item = item_from_external_id(source, external_id, item_meta, item_to_idx)
+        except KeyError:
+            if ignore_missing:
+                continue
+            raise
+        history_ids.append(item["item_id"])
+        ratings.append(float(rating))
+        resolved.append(item)
+    if not history_ids:
+        raise ValueError("None of the supplied external IDs mapped to the model catalog.")
+    return history_ids, ratings, resolved
+
+
+def recommend_from_external_ratings(
+    model: CLEPIDTN,
+    item_index: torch.Tensor,
+    external_ratings: Sequence[tuple[str, int, float]],
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+    cfg: RecConfig,
+    k: int = 10,
+    domain: str | None = None,
+    text_index: torch.Tensor | None = None,
+    ignore_missing: bool = False,
+    **recommend_kwargs,
+) -> tuple[list[tuple[int, float]], list[dict]]:
+    history_ids, ratings, resolved = history_from_external_ratings(
+        external_ratings,
+        item_meta,
+        item_to_idx,
+        ignore_missing=ignore_missing,
+    )
+    # External ratings are 1-5 star ratings; convert to [-1, 1] weights
+    # before passing to recommend_from_history.
+    _, normalized_weights = _normalize_history_weights(
+        history_ids, ratings, star_rating_scale=True,
+    )
+    recommendations = recommend_from_history(
+        model,
+        item_index,
+        history_ids,
+        user_id=None,
+        activity=len(history_ids),
+        cfg=cfg,
+        k=k,
+        domain=domain,
+        text_index=text_index,
+        history_weights=normalized_weights,
+        **recommend_kwargs,
+    )
+    return recommendations, resolved
+
+
+def maybe_enrich_with_rawg(app_id: int) -> dict:
+    import requests
+
+    key = os.getenv("RAWG_API_KEY")
+    if not key:
+        raise RuntimeError("Set RAWG_API_KEY before calling RAWG enrichment.")
+    r = requests.get(f"https://api.rawg.io/api/games/{app_id}", params={"key": key}, timeout=20)
+    r.raise_for_status()
+    return r.json()
+
+
+def maybe_enrich_with_tmdb(tmdb_id: int) -> dict:
+    import requests
+
+    token = os.getenv("TMDB_BEARER_TOKEN")
+    if not token:
+        raise RuntimeError("Set TMDB_BEARER_TOKEN before calling TMDB enrichment.")
+    r = requests.get(
+        f"https://api.themoviedb.org/3/movie/{tmdb_id}",
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=20,
+    )
+    r.raise_for_status()
+    return r.json()

recommender_api_improved8.py

@@ -0,0 +1,1330 @@
+"""
+recommender_api_improved8.py
+============================
+FastAPI server for the CL-EPIDTN recommender (improved_8).
+No QuestroDb dependency — all user signals arrive in the request body.
+
+Features
+--------
+- Accepts users_ratings.csv-style profiles (survey labels) AND numeric stars.
+- Wishlist / ignore-list items mapped to "Didn't watch but would watch" /
+  "Didn't watch and wouldn't watch" signals automatically.
+- Parental-control genre/tag blocking (always case-insensitive).
+- Pagination via `offset` parameter so the backend can fetch more pages.
+- RAG reranking endpoint: score a pre-fetched candidate list with the model.
+- API-safe IDs: accepts `movie_123`, `movie:123`, and returns string IDs.
+- Runtime catalog hot-add for cold-start items.
+
+Start with:
+    uvicorn recommender_api_improved8:app --host 0.0.0.0 --port 7749 --reload
+
+Artifacts directory: ./artifacts_improved8/
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import pickle
+import re
+import threading
+from contextlib import asynccontextmanager
+from typing import Literal
+
+import pandas as pd
+import torch
+import torch.nn as nn
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field, field_validator
+
+from cl_epidtn_recommender_improved_8 import (
+    CLEPIDTN,
+    PAD,
+    RecConfig,
+    SURVEY_RATING_VALUES,
+    recommend_from_history,
+    survey_rating_weight,
+)
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+ARTIFACTS_DIR = os.getenv("ARTIFACTS_DIR", "artifacts_improved8")
+
+CONFIG = {
+    "model_checkpoint": os.getenv(
+        "MODEL_CHECKPOINT",
+        os.path.join(ARTIFACTS_DIR, "improved_8epochs.pt"),
+    ),
+    "item_meta_path": os.getenv(
+        "ITEM_META_PATH",
+        os.path.join(ARTIFACTS_DIR, "item_meta.pkl"),
+    ),
+    "item_index_path": os.getenv(
+        "ITEM_INDEX_PATH",
+        os.path.join(ARTIFACTS_DIR, "item_index.pt"),
+    ),
+    "item_to_idx_path": os.getenv(
+        "ITEM_TO_IDX_PATH",
+        os.path.join(ARTIFACTS_DIR, "item_to_idx.pkl"),
+    ),
+    "title_lookup_path": os.getenv(
+        "TITLE_LOOKUP_PATH",
+        os.path.join(ARTIFACTS_DIR, "title_lookup.pkl"),
+    ),
+    "text_embeddings_path": os.getenv(
+        "TEXT_EMBEDDINGS_PATH",
+        os.path.join(ARTIFACTS_DIR, "improved_item_text_embeddings.pt"),
+    ),
+    "model_version": "improved_8",
+    "max_recs": int(os.getenv("MAX_RECS", "100")),
+    "text_encoder_model": os.getenv(
+        "TEXT_ENCODER_MODEL",
+        "sentence-transformers/all-MiniLM-L6-v2",
+    ),
+    # Over-fetch multiplier: fetch this many more candidates before filtering
+    # so that blocked-genre filtering still returns the requested `k` items.
+    "overfetch_multiplier": int(os.getenv("OVERFETCH_MULTIPLIER", "5")),
+    # Title-family calibration helps single-seed profiles prefer obvious
+    # franchise neighbors before broad genre matches like "open world action".
+    "title_family_boost": float(os.getenv("TITLE_FAMILY_BOOST", "0.40")),
+    "title_family_extra_candidates": int(os.getenv("TITLE_FAMILY_EXTRA_CANDIDATES", "50")),
+}
+
+
+# ---------------------------------------------------------------------------
+# Rating label mappings — matches users_ratings.csv exactly
+# ---------------------------------------------------------------------------
+
+# Survey text labels → numeric weight in [-1, 1]
+_LABEL_WEIGHTS: dict[str, float] = {
+    label: survey_rating_weight(label) for label in SURVEY_RATING_VALUES
+}
+
+# Star ratings (1–5) → weight in [-1, 1]
+def _stars_to_weight(stars: float) -> float:
+    return max(-1.0, min((stars - 3.0) / 2.0, 1.0))
+
+
+# ---------------------------------------------------------------------------
+# Genre / tag lookup builder
+# ---------------------------------------------------------------------------
+
+def _build_item_genre_lookup(
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+) -> dict[int, set[str]]:
+    """Build item_id → set of lowercase genre/tag strings.
+
+    Sources (all lowercased):
+    - `hf_genres` column (pipe- or comma-separated)
+    - `hf_tags` column (pipe- or comma-separated)
+    - first 20 tokens from the `tokens` column (genre-like keywords)
+    """
+    lookup: dict[int, set[str]] = {}
+    for row in item_meta.itertuples(index=False):
+        idx = item_to_idx.get(row.item_key)
+        if idx is None:
+            continue
+        genres: set[str] = set()
+        for col_name in ("hf_genres", "hf_tags"):
+            value = getattr(row, col_name, None)
+            if value and not (isinstance(value, float) and math.isnan(value)):
+                for part in re.split(r"[|,]", str(value)):
+                    part = part.strip().lower()
+                    if part:
+                        genres.add(part)
+        # Also extract the first tokens which are usually genre keywords
+        tokens_value = getattr(row, "tokens", "")
+        if tokens_value and isinstance(tokens_value, str):
+            for tok in tokens_value.split()[:20]:
+                tok = tok.strip().lower()
+                if len(tok) > 2:
+                    genres.add(tok)
+        lookup[idx] = genres
+    return lookup
+
+
+def _filter_blocked_genres(
+    recommendations: list[tuple[int, float]],
+    blocked_genres: set[str],
+    genre_lookup: dict[int, set[str]],
+) -> list[tuple[int, float]]:
+    """Remove items whose genre set intersects the blocked set."""
+    if not blocked_genres:
+        return recommendations
+    return [
+        (item_id, score)
+        for item_id, score in recommendations
+        if not genre_lookup.get(item_id, set()).intersection(blocked_genres)
+    ]
+
+
+def _clean_int_id(value) -> int | None:
+    if value is None or pd.isna(value):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _build_provider_id_lookup(
+    item_meta: pd.DataFrame,
+    item_to_idx: dict[str, int],
+) -> dict[int, dict[str, int | None]]:
+    lookup: dict[int, dict[str, int | None]] = {}
+    for row in item_meta.itertuples(index=False):
+        idx = item_to_idx.get(row.item_key)
+        if idx is None:
+            continue
+        lookup[idx] = {
+            "tmdb_id": _clean_int_id(getattr(row, "tmdb_id", None)),
+            "rawg_id": _clean_int_id(getattr(row, "rawg_id", None)),
+        }
+    return lookup
+
+
+# ---------------------------------------------------------------------------
+# Application state
+# ---------------------------------------------------------------------------
+
+class AppState:
+    model: CLEPIDTN | None = None
+    item_index: torch.Tensor | None = None
+    text_index: torch.Tensor | None = None
+    item_meta: pd.DataFrame | None = None
+    item_to_idx: dict[str, int] | None = None
+    idx_to_key: dict[int, str] | None = None
+    title_lookup: dict[int, str] | None = None
+    provider_id_lookup: dict[int, dict[str, int | None]] | None = None
+    item_genre_lookup: dict[int, set[str]] | None = None
+    cfg: RecConfig | None = None
+    lock = threading.RLock()
+    hot_added_count: int = 0
+
+
+state = AppState()
+
+
+# ---------------------------------------------------------------------------
+# Startup / shutdown
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    _load_artifacts()
+    yield
+
+
+def _load_artifacts() -> None:
+    with state.lock:
+        cfg = RecConfig()
+        state.cfg = cfg
+
+        # item_to_idx
+        with open(CONFIG["item_to_idx_path"], "rb") as f:
+            state.item_to_idx = pickle.load(f)
+        state.idx_to_key = {v: k for k, v in state.item_to_idx.items()}
+
+        # item_meta
+        with open(CONFIG["item_meta_path"], "rb") as f:
+            state.item_meta = pickle.load(f)
+
+        # title_lookup
+        if os.path.exists(CONFIG["title_lookup_path"]):
+            with open(CONFIG["title_lookup_path"], "rb") as f:
+                state.title_lookup = pickle.load(f)
+        else:
+            state.title_lookup = {}
+
+        # text embeddings (optional — enhances content-based scoring)
+        text_emb_path = CONFIG["text_embeddings_path"]
+        if os.path.exists(text_emb_path):
+            raw = torch.load(text_emb_path, map_location="cpu", weights_only=False)
+            if isinstance(raw, dict) and "tensor" in raw:
+                state.text_index = raw["tensor"]
+            elif isinstance(raw, torch.Tensor):
+                state.text_index = raw
+            else:
+                state.text_index = None
+            print(f"[startup] text embeddings loaded: {state.text_index.shape if state.text_index is not None else 'N/A'}")
+        else:
+            state.text_index = None
+
+        # item_index
+        state.item_index = torch.load(
+            CONFIG["item_index_path"], map_location="cpu", weights_only=False,
+        )
+
+        # model
+        checkpoint = torch.load(
+            CONFIG["model_checkpoint"], map_location=cfg.device, weights_only=False,
+        )
+        model: CLEPIDTN = checkpoint["model"]
+        model.to(cfg.device)
+        model.eval()
+        state.model = model
+
+        # genre lookup
+        state.item_genre_lookup = _build_item_genre_lookup(
+            state.item_meta, state.item_to_idx,
+        )
+        state.provider_id_lookup = _build_provider_id_lookup(
+            state.item_meta, state.item_to_idx,
+        )
+        state.hot_added_count = 0
+
+        print(
+            f"[startup] model loaded | "
+            f"{len(state.item_to_idx):,} items | "
+            f"item_index {state.item_index.shape} | "
+            f"genres tracked: {len(state.item_genre_lookup):,} items"
+        )
+
+
+# ---------------------------------------------------------------------------
+# FastAPI app
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="Questro Recommender API (improved_8)",
+    version=CONFIG["model_version"],
+    description=(
+        "CL-EPIDTN recommendation engine with parental-control genre blocking, "
+        "pagination, and a RAG reranking tool."
+    ),
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ---------------------------------------------------------------------------
+# Pydantic models
+# ---------------------------------------------------------------------------
+
+class RatingItem(BaseModel):
+    """A single item rating — supports BOTH survey labels and numeric stars.
+
+    Provide exactly ONE of `rating` (survey label) or `stars` (numeric).
+    You can also use `source` to signal wishlist/ignore items.
+    """
+    item_id: str = Field(
+        description=(
+            'Item identifier in the format "movie_123", "movie:123", '
+            '"game_123", or "game:123".'
+        ),
+    )
+    title: str | None = Field(
+        default=None,
+        description="Human-readable title (optional, for logging only).",
+    )
+    type: Literal["movie", "game"] | None = Field(
+        default=None,
+        description='Domain hint. Inferred from item_id prefix if omitted.',
+    )
+    rating: str | None = Field(
+        default=None,
+        description=(
+            "Survey-style label.  One of: "
+            '"5 Stars", "4 Stars", "3 Stars", "2 Stars", "1 Star", '
+            '"Didn\'t watch but would watch", "Didn\'t play but would play", '
+            '"Didn\'t watch and wouldn\'t watch", "Didn\'t play and wouldn\'t play".'
+        ),
+    )
+    stars: float | None = Field(
+        default=None,
+        ge=1.0,
+        le=5.0,
+        description="Numeric star rating (1.0–5.0). Alternative to `rating`.",
+    )
+    source: Literal["rating", "wishlist", "ignore"] | None = Field(
+        default=None,
+        description=(
+            'Signal source.  "wishlist" → treated as "would watch/play" (3.5 stars).  '
+            '"ignore" → treated as "wouldn\'t watch/play" (1.5 stars).  '
+            '"rating" or null → uses `rating` or `stars` field.'
+        ),
+    )
+
+    @field_validator("rating", mode="before")
+    @classmethod
+    def _validate_label(cls, v):
+        if v is not None and v not in SURVEY_RATING_VALUES:
+            raise ValueError(
+                f"Invalid rating label: {v!r}. "
+                f"Must be one of: {list(SURVEY_RATING_VALUES.keys())}"
+            )
+        return v
+
+
+class UserProfile(BaseModel):
+    """User profile matching users_ratings.csv schema."""
+    age: int | None = Field(default=None, ge=1, le=120)
+    gender: str | None = None
+    profession: str | None = None
+    country: str | None = None
+    movie_genres_fav: str | None = Field(
+        default=None,
+        description='Pipe-separated favourite movie genres, e.g. "Action|Comedy".',
+    )
+    movie_genres_disliked: str | None = Field(
+        default=None,
+        description='Pipe-separated disliked movie genres.',
+    )
+    game_genres_fav: str | None = Field(
+        default=None,
+        description='Pipe-separated favourite game genres.',
+    )
+    game_genres_disliked: str | None = Field(
+        default=None,
+        description='Pipe-separated disliked game genres.',
+    )
+    ratings: list[RatingItem] = Field(
+        min_length=1,
+        description="User's interaction history (at least 1 item).",
+    )
+
+
+class RecommendRequest(BaseModel):
+    """Request body for /recommend."""
+    user: UserProfile
+    domain: Literal["movie", "game"] | None = Field(
+        default=None,
+        description='Filter to "movie" or "game".  Omit for cross-domain.',
+    )
+    k: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Number of recommendations per page.",
+    )
+    offset: int = Field(
+        default=0,
+        ge=0,
+        description="Pagination offset.  0 = first page, k = second page, etc.",
+    )
+    blocked_genres: list[str] | None = Field(
+        default=None,
+        description=(
+            "Genres/tags to block (parental controls).  "
+            "Case-insensitive.  Pass null or omit for no blocking."
+        ),
+    )
+
+
+class CandidateItem(BaseModel):
+    """An item from the RAG's candidate list."""
+    item_id: str = Field(
+        description='Item identifier, e.g. "movie_155", "movie:155", "game_271590", or "game:271590".',
+    )
+    title: str | None = Field(default=None, description="Optional title.")
+
+
+class CatalogNewItem(BaseModel):
+    """Register a catalog item that was not present when improved_8 was trained."""
+    item_id: str = Field(
+        description='API/internal item ID. Accepts "movie_123", "movie:123", "game_123", or "game:123".',
+    )
+    title: str
+    domain: Literal["movie", "game"] | None = Field(
+        default=None,
+        description="Optional domain override. Inferred from item_id when omitted.",
+    )
+    description: str = ""
+    genres: str = Field(default="", description='Pipe- or comma-separated genres, e.g. "Action|RPG".')
+    tags: str = Field(default="", description="Pipe- or comma-separated tags.")
+    provider_id: int | None = Field(
+        default=None,
+        description="TMDB ID for movies, RAWG ID for games.",
+    )
+
+
+class CatalogAddRequest(BaseModel):
+    items: list[CatalogNewItem] = Field(min_length=1, max_length=500)
+
+
+class CatalogAddResponse(BaseModel):
+    added: list[str]
+    already_exists: list[str]
+    failed: dict[str, str]
+    n_items: int
+    text_index_updated: bool
+
+
+class ReloadResponse(BaseModel):
+    status: str
+    n_items: int
+    text_index_loaded: bool
+    hot_added_count: int
+
+
+class RerankRequest(BaseModel):
+    """Request body for /recommend/rerank (RAG tool)."""
+    user: UserProfile
+    candidate_items: list[CandidateItem] = Field(
+        min_length=1,
+        description="Items fetched by the RAG to be re-ranked by the recommender.",
+    )
+    blocked_genres: list[str] | None = Field(
+        default=None,
+        description="Genres/tags to block (case-insensitive).",
+    )
+    k: int | None = Field(
+        default=None,
+        ge=1,
+        le=100,
+        description="Max items to return.  null = return all candidates ranked.",
+    )
+
+
+class RecommendationItem(BaseModel):
+    item_id: int | None = Field(
+        default=None,
+        description="Backend provider ID: TMDB ID for movies, RAWG ID for games.",
+    )
+    item_key: str
+    title: str
+    domain: Literal["movie", "game"]
+    score: float
+
+
+class RecommendResponse(BaseModel):
+    count: int
+    total_available: int
+    domain: str | None
+    offset: int
+    k: int
+    recommendations: list[RecommendationItem]
+    signals_used: int
+    blocked_genres: list[str]
+    model_version: str
+    has_more: bool
+
+
+class RerankResponse(BaseModel):
+    count: int
+    recommendations: list[RecommendationItem]
+    signals_used: int
+    candidates_submitted: int
+    candidates_matched: int
+    blocked_genres: list[str]
+    model_version: str
+
+
+class HealthResponse(BaseModel):
+    status: str
+    model_loaded: bool
+    n_items: int
+    n_genres_tracked: int
+    text_index_loaded: bool
+    model_version: str
+    hot_added_count: int
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _require_model() -> None:
+    if state.model is None or state.item_index is None:
+        raise HTTPException(status_code=503, detail="Model not loaded yet.")
+
+
+def _parse_item_key(item_id: str, domain_hint: str | None = None) -> str | None:
+    """Normalize API IDs to internal item keys (`movie:123`, `game:123`)."""
+    value = str(item_id).strip()
+    if not value:
+        return None
+    if ":" in value:
+        domain, raw_id = value.split(":", 1)
+    elif "_" in value:
+        domain, raw_id = value.split("_", 1)
+    else:
+        return None
+    domain = (domain_hint or domain).strip().lower()
+    raw_id = raw_id.strip()
+    if domain not in {"movie", "game"} or not raw_id:
+        return None
+    return f"{domain}:{raw_id}"
+
+
+def _catalog_tokens(*values: str) -> str:
+    text = " ".join(value for value in values if value)
+    return " ".join(t for t in re.findall(r"[a-z0-9]+", text.lower()) if len(t) > 2)
+
+
+_TITLE_VERSION_WORDS = {
+    "i", "ii", "iii", "iv", "v", "vi", "vii", "viii", "ix", "x",
+    "one", "two", "three", "four", "five",
+    "definitive", "edition", "complete", "collection", "remastered",
+    "remaster", "reload", "reloaded", "deluxe", "ultimate", "goty",
+    "enhanced", "pack", "dlc", "expansion", "pass", "starter",
+    "content", "mod", "multiplayer",
+}
+
+
+def _title_family_tokens(title: str) -> tuple[str, ...]:
+    """Extract stable franchise-like title tokens.
+
+    This intentionally drops version/edition/DLC words so "Grand Theft Auto V"
+    can match "Grand Theft Auto IV" without hard-coding either title.
+    """
+    value = re.sub(r"\((?:19|20)\d{2}\)", " ", str(title).lower())
+    value = value.replace("™", " ").replace("®", " ")
+    tokens = [
+        token
+        for token in re.findall(r"[a-z0-9]+", value)
+        if len(token) > 1
+        and not token.isdigit()
+        and token not in _TITLE_VERSION_WORDS
+    ]
+    return tuple(tokens[:4])
+
+
+def _family_prefix_score(a: tuple[str, ...], b: tuple[str, ...]) -> float:
+    if len(a) < 2 or len(b) < 2:
+        return 0.0
+    shared_prefix = 0
+    for left, right in zip(a, b):
+        if left != right:
+            break
+        shared_prefix += 1
+    if shared_prefix >= 3:
+        return 1.0
+    if shared_prefix == 2:
+        return 0.65
+    return 0.0
+
+
+def _positive_history_ids(history_ids: list[int], weights: list[float]) -> list[int]:
+    return [idx for idx, weight in zip(history_ids, weights) if weight > 0]
+
+
+def _title_family_candidates(
+    history_ids: list[int],
+    weights: list[float],
+    domain: str | None,
+) -> list[int]:
+    if state.item_meta is None or state.item_to_idx is None:
+        return []
+    positive_families = [
+        _title_family_tokens((state.title_lookup or {}).get(item_id, ""))
+        for item_id in _positive_history_ids(history_ids, weights)
+    ]
+    positive_families = [family for family in positive_families if len(family) >= 2]
+    if not positive_families:
+        return []
+
+    history_set = set(history_ids)
+    rows: list[tuple[int, float]] = []
+    for row in state.item_meta.itertuples(index=False):
+        item_key = getattr(row, "item_key", None)
+        if not item_key:
+            continue
+        item_id = state.item_to_idx.get(item_key)
+        if item_id is None or item_id in history_set:
+            continue
+        row_domain = getattr(row, "domain", None)
+        if domain is not None and row_domain != domain:
+            continue
+        family = _title_family_tokens(getattr(row, "title", ""))
+        score = max((_family_prefix_score(src, family) for src in positive_families), default=0.0)
+        if score > 0:
+            rows.append((item_id, score))
+    rows.sort(key=lambda pair: pair[1], reverse=True)
+    return [item_id for item_id, _ in rows[: CONFIG["title_family_extra_candidates"]]]
+
+
+def _apply_title_family_boost(
+    recommendations: list[tuple[int, float]],
+    history_ids: list[int],
+    weights: list[float],
+) -> list[tuple[int, float]]:
+    boost = CONFIG["title_family_boost"]
+    if boost <= 0:
+        return recommendations
+    positive_families = [
+        _title_family_tokens((state.title_lookup or {}).get(item_id, ""))
+        for item_id in _positive_history_ids(history_ids, weights)
+    ]
+    positive_families = [family for family in positive_families if len(family) >= 2]
+    if not positive_families:
+        return recommendations
+
+    adjusted: list[tuple[int, float]] = []
+    for item_id, score in recommendations:
+        title = (state.title_lookup or {}).get(item_id, "")
+        family = _title_family_tokens(title)
+        family_score = max((_family_prefix_score(src, family) for src in positive_families), default=0.0)
+        adjusted.append((item_id, float(score) + boost * family_score))
+    adjusted.sort(key=lambda pair: pair[1], reverse=True)
+    return adjusted
+
+
+def _genre_set_from_new_item(item: CatalogNewItem) -> set[str]:
+    out: set[str] = set()
+    for value in (item.genres, item.tags):
+        for part in re.split(r"[|,]", value or ""):
+            part = part.strip().lower()
+            if part:
+                out.add(part)
+    return out
+
+
+def _candidate_ids_for_loaded_index() -> torch.Tensor:
+    """Use the loaded item_index length, not only the model embedding table length."""
+    if state.item_index is None:
+        return torch.empty(0, dtype=torch.long)
+    return torch.arange(1, state.item_index.size(0), dtype=torch.long)
+
+
+def _expand_model_for_hot_item(model: CLEPIDTN, new_max_idx: int, domain_ids_map: dict[int, int]) -> None:
+    """Grow model lookup tables for a batch of hot-added items in one pass.
+
+    Args:
+        model:          The live CLEPIDTN model.
+        new_max_idx:    The highest new item index in this batch.
+        domain_ids_map: {item_idx: domain_id (0=movie,1=game)} for every new item.
+
+    All intermediate tensors are built on CPU and moved to the target device in a
+    single .to() call — this avoids accumulating CUDA async errors from repeated
+    per-item GPU allocations.
+    """
+    device = model.item_id.weight.device
+
+    # ── item_id embedding ────────────────────────────────────────────────────
+    old_emb = model.item_id
+    if new_max_idx >= old_emb.num_embeddings:
+        new_emb = nn.Embedding(new_max_idx + 1, old_emb.embedding_dim, padding_idx=PAD)
+        with torch.no_grad():
+            new_emb.weight.zero_()
+            new_emb.weight[: old_emb.num_embeddings].copy_(old_emb.weight.data.cpu())
+        model.item_id = new_emb.to(device)
+
+    # ── item_token_ids ───────────────────────────────────────────────────────
+    if new_max_idx >= model.item_token_ids.size(0):
+        extra = new_max_idx + 1 - model.item_token_ids.size(0)
+        pad_rows = torch.zeros(
+            (extra, model.item_token_ids.size(1)),
+            dtype=model.item_token_ids.dtype,
+        )
+        model.item_token_ids = torch.cat(
+            [model.item_token_ids.cpu(), pad_rows], dim=0
+        ).to(device)
+
+    # ── item_domain_ids ──────────────────────────────────────────────────────
+    if new_max_idx >= model.item_domain_ids.size(0):
+        extra = new_max_idx + 1 - model.item_domain_ids.size(0)
+        # Default 0 (movie); will be overwritten per-item below.
+        pad_domains = torch.zeros(extra, dtype=model.item_domain_ids.dtype)
+        model.item_domain_ids = torch.cat(
+            [model.item_domain_ids.cpu(), pad_domains], dim=0
+        ).to(device)
+
+    for idx, domain_id in domain_ids_map.items():
+        model.item_domain_ids[idx] = domain_id
+
+
+def _encode_catalog_text(items: list[CatalogNewItem]) -> torch.Tensor | None:
+    try:
+        from sentence_transformers import SentenceTransformer
+    except ImportError:
+        return None
+    # Always encode on CPU — the main CUDA context may be in an error state
+    # from a stale device-side assert, and loading a second model to the same
+    # GPU device would surface that error here and crash the server.
+    encoder = SentenceTransformer(CONFIG["text_encoder_model"], device="cpu")
+    texts = [
+        f"{item.title}. {item.description} {item.genres} {item.tags}".strip()
+        for item in items
+    ]
+    emb = encoder.encode(texts, normalize_embeddings=True, convert_to_numpy=True)
+    return torch.tensor(emb, dtype=torch.float32)
+
+
+def _resolve_rating_item(item: RatingItem) -> tuple[int, float] | None:
+    """Resolve a single RatingItem to (model_item_id, weight).
+
+    Returns None if the item can't be resolved.
+    """
+    # Determine weight
+    weight: float
+    if item.source == "wishlist":
+        weight = _LABEL_WEIGHTS.get("Didn't watch but would watch", 0.25)
+    elif item.source == "ignore":
+        weight = _LABEL_WEIGHTS.get("Didn't watch and wouldn't watch", -0.75)
+    elif item.rating is not None:
+        weight = _LABEL_WEIGHTS.get(item.rating, 0.0)
+    elif item.stars is not None:
+        weight = _stars_to_weight(item.stars)
+    else:
+        # No rating info at all — treat as mild positive
+        weight = 0.25
+
+    item_key = _parse_item_key(item.item_id, item.type)
+    if item_key is None:
+        return None
+
+    model_idx = state.item_to_idx.get(item_key)
+    if model_idx is None:
+        return None
+
+    return model_idx, weight
+
+
+def _resolve_user_profile(
+    profile: UserProfile,
+) -> tuple[list[int], list[float]]:
+    """Convert a UserProfile's ratings into (history_ids, weights)."""
+    history_ids: list[int] = []
+    weights: list[float] = []
+    for item in profile.ratings:
+        result = _resolve_rating_item(item)
+        if result is not None:
+            history_ids.append(result[0])
+            weights.append(result[1])
+    return history_ids, weights
+
+
+def _format_recommendation(
+    item_id: int,
+    score: float,
+) -> RecommendationItem:
+    """Map a model item_id + score into a response item."""
+    item_key = state.idx_to_key.get(item_id, "")
+    domain_part, _, _ = item_key.partition(":")
+    title = (state.title_lookup or {}).get(item_id, item_key)
+    provider_ids = (state.provider_id_lookup or {}).get(item_id, {})
+    provider_item_id = (
+        provider_ids.get("tmdb_id")
+        if domain_part == "movie"
+        else provider_ids.get("rawg_id")
+        if domain_part == "game"
+        else None
+    )
+    return RecommendationItem(
+        item_id=provider_item_id,
+        item_key=item_key,
+        title=title,
+        domain=domain_part if domain_part in {"movie", "game"} else "movie",
+        score=round(float(score), 6),
+    )
+
+
+def _normalize_blocked(blocked_genres: list[str] | None) -> set[str]:
+    """Return a lowercased set of blocked genres/tags."""
+    if not blocked_genres:
+        return set()
+    return {g.strip().lower() for g in blocked_genres if g.strip()}
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/health", response_model=HealthResponse, tags=["Meta"])
+def health():
+    """Health check — verify the model is loaded before sending requests."""
+    with state.lock:
+        return HealthResponse(
+            status="ok",
+            model_loaded=state.model is not None,
+            n_items=len(state.item_to_idx) if state.item_to_idx else 0,
+            n_genres_tracked=len(state.item_genre_lookup) if state.item_genre_lookup else 0,
+            text_index_loaded=state.text_index is not None,
+            model_version=CONFIG["model_version"],
+            hot_added_count=state.hot_added_count,
+        )
+
+
+@app.get("/genres", tags=["Meta"], summary="List all genres available for blocking")
+def list_genres():
+    """Return all unique genres/tags in the catalog (lowercased).
+
+    Use this to populate the parental-controls UI.
+    """
+    if not state.item_genre_lookup:
+        return {"genres": []}
+    all_genres: set[str] = set()
+    for genres in state.item_genre_lookup.values():
+        all_genres.update(genres)
+    # Return sorted, keeping only meaningful genre-like tokens (len > 2)
+    return {"genres": sorted(g for g in all_genres if len(g) > 2)}
+
+
+@app.post(
+    "/admin/reload",
+    response_model=ReloadResponse,
+    tags=["Admin"],
+    summary="Reload model artifacts from disk",
+)
+def reload_artifacts():
+    """Reload all on-disk artifacts. Runtime hot-added items are intentionally cleared."""
+    _load_artifacts()
+    return ReloadResponse(
+        status="ok",
+        n_items=len(state.item_to_idx) if state.item_to_idx else 0,
+        text_index_loaded=state.text_index is not None,
+        hot_added_count=state.hot_added_count,
+    )
+
+
+@app.post(
+    "/catalog/add",
+    response_model=CatalogAddResponse,
+    tags=["Catalog"],
+    summary="Hot-add cold-start catalog items at runtime",
+)
+def add_catalog_items(request: CatalogAddRequest):
+    """Register new catalog items without retraining.
+
+    Hot-added items receive zero learned embeddings, but can rank through text
+    similarity when `sentence-transformers` is installed and text embeddings are
+    loaded. They are runtime-only; use `/admin/reload` or restart to return to
+    the persisted artifact state.
+    """
+    _require_model()
+
+    added: list[str] = []
+    already_exists: list[str] = []
+    failed: dict[str, str] = {}
+    items_to_encode: list[CatalogNewItem] = []
+    ids_to_encode: list[int] = []
+
+    with state.lock:
+        if state.item_to_idx is None or state.idx_to_key is None:
+            raise HTTPException(status_code=503, detail="Catalog mappings not loaded.")
+        if state.item_index is None or state.model is None:
+            raise HTTPException(status_code=503, detail="Model index not loaded.")
+
+        next_idx = max(state.idx_to_key.keys(), default=0) + 1
+
+        # Collect the highest new index and domain mapping for a single batch
+        # expansion after the loop (avoids repeated GPU alloc/cat per item).
+        new_max_idx: int = -1
+        domain_ids_map: dict[int, int] = {}
+        new_meta_rows: list[dict] = []
+
+        for item in request.items:
+            item_key = _parse_item_key(item.item_id, item.domain)
+            if item_key is None:
+                failed[item.item_id] = "Invalid item_id. Expected movie/game with '_' or ':'."
+                continue
+            domain, _, _ = item_key.partition(":")
+            if item_key in state.item_to_idx:
+                already_exists.append(item_key)
+                continue
+
+            new_idx = next_idx
+            next_idx += 1
+
+            state.item_to_idx[item_key] = new_idx
+            state.idx_to_key[new_idx] = item_key
+            if state.title_lookup is None:
+                state.title_lookup = {}
+            state.title_lookup[new_idx] = item.title
+            new_max_idx = max(new_max_idx, new_idx)
+            domain_ids_map[new_idx] = 0 if domain == "movie" else 1
+
+            if state.item_genre_lookup is None:
+                state.item_genre_lookup = {}
+            genres = _genre_set_from_new_item(item)
+            tokens = _catalog_tokens(item.genres, item.tags, item.title, item.description)
+            for tok in tokens.split()[:20]:
+                genres.add(tok)
+            state.item_genre_lookup[new_idx] = genres
+            if state.provider_id_lookup is None:
+                state.provider_id_lookup = {}
+            state.provider_id_lookup[new_idx] = {
+                "tmdb_id": item.provider_id if domain == "movie" else None,
+                "rawg_id": item.provider_id if domain == "game" else None,
+            }
+
+            new_row = {
+                "item_key": item_key,
+                "title": item.title,
+                "domain": domain,
+                "tokens": tokens,
+                "user_reviews": 0,
+                "description": item.description,
+                "tmdb_id": pd.NA,
+                "rawg_id": pd.NA,
+                "hf_genres": item.genres,
+                "hf_tags": item.tags,
+            }
+            if domain == "movie" and item.provider_id is not None:
+                new_row["tmdb_id"] = item.provider_id
+            if domain == "game" and item.provider_id is not None:
+                new_row["rawg_id"] = item.provider_id
+            new_meta_rows.append(new_row)
+
+            if state.text_index is not None:
+                items_to_encode.append(item)
+                ids_to_encode.append(new_idx)
+            added.append(item_key)
+
+        # ── Single-pass tensor expansion for all newly added items ────────
+        # Build on CPU then move to device in one .to() call — prevents CUDA
+        # async errors from accumulating across per-item GPU allocations.
+        if new_max_idx >= 0:
+            _device = state.item_index.device
+
+            try:
+                if new_max_idx >= state.item_index.size(0):
+                    needed = new_max_idx + 1 - state.item_index.size(0)
+                    zero_vecs = torch.zeros(
+                        (needed, state.item_index.size(1)),
+                        dtype=state.item_index.dtype,
+                    )
+                    state.item_index = torch.cat(
+                        [state.item_index.cpu(), zero_vecs], dim=0
+                    ).to(_device)
+            except RuntimeError as _exc:
+                # A stale CUDA async error from a previous request can surface
+                # here on the first .to(device) call.  The catalog state is still
+                # valid on CPU; the items will score with zero embeddings and
+                # the rerank bounds-guard will keep them out of the CUDA forward.
+                print(
+                    f"Warning: item_index GPU expansion failed (max_idx={new_max_idx}): {_exc}\n"
+                    "Catalog entries are registered; they will be skipped by rerank."
+                )
+
+            try:
+                _expand_model_for_hot_item(state.model, new_max_idx, domain_ids_map)
+            except RuntimeError as _exc:
+                print(
+                    f"Warning: GPU model expansion failed for hot-add batch "
+                    f"(max_idx={new_max_idx}): {_exc}\n"
+                    "Items are registered in catalog but will score with zero embeddings."
+                )
+
+            if state.text_index is not None and new_max_idx >= state.text_index.size(0):
+                try:
+                    needed = new_max_idx + 1 - state.text_index.size(0)
+                    zero_text = torch.zeros(
+                        (needed, state.text_index.size(1)),
+                        dtype=state.text_index.dtype,
+                    )
+                    state.text_index = torch.cat(
+                        [state.text_index.cpu(), zero_text], dim=0
+                    ).to(_device)
+                except RuntimeError as _exc:
+                    print(f"Warning: text_index GPU expansion failed: {_exc}")
+
+        # Bulk pandas concat — one allocation for the entire batch instead of
+        # one per item (O(N²) → O(N)).
+        if new_meta_rows:
+            state.item_meta = pd.concat(
+                [state.item_meta, pd.DataFrame(new_meta_rows)],
+                ignore_index=True,
+                sort=False,
+            )
+
+        state.hot_added_count += len(added)
+
+    text_index_updated = False
+    if items_to_encode:
+        try:
+            encoded = _encode_catalog_text(items_to_encode)
+        except Exception as _enc_exc:
+            print(f"Warning: text encoding failed, skipping text index update: {_enc_exc}")
+            encoded = None
+        if encoded is not None:
+            try:
+                with state.lock:
+                    if state.text_index is not None:
+                        if encoded.size(1) != state.text_index.size(1):
+                            for item_key in added:
+                                failed[item_key] = "Text encoder dimension did not match loaded text index."
+                        else:
+                            needed = max(ids_to_encode) + 1 - state.text_index.size(0)
+                            if needed > 0:
+                                pad = torch.zeros(
+                                    (needed, state.text_index.size(1)),
+                                    dtype=state.text_index.dtype,
+                                )
+                                state.text_index = torch.cat([state.text_index, pad], dim=0)
+                            state.text_index[ids_to_encode] = encoded.to(state.text_index.dtype)
+                            text_index_updated = True
+            except Exception as _tidx_exc:
+                print(f"Warning: text index write failed: {_tidx_exc}")
+
+    return CatalogAddResponse(
+        added=added,
+        already_exists=already_exists,
+        failed=failed,
+        n_items=len(state.item_to_idx) if state.item_to_idx else 0,
+        text_index_updated=text_index_updated,
+    )
+
+
+@app.post(
+    "/recommend",
+    response_model=RecommendResponse,
+    tags=["Recommendations"],
+    summary="Get personalised recommendations with pagination & parental controls",
+)
+def recommend(request: RecommendRequest):
+    """Accept a user profile and return personalised, genre-filtered recommendations.
+
+    - Supports survey labels, numeric stars, and wishlist/ignore signals.
+    - `blocked_genres` removes items matching any blocked genre/tag (case-insensitive).
+    - The API guarantees exactly `k` results (or fewer if the catalog is exhausted),
+      AFTER genre filtering.
+    - Use `offset` for pagination: page 1 = offset 0, page 2 = offset k, etc.
+    """
+    _require_model()
+
+    blocked = _normalize_blocked(request.blocked_genres)
+    desired_total = request.offset + request.k
+    multiplier = CONFIG["overfetch_multiplier"] if blocked else 1
+    fetch_k = min(max(desired_total * multiplier, desired_total + 1), CONFIG["max_recs"] * multiplier)
+
+    # Hold the lock for the entire inference block.  /catalog/add swaps tensors
+    # and model attributes (state.item_index, model.item_id, …) under the same
+    # lock; reading them concurrently without the lock risks shape-mismatch
+    # crashes from a mid-swap read.  A read-write lock is the next step if this
+    # becomes a throughput bottleneck.
+    with state.lock:
+        # Resolve user ratings
+        history_ids, weights = _resolve_user_profile(request.user)
+        if not history_ids:
+            raise HTTPException(
+                status_code=422,
+                detail="None of the provided items are in the model catalog.",
+            )
+
+        try:
+            raw_recs = recommend_from_history(
+                state.model,
+                state.item_index,
+                history_ids,
+                user_id=None,
+                activity=len(history_ids),
+                cfg=state.cfg,
+                k=fetch_k,
+                domain=request.domain,
+                text_index=state.text_index,
+                history_weights=weights,
+                candidate_item_ids=_candidate_ids_for_loaded_index(),
+            )
+            title_family_ids = _title_family_candidates(history_ids, weights, request.domain)
+            if title_family_ids:
+                candidate_ids = sorted({item_id for item_id, _ in raw_recs}.union(title_family_ids))
+                raw_recs = recommend_from_history(
+                    state.model,
+                    state.item_index,
+                    history_ids,
+                    user_id=None,
+                    activity=len(history_ids),
+                    cfg=state.cfg,
+                    k=len(candidate_ids),
+                    domain=request.domain,
+                    text_index=state.text_index,
+                    history_weights=weights,
+                    candidate_item_ids=torch.tensor(candidate_ids, dtype=torch.long),
+                )
+                raw_recs = _apply_title_family_boost(raw_recs, history_ids, weights)
+        except ValueError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+        # Apply genre blocking
+        if blocked:
+            filtered = _filter_blocked_genres(raw_recs, blocked, state.item_genre_lookup)
+        else:
+            filtered = raw_recs
+
+        # Pagination: slice [offset : offset + k]
+        total_available = len(filtered)
+        page = filtered[request.offset : request.offset + request.k]
+        results = [_format_recommendation(item_id, score) for item_id, score in page]
+
+    return RecommendResponse(
+        count=len(results),
+        total_available=total_available,
+        domain=request.domain,
+        offset=request.offset,
+        k=request.k,
+        recommendations=results,
+        signals_used=len(history_ids),
+        blocked_genres=sorted(blocked) if blocked else [],
+        model_version=CONFIG["model_version"],
+        has_more=(request.offset + request.k) < total_available,
+    )
+
+
+@app.post(
+    "/recommend/rerank",
+    response_model=RerankResponse,
+    tags=["RAG Tool"],
+    summary="Re-rank a RAG-fetched candidate list using the recommender model",
+)
+def rerank(request: RerankRequest):
+    """Score and re-rank a list of externally-fetched items using the user's profile.
+
+    Use this as a tool in your RAG pipeline:
+    1. Your RAG retrieves a broad list of candidate items.
+    2. POST them here with the user's profile.
+    3. The recommender scores each candidate against the user and returns them
+       ranked by personalised relevance, with blocked genres filtered out.
+    """
+    _require_model()
+
+    # Same lock rationale as /recommend: /catalog/add swaps model attributes and
+    # tensor references under state.lock; inference must hold the same lock to
+    # avoid reading a half-swapped tensor.
+    with state.lock:
+        # Resolve user ratings
+        history_ids, weights = _resolve_user_profile(request.user)
+        if not history_ids:
+            raise HTTPException(
+                status_code=422,
+                detail="None of the user's items are in the model catalog.",
+            )
+
+        # Resolve candidate items to model IDs
+        candidate_model_ids: list[int] = []
+        candidate_map: dict[int, CandidateItem] = {}
+        for candidate in request.candidate_items:
+            item_key = _parse_item_key(candidate.item_id)
+            if item_key is None:
+                continue
+            model_idx = state.item_to_idx.get(item_key)
+            if model_idx is not None:
+                candidate_model_ids.append(model_idx)
+                candidate_map[model_idx] = candidate
+
+        if not candidate_model_ids:
+            raise HTTPException(
+                status_code=422,
+                detail="None of the candidate items are in the model catalog.",
+            )
+
+        # Remove candidates that are already in the user's history
+        history_set = set(history_ids)
+        candidate_model_ids = [c for c in candidate_model_ids if c not in history_set]
+
+        if not candidate_model_ids:
+            raise HTTPException(
+                status_code=422,
+                detail="All candidate items are already in the user's history.",
+            )
+
+        # Clamp to the safe scoring range.
+        # Hot-added items whose index exceeds the trained embedding bounds have zero
+        # learned vectors and — more critically — would trigger a CUDA device-side
+        # assert inside item_features() because the embedding kernel asserts
+        # 0 <= idx < num_embeddings.  We skip them here; they remain in the catalog
+        # and Gemini/RAG still sees their FAISS similarity scores.
+        n_safe = min(
+            state.model.item_id.num_embeddings,
+            state.model.item_token_ids.size(0),
+            state.model.item_domain_ids.size(0),
+            state.item_index.size(0),
+        )
+        scoreable = [mid for mid in candidate_model_ids if mid < n_safe]
+        unscoreable = [mid for mid in candidate_model_ids if mid >= n_safe]
+
+        if unscoreable:
+            print(
+                f"Rerank: {len(unscoreable)} hot-added candidates skipped "
+                f"(indices {min(unscoreable)}–{max(unscoreable)} beyond safe "
+                f"range {n_safe}). They will use FAISS scores."
+            )
+
+        if not scoreable:
+            # All candidates are hot-added items — return empty so RAG falls back
+            # to raw FAISS scores rather than crashing.
+            return RerankResponse(
+                count=0,
+                recommendations=[],
+                signals_used=len(history_ids),
+                candidates_submitted=len(request.candidate_items),
+                candidates_matched=len(candidate_map),
+                blocked_genres=[],
+                model_version=CONFIG["model_version"],
+            )
+
+        # Bounds-check history too.  recommend_from_history passes history_ids
+        # to model.item_features() on the same CUDA path as candidates — an
+        # out-of-range history index (e.g. user rated a hot-added item) poisons
+        # the CUDA context just as badly as an out-of-range candidate would.
+        safe_hist = [(h, w) for h, w in zip(history_ids, weights) if h < n_safe]
+        if not safe_hist:
+            return RerankResponse(
+                count=0,
+                recommendations=[],
+                signals_used=0,
+                candidates_submitted=len(request.candidate_items),
+                candidates_matched=len(candidate_map),
+                blocked_genres=[],
+                model_version=CONFIG["model_version"],
+            )
+        history_ids = [h for h, w in safe_hist]
+        weights = [w for h, w in safe_hist]
+
+        # Score candidates using the model
+        candidate_tensor = torch.tensor(
+            sorted(set(scoreable)), dtype=torch.long,
+        )
+
+        try:
+            scored = recommend_from_history(
+                state.model,
+                state.item_index,
+                history_ids,
+                user_id=None,
+                activity=len(history_ids),
+                cfg=state.cfg,
+                k=len(candidate_tensor),
+                domain=None,  # don't domain-filter — candidates are already curated
+                text_index=state.text_index,
+                history_weights=weights,
+                candidate_item_ids=candidate_tensor,
+            )
+        except (ValueError, RuntimeError) as exc:
+            if "CUDA" in str(exc) or "device-side" in str(exc):
+                # A stale CUDA async error surfaced during scoring.
+                # Return empty so RAG falls back to FAISS scores rather than crash.
+                print(f"Rerank: CUDA error during model scoring, falling back to FAISS. {exc}")
+                return RerankResponse(
+                    count=0,
+                    recommendations=[],
+                    signals_used=len(history_ids),
+                    candidates_submitted=len(request.candidate_items),
+                    candidates_matched=len(candidate_map),
+                    blocked_genres=[],
+                    model_version=CONFIG["model_version"],
+                )
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+        # Apply genre blocking
+        blocked = _normalize_blocked(request.blocked_genres)
+        if blocked:
+            scored = _filter_blocked_genres(scored, blocked, state.item_genre_lookup)
+
+        # Limit results
+        if request.k is not None:
+            scored = scored[: request.k]
+
+        results = [_format_recommendation(item_id, score) for item_id, score in scored]
+
+    return RerankResponse(
+        count=len(results),
+        recommendations=results,
+        signals_used=len(history_ids),
+        candidates_submitted=len(request.candidate_items),
+        candidates_matched=len(candidate_map),
+        blocked_genres=sorted(blocked) if blocked else [],
+        model_version=CONFIG["model_version"],
+    )

requirements.docker.txt

@@ -0,0 +1,20 @@
+# Runtime dependencies for the CL-EPIDTN recommender API (improved_8).
+# CPU torch is installed separately in the Dockerfile from the PyTorch CPU index.
+# Versions are pinned to match the recommender service for a consistent stack.
+fastapi==0.137.0
+uvicorn==0.49.0
+pydantic==2.13.4
+pandas==3.0.3
+numpy==1.26.4
+# Required to unpickle item_meta.pkl (pandas data uses pyarrow-backed dtypes).
+pyarrow==24.0.0
+tqdm==4.68.2
+
+# Text encoder for catalog hot-add (sentence-transformers/all-MiniLM-L6-v2)
+sentence-transformers==5.5.1
+transformers==5.12.0
+tokenizers==0.22.2
+huggingface_hub==1.19.0
+safetensors==0.8.0
+scikit-learn==1.9.0
+scipy==1.17.1