Initial deployment setup for Recommendation_Deploy

.dockerignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+.git/
+.gitignore
+*.ipynb
+*.md
+.env
+venv/
+.venv/
+extracted_notebook.py

.gitattributes

@@ -0,0 +1 @@
+* text=auto

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+venv/
+.venv/
+.env
+extracted_notebook.py

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.9-slim
+
+ENV HF_HOME=/tmp/huggingface
+ENV PYTHONUNBUFFERED=1
+
+# Set up a new user named "user" with user ID 1000
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# Set working directory
+WORKDIR /app
+
+# Copy requirements and install
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy project files
+COPY --chown=user . .
+
+# Expose port 7860 for Hugging Face Spaces
+EXPOSE 7860
+
+# Run uvicorn
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,198 @@
+---
+title: LITVISION Recommendation API
+emoji: 📚
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+license: mit
+---
+
+# LITVISION Book Recommendation API
+
+A production-ready FastAPI service for the LITVISION Book Recommendation Feature. This API provides personalized book recommendations using zero-shot genre classification, SentenceTransformer embeddings, FAISS similarity search, and an event-weighted ranking pipeline.
+
+Fully configured for deployment on Hugging Face Spaces with Docker SDK.
+
+## Features
+
+- **Zero-Shot Genre Classification** using `joeddav/xlm-roberta-large-xnli`
+- **SentenceTransformer Embeddings** using `paraphrase-multilingual-MiniLM-L12-v2`
+- **FAISS Similarity Search** with `IndexFlatIP` for cosine similarity on normalized vectors
+- **Event-Weighted User Profiling** with configurable view/like weights
+- **Genre-Balanced Feed Allocation** for diverse recommendations
+- **Cosine-Similarity Ranking Pipeline** for personalized ordering
+- **GPU/CPU Fallback** with FP16 optimization on CUDA
+- **Async Processing** via `asyncio.to_thread` for non-blocking inference
+- **Production Error Handling** including CUDA OOM recovery
+
+## API Endpoints
+
+### GET /
+
+Returns basic API information.
+
+```json
+{
+  "api": "LITVISION Book Recommendation API",
+  "status": "online",
+  "version": "1.0.0",
+  "endpoints": ["/health", "/recommend"]
+}
+```
+
+### GET /health
+
+Returns health status and model readiness.
+
+```json
+{
+  "status": "healthy",
+  "models_loaded": true,
+  "device": "cuda",
+  "total_books": 200,
+  "faiss_index_size": 200
+}
+```
+
+### POST /recommend
+
+Generates personalized book recommendations for a user.
+
+**Request Body:**
+
+```json
+{
+  "user_id": 1,
+  "interactions": [
+    {
+      "book_id": 5,
+      "event_type": "like",
+      "timestamp": "2025-01-01T00:00:00"
+    },
+    {
+      "book_id": 12,
+      "event_type": "view",
+      "timestamp": "2025-01-02T00:00:00"
+    }
+  ],
+  "favorite_genres": ["Fantasy", "Science Fiction"],
+  "viewed_books": [1, 2, 3],
+  "feed_size": 20
+}
+```
+
+**Parameters:**
+
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| user_id | int | Yes | — | Unique user identifier (> 0) |
+| interactions | list | No | null | Explicit user-book interaction events |
+| favorite_genres | list | No | null | Preferred genres for boosting |
+| viewed_books | list | No | null | Book IDs already viewed by the user |
+| feed_size | int | No | 20 | Number of recommendations (1-100) |
+
+**Valid Genres:**
+
+Fantasy, Romance, Mystery, Science Fiction, Self-Help, History, Business, Children, Horror, Poetry
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "user_id": 1,
+  "recommendations": [
+    {
+      "book_id": 42,
+      "title": "Fantasy Book 42",
+      "author": "Author 7",
+      "genre": "Fantasy",
+      "score": 0.9234
+    }
+  ],
+  "genre_distribution": {
+    "Fantasy": 8,
+    "Romance": 4,
+    "Mystery": 3,
+    "Science Fiction": 2,
+    "Self-Help": 1,
+    "History": 1,
+    "Children": 1
+  },
+  "total_recommendations": 20,
+  "processing_time_seconds": 1.234
+}
+```
+
+## Folder Structure
+
+```text
+.
+├── app.py                # FastAPI endpoints and lifespan events
+├── recommender.py        # Full recommendation pipeline engine
+├── utils.py              # Logging, device helpers, and cleanup
+├── requirements.txt      # Python dependencies
+├── Dockerfile            # Container configuration for HF Spaces
+├── .dockerignore         # Docker build exclusions
+├── .gitignore            # Git exclusions
+├── .gitattributes        # Line ending configuration
+├── README.md             # This file
+└── sample_data/
+    └── books.csv         # Sample book dataset (200 books)
+```
+
+## Local Development
+
+### 1. Install Python Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### 2. Run the Server
+
+```bash
+uvicorn app:app --host 0.0.0.0 --port 7860 --reload
+```
+
+### 3. Test with cURL
+
+```bash
+curl -X POST http://localhost:7860/recommend \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": 1, "feed_size": 10}'
+```
+
+## Docker Build and Run
+
+### Build the Image
+
+```bash
+docker build -t litvision-recommender .
+```
+
+### Run the Container
+
+```bash
+docker run -p 7860:7860 litvision-recommender
+```
+
+With GPU support:
+
+```bash
+docker run -p 7860:7860 --gpus all litvision-recommender
+```
+
+## Deployment to Hugging Face Spaces
+
+1. Go to [Hugging Face](https://huggingface.co) and create a new Space.
+2. Select **Docker** as the Space SDK.
+3. Upload all the files in this directory to the repository.
+4. The Space will automatically build the container and start the Uvicorn server on port 7860.
+
+## Troubleshooting
+
+- **Models loading slowly:** The first startup downloads `xlm-roberta-large-xnli` (~2.2 GB) and `paraphrase-multilingual-MiniLM-L12-v2`. Subsequent starts use the cached models.
+- **CUDA OOM:** The API automatically clears CUDA cache and returns HTTP 503. Retry the request or reduce `feed_size`.
+- **503 on first request:** Models may still be loading. Check `/health` endpoint for status.

app.py

@@ -0,0 +1,325 @@
+"""
+LITVISION Recommendation API
+==============================
+Production FastAPI application for personalized book recommendations.
+Deployed on Hugging Face Spaces via Docker SDK.
+"""
+
+import time
+import logging
+import asyncio
+from contextlib import asynccontextmanager
+from typing import Dict, List, Optional
+
+import torch
+from fastapi import FastAPI, HTTPException, Request, BackgroundTasks
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, field_validator
+
+from utils import setup_logging, safe_cuda_empty_cache, cleanup_temp_files, validate_positive_int
+from recommender import engine, GENRES
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+setup_logging()
+logger = logging.getLogger("litvision.recommendation")
+
+# ---------------------------------------------------------------------------
+# Pydantic models
+# ---------------------------------------------------------------------------
+
+class Interaction(BaseModel):
+    """A single user–book interaction event."""
+    book_id: int = Field(..., gt=0, description="ID of the book")
+    event_type: str = Field(
+        default="view",
+        description="Interaction type: 'view' or 'like'",
+    )
+    timestamp: Optional[str] = Field(
+        default=None,
+        description="ISO-8601 timestamp of the interaction",
+    )
+
+    @field_validator("event_type")
+    @classmethod
+    def validate_event_type(cls, v: str) -> str:
+        allowed = {"view", "like"}
+        if v not in allowed:
+            raise ValueError(f"event_type must be one of {allowed}, got '{v}'")
+        return v
+
+
+class RecommendRequest(BaseModel):
+    """Payload for POST /recommend."""
+    user_id: int = Field(..., gt=0, description="Unique user identifier")
+    interactions: Optional[List[Interaction]] = Field(
+        default=None,
+        description="List of explicit user–book interactions",
+    )
+    favorite_genres: Optional[List[str]] = Field(
+        default=None,
+        description="User's preferred genres",
+    )
+    viewed_books: Optional[List[int]] = Field(
+        default=None,
+        description="IDs of books the user has already viewed",
+    )
+    feed_size: int = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="Number of recommendations to return (1-100)",
+    )
+
+    @field_validator("favorite_genres")
+    @classmethod
+    def validate_genres(cls, v: Optional[List[str]]) -> Optional[List[str]]:
+        if v is not None:
+            invalid = [g for g in v if g not in GENRES]
+            if invalid:
+                raise ValueError(
+                    f"Invalid genres: {invalid}. Valid genres: {GENRES}"
+                )
+        return v
+
+    @field_validator("viewed_books")
+    @classmethod
+    def validate_viewed_books(cls, v: Optional[List[int]]) -> Optional[List[int]]:
+        if v is not None:
+            for bid in v:
+                if bid < 1:
+                    raise ValueError(f"viewed_books IDs must be positive, got {bid}")
+        return v
+
+
+class BookResponse(BaseModel):
+    """A single recommended book."""
+    book_id: int
+    title: str
+    author: str
+    genre: str
+    score: Optional[float] = None
+
+
+class RecommendResponse(BaseModel):
+    """Response from POST /recommend."""
+    success: bool
+    user_id: int
+    recommendations: List[BookResponse]
+    genre_distribution: Dict[str, int]
+    total_recommendations: int
+    processing_time_seconds: float
+
+
+class RootResponse(BaseModel):
+    api: str
+    status: str
+    version: str
+    endpoints: List[str]
+
+
+class HealthResponse(BaseModel):
+    status: str
+    models_loaded: bool
+    device: str
+    total_books: int
+    faiss_index_size: int
+
+
+class VersionResponse(BaseModel):
+    service: str
+    version: str
+
+
+# ---------------------------------------------------------------------------
+# Application lifespan
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Startup: load models. Shutdown: cleanup caches."""
+    logger.info("API starting...")
+    try:
+        logger.info("Loading recommendation engine...")
+        await asyncio.to_thread(engine.load_models)
+        logger.info("Recommendation engine loaded successfully")
+        logger.info("Server ready")
+    except Exception as exc:
+        logger.error(f"Failed to load models on startup: {exc}", exc_info=True)
+        # Allow the app to start anyway so /health can report the issue
+    yield
+    logger.info("Shutting down — cleaning up …")
+    cleanup_temp_files()
+    safe_cuda_empty_cache()
+    logger.info("Shutdown complete")
+
+
+# ---------------------------------------------------------------------------
+# FastAPI app
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="LITVISION Book Recommendation API",
+    description=(
+        "AI-powered personalized book recommendation service using "
+        "zero-shot classification, SentenceTransformer embeddings, "
+        "and FAISS similarity search."
+    ),
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@app.get("/", response_model=RootResponse, tags=["Recommendation"])
+async def root():
+    """Basic API information."""
+    return {
+        "api": "LITVISION Book Recommendation API",
+        "status": "online",
+        "version": "1.0.0",
+        "endpoints": ["/health", "/recommend", "/version"],
+    }
+
+
+@app.get("/health", response_model=HealthResponse, tags=["Recommendation"])
+async def health():
+    """Health check — reports model readiness and device info."""
+    return {
+        "status": "healthy" if engine._loaded else "loading",
+        "models_loaded": engine._loaded,
+        "device": engine.device,
+        "total_books": len(engine.books_df) if engine.books_df is not None else 0,
+        "faiss_index_size": engine.faiss_index.ntotal if engine.faiss_index else 0,
+    }
+
+@app.get("/version", response_model=VersionResponse, tags=["Recommendation"])
+async def version():
+    """Return API version information."""
+    return {
+        "service": "LITVISION Recommendation API",
+        "version": "1.0.0"
+    }
+
+
+@app.post("/recommend", response_model=RecommendResponse, tags=["Recommendation"])
+async def recommend(request: RecommendRequest, background_tasks: BackgroundTasks):
+    """
+    Generate personalized book recommendations.
+
+    Uses the full notebook pipeline:
+    1. Build user interaction DataFrame from request payload
+    2. Compute genre interest ratios (event-weighted)
+    3. Genre-balanced feed allocation
+    4. Cosine-similarity ranking via user embedding vector
+    """
+    start_time = time.time()
+
+    # Guard: models must be loaded
+    if not engine._loaded:
+        raise HTTPException(
+            status_code=503,
+            detail="Models are still loading. Please retry in a few moments.",
+        )
+
+    try:
+        # 1. Build interactions DataFrame
+        interactions_dicts = None
+        if request.interactions:
+            interactions_dicts = [
+                {
+                    "book_id": i.book_id,
+                    "event_type": i.event_type,
+                    "timestamp": i.timestamp,
+                }
+                for i in request.interactions
+            ]
+
+        interactions_df = await asyncio.to_thread(
+            engine.build_interactions_df,
+            request.user_id,
+            interactions_dicts,
+            request.viewed_books,
+            request.favorite_genres,
+        )
+
+        # 2. Generate recommendations (heavy — offloaded from event loop)
+        try:
+            feed = await asyncio.wait_for(
+                asyncio.to_thread(
+                    engine.build_mixed_feed,
+                    request.user_id,
+                    interactions_df,
+                    request.feed_size,
+                ),
+                timeout=60.0
+            )
+        except asyncio.TimeoutError:
+            raise HTTPException(status_code=504, detail="Request processing timed out.")
+
+        # 3. Build response
+        recommendations: List[BookResponse] = []
+        for _, row in feed.iterrows():
+            recommendations.append(
+                BookResponse(
+                    book_id=int(row["book_id"]),
+                    title=str(row["title"]),
+                    author=str(row["author"]),
+                    genre=str(row["genre"]),
+                    score=round(float(row["score"]), 4) if "score" in row.index else None,
+                )
+            )
+
+        genre_dist = feed["genre"].value_counts().to_dict()
+        elapsed = round(time.time() - start_time, 3)
+
+        logger.info(
+            f"Recommendation for user {request.user_id}: "
+            f"{len(recommendations)} books in {elapsed}s"
+        )
+
+        return RecommendResponse(
+            success=True,
+            user_id=request.user_id,
+            recommendations=recommendations,
+            genre_distribution=genre_dist,
+            total_recommendations=len(recommendations),
+            processing_time_seconds=elapsed,
+        )
+
+    except torch.cuda.OutOfMemoryError as exc:
+        safe_cuda_empty_cache()
+        logger.error(f"CUDA OOM during recommendation: {exc}")
+        raise HTTPException(
+            status_code=503,
+            detail="GPU out of memory. CUDA cache cleared — please retry.",
+        )
+    except ValueError as exc:
+        logger.warning(f"Validation error: {exc}")
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception as exc:
+        logger.error(f"Recommendation error: {exc}", exc_info=True)
+        error_msg = str(exc).lower()
+        if "out of memory" in error_msg:
+            safe_cuda_empty_cache()
+            raise HTTPException(
+                status_code=503,
+                detail="Out of memory. Cache cleared — please retry.",
+            )
+        raise HTTPException(status_code=500, detail=f"Internal error: {exc}")
+    finally:
+        background_tasks.add_task(cleanup_temp_files)

recommender.py

@@ -0,0 +1,553 @@
+"""
+LITVISION Recommendation Engine
+================================
+Complete recommendation pipeline preserving every component from
+the original Jupyter Notebook:
+
+  • Zero-shot genre classification  (joeddav/xlm-roberta-large-xnli)
+  • SentenceTransformer embeddings  (paraphrase-multilingual-MiniLM-L12-v2)
+  • FAISS IndexFlatIP similarity search
+  • Event-weighted user vector construction
+  • Proportional genre-balanced feed allocation
+  • Cosine-similarity ranking pipeline
+
+NO logic has been simplified, removed, or replaced.
+"""
+
+import os
+import logging
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional, Set, Tuple
+
+import numpy as np
+import pandas as pd
+import torch
+import faiss
+from transformers import pipeline as hf_pipeline
+from sentence_transformers import SentenceTransformer
+
+from utils import get_device, safe_cuda_empty_cache
+
+logger = logging.getLogger("litvision.recommendation")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Constants — identical to the notebook
+# ═══════════════════════════════════════════════════════════════════════════
+
+GENRES: List[str] = [
+    "Fantasy", "Romance", "Mystery", "Science Fiction", "Self-Help",
+    "History", "Business", "Children", "Horror", "Poetry",
+]
+
+EVENT_W: Dict[str, float] = {"view": 1.0, "like": 3.0}
+
+TEMPLATES: Dict[str, List[str]] = {
+    "Fantasy": [
+        "A young hero discovers a hidden kingdom and must defeat a dark sorcerer.",
+        "Dragons rise again as an ancient prophecy awakens in the north.",
+    ],
+    "Romance": [
+        "Two strangers meet in a small cafe and find love against all odds.",
+        "A long-distance relationship is tested by secrets and time.",
+    ],
+    "Mystery": [
+        "A detective investigates a series of murders in a quiet town.",
+        "A missing diary reveals clues to an old family crime.",
+    ],
+    "Science Fiction": [
+        "A crew travels through a wormhole to save humanity from collapse.",
+        "An AI gains consciousness and changes the future of Earth.",
+    ],
+    "Self-Help": [
+        "A practical guide to build habits and improve focus every day.",
+        "Learn to manage anxiety with simple routines and mindset shifts.",
+    ],
+    "History": [
+        "An account of ancient empires and the wars that shaped the world.",
+        "A deep dive into the political revolutions of the 20th century.",
+    ],
+    "Business": [
+        "How startups scale products and build strong teams.",
+        "Negotiation tactics and leadership strategies for managers.",
+    ],
+    "Children": [
+        "A curious cat explores the city and learns about friendship.",
+        "A magical school adventure for kids with puzzles and fun.",
+    ],
+    "Horror": [
+        "A haunted house whispers at night, luring visitors inside.",
+        "A village faces a terrifying creature in the woods.",
+    ],
+    "Poetry": [
+        "A collection of poems about love, loss, and hope.",
+        "Minimalist poems inspired by nature and silence.",
+    ],
+}
+
+SAMPLE_DATA_DIR = os.path.join(os.path.dirname(__file__), "sample_data")
+BOOKS_CSV_PATH = os.path.join(SAMPLE_DATA_DIR, "books.csv")
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Recommendation Engine
+# ═══════════════════════════════════════════════════════════════════════════
+
+
+class RecommendationEngine:
+    """
+    Production wrapper around the full notebook recommendation pipeline.
+    Models are loaded lazily on first call or explicitly via ``load_models()``.
+    """
+
+    def __init__(self) -> None:
+        self.device: str = "cpu"
+        self.embed_model: Optional[SentenceTransformer] = None
+        self.zero_shot = None
+        self.books_df: Optional[pd.DataFrame] = None
+        self.book_embeddings: Optional[np.ndarray] = None
+        self.faiss_index: Optional[faiss.IndexFlatIP] = None
+        self.bookid_to_idx: Dict[int, int] = {}
+        self._loaded = False
+        # Per-user feed state (identical to notebook)
+        self.user_feed_state: Dict[int, Set[int]] = {}
+
+    # ------------------------------------------------------------------
+    # Model loading
+    # ------------------------------------------------------------------
+
+    def load_models(self) -> None:
+        """Load all AI models and build the FAISS index."""
+        if self._loaded:
+            return
+
+        self.device = get_device()
+        logger.info("Loading recommendation models …")
+
+        # 1. Zero-shot classifier — identical model to notebook
+        logger.info("Loading zero-shot classifier: joeddav/xlm-roberta-large-xnli")
+        zs_device = 0 if self.device == "cuda" else -1
+        self.zero_shot = hf_pipeline(
+            "zero-shot-classification",
+            model="joeddav/xlm-roberta-large-xnli",
+            device=zs_device,
+        )
+
+        # FP16 on CUDA for the zero-shot model
+        if self.device == "cuda":
+            try:
+                self.zero_shot.model.half()
+                logger.info("Zero-shot model converted to FP16")
+            except Exception as e:
+                logger.warning(f"Could not convert zero-shot to FP16: {e}")
+
+        # 2. SentenceTransformer — identical model to notebook
+        logger.info(
+            "Loading SentenceTransformer: "
+            "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
+        )
+        self.embed_model = SentenceTransformer(
+            "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
+            device=self.device,
+        )
+        if self.device == "cuda":
+            try:
+                self.embed_model.half()
+                logger.info("SentenceTransformer converted to FP16")
+            except Exception as e:
+                logger.warning(f"Could not convert embed model to FP16: {e}")
+
+        # 3. Load / generate books dataset
+        self.books_df = self._load_books()
+
+        # 4. Classify genres (zero-shot) — identical to notebook
+        self._classify_genres()
+
+        # 5. Build embeddings + FAISS index — identical to notebook
+        self._build_index()
+
+        self._loaded = True
+        logger.info(
+            f"Recommendation engine ready — "
+            f"{len(self.books_df)} books, FAISS dim={self.faiss_index.d}"
+        )
+
+    # ------------------------------------------------------------------
+    # Books dataset
+    # ------------------------------------------------------------------
+
+    def _load_books(self) -> pd.DataFrame:
+        """Load books from CSV or generate the default sample set."""
+        if os.path.exists(BOOKS_CSV_PATH):
+            logger.info(f"Loading books from {BOOKS_CSV_PATH}")
+            df = pd.read_csv(BOOKS_CSV_PATH)
+            required = {"book_id", "title", "author", "description"}
+            if not required.issubset(set(df.columns)):
+                raise ValueError(
+                    f"books.csv must contain columns {required}, "
+                    f"found {set(df.columns)}"
+                )
+            return df
+
+        logger.info("No books.csv found — generating sample data (seed=42)")
+        df = self._make_books(200)
+        os.makedirs(SAMPLE_DATA_DIR, exist_ok=True)
+        df.to_csv(BOOKS_CSV_PATH, index=False)
+        logger.info(f"Saved {len(df)} books to {BOOKS_CSV_PATH}")
+        return df
+
+    @staticmethod
+    def _make_books(n_books: int = 200) -> pd.DataFrame:
+        """Generate sample books — identical to notebook ``make_books``."""
+        np.random.seed(42)
+        rows = []
+        for i in range(1, n_books + 1):
+            g = np.random.choice(GENRES)
+            desc = np.random.choice(TEMPLATES[g])
+            title = f"{g} Book {i}"
+            author = f"Author {np.random.randint(1, 60)}"
+            rows.append([i, title, author, desc])
+        return pd.DataFrame(rows, columns=["book_id", "title", "author", "description"])
+
+    # ------------------------------------------------------------------
+    # Genre classification — identical to notebook
+    # ------------------------------------------------------------------
+
+    def classify_genre(self, text: str) -> Tuple[str, float]:
+        """Zero-shot genre classification — identical to notebook."""
+        out = self.zero_shot(text, candidate_labels=GENRES, multi_label=False)
+        return out["labels"][0], float(out["scores"][0])
+
+    def _classify_genres(self) -> None:
+        """Classify all books in the dataset — identical to notebook loop."""
+        if "genre" in self.books_df.columns and "genre_confidence" in self.books_df.columns:
+            logger.info("Genre columns already present — skipping classification")
+            return
+
+        logger.info("Classifying genres for all books …")
+        genres, scores = [], []
+        texts = (self.books_df["title"] + " | " + self.books_df["description"]).tolist()
+        for i, txt in enumerate(texts):
+            g, s = self.classify_genre(txt)
+            genres.append(g)
+            scores.append(s)
+            if (i + 1) % 50 == 0:
+                logger.info(f"  classified {i + 1}/{len(texts)} books")
+
+        self.books_df["genre"] = genres
+        self.books_df["genre_confidence"] = scores
+        # Persist updated CSV
+        self.books_df.to_csv(BOOKS_CSV_PATH, index=False)
+        logger.info("Genre classification complete")
+
+    # ------------------------------------------------------------------
+    # Embeddings + FAISS — identical to notebook
+    # ------------------------------------------------------------------
+
+    def _build_index(self) -> None:
+        """Build SentenceTransformer embeddings and FAISS index."""
+        self.books_df["text"] = (
+            "Title: " + self.books_df["title"]
+            + " | Author: " + self.books_df["author"]
+            + " | Genre: " + self.books_df["genre"]
+            + " | Description: " + self.books_df["description"]
+        )
+
+        logger.info("Encoding book embeddings …")
+        self.book_embeddings = self.embed_model.encode(
+            self.books_df["text"].tolist(),
+            batch_size=64,
+            show_progress_bar=True,
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+        ).astype("float32")
+
+        dim = self.book_embeddings.shape[1]
+        self.faiss_index = faiss.IndexFlatIP(dim)  # cosine (normalized)
+        self.faiss_index.add(self.book_embeddings)
+
+        self.bookid_to_idx = {
+            int(bid): i
+            for i, bid in enumerate(self.books_df["book_id"].tolist())
+        }
+
+        logger.info(
+            f"FAISS index built — embeddings {self.book_embeddings.shape}, "
+            f"ntotal={self.faiss_index.ntotal}"
+        )
+
+    # ------------------------------------------------------------------
+    # User interest ratios — identical to notebook
+    # ------------------------------------------------------------------
+
+    def user_interest_ratios(
+        self,
+        user_id: int,
+        interactions_df: pd.DataFrame,
+    ) -> Dict[str, float]:
+        """Compute weighted genre interest ratios — identical to notebook."""
+        u = interactions_df[interactions_df.user_id == user_id].merge(
+            self.books_df[["book_id", "genre"]], on="book_id", how="left"
+        )
+        if u.empty:
+            return {g: 1 / len(GENRES) for g in GENRES}
+
+        u["w"] = u["event_type"].map(EVENT_W).fillna(0.0)
+        s = u.groupby("genre")["w"].sum().reindex(GENRES, fill_value=0.0)
+
+        total = s.sum()
+        if total == 0:
+            return {g: 1 / len(GENRES) for g in GENRES}
+
+        return (s / total).to_dict()
+
+    # ------------------------------------------------------------------
+    # User vector — identical to notebook
+    # ------------------------------------------------------------------
+
+    def build_user_vector(
+        self,
+        user_id: int,
+        interactions_df: pd.DataFrame,
+    ) -> Tuple[Optional[np.ndarray], Set[int]]:
+        """Build weighted user embedding vector — identical to notebook."""
+        u = interactions_df[interactions_df.user_id == user_id]
+        if u.empty:
+            return None, set()
+
+        vecs: List[np.ndarray] = []
+        weights: List[float] = []
+        seen: Set[int] = set()
+
+        for _, row in u.iterrows():
+            bid = int(row["book_id"])
+            ev = row["event_type"]
+            if bid not in self.bookid_to_idx:
+                continue
+            w = EVENT_W.get(ev, 0.0)
+            if w == 0:
+                continue
+            vecs.append(self.book_embeddings[self.bookid_to_idx[bid]])
+            weights.append(w)
+            seen.add(bid)
+
+        if not vecs:
+            return None, seen
+
+        vecs_arr = np.array(vecs)
+        weights_arr = np.array(weights).reshape(-1, 1)
+
+        user_vec = np.sum(vecs_arr * weights_arr, axis=0) / (
+            np.sum(np.abs(weights_arr)) + 1e-9
+        )
+        user_vec = user_vec / (np.linalg.norm(user_vec) + 1e-9)
+        return user_vec.astype("float32"), seen
+
+    # ------------------------------------------------------------------
+    # Feed allocation — identical to notebook
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def allocate_feed(
+        ratios: Dict[str, float],
+        unseen_counts: Dict[str, int],
+        feed_size: int = 50,
+    ) -> Dict[str, int]:
+        """Proportional genre allocation — identical to notebook."""
+        alloc = {g: 0 for g in GENRES}
+        remaining = feed_size
+
+        # Target counts proportional to ratios
+        target = {
+            g: int(round(ratios.get(g, 0.0) * feed_size)) for g in GENRES
+        }
+
+        # Cap by availability
+        for g in GENRES:
+            alloc[g] = min(target[g], unseen_counts.get(g, 0))
+            remaining -= alloc[g]
+
+        # Distribute leftovers to best-ratio genres that still have items
+        while remaining > 0:
+            candidates = [
+                g for g in GENRES if alloc[g] < unseen_counts.get(g, 0)
+            ]
+            if not candidates:
+                break
+            g = max(candidates, key=lambda x: ratios.get(x, 0.0))
+            alloc[g] += 1
+            remaining -= 1
+
+        return alloc
+
+    # ------------------------------------------------------------------
+    # Mixed feed builder — identical to notebook
+    # ------------------------------------------------------------------
+
+    def build_mixed_feed(
+        self,
+        user_id: int,
+        interactions_df: pd.DataFrame,
+        feed_size: int = 50,
+        random_state: int = 42,
+    ) -> pd.DataFrame:
+        """Build a genre-balanced, similarity-ranked feed — identical to notebook."""
+        ratios = self.user_interest_ratios(user_id, interactions_df)
+
+        seen = set(
+            interactions_df.loc[
+                interactions_df.user_id == user_id, "book_id"
+            ]
+            .astype(int)
+            .tolist()
+        )
+        unseen_df = self.books_df[~self.books_df.book_id.isin(seen)].copy()
+
+        unseen_counts = (
+            unseen_df.groupby("genre")["book_id"]
+            .count()
+            .reindex(GENRES, fill_value=0)
+            .to_dict()
+        )
+        alloc = self.allocate_feed(ratios, unseen_counts, feed_size=feed_size)
+
+        parts: List[pd.DataFrame] = []
+        for g, k in alloc.items():
+            if k <= 0:
+                continue
+            g_df = unseen_df[unseen_df.genre == g]
+            if len(g_df) == 0:
+                continue
+            parts.append(
+                g_df.sample(n=min(k, len(g_df)), random_state=random_state)
+            )
+
+        if not parts:
+            return self.books_df.sample(feed_size, random_state=random_state)[
+                ["book_id", "title", "author", "genre"]
+            ]
+
+        feed = pd.concat(parts, ignore_index=True)
+
+        # Shuffle / ranking — identical to notebook
+        feed = feed.sample(frac=1.0, random_state=random_state).reset_index(
+            drop=True
+        )
+
+        user_vec, _ = self.build_user_vector(user_id, interactions_df)
+        if user_vec is not None:
+            idxs = [
+                self.bookid_to_idx[int(b)] for b in feed["book_id"].tolist()
+            ]
+            feed_vecs = self.book_embeddings[idxs]
+            feed["score"] = (feed_vecs @ user_vec).astype(float)
+            feed = feed.sort_values("score", ascending=False).reset_index(
+                drop=True
+            )
+
+        cols = ["book_id", "title", "author", "genre"]
+        if "score" in feed.columns:
+            cols.append("score")
+        return feed[cols]
+
+    # ------------------------------------------------------------------
+    # Paginated feed — identical to notebook
+    # ------------------------------------------------------------------
+
+    def get_next_feed_page(
+        self,
+        user_id: int,
+        interactions_df: pd.DataFrame,
+        page_size: int = 20,
+    ) -> pd.DataFrame:
+        """Return the next page of unseen recommendations — identical to notebook."""
+        shown = self.user_feed_state.get(user_id, set())
+
+        # Add temporary "view" interactions for already-shown books
+        if len(shown) > 0:
+            temp_rows = pd.DataFrame(
+                {
+                    "user_id": [user_id] * len(shown),
+                    "book_id": list(shown),
+                    "event_type": ["view"] * len(shown),
+                    "timestamp": [datetime.now().isoformat()] * len(shown),
+                }
+            )
+            temp_interactions = pd.concat(
+                [interactions_df, temp_rows], ignore_index=True
+            )
+        else:
+            temp_interactions = interactions_df
+
+        page = self.build_mixed_feed(
+            user_id,
+            temp_interactions,
+            feed_size=page_size,
+            random_state=np.random.randint(0, 10_000),
+        )
+
+        # Update shown state
+        self.user_feed_state[user_id] = shown.union(
+            set(page["book_id"].astype(int).tolist())
+        )
+        return page
+
+    def reset_user_feed(self, user_id: int) -> None:
+        """Clear pagination state for a user."""
+        self.user_feed_state.pop(user_id, None)
+
+    # ------------------------------------------------------------------
+    # Generate interactions from request payload
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def build_interactions_df(
+        user_id: int,
+        interactions: Optional[List[dict]] = None,
+        viewed_books: Optional[List[int]] = None,
+        favorite_genres: Optional[List[str]] = None,
+    ) -> pd.DataFrame:
+        """
+        Construct a pandas DataFrame of user interactions from the API
+        request payload.  This merges explicit interaction events,
+        viewed-book IDs (as implicit views), and favourite genres
+        (synthesised as likes for books in those genres).
+        """
+        rows: List[dict] = []
+        now_iso = datetime.now().isoformat()
+
+        # 1. Explicit interactions
+        if interactions:
+            for inter in interactions:
+                rows.append(
+                    {
+                        "user_id": user_id,
+                        "book_id": int(inter["book_id"]),
+                        "event_type": inter.get("event_type", "view"),
+                        "timestamp": inter.get("timestamp", now_iso),
+                    }
+                )
+
+        # 2. Viewed books → implicit "view" events
+        if viewed_books:
+            for bid in viewed_books:
+                rows.append(
+                    {
+                        "user_id": user_id,
+                        "book_id": int(bid),
+                        "event_type": "view",
+                        "timestamp": now_iso,
+                    }
+                )
+
+        if not rows:
+            return pd.DataFrame(
+                columns=["user_id", "book_id", "event_type", "timestamp"]
+            )
+
+        return pd.DataFrame(rows)
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# Module-level singleton
+# ═══════════════════════════════════════════════════════════════════════════
+
+engine = RecommendationEngine()

requirements.txt

@@ -0,0 +1,13 @@
+fastapi>=0.100.0
+uvicorn>=0.23.0
+python-multipart>=0.0.6
+transformers>=4.33.0
+torch>=2.0.0
+sentence-transformers>=2.2.0
+faiss-cpu>=1.7.4
+pandas>=2.0.0
+numpy>=1.24.0
+scikit-learn>=1.3.0
+accelerate>=0.23.0
+tqdm>=4.66.0
+pydantic>=2.0.0

sample_data/books.csv

@@ -0,0 +1,201 @@
+book_id,title,author,description
+1,Business Book 1,Author 29,Negotiation tactics and leadership strategies for managers.
+2,Children Book 2,Author 21,A curious cat explores the city and learns about friendship.
+3,Business Book 3,Author 19,Negotiation tactics and leadership strategies for managers.
+4,Business Book 4,Author 11,How startups scale products and build strong teams.
+5,Children Book 5,Author 36,A curious cat explores the city and learns about friendship.
+6,Children Book 6,Author 3,A magical school adventure for kids with puzzles and fun.
+7,History Book 7,Author 2,An account of ancient empires and the wars that shaped the world.
+8,Children Book 8,Author 30,A magical school adventure for kids with puzzles and fun.
+9,History Book 9,Author 21,A deep dive into the political revolutions of the 20th century.
+10,Fantasy Book 10,Author 58,Dragons rise again as an ancient prophecy awakens in the north.
+11,History Book 11,Author 44,An account of ancient empires and the wars that shaped the world.
+12,Horror Book 12,Author 27,"A haunted house whispers at night, luring visitors inside."
+13,Poetry Book 13,Author 28,Minimalist poems inspired by nature and silence.
+14,Mystery Book 14,Author 55,A missing diary reveals clues to an old family crime.
+15,Science Fiction Book 15,Author 57,An AI gains consciousness and changes the future of Earth.
+16,Mystery Book 16,Author 51,A detective investigates a series of murders in a quiet town.
+17,Business Book 17,Author 9,How startups scale products and build strong teams.
+18,Business Book 18,Author 4,Negotiation tactics and leadership strategies for managers.
+19,Horror Book 19,Author 14,A village faces a terrifying creature in the woods.
+20,Romance Book 20,Author 9,A long-distance relationship is tested by secrets and time.
+21,Poetry Book 21,Author 2,"A collection of poems about love, loss, and hope."
+22,Science Fiction Book 22,Author 47,An AI gains consciousness and changes the future of Earth.
+23,Business Book 23,Author 8,Negotiation tactics and leadership strategies for managers.
+24,Mystery Book 24,Author 17,A missing diary reveals clues to an old family crime.
+25,Science Fiction Book 25,Author 40,An AI gains consciousness and changes the future of Earth.
+26,Science Fiction Book 26,Author 6,An AI gains consciousness and changes the future of Earth.
+27,History Book 27,Author 4,A deep dive into the political revolutions of the 20th century.
+28,History Book 28,Author 18,An account of ancient empires and the wars that shaped the world.
+29,Poetry Book 29,Author 34,Minimalist poems inspired by nature and silence.
+30,Poetry Book 30,Author 36,Minimalist poems inspired by nature and silence.
+31,Children Book 31,Author 23,A magical school adventure for kids with puzzles and fun.
+32,Horror Book 32,Author 40,A village faces a terrifying creature in the woods.
+33,Self-Help Book 33,Author 45,Learn to manage anxiety with simple routines and mindset shifts.
+34,Romance Book 34,Author 53,Two strangers meet in a small cafe and find love against all odds.
+35,Children Book 35,Author 25,A magical school adventure for kids with puzzles and fun.
+36,Horror Book 36,Author 15,"A haunted house whispers at night, luring visitors inside."
+37,Fantasy Book 37,Author 7,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+38,Horror Book 38,Author 1,A village faces a terrifying creature in the woods.
+39,Children Book 39,Author 11,A magical school adventure for kids with puzzles and fun.
+40,Mystery Book 40,Author 8,A detective investigates a series of murders in a quiet town.
+41,Mystery Book 41,Author 33,A detective investigates a series of murders in a quiet town.
+42,Self-Help Book 42,Author 39,Learn to manage anxiety with simple routines and mindset shifts.
+43,Poetry Book 43,Author 28,"A collection of poems about love, loss, and hope."
+44,Business Book 44,Author 8,How startups scale products and build strong teams.
+45,Romance Book 45,Author 48,Two strangers meet in a small cafe and find love against all odds.
+46,Business Book 46,Author 24,How startups scale products and build strong teams.
+47,Self-Help Book 47,Author 44,A practical guide to build habits and improve focus every day.
+48,Children Book 48,Author 27,A magical school adventure for kids with puzzles and fun.
+49,Mystery Book 49,Author 35,A detective investigates a series of murders in a quiet town.
+50,Self-Help Book 50,Author 14,A practical guide to build habits and improve focus every day.
+51,Mystery Book 51,Author 5,A detective investigates a series of murders in a quiet town.
+52,Poetry Book 52,Author 14,"A collection of poems about love, loss, and hope."
+53,Business Book 53,Author 9,How startups scale products and build strong teams.
+54,Poetry Book 54,Author 13,Minimalist poems inspired by nature and silence.
+55,Mystery Book 55,Author 32,A detective investigates a series of murders in a quiet town.
+56,Business Book 56,Author 52,How startups scale products and build strong teams.
+57,Science Fiction Book 57,Author 37,An AI gains consciousness and changes the future of Earth.
+58,Business Book 58,Author 45,How startups scale products and build strong teams.
+59,Science Fiction Book 59,Author 32,A crew travels through a wormhole to save humanity from collapse.
+60,Business Book 60,Author 51,How startups scale products and build strong teams.
+61,History Book 61,Author 2,A deep dive into the political revolutions of the 20th century.
+62,Poetry Book 62,Author 57,"A collection of poems about love, loss, and hope."
+63,Self-Help Book 63,Author 28,Learn to manage anxiety with simple routines and mindset shifts.
+64,Science Fiction Book 64,Author 11,An AI gains consciousness and changes the future of Earth.
+65,Poetry Book 65,Author 28,"A collection of poems about love, loss, and hope."
+66,Horror Book 66,Author 33,"A haunted house whispers at night, luring visitors inside."
+67,Fantasy Book 67,Author 27,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+68,Horror Book 68,Author 13,A village faces a terrifying creature in the woods.
+69,Horror Book 69,Author 39,"A haunted house whispers at night, luring visitors inside."
+70,History Book 70,Author 27,A deep dive into the political revolutions of the 20th century.
+71,Horror Book 71,Author 37,A village faces a terrifying creature in the woods.
+72,Fantasy Book 72,Author 42,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+73,Children Book 73,Author 59,A curious cat explores the city and learns about friendship.
+74,History Book 74,Author 32,A deep dive into the political revolutions of the 20th century.
+75,Children Book 75,Author 52,A curious cat explores the city and learns about friendship.
+76,Fantasy Book 76,Author 49,Dragons rise again as an ancient prophecy awakens in the north.
+77,Poetry Book 77,Author 12,Minimalist poems inspired by nature and silence.
+78,Business Book 78,Author 3,Negotiation tactics and leadership strategies for managers.
+79,Fantasy Book 79,Author 49,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+80,Children Book 80,Author 59,A curious cat explores the city and learns about friendship.
+81,Fantasy Book 81,Author 2,Dragons rise again as an ancient prophecy awakens in the north.
+82,History Book 82,Author 37,An account of ancient empires and the wars that shaped the world.
+83,Fantasy Book 83,Author 19,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+84,Romance Book 84,Author 44,Two strangers meet in a small cafe and find love against all odds.
+85,Poetry Book 85,Author 6,Minimalist poems inspired by nature and silence.
+86,Business Book 86,Author 55,Negotiation tactics and leadership strategies for managers.
+87,Children Book 87,Author 17,A curious cat explores the city and learns about friendship.
+88,History Book 88,Author 5,A deep dive into the political revolutions of the 20th century.
+89,Science Fiction Book 89,Author 6,An AI gains consciousness and changes the future of Earth.
+90,History Book 90,Author 48,An account of ancient empires and the wars that shaped the world.
+91,Fantasy Book 91,Author 59,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+92,History Book 92,Author 29,A deep dive into the political revolutions of the 20th century.
+93,Mystery Book 93,Author 59,A missing diary reveals clues to an old family crime.
+94,Science Fiction Book 94,Author 26,A crew travels through a wormhole to save humanity from collapse.
+95,Mystery Book 95,Author 19,A detective investigates a series of murders in a quiet town.
+96,Science Fiction Book 96,Author 7,An AI gains consciousness and changes the future of Earth.
+97,Science Fiction Book 97,Author 33,A crew travels through a wormhole to save humanity from collapse.
+98,Children Book 98,Author 39,A magical school adventure for kids with puzzles and fun.
+99,Romance Book 99,Author 1,A long-distance relationship is tested by secrets and time.
+100,Horror Book 100,Author 50,"A haunted house whispers at night, luring visitors inside."
+101,Business Book 101,Author 30,How startups scale products and build strong teams.
+102,Poetry Book 102,Author 7,"A collection of poems about love, loss, and hope."
+103,Poetry Book 103,Author 57,Minimalist poems inspired by nature and silence.
+104,Science Fiction Book 104,Author 49,An AI gains consciousness and changes the future of Earth.
+105,Romance Book 105,Author 48,Two strangers meet in a small cafe and find love against all odds.
+106,Self-Help Book 106,Author 32,A practical guide to build habits and improve focus every day.
+107,Business Book 107,Author 41,How startups scale products and build strong teams.
+108,Mystery Book 108,Author 48,A detective investigates a series of murders in a quiet town.
+109,Mystery Book 109,Author 24,A missing diary reveals clues to an old family crime.
+110,History Book 110,Author 33,A deep dive into the political revolutions of the 20th century.
+111,Children Book 111,Author 11,A magical school adventure for kids with puzzles and fun.
+112,Fantasy Book 112,Author 36,Dragons rise again as an ancient prophecy awakens in the north.
+113,History Book 113,Author 20,A deep dive into the political revolutions of the 20th century.
+114,Mystery Book 114,Author 25,A missing diary reveals clues to an old family crime.
+115,Mystery Book 115,Author 29,A detective investigates a series of murders in a quiet town.
+116,Romance Book 116,Author 46,A long-distance relationship is tested by secrets and time.
+117,Romance Book 117,Author 54,A long-distance relationship is tested by secrets and time.
+118,Mystery Book 118,Author 41,A missing diary reveals clues to an old family crime.
+119,Science Fiction Book 119,Author 4,A crew travels through a wormhole to save humanity from collapse.
+120,Fantasy Book 120,Author 21,Dragons rise again as an ancient prophecy awakens in the north.
+121,Science Fiction Book 121,Author 8,An AI gains consciousness and changes the future of Earth.
+122,Business Book 122,Author 17,How startups scale products and build strong teams.
+123,Fantasy Book 123,Author 12,Dragons rise again as an ancient prophecy awakens in the north.
+124,Mystery Book 124,Author 55,A missing diary reveals clues to an old family crime.
+125,History Book 125,Author 30,A deep dive into the political revolutions of the 20th century.
+126,History Book 126,Author 45,A deep dive into the political revolutions of the 20th century.
+127,Mystery Book 127,Author 8,A missing diary reveals clues to an old family crime.
+128,Romance Book 128,Author 30,Two strangers meet in a small cafe and find love against all odds.
+129,Fantasy Book 129,Author 47,Dragons rise again as an ancient prophecy awakens in the north.
+130,Fantasy Book 130,Author 48,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+131,Mystery Book 131,Author 35,A missing diary reveals clues to an old family crime.
+132,Fantasy Book 132,Author 17,Dragons rise again as an ancient prophecy awakens in the north.
+133,Self-Help Book 133,Author 35,Learn to manage anxiety with simple routines and mindset shifts.
+134,Horror Book 134,Author 24,"A haunted house whispers at night, luring visitors inside."
+135,Fantasy Book 135,Author 53,Dragons rise again as an ancient prophecy awakens in the north.
+136,Mystery Book 136,Author 33,A missing diary reveals clues to an old family crime.
+137,Science Fiction Book 137,Author 21,A crew travels through a wormhole to save humanity from collapse.
+138,Business Book 138,Author 3,How startups scale products and build strong teams.
+139,Romance Book 139,Author 42,Two strangers meet in a small cafe and find love against all odds.
+140,History Book 140,Author 3,A deep dive into the political revolutions of the 20th century.
+141,Children Book 141,Author 24,A magical school adventure for kids with puzzles and fun.
+142,Romance Book 142,Author 47,A long-distance relationship is tested by secrets and time.
+143,History Book 143,Author 2,An account of ancient empires and the wars that shaped the world.
+144,Poetry Book 144,Author 26,Minimalist poems inspired by nature and silence.
+145,Fantasy Book 145,Author 33,Dragons rise again as an ancient prophecy awakens in the north.
+146,Horror Book 146,Author 54,"A haunted house whispers at night, luring visitors inside."
+147,Business Book 147,Author 42,How startups scale products and build strong teams.
+148,Business Book 148,Author 35,Negotiation tactics and leadership strategies for managers.
+149,Romance Book 149,Author 24,Two strangers meet in a small cafe and find love against all odds.
+150,Poetry Book 150,Author 57,"A collection of poems about love, loss, and hope."
+151,Science Fiction Book 151,Author 20,A crew travels through a wormhole to save humanity from collapse.
+152,Fantasy Book 152,Author 46,Dragons rise again as an ancient prophecy awakens in the north.
+153,Mystery Book 153,Author 15,A detective investigates a series of murders in a quiet town.
+154,Romance Book 154,Author 32,A long-distance relationship is tested by secrets and time.
+155,Business Book 155,Author 22,How startups scale products and build strong teams.
+156,Mystery Book 156,Author 58,A detective investigates a series of murders in a quiet town.
+157,History Book 157,Author 58,A deep dive into the political revolutions of the 20th century.
+158,History Book 158,Author 52,An account of ancient empires and the wars that shaped the world.
+159,Poetry Book 159,Author 15,Minimalist poems inspired by nature and silence.
+160,History Book 160,Author 37,An account of ancient empires and the wars that shaped the world.
+161,Fantasy Book 161,Author 53,Dragons rise again as an ancient prophecy awakens in the north.
+162,Self-Help Book 162,Author 4,A practical guide to build habits and improve focus every day.
+163,History Book 163,Author 32,An account of ancient empires and the wars that shaped the world.
+164,Science Fiction Book 164,Author 47,An AI gains consciousness and changes the future of Earth.
+165,Mystery Book 165,Author 40,A detective investigates a series of murders in a quiet town.
+166,Science Fiction Book 166,Author 13,An AI gains consciousness and changes the future of Earth.
+167,Romance Book 167,Author 42,A long-distance relationship is tested by secrets and time.
+168,Mystery Book 168,Author 56,A detective investigates a series of murders in a quiet town.
+169,Mystery Book 169,Author 58,A missing diary reveals clues to an old family crime.
+170,Business Book 170,Author 37,Negotiation tactics and leadership strategies for managers.
+171,Poetry Book 171,Author 23,"A collection of poems about love, loss, and hope."
+172,Horror Book 172,Author 53,A village faces a terrifying creature in the woods.
+173,Fantasy Book 173,Author 58,Dragons rise again as an ancient prophecy awakens in the north.
+174,Fantasy Book 174,Author 34,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+175,History Book 175,Author 25,A deep dive into the political revolutions of the 20th century.
+176,Children Book 176,Author 53,A curious cat explores the city and learns about friendship.
+177,Fantasy Book 177,Author 39,Dragons rise again as an ancient prophecy awakens in the north.
+178,Self-Help Book 178,Author 29,Learn to manage anxiety with simple routines and mindset shifts.
+179,Business Book 179,Author 12,How startups scale products and build strong teams.
+180,Poetry Book 180,Author 51,Minimalist poems inspired by nature and silence.
+181,Self-Help Book 181,Author 57,Learn to manage anxiety with simple routines and mindset shifts.
+182,Self-Help Book 182,Author 49,A practical guide to build habits and improve focus every day.
+183,Science Fiction Book 183,Author 12,A crew travels through a wormhole to save humanity from collapse.
+184,Poetry Book 184,Author 48,Minimalist poems inspired by nature and silence.
+185,Self-Help Book 185,Author 36,A practical guide to build habits and improve focus every day.
+186,Fantasy Book 186,Author 30,Dragons rise again as an ancient prophecy awakens in the north.
+187,Self-Help Book 187,Author 58,A practical guide to build habits and improve focus every day.
+188,Poetry Book 188,Author 5,Minimalist poems inspired by nature and silence.
+189,Science Fiction Book 189,Author 52,An AI gains consciousness and changes the future of Earth.
+190,Poetry Book 190,Author 19,Minimalist poems inspired by nature and silence.
+191,Poetry Book 191,Author 1,Minimalist poems inspired by nature and silence.
+192,Children Book 192,Author 45,A curious cat explores the city and learns about friendship.
+193,Science Fiction Book 193,Author 24,An AI gains consciousness and changes the future of Earth.
+194,Business Book 194,Author 49,Negotiation tactics and leadership strategies for managers.
+195,Science Fiction Book 195,Author 12,An AI gains consciousness and changes the future of Earth.
+196,Romance Book 196,Author 33,Two strangers meet in a small cafe and find love against all odds.
+197,Fantasy Book 197,Author 51,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+198,Self-Help Book 198,Author 3,Learn to manage anxiety with simple routines and mindset shifts.
+199,Fantasy Book 199,Author 40,A young hero discovers a hidden kingdom and must defeat a dark sorcerer.
+200,Poetry Book 200,Author 44,"A collection of poems about love, loss, and hope."

utils.py

@@ -0,0 +1,106 @@
+"""
+LITVISION Recommendation API — Utility Module
+===============================================
+Production logging, device management, CUDA OOM handling,
+and temp/cache cleanup helpers.
+"""
+
+import os
+import gc
+import logging
+import shutil
+from typing import Optional
+
+import torch
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+
+LOG_FORMAT = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    """Configure production-grade structured logging."""
+    logging.basicConfig(
+        level=level,
+        format=LOG_FORMAT,
+        datefmt=LOG_DATE_FORMAT,
+        force=True,
+    )
+    # Silence overly chatty third-party loggers
+    for noisy in ("transformers", "sentence_transformers", "faiss", "urllib3"):
+        logging.getLogger(noisy).setLevel(logging.WARNING)
+
+
+logger = logging.getLogger("litvision.recommendation")
+
+# ---------------------------------------------------------------------------
+# Device helpers
+# ---------------------------------------------------------------------------
+
+
+def get_device() -> str:
+    """Return the best available torch device string."""
+    if torch.cuda.is_available():
+        device = "cuda"
+        gpu_name = torch.cuda.get_device_name(0)
+        mem = torch.cuda.get_device_properties(0).total_mem / (1024 ** 3)
+        logger.info(f"CUDA device detected: {gpu_name} ({mem:.1f} GB)")
+    else:
+        device = "cpu"
+        logger.info("No CUDA device — running on CPU")
+    return device
+
+
+def safe_cuda_empty_cache() -> None:
+    """Clear CUDA cache if available; silently no-op on CPU."""
+    if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+        gc.collect()
+        logger.info("CUDA cache cleared")
+
+
+def handle_cuda_oom(exc: Exception) -> str:
+    """Handle a CUDA OOM exception: clear caches and return a user message."""
+    safe_cuda_empty_cache()
+    msg = (
+        "GPU out of memory during recommendation generation. "
+        "The CUDA cache has been cleared. Please retry with a smaller request."
+    )
+    logger.error(f"CUDA OOM: {exc}")
+    return msg
+
+# ---------------------------------------------------------------------------
+# Temp / cache cleanup
+# ---------------------------------------------------------------------------
+
+_TEMP_DIRS = [
+    os.environ.get("HF_HOME", "/tmp/huggingface"),
+]
+
+
+def cleanup_temp_files() -> None:
+    """Remove transient cache artefacts that are safe to delete."""
+    for d in _TEMP_DIRS:
+        cache_dir = os.path.join(d, "hub", ".locks")
+        if os.path.isdir(cache_dir):
+            try:
+                shutil.rmtree(cache_dir, ignore_errors=True)
+                logger.info(f"Cleaned lock dir: {cache_dir}")
+            except Exception as e:
+                logger.warning(f"Could not clean {cache_dir}: {e}")
+
+# ---------------------------------------------------------------------------
+# Validation helpers
+# ---------------------------------------------------------------------------
+
+
+def validate_positive_int(value: int, name: str, max_val: Optional[int] = None) -> int:
+    """Ensure *value* is a positive integer, optionally capped at *max_val*."""
+    if not isinstance(value, int) or value < 1:
+        raise ValueError(f"{name} must be a positive integer, got {value!r}")
+    if max_val is not None and value > max_val:
+        raise ValueError(f"{name} must be ≤ {max_val}, got {value}")
+    return value