initial commit

.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+{
+  "name": "Python 3",
+  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+  "image": "mcr.microsoft.com/devcontainers/python:1-3.11-bookworm",
+  "customizations": {
+    "codespaces": {
+      "openFiles": [
+        "README.md",
+        "src/book_recommender/apps/main_app.py"
+      ]
+    },
+    "vscode": {
+      "settings": {},
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance"
+      ]
+    }
+  },
+  "updateContentCommand": "[ -f packages.txt ] && sudo apt update && sudo apt upgrade -y && sudo xargs apt install -y <packages.txt; [ -f requirements.txt ] && pip3 install --user -r requirements.txt; pip3 install --user streamlit; echo '✅ Packages installed and Requirements met'",
+  "postAttachCommand": {
+    "server": "streamlit run src/book_recommender/apps/main_app.py --server.enableCORS false --server.enableXsrfProtection false"
+  },
+  "portsAttributes": {
+    "8501": {
+      "label": "Application",
+      "onAutoForward": "openPreview"
+    }
+  },
+  "forwardPorts": [
+    8501
+  ]
+}

.dockerignore

@@ -0,0 +1,31 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+pip-log.txt
+pip-delete-this-directory.txt
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.git
+.mypy_cache
+.pytest_cache
+.ruff_cache
+
+# Data (Except processed)
+data/raw
+data/feedback
+!data/processed
+
+# Frontend (Don't copy frontend code into backend image)
+frontend/
+node_modules/

.env.example

@@ -0,0 +1,10 @@
+# API Keys
+GROQ_API_KEY=your_groq_api_key_here
+GOOGLE_BOOKS_API_KEY=your_google_books_key_optional
+
+# App Config
+LOG_LEVEL=INFO
+PORT=8000
+PERSONALIZER_URL=http://localhost:8001 # Or your Hugging Face Space URL
+
+HF_DATASET_ID=nice-bill/book-recommender-data

.gitattributes

@@ -1,35 +1,4 @@
-*.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
+*.safetensors 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
+*.csv filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,85 @@
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+
+# Virtual Environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Data (but keep structure)
+data/raw/*.csv
+data/processed/*.parquet
+data/processed/*.npy
+data/processed/*.pkl
+data/processed/model_cache/
+data/processed/embedding_metadata.json
+!data/raw/.gitkeep
+!data/processed/.gitkeep
+
+# Logs
+logs/*.log
+!logs/.gitkeep
+
+# Environment
+.env
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+
+# CI/CD
+.github/workflows/*.log
+
+# Keep directory structure
+!**/.gitkeep
+
+# Existing rules from before
+docs/gemini.md
+scripts/Advanced Features To Consider.txt
+scripts/Book_Recommender_Project_SEC.txt
+
+.ruff_cache/
+.mypy_cache/
+
+run_analytics.bat
+run_api.bat
+run_app.bat

.python-version

@@ -0,0 +1 @@
+3.12

.streamlit/config.toml

@@ -0,0 +1,9 @@
+# .streamlit/config.toml
+
+[theme]
+base="dark"
+primaryColor="#FF4B4B"
+backgroundColor="#0E1117"
+secondaryBackgroundColor="#262730"
+textColor="#FAFAFA"
+font="sans serif"

DEPLOYMENT_NOTES.md

@@ -0,0 +1,69 @@
+# Deployment Notes & Configuration Guide
+
+*Created on: November 30, 2025*
+*Project Status: MVP Complete / Production Ready*
+
+This document serves as a "black box" recovery manual. If you return to this project in the future and need to redeploy it, follow these exact steps.
+
+---
+
+## 1. Environment Variables 
+These are the variables you MUST set in your cloud provider (Render/Vercel/Railway) for the app to function.
+
+### **Backend (FastAPI / Docker)**
+*Deployment Platform: Render (Web Service) or Railway*
+
+| Variable Name | Value (Example/Format) | Purpose |
+| :--- | :--- | :--- |
+| `HF_DATASET_ID` | `nice-bill/book-recommender-data` | **CRITICAL.** Tells the app where to download the embeddings/parquet files from Hugging Face. |
+| `GROQ_API_KEY` | `gsk_...` | Required for the "Why this match?" AI explanations. Get a key at [console.groq.com](https://console.groq.com). |
+| `HF_TOKEN` | `hf_...` | *(Optional)* Only required if you made your Hugging Face dataset PRIVATE. |
+| `PORT` | `8000` | (Render sets this automatically, but good to know). |
+
+### **Frontend (React / Vite)**
+*Deployment Platform: Vercel or Netlify*
+
+| Variable Name | Value (Example/Format) | Purpose |
+| :--- | :--- | :--- |
+| `VITE_API_URL` | `https://your-app-name.onrender.com` | Points the frontend to your live backend. **Do not add a trailing slash.** |
+
+---
+
+## 2. Build Settings
+
+### **Backend**
+*   **Runtime:** Docker
+*   **Dockerfile Path:** `docker/Dockerfile.backend`
+*   **Context Directory:** `.` (Root of the repo)
+*   **Start Command:** (Handled automatically by Dockerfile: `scripts/download_data.py && uvicorn ...`)
+
+### **Frontend**
+*   **Framework Preset:** Vite
+*   **Root Directory:** `frontend`
+*   **Build Command:** `npm run build`
+*   **Output Directory:** `dist`
+*   **Node Version:** 18.x or 20.x
+
+---
+
+## 3. "Cold Start" Recovery
+If the application is crashing on startup after a long time:
+
+1.  **Check Hugging Face Data:**
+    *   Go to: `https://huggingface.co/datasets/nice-bill/book-recommender-data`
+    *   Ensure these 4 files still exist: `books_cleaned.parquet`, `book_embeddings.npy`, `cluster_cache.pkl`, `embedding_metadata.json`.
+
+2.  **Check Groq API:**
+    *   API keys sometimes expire or quotas change. Generate a new one if the "Why this match?" feature fails.
+
+3.  **Local Run:**
+    *   Backend: `uv run src/book_recommender/api/main.py`
+    *   Frontend: `cd frontend && npm run dev`
+
+---
+
+## 4. Key Features Summary
+*   **Search:** Semantic search using `all-MiniLM-L6-v2` embeddings.
+*   **Explanation:** Uses Llama 3 (via Groq) to explain recommendations.
+*   **Data Layer:** Self-healing. Downloads data on boot if missing.
+*   **UI:** React + Tailwind + Lucide Icons. Features "Glassmorphism" and tactile hover effects.

Dockerfile.backend

@@ -0,0 +1,74 @@
+# Build Stage
+FROM python:3.10-slim AS builder
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    python3-dev \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+RUN pip install --no-cache-dir uv
+
+COPY requirements.backend.txt .
+
+# Create virtual environment and install dependencies
+ENV UV_HTTP_TIMEOUT=300
+RUN uv venv .venv && \
+    uv pip install --no-cache -r requirements.backend.txt --extra-index-url https://download.pytorch.org/whl/cpu
+
+# --- Runtime Stage ---
+FROM python:3.10-slim
+
+WORKDIR /app
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PATH="/app/.venv/bin:$PATH"
+ENV LANG=C.UTF-8
+ENV LC_ALL=C.UTF-8
+
+# Install runtime dependencies (curl for healthcheck)
+RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
+
+# Copy virtual environment from builder
+COPY --from=builder /app/.venv /app/.venv
+
+# Copy Scripts
+COPY scripts/ ./scripts/
+
+# Data & Model Baking
+ENV HF_HOME=/app/data/model_cache
+
+# Download Model (Bake into image)
+RUN /app/.venv/bin/python scripts/download_model.py
+
+# Download Data (Bake into image)
+RUN /app/.venv/bin/python scripts/download_data.py
+
+# Copy Code
+COPY src/ ./src/
+
+# Create directories and permissions
+RUN mkdir -p data/processed data/feedback logs
+#    addgroup --system app && adduser --system --group app && \
+#    chown -R app:app /app
+
+# USER app
+
+# Expose port
+EXPOSE 7860
+
+# Healthcheck
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:7860/health || exit 1
+
+# Run Command
+CMD ["/app/.venv/bin/uvicorn", "src.book_recommender.api.main:app", "--host", "0.0.0.0", "--port", "7860"]

Makefile

@@ -0,0 +1,53 @@
+.PHONY: install test lint format clean run-web run-api run-analytics docker-build docker-up
+
+install:
+	pip install -r requirements.txt
+	pip install -r requirements-dev.txt
+
+install-dev:
+	pip install -e ".[dev]"
+
+test:
+	pytest --cov=src --cov-report=html --cov-report=term
+
+lint:
+	ruff check src/ tests/
+	black --check src/ tests/
+	mypy src/
+
+format:
+	black src/ tests/
+	ruff check --fix src/ tests/
+
+clean:
+	find . -type d -name "__pycache__" -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	rm -rf .pytest_cache .coverage htmlcov dist build *.egg-info
+
+run-web:
+	PYTHONPATH=. python -m streamlit run src/book_recommender/apps/main_app.py
+
+run-api:
+	PYTHONPATH=. python -m uvicorn src.book_recommender.api.main:app --reload
+
+run-analytics:
+	PYTHONPATH=. python -m streamlit run src/book_recommender/apps/analytics_app.py --server.port=8502
+
+docker-build:
+	docker build -t bookfinder-ai:latest .
+
+docker-up:
+	docker-compose up
+
+docker-down:
+	docker-compose down
+
+help:
+	@echo "Available commands:"
+	@echo "  make install        - Install dependencies"
+	@echo "  make test          - Run tests with coverage"
+	@echo "  make lint          - Run linters"
+	@echo "  make format        - Format code"
+	@echo "  make run-web       - Start Streamlit app"
+	@echo "  make run-api       - Start FastAPI server"
+	@echo "  make docker-up     - Start all services with Docker"

README.md

@@ -9,4 +9,165 @@ license: mit
 short_description: Semantic Book Recommendation API powered by DeepShelf.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Serendipity (Book Discovery Platform)
+
+![Serendipity UI](https://img.shields.io/badge/Frontend-React_18-indigo) ![Backend](https://img.shields.io/badge/Backend-FastAPI-009688) ![Engine](https://img.shields.io/badge/AI_Engine-DeepShelf-blueviolet) ![Status](https://img.shields.io/badge/Status-Active-success)
+
+**Serendipity** is a next-generation book discovery platform that moves beyond keyword matching. It uses **Semantic Search** and **Vector Embeddings** to understand the "vibe", plot, and emotional resonance of a book.
+
+Powered by the **DeepShelf Engine**, it allows users to search for "a cyberpunk detective story set in Tokyo" and get results that match the *meaning*, not just the words.
+
+---
+
+## Key Features
+
+### The Experience (Frontend)
+*   **Semantic Search:** Type natural language queries like "sad books that feel like a rainy day."
+*   **Persona Picker (New!):** Experience the personalization engine by switching between pre-defined personas (e.g., "The Futurist", "The History Buff") to see how recommendations adapt to different reading histories.
+*   **Curated Clusters:** Explore automatically generated collections like "Space Opera", "Victorian Mystery", etc.
+*   **Explainability:** The AI explains *why* a book was recommended (e.g., "92% Plot Match", "Similar tone to your history").
+
+### The Engine (Backend)
+*   **Microservice Architecture:**
+    *   **Books API:** Handles business logic, product data, and frontend communication.
+    *   **Personalisation Engine:** A dedicated vector search service (FAISS + Transformers) deployed separately.
+*   **Performance:**
+    *   **IVF-PQ Indexing:** 100k+ books indexed with 48x compression (150MB -> 3MB) for <50ms query times.
+    *   **Hybrid Search:** Combines dense vector retrieval with metadata filtering.
+
+---
+
+## System Architecture
+
+The system consists of two main services and a frontend:
+
+```mermaid
+graph LR
+    User((User)) --> Frontend[React App]
+    Frontend --> BooksAPI[Books API (FastAPI)]
+    BooksAPI --> DB[(Book Catalog CSV)]
+    BooksAPI --> PersonaliseAPI[Personalisation Engine]
+    PersonaliseAPI --> VectorDB[(FAISS Index)]
+```
+
+*   **Frontend:** React, Tailwind, Vite (Static Build)
+*   **Books API:** Python, FastAPI (Deployed on Hugging Face Spaces)
+*   **Personalisation Engine:** Python, Sentence-Transformers, FAISS (Deployed on Hugging Face Spaces)
+
+---
+
+## Getting Started
+
+### Prerequisites
+*   **Python 3.10+** (Essential for dependency compatibility)
+*   **Node.js 18+**
+*   **Git**
+
+### 1. Clone the Repository
+```bash
+git clone <your-repo-url>
+cd books
+```
+
+### 2. Backend Setup (Books API)
+
+It is highly recommended to use `uv` for fast dependency management, but `pip` works too.
+
+```bash
+# 1. Create virtual environment
+pip install uv
+uv venv .venv
+
+# 2. Activate environment
+# Windows:
+.venv\Scripts\activate
+# Linux/Mac:
+source .venv/bin/activate
+
+# 3. Install dependencies
+uv pip install -r requirements.txt
+```
+
+**Configuration (`.env`):**
+Copy `.env.example` to `.env` and configure the URL of your personalisation service.
+```bash
+cp .env.example .env
+```
+In `.env`:
+```ini
+PORT=8000
+# URL of your deployed Personalisation Engine (or http://localhost:8001 if running locally)
+PERSONALIZER_URL=https://nice-bill-personalisation-engine.hf.space
+```
+
+**Run the API:**
+```bash
+python src/book_recommender/api/main.py
+# API will start at http://localhost:8000
+# Swagger Docs: http://localhost:8000/docs
+```
+
+### 3. Frontend Setup
+
+```bash
+cd frontend
+
+# 1. Install dependencies
+npm install
+
+# 2. Start Dev Server
+npm run dev
+```
+Open `http://localhost:5173` in your browser.
+
+---
+
+## Deployment Guide
+
+### Option 1: Docker (Recommended)
+
+The project includes a production-ready `Dockerfile` optimized for Hugging Face Spaces.
+
+```bash
+# Build the image
+docker build -t serendipity-api -f docker/Dockerfile.backend .
+
+# Run the container
+docker run -p 7860:7860 -e PERSONALIZER_URL=https://nice-bill-personalisation-engine.hf.space serendipity-api
+```
+
+### Option 2: Hugging Face Spaces
+
+1.  Create a new **Docker** Space on Hugging Face.
+2.  Connect it to your GitHub repository (or push manually).
+3.  Set the following **Variables** in the Space settings:
+    *   `PERSONALIZER_URL`: `https://nice-bill-personalisation-engine.hf.space` (or your engine's URL)
+4.  The Space will automatically build using `docker/Dockerfile.backend` and serve on port 7860.
+
+---
+
+## Project Structure
+
+```
+books/
+├── data/                   # Data storage
+│   ├── catalog/            # CSV/Parquet metadata
+│   └── embeddings_cache.npy # Vector data
+├── docker/                 # Docker configuration
+│   └── Dockerfile.backend
+├── frontend/               # React Application
+│   ├── src/
+│   └���─ public/
+├── scripts/                # Data processing scripts
+│   ├── download_data.py    # Fetches datasets
+│   └── prepare_100k_data.py # Raw data cleaning
+├── src/
+│   └── book_recommender/
+│       ├── api/            # FastAPI endpoints
+│       ├── ml/             # Machine Learning logic
+│       └── services/       # External service connectors
+└── tests/                  # Pytest suite
+```
+
+## License
+MIT License.

data/feedback/user_feedback.jsonl

@@ -0,0 +1,4 @@
+{"timestamp": "2025-12-02T20:22:43.042683", "query": "fantasy adventure", "book_id": "4", "book_title": "Unrelated Book", "book_authors": "Author C", "feedback": "positive", "session_id": "test_session_1"}
+{"timestamp": "2025-12-02T20:22:43.057774", "query": "sci-fi classic", "book_id": "5", "book_title": "Sci-Fi Classic", "book_authors": "Author D", "feedback": "negative", "session_id": "test_session_1"}
+{"timestamp": "2025-12-02T21:43:22.362305", "query": "Cyberpunk noir detective", "book_id": "70962", "book_title": "Murder in the Rue de Paradis", "book_authors": "Cara Black", "feedback": "positive", "session_id": null}
+{"timestamp": "2025-12-03T00:35:54.674627", "query": "Psychological horror 1920s", "book_id": "89722", "book_title": "Three Case Histories", "book_authors": "Sigmund Freud,Philip Rieff", "feedback": "positive", "session_id": null}

docs/ARCHITECTURE.md

@@ -0,0 +1,176 @@
+# Architecture Overview: DeepShelf
+
+This document provides a detailed overview of the BookFinder application's architecture, outlining its components, data flow, and key technology decisions.
+
+## System Overview
+
+BookFinder is a content-based book recommendation system that leverages natural language processing (NLP) and vector similarity search to help users discover books. It comprises a Streamlit-based web application for user interaction, a FastAPI service for programmatic access, and a suite of Python scripts for data processing and embedding generation.
+
+The core principle is to transform book descriptions into high-dimensional numerical vectors (embeddings) using a pre-trained sentence transformer model. These embeddings are then used to find semantically similar books or to cluster books into thematic collections.
+
+## Component Descriptions
+
+The system is structured into several modular components:
+
+1.  **Data Layer (`data/`)**: Stores raw, prepared, and processed data.
+    *   `data/raw/`: Original datasets (e.g., `goodreads_data.csv`).
+    *   `data/processed/`: Cleaned book metadata (`books_cleaned.parquet`), pre-computed embeddings (`book_embeddings.npy`), and embedding metadata (`embedding_metadata.json`).
+
+2.  **Scripts Layer (`scripts/`)**: Utility scripts for data handling and model preparation.
+    *   `prepare_goodreads_data.py`: Adapts raw data sources to a standardized format.
+    *   `download_model.py` (optional): For pre-downloading the sentence transformer model.
+
+3.  **Source Code Layer (`src/book_recommender/`)**: Contains the core logic of the application, organized into sub-packages.
+    *   **`src/book_recommender/core/`**: Core utilities and configurations.
+        *   `config.py`: Centralized configuration settings and constants.
+        *   `exceptions.py`: Custom exception definitions for error handling.
+        *   `logging_config.py`: Centralized logging configuration for the entire application.
+    *   **`src/book_recommender/data/`**: Data processing components.
+        *   `processor.py`: Handles data cleaning, normalization, deduplication, and feature engineering (e.g., creating `combined_text` for embeddings).
+    *   **`src/book_recommender/ml/`**: Machine Learning related components.
+        *   `embedder.py`: Manages the loading of the Sentence Transformer model and generation of embeddings for books and user queries. It uses `lru_cache` for efficient model loading.
+        *   `recommender.py`: Implements the core recommendation logic using a FAISS index for fast Approximate Nearest Neighbor (ANN) search on book embeddings.
+        *   `clustering.py`: Contains logic for K-Means clustering of book embeddings and generating descriptive names for these clusters based on common genres.
+        *   `explainability.py`: Provides rule-based explanations for recommendations, detailing contributing factors like genre, keywords, and author similarity.
+        *   `feedback.py`: Manages saving and retrieving user feedback on recommendations to a JSONL file.
+    *   `src/book_recommender/utils.py`: General utility functions, including book cover fetching from various APIs (Google Books, Open Library) and batch processing.
+
+4.  **User Interface Layer (`src/book_recommender/apps/`)**: Streamlit applications.
+    *   `main_app.py`: The main interactive web application where users can get book recommendations, browse by genre/query, view explanations, and provide feedback.
+    *   `analytics_app.py`: A separate Streamlit dashboard to visualize collected user feedback and system usage statistics.
+
+5.  **API Layer (`src/book_recommender/api/`)**: FastAPI application for programmatic access.
+    *   `main.py`: Defines the FastAPI application and its endpoints (recommendations, book listing, search, stats, clusters, explanations, feedback).
+    *   `models.py`: Pydantic models for request and response data validation and serialization.
+    *   `dependencies.py`: FastAPI dependency injection functions to manage and cache shared resources like the `BookRecommender` and embedding models.
+
+6.  **CI/CD (`.github/workflows/ci-cd.yml`)**: GitHub Actions workflow for automated testing and code quality checks.
+
+7.  **Containerization (`streamlit.Dockerfile`, `api.Dockerfile`, `analytics.Dockerfile`, `docker-compose.yml`)**: For packaging and orchestrating the application services.
+    *   `streamlit.Dockerfile`: Defines the build process for the main Streamlit application into a Docker image.
+    *   `api.Dockerfile`: Defines the build process for the FastAPI application into a Docker image.
+    *   `analytics.Dockerfile`: Defines the build process for the analytics Streamlit application into a Docker image.
+    *   `docker-compose.yml`: Orchestrates the `streamlit`, `api`, and `analytics` services for local development and deployment.
+
+## Data Flow
+
+The primary data flow for generating recommendations and user interaction is as follows:
+
+1.  **Raw Data Ingestion**: Raw CSV datasets (e.g., `goodreads_data.csv`) are placed in `data/raw/`.
+2.  **Data Preparation**: The `scripts/prepare_goodreads_data.py` script and `src/book_recommender/data/processor.py` clean, standardize, and deduplicate the raw data, saving it as `books_cleaned.parquet` in `data/processed/`.
+3.  **Embedding Generation**: `src/book_recommender/ml/embedder.py` loads `books_cleaned.parquet` and generates semantic embeddings for each book's `combined_text`, saving them as `book_embeddings.npy` in `data/processed/`.
+4.  **Application Startup**:
+    *   The `src/book_recommender/apps/main_app.py` (Streamlit) and `src/book_recommender/api/main.py` (FastAPI) applications load `books_cleaned.parquet` and `book_embeddings.npy` into memory.
+    *   `src/book_recommender/ml/recommender.py` initializes a FAISS index with these embeddings for fast similarity search.
+    *   `src/book_recommender/ml/clustering.py` generates book clusters and their names from the embeddings.
+5.  **User Interaction (Streamlit `src/book_recommender/apps/main_app.py`)**:
+    *   User inputs a natural language query or browses clusters.
+    *   If a query, `src/book_recommender/ml/embedder.py` generates an embedding for the query.
+    *   `src/book_recommender/ml/recommender.py` uses the query embedding (or a book's embedding from a title search) to find similar books.
+    *   `src/book_recommender/ml/explainability.py` generates reasons for recommendations.
+    *   `src/book_recommender/utils.py` fetches book cover images.
+    *   `src/book_recommender/ml/feedback.py` stores user feedback on recommendations.
+6.  **API Interaction (FastAPI `src/book_recommender/api/main.py`)**:
+    *   External clients send requests to API endpoints (e.g., `/recommend/query`, `/books`, `/feedback`).
+    *   `src/book_recommender/api/dependencies.py` ensures efficient loading and caching of `recommender` and `embedder` instances.
+    *   Requests are validated using Pydantic models (`src/book_recommender/api/models.py`).
+    *   Core logic in `src/book_recommender/` modules is invoked (e.g., `recommender.py`, `explainability.py`, `feedback.py`).
+    *   Responses are returned, adhering to defined Pydantic response models.
+    
+        **Example API Calls:**
+
+        ```bash
+        # Health Check
+        curl http://localhost:8000/health
+
+        # Recommend by Query
+        curl -X POST "http://localhost:8000/recommend/query" \
+          -H "Content-Type: application/json" \
+          -d '{
+            "query": "fantasy adventure with dragons",
+            "top_k": 5
+          }'
+
+        # List all Clusters
+        curl http://localhost:8000/clusters
+
+        # Submit Feedback
+        curl -X POST "http://localhost:8000/feedback" \
+          -H "Content-Type: application/json" \
+          -d '{
+            "query": "fantasy adventure with dragons",
+            "book_id": "example_book_id",
+            "feedback_type": "positive",
+            "session_id": "user_session_abc"
+          }'
+        ```
+
+7.  **Analytics (`src/book_recommender/apps/analytics_app.py`)**:
+    *   Loads accumulated feedback data from `data/feedback/user_feedback.jsonl` using `src/book_recommender/ml/feedback.py`.
+    *   Processes and visualizes statistics using Streamlit and Plotly.
+
+```mermaid
+graph TD
+    subgraph Data Flow & Processing
+        raw_data[Raw Data (CSV)] --> A(scripts/prepare_goodreads_data.py);
+        A --> B[books_prepared.csv];
+        B --> C{src/book_recommender/data/processor.py};
+        C --> D[books_cleaned.parquet];
+        D --contains text--> E{src/book_recommender/ml/embedder.py};
+        E --> F[book_embeddings.npy];
+    end
+
+    subgraph Application Runtime
+        G(src/book_recommender/apps/main_app.py - Streamlit UI) --loads--> D & F;
+        G --uses--> H(src/book_recommender/ml/recommender.py);
+        G --uses--> I(src/book_recommender/ml/embedder.py);
+        G --uses--> J(src/book_recommender/ml/clustering.py);
+        G --uses--> K(src/book_recommender/ml/explainability.py);
+        G --uses--> L(src/book_recommender/ml/feedback.py);
+        
+        M(src/book_recommender/api/main.py - FastAPI) --uses--> N(src/book_recommender/api/dependencies.py);
+        N --loads--> D & F;
+        N --uses--> H & I & J & K & L;
+
+        O(src/book_recommender/apps/analytics_app.py - Streamlit Dashboard) --loads--> P[user_feedback.jsonl];
+        P --via--> L;
+
+        User[User] --Interacts with--> G;
+        Client[External Client] --Interacts with--> M;
+    end
+
+    subgraph Utilities & Configuration
+        Q[src/book_recommender/core/config.py];
+        R[src/book_recommender/utils.py];
+        S[src/book_recommender/core/logging_config.py];
+    end
+
+    style raw_data fill:#f9f,stroke:#333,stroke-width:2px
+    style D fill:#ccf,stroke:#333,stroke-width:2px
+    style F fill:#ccf,stroke:#333,stroke-width:2px
+    style P fill:#fcc,stroke:#333,stroke-width:2px
+```
+
+## Technology Decisions
+
+*   **Python 3.10+**: Modern, versatile language.
+*   **Streamlit**: Chosen for rapid development of interactive web UIs with minimal frontend code. Its caching mechanisms (`@st.cache_resource`, `@st.cache_data`) are crucial for performance with ML models.
+*   **FastAPI**: Selected for building a high-performance, asynchronous API with automatic Pydantic-based data validation and Swagger/OpenAPI documentation.
+*   **Sentence-Transformers**: A powerful library for generating dense vector embeddings from text, suitable for semantic search.
+*   **FAISS**: An efficient library for similarity search and clustering of dense vectors, essential for scaling recommendations.
+*   **Pandas / NumPy**: Standard libraries for data manipulation and numerical operations.
+*   **Scikit-learn**: Used for traditional machine learning tasks like K-Means clustering.
+*   **Plotly Express**: For creating interactive and aesthetically pleasing visualizations in the analytics dashboard.
+*   **Pydantic**: Data validation and settings management using Python type hints, integral to FastAPI.
+*   **python-dotenv**: For managing environment variables, facilitating flexible configuration across environments.
+*   **GitHub Actions**: For Continuous Integration/Continuous Deployment (CI/CD), automating testing, linting, and Docker image builds.
+*   **Docker / Docker Compose**: For containerizing the application and orchestrating multi-service deployments, ensuring consistent environments.
+
+## Future Considerations
+
+*   **Data Version Control (DVC)**: Implement DVC for robust tracking of data and model versions, enhancing reproducibility in production.
+*   **Scalability**: For extremely large datasets, consider distributed FAISS indexes or cloud-native vector databases.
+*   **Advanced Explanations**: Explore more sophisticated XAI techniques beyond rule-based, potentially involving LLMs or specific feature attribution methods.
+*   **User Authentication**: For multi-user scenarios, integrate an authentication system (e.g., OAuth2, JWT).
+*   **Database Integration**: Replace JSONL feedback storage with a dedicated database (e.g., PostgreSQL) for more robust data management and querying.
+*   **Full UI Testing**: Implement UI tests using tools like Playwright or Selenium to ensure frontend consistency and functionality.

frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

frontend/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

frontend/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

frontend/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Crimson+Pro:ital,wght@0,400..800;1,400..800&family=Inter:wght@100..900&display=swap" rel="stylesheet">
+    <title>Serendipity</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "serendipity-web",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "axios": "^1.13.2",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.555.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router-dom": "^7.9.6",
+    "tailwind-merge": "^3.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "autoprefixer": "^10.4.22",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^3.4.17",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

frontend/src/App.css

@@ -0,0 +1,42 @@
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

frontend/src/App.tsx

@@ -0,0 +1,616 @@
+import { useState, useEffect, useRef } from 'react';
+import { 
+  Search, BookOpen, Loader2, X, Sparkles, LayoutGrid, 
+  CheckCircle, Moon, Sun, Info, Bookmark, ArrowLeft, Users
+} from 'lucide-react';
+import { api } from './api';
+import { Loader } from './Loader';
+import { BookCover } from './BookCover';
+import { BookCard } from './BookCard';
+import { DEMO_PERSONAS } from './data/personas';
+import type { RecommendationResult, BookCluster } from './types';
+
+function App() {
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<RecommendationResult[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [longLoading, setLongLoading] = useState(false); 
+  const [hasSearched, setHasSearched] = useState(false);
+  
+  // Modal State
+  const [selectedResult, setSelectedResult] = useState<RecommendationResult | null>(null);
+  const [historyStack, setHistoryStack] = useState<RecommendationResult[]>([]);
+  const [explanation, setExplanation] = useState<{ summary: string; details: Record<string, number> } | null>(null);
+  const [explaining, setExplaining] = useState(false);
+  const [showAbout, setShowAbout] = useState(false);
+  const modalRef = useRef<HTMLDivElement>(null);
+  
+  // Related Books State
+  const [relatedBooks, setRelatedBooks] = useState<RecommendationResult[]>([]);
+  const [loadingRelated, setLoadingRelated] = useState(false);
+
+  // Dynamic Clusters State
+  const [clusters, setClusters] = useState<BookCluster[]>([]);
+  const [loadingClusters, setLoadingClusters] = useState(true);
+
+  // Toast State
+  const [toast, setToast] = useState<{ message: string; visible: boolean } | null>(null);
+
+  // Settings / Theme State
+  const [darkMode, setDarkMode] = useState(false);
+  
+  // Personalization / History State
+  const [readHistory, setReadHistory] = useState<string[]>(() => {
+      try {
+          return JSON.parse(localStorage.getItem('bookfinder_read_history') || '[]');
+      } catch {
+          return [];
+      }
+  });
+
+  useEffect(() => {
+    if (selectedResult && modalRef.current) {
+      modalRef.current.scrollTop = 0;
+    }
+  }, [selectedResult]);
+
+  useEffect(() => {
+    const savedTheme = localStorage.getItem('bookfinder_theme_mode');
+    if (savedTheme) {
+        setDarkMode(savedTheme === 'dark');
+    } else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) {
+        setDarkMode(true);
+    }
+  }, []);
+
+  useEffect(() => {
+    localStorage.setItem('bookfinder_theme_mode', darkMode ? 'dark' : 'light');
+    if (darkMode) {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }, [darkMode]);
+
+  useEffect(() => {
+    localStorage.setItem('bookfinder_read_history', JSON.stringify(readHistory));
+  }, [readHistory]);
+
+  const toggleReadBook = (title: string) => {
+      setReadHistory(prev => {
+          if (prev.includes(title)) {
+              showToast("Removed from library");
+              return prev.filter(t => t !== title);
+          } else {
+              showToast("Added to library");
+              return [...prev, title];
+          }
+      });
+      triggerHaptic();
+  };
+
+  const handlePersonalize = async () => {
+      if (readHistory.length === 0) {
+          showToast("Mark some books as read first!");
+          return;
+      }
+      triggerHaptic();
+      setLoading(true);
+      setHasSearched(true);
+      setResults([]);
+      setQuery("✨ Selected for you");
+      
+      try {
+          const data = await api.recommendPersonalized(readHistory);
+          setResults(data);
+      } catch (err) {
+          console.error(err);
+          showToast("Failed to personalize. Try again.");
+      } finally {
+          setLoading(false);
+      }
+  };
+
+  const handlePersonaSelect = (persona: typeof DEMO_PERSONAS[0]) => {
+    triggerHaptic();
+    setReadHistory(persona.history);
+    showToast(`Switched to ${persona.name} mode`);
+    
+    setLoading(true);
+    setHasSearched(true);
+    setResults([]);
+    setQuery(`👤 Demo: ${persona.name}`);
+    
+    api.recommendPersonalized(persona.history)
+       .then(setResults)
+       .catch(err => {
+           console.error(err);
+           showToast("Failed to load persona.");
+       })
+       .finally(() => setLoading(false));
+  };
+
+  const toggleTheme = async (e: React.MouseEvent) => {
+    const isDark = !darkMode;
+    if (!(document as any).startViewTransition) {
+      setDarkMode(isDark);
+      return;
+    }
+    const x = e.clientX;
+    const y = e.clientY;
+    const endRadius = Math.hypot(Math.max(x, window.innerWidth - x), Math.max(y, window.innerHeight - y));
+    const transition = (document as any).startViewTransition(() => setDarkMode(isDark));
+    await transition.ready;
+    const clipPath = [`circle(0px at ${x}px ${y}px)`, `circle(${endRadius}px at ${x}px ${y}px)`];
+    document.documentElement.animate(
+      { clipPath: isDark ? clipPath : [...clipPath].reverse() },
+      { duration: 500, easing: 'ease-in-out', pseudoElement: isDark ? '::view-transition-new(root)' : '::view-transition-old(root)' }
+    );
+  };
+
+  const triggerHaptic = () => {
+    if (typeof navigator !== 'undefined' && navigator.vibrate) {
+      navigator.vibrate(10);
+    }
+  };
+
+  useEffect(() => {
+    const fetchClusters = async () => {
+      try {
+        const data = await api.getClusters();
+        setClusters(data.slice(0, 6));
+      } catch (err) {
+        console.error("Failed to fetch clusters", err);
+      } finally {
+        setLoadingClusters(false);
+      }
+    };
+    fetchClusters();
+  }, []);
+
+  const showToast = (message: string) => {
+    setToast({ message, visible: true });
+    setTimeout(() => setToast(null), 3000);
+  };
+
+  const handleSearch = async (e?: React.FormEvent) => {
+    if (e) e.preventDefault();
+    if (!query.trim()) return;
+    triggerHaptic();
+    setLoading(true);
+    setLongLoading(false);
+    setHasSearched(true);
+    setResults([]); 
+    const timer = setTimeout(() => setLongLoading(true), 3000);
+    try {
+      const data = await api.recommendByQuery(query);
+      setResults(data);
+    } catch (err) {
+      console.error(err);
+    } finally {
+      clearTimeout(timer);
+      setLoading(false);
+      setLongLoading(false);
+    }
+  };
+
+  const handleQuickSearch = (text: string) => {
+    setQuery(text);
+    triggerHaptic();
+    setLoading(true);
+    setLongLoading(false);
+    setHasSearched(true);
+    setResults([]);
+    const timer = setTimeout(() => setLongLoading(true), 3000);
+    api.recommendByQuery(text).then(setResults).catch(console.error).finally(() => {
+        clearTimeout(timer);
+        setLoading(false);
+        setLongLoading(false);
+    });
+  };
+
+  const handleFeedback = async (bookId: string, type: 'positive' | 'negative') => {
+      triggerHaptic();
+      try {
+        await api.submitFeedback(query, bookId, type);
+        showToast(type === 'positive' ? "Thanks! We'll show more like this." : "Thanks! We'll tune our results.");
+      } catch (err) {
+        console.error(err);
+      }
+  };
+
+  const handleReadMore = async (result: RecommendationResult, isDrillingDown = false) => {
+    triggerHaptic();
+    if (isDrillingDown && selectedResult) {
+        setHistoryStack(prev => [...prev, selectedResult]);
+    } else if (!isDrillingDown) {
+        setHistoryStack([]);
+    }
+    setSelectedResult(result);
+    setExplaining(true);
+    setExplanation(null);
+    setRelatedBooks([]);
+    setLoadingRelated(true);
+    try {
+      const [expl, related] = await Promise.allSettled([
+        api.explainRecommendation(query || result.book.title, result.book, result.similarity_score),
+        api.getRelatedBooks(result.book.title)
+      ]);
+      if (expl.status === 'fulfilled') setExplanation(expl.value);
+      if (related.status === 'fulfilled') setRelatedBooks(related.value);
+    } catch (err) {
+      console.error("Failed to fetch details", err);
+    } finally {
+      setExplaining(false);
+      setLoadingRelated(false);
+    }
+  };
+  
+  const handleBack = () => {
+      triggerHaptic();
+      if (historyStack.length > 0) {
+          const prev = historyStack[historyStack.length - 1];
+          setHistoryStack(curr => curr.slice(0, -1));
+          setSelectedResult(prev);
+          setRelatedBooks([]);
+          setExplanation(null);
+          setLoadingRelated(true);
+          setExplaining(true);
+          Promise.allSettled([
+            api.explainRecommendation(query || prev.book.title, prev.book, prev.similarity_score),
+            api.getRelatedBooks(prev.book.title)
+          ]).then(([expl, related]) => {
+             if (expl.status === 'fulfilled') setExplanation(expl.value);
+             if (related.status === 'fulfilled') setRelatedBooks(related.value);
+             setExplaining(false);
+             setLoadingRelated(false);
+          });
+      }
+  };
+
+  const closeModal = () => {
+    setSelectedResult(null);
+    setHistoryStack([]);
+    setExplanation(null);
+    setRelatedBooks([]);
+  };
+
+  const handleClusterClick = (clusterName: string) => {
+    triggerHaptic();
+    setQuery(clusterName);
+    setLoading(true);
+    setHasSearched(true);
+    setResults([]);
+    api.recommendByQuery(clusterName).then(setResults).catch(console.error).finally(() => setLoading(false));
+  };
+
+  return (
+    <div className={`min-h-screen font-sans selection:bg-indigo-500 selection:text-white transition-colors duration-300 ${darkMode ? 'bg-zinc-950 text-zinc-100' : 'bg-zinc-50 text-zinc-900'}`}>
+      
+      <div className="fixed inset-0 -z-10 bg-zinc-50 dark:bg-zinc-950 transition-colors duration-500" />
+      <div className="fixed inset-0 -z-10 bg-noise opacity-[0.04] dark:opacity-[0.06] pointer-events-none mix-blend-overlay" />
+      <div className="fixed inset-0 -z-10 bg-dot-pattern pointer-events-none" />
+      <div className="fixed inset-0 -z-10 bg-gradient-to-br from-rose-100/40 via-white to-indigo-100/40 dark:from-indigo-950/30 dark:via-zinc-950 dark:to-purple-950/30 pointer-events-none" />
+
+      {toast && (
+        <div className="fixed bottom-6 right-6 bg-zinc-900 dark:bg-zinc-800 text-white px-4 py-3 rounded-xl shadow-2xl flex items-center gap-3 animate-slide-up z-[60] border border-zinc-800 dark:border-zinc-700">
+          <CheckCircle className="w-5 h-5 text-green-400" />
+          <span className="text-sm font-medium">{toast.message}</span>
+        </div>
+      )}
+
+      <header className="sticky top-0 z-30 border-b border-zinc-200/50 dark:border-zinc-800/50 bg-white/70 dark:bg-zinc-950/70 backdrop-blur-xl">
+        <div className="max-w-3xl mx-auto px-6 h-16 flex items-center justify-between">
+                    <div className="flex items-center gap-3 group cursor-pointer" onClick={() => setActiveView('search')}>
+                      <div className="relative">
+                        <div className="absolute -inset-1 bg-indigo-500/20 rounded-full blur-sm group-hover:bg-indigo-500/30 transition-colors"></div>
+                        <BookOpen className="w-8 h-8 text-indigo-600 dark:text-indigo-400 relative" />
+                      </div>
+                      <span className="text-zinc-900 dark:text-white font-serif text-xl tracking-normal">Serendipity</span>
+                    </div>
+          
+          <div className="flex items-center gap-2">
+             <button onClick={toggleTheme} className="p-2 rounded-full hover:bg-black/5 dark:hover:bg-white/10 transition-colors text-zinc-500 dark:text-zinc-400">
+                {darkMode ? <Sun className="w-5 h-5" /> : <Moon className="w-5 h-5" />}
+             </button>
+             <button onClick={() => setShowAbout(true)} className="p-2 ml-2 rounded-full hover:bg-black/5 dark:hover:bg-white/10 transition-colors text-zinc-500 dark:text-zinc-400">
+                <Info className="w-5 h-5" />
+             </button>
+          </div>
+        </div>
+      </header>
+
+      <main className="max-w-3xl mx-auto px-6 pb-24 relative z-10">
+        <div className={`transition-all duration-700 ease-out ${hasSearched ? 'py-10' : 'py-28'}`}>
+          {!hasSearched && (
+            <div className="text-center mb-10 animate-fade-in">
+              <h1 className="text-5xl sm:text-7xl font-black tracking-tighter mb-6 text-zinc-900 dark:text-white font-serif">
+                Find your next<br/>
+                <span className="text-indigo-600 dark:text-indigo-500 italic">obsession.</span>
+              </h1>
+              <p className="text-lg max-w-md mx-auto text-zinc-500 dark:text-zinc-400 leading-relaxed font-medium">
+                Describe the vibe, plot, or character you're looking for.
+              </p>
+            </div>
+          )}
+          
+          <form onSubmit={handleSearch} className="relative max-w-xl mx-auto z-10">
+            <input
+              type="text"
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              placeholder="e.g. A sci-fi thriller about AI consciousness..."
+              className="relative w-full bg-white dark:bg-zinc-900 border-2 border-zinc-200 dark:border-zinc-800 focus:border-indigo-500 dark:focus:border-indigo-500 rounded-full py-4 pl-6 pr-24 text-lg outline-none transition-all placeholder:text-zinc-400 dark:placeholder:text-zinc-600 shadow-xl shadow-zinc-200/50 dark:shadow-black/50 text-zinc-900 dark:text-white"
+              autoFocus
+            />
+            {query && (
+              <button
+                type="button"
+                onClick={() => { setQuery(''); triggerHaptic(); setResults([]); }}
+                className="absolute right-14 top-1/2 -translate-y-1/2 p-2 text-zinc-400 hover:text-zinc-600 dark:hover:text-zinc-200 transition-colors"
+              >
+                <X className="w-5 h-5" />
+              </button>
+            )}
+            <button 
+              type="submit"
+              disabled={loading || !query.trim()}
+              className="absolute right-2 top-2 p-2.5 bg-indigo-600 text-white rounded-full hover:bg-indigo-700 disabled:opacity-50 disabled:hover:bg-indigo-600 transition-all active:scale-90 shadow-lg shadow-indigo-500/30"
+              onClick={triggerHaptic}
+            >
+              {loading ? <Loader2 className="w-5 h-5 animate-spin" /> : <Search className="w-5 h-5" />}
+            </button>
+          </form>
+          
+          {loading && longLoading && (
+            <div className="text-center mt-4 animate-fade-in">
+              <p className="text-sm font-medium text-indigo-600 dark:text-indigo-400 flex items-center justify-center gap-2">
+                <Loader2 className="w-3 h-3 animate-spin" />
+                Waking up... this might take a moment 😴
+              </p>
+            </div>
+          )}
+
+          {!hasSearched && !loading && (
+            <div className="mt-8 flex flex-col items-center gap-6 animate-fade-in animation-delay-200">
+                <div className="flex flex-wrap justify-center gap-3">
+                {[
+                    "Cyberpunk noir detective",
+                    "Cozy cottagecore mystery",
+                    "Space opera with politics",
+                    "Psychological horror 1920s"
+                ].map((prompt) => (
+                    <button key={prompt} onClick={() => handleQuickSearch(prompt)} className="px-4 py-2 rounded-full text-sm font-medium bg-white dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800 text-zinc-600 dark:text-zinc-400 hover:border-indigo-400 dark:hover:border-indigo-500 hover:text-indigo-600 dark:hover:text-indigo-400 transition-all shadow-sm hover:shadow-md active:scale-95">
+                    ✨ {prompt}
+                    </button>
+                ))}
+                </div>
+
+                {/* Demo Personas */}
+                <div className="w-full max-w-2xl mt-4 p-6 bg-zinc-50/50 dark:bg-zinc-900/30 rounded-3xl border border-zinc-100 dark:border-zinc-800/50 backdrop-blur-sm">
+                    <div className="flex items-center justify-center gap-2 text-xs uppercase tracking-widest font-bold mb-4 text-zinc-400 dark:text-zinc-600">
+                        <Users className="w-4 h-4" />
+                        Try a Demo Persona
+                    </div>
+                    <div className="grid grid-cols-2 sm:grid-cols-4 gap-3">
+                        {DEMO_PERSONAS.map(persona => (
+                            <button
+                                key={persona.id}
+                                onClick={() => handlePersonaSelect(persona)}
+                                className="flex flex-col items-center gap-2 p-3 bg-white dark:bg-zinc-900 rounded-xl border border-zinc-200 dark:border-zinc-800 hover:border-indigo-400 dark:hover:border-indigo-500 hover:shadow-lg transition-all active:scale-95 group"
+                            >
+                                <span className="text-2xl group-hover:scale-110 transition-transform">{persona.emoji}</span>
+                                <div className="text-center">
+                                    <div className="text-xs font-bold text-zinc-900 dark:text-zinc-100">{persona.name}</div>
+                                    <div className="text-[10px] text-zinc-500 dark:text-zinc-500 leading-tight mt-1 line-clamp-2">{persona.description}</div>
+                                </div>
+                            </button>
+                        ))}
+                    </div>
+                </div>
+
+                {/* Personalization Trigger */}
+                {readHistory.length > 0 && (
+                    <button 
+                        onClick={handlePersonalize}
+                        className="mt-2 flex items-center gap-2 px-6 py-3 bg-gradient-to-r from-indigo-600 to-purple-600 text-white rounded-full font-bold text-sm shadow-xl shadow-indigo-500/20 hover:scale-105 active:scale-95 transition-all"
+                    >
+                        <Bookmark className="w-4 h-4 fill-white/20" />
+                        Recommend based on my {readHistory.length} reads
+                    </button>
+                )}
+            </div>
+          )}
+
+          {!hasSearched && (
+            <div className="mt-20 animate-slide-up animation-delay-500">
+              <div className="flex items-center justify-center gap-2 text-xs uppercase tracking-widest font-bold mb-8 text-zinc-400 dark:text-zinc-600">
+                 <LayoutGrid className="w-4 h-4" />
+                 Curated Collections
+              </div>
+              
+              {loadingClusters ? (
+                <div className="grid grid-cols-2 sm:grid-cols-3 gap-4">
+                   {[1,2,3,4,5,6].map(i => (
+                     <div key={i} className="h-32 bg-white dark:bg-zinc-900 rounded-2xl border border-zinc-200 dark:border-zinc-800 animate-pulse" />
+                   ))}
+                </div>
+              ) : (
+                <div className="grid grid-cols-2 sm:grid-cols-3 gap-4">
+                  {clusters.map(cluster => (
+                    <button 
+                      key={cluster.id}
+                      onClick={() => handleClusterClick(cluster.name)}
+                      className="text-left p-4 bg-white dark:bg-zinc-900/50 hover:bg-zinc-50 dark:hover:bg-zinc-800 border border-zinc-200 dark:border-zinc-800 hover:border-indigo-300 dark:hover:border-indigo-500/50 transition-all rounded-2xl group active:scale-95 duration-200 shadow-sm hover:shadow-md"
+                    >
+                      <h3 className="font-bold text-zinc-800 dark:text-zinc-200 group-hover:text-indigo-600 dark:group-hover:text-indigo-400 truncate transition-colors">{cluster.name}</h3>
+                      <p className="text-xs text-zinc-500 dark:text-zinc-500 mt-1 font-medium">{cluster.size} books</p>
+                      
+                      <div className="flex mt-4 -space-x-3 overflow-hidden px-1 pb-1">
+                        {cluster.top_books.slice(0, 3).map((book, i) => (
+                          <div key={book.id} className={`w-8 h-12 bg-zinc-200 dark:bg-zinc-800 rounded-sm shadow-md border border-white/50 dark:border-zinc-700 relative z-${3-i} transform transition-transform group-hover:-translate-y-1 duration-300 overflow-hidden`} style={{transitionDelay: `${i*50}ms`}}>
+                             <BookCover src={book.cover_image_url} title={book.title} author={book.authors[0]} className="w-full h-full" />
+                          </div>
+                        ))}
+                      </div>
+                    </button>
+                  ))}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+
+        <div className="space-y-6 min-h-[50vh]">
+          {loading && results.length === 0 ? (
+             <div className="animate-fade-in pt-10">
+                <Loader />
+             </div>
+          ) : (
+            results.map((result) => (
+              <BookCard 
+                key={result.book.id} 
+                result={result} 
+                isRead={readHistory.includes(result.book.title)}
+                onToggleRead={toggleReadBook}
+                onClick={() => handleReadMore(result)} 
+                onFeedback={handleFeedback} 
+              />
+            ))
+          )}
+        </div>
+
+        {hasSearched && results.length === 0 && !loading && (
+          <div className="text-center text-zinc-400 dark:text-zinc-600 py-12">
+            No books found matching that description.
+          </div>
+        )}
+      </main>
+
+      {selectedResult && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center p-4 sm:p-6">
+          <div className="absolute inset-0 bg-zinc-900/60 dark:bg-black/80 backdrop-blur-sm transition-opacity" onClick={closeModal} />
+          <div ref={modalRef} className="bg-white dark:bg-zinc-900 rounded-3xl shadow-2xl w-full max-w-2xl max-h-[90vh] overflow-y-auto relative animate-slide-up z-50 no-scrollbar border border-zinc-200 dark:border-zinc-800">
+            <button onClick={() => { triggerHaptic(); closeModal(); }} className="absolute right-4 top-4 p-2 bg-white/80 dark:bg-black/50 backdrop-blur hover:bg-zinc-100 dark:hover:bg-zinc-800 text-zinc-500 dark:text-zinc-400 rounded-full transition-colors z-10 shadow-sm">
+              <X className="w-5 h-5" />
+            </button>
+            {historyStack.length > 0 && (
+                <button onClick={handleBack} className="absolute left-4 top-4 p-2 bg-white/80 dark:bg-black/50 backdrop-blur hover:bg-zinc-100 dark:hover:bg-zinc-800 text-zinc-500 dark:text-zinc-400 rounded-full transition-colors z-10 shadow-sm flex items-center gap-1 pr-3">
+                    <ArrowLeft className="w-5 h-5" />
+                    <span className="text-xs font-bold">Back</span>
+                </button>
+            )}
+            <div className="grid sm:grid-cols-[220px_1fr] gap-0 sm:gap-8">
+               <div className="bg-zinc-100 dark:bg-zinc-800 h-64 sm:h-auto sm:aspect-[2/3] relative overflow-hidden">
+                  <BookCover src={selectedResult.book.cover_image_url} title={selectedResult.book.title} author={selectedResult.book.authors[0]} className="w-full h-full" />
+                  <div className="absolute inset-0 bg-gradient-to-t from-black/60 to-transparent sm:hidden"></div>
+                  <h2 className="absolute bottom-4 left-4 right-4 text-2xl font-bold font-serif text-white sm:hidden leading-tight shadow-black drop-shadow-md">{selectedResult.book.title}</h2>
+               </div>
+               <div className="p-6 sm:pl-0 sm:py-8 space-y-6">
+                  <div className="hidden sm:block">
+                    <h2 className="text-3xl sm:text-4xl font-bold font-serif leading-tight mb-2 text-zinc-900 dark:text-white">{selectedResult.book.title}</h2>
+                    <p className="text-lg text-zinc-500 dark:text-zinc-400 font-medium">by {selectedResult.book.authors.join(', ')}</p>
+                  </div>
+                  <div className="prose prose-zinc dark:prose-invert prose-sm max-w-none leading-relaxed">
+                    <p>{selectedResult.book.description}</p>
+                  </div>
+                  <div className="bg-indigo-50/50 dark:bg-indigo-900/20 rounded-2xl p-5 border border-indigo-100 dark:border-indigo-500/20">
+                    <div className="flex items-center gap-2 mb-3 text-indigo-600 dark:text-indigo-400 font-bold text-xs uppercase tracking-widest">
+                      <Sparkles className="w-4 h-4" />
+                      Why this match?
+                    </div>
+                    {explaining ? (
+                      <div className="flex items-center gap-2 text-indigo-400 dark:text-indigo-300 text-sm font-medium">
+                        <Loader2 className="w-4 h-4 animate-spin" />
+                        Reading your mind...
+                      </div>
+                    ) : explanation ? (
+                      <div className="space-y-3">
+                        <p className="text-sm text-zinc-800 dark:text-zinc-200 font-medium leading-relaxed">{explanation.summary}</p>
+                        <div className="flex flex-wrap gap-2">
+                          {Object.entries(explanation.details).map(([key, val]) => (
+                            <span key={key} className="text-[10px] font-bold uppercase bg-white dark:bg-zinc-800 border border-indigo-100 dark:border-indigo-500/30 px-2 py-1 rounded-md text-indigo-600 dark:text-indigo-300 shadow-sm">
+                              {key} {val}%
+                            </span>
+                          ))}
+                        </div>
+                      </div>
+                    ) : (
+                       <p className="text-sm text-red-400">Could not generate explanation.</p>
+                    )}
+                  </div>
+                  <div className="pt-4 flex flex-col sm:flex-row gap-3">
+                    <a href={`https://www.goodreads.com/search?q=${encodeURIComponent(selectedResult.book.title + ' ' + selectedResult.book.authors.join(', '))}`} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-2 px-6 py-3 bg-white dark:bg-zinc-800 text-zinc-900 dark:text-white border border-zinc-200 dark:border-zinc-700 font-bold rounded-full hover:bg-zinc-50 dark:hover:bg-zinc-700 hover:scale-105 transition-all active:scale-95 flex-1 justify-center shadow-sm" onClick={triggerHaptic}>
+                      <BookOpen className="w-4 h-4" />
+                      Goodreads
+                    </a>
+                    <a href={`https://www.google.com/search?q=${encodeURIComponent(selectedResult.book.title + ' by ' + selectedResult.book.authors.join(', '))}`} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-2 px-6 py-3 bg-zinc-900 dark:bg-indigo-600 text-white font-bold rounded-full hover:bg-black dark:hover:bg-indigo-700 hover:scale-105 transition-all active:scale-95 flex-1 justify-center shadow-xl shadow-zinc-900/20 dark:shadow-indigo-500/30" onClick={triggerHaptic}>
+                      <Search className="w-4 h-4" />
+                      Google
+                    </a>
+                  </div>
+                  <div className="pt-8 border-t border-dashed border-zinc-200 dark:border-zinc-800">
+                    <h3 className="text-xs font-bold text-zinc-400 dark:text-zinc-500 mb-4 uppercase tracking-widest">You might also like</h3>
+                    {loadingRelated ? (
+                        <div className="flex gap-4">
+                            {[1, 2, 3].map(i => (
+                                <div key={i} className="w-32 h-48 bg-zinc-100 dark:bg-zinc-800 rounded-xl animate-pulse" />
+                            ))}
+                        </div>
+                    ) : (
+                        <div className="grid grid-cols-2 sm:grid-cols-3 gap-4">
+                            {relatedBooks.map(rel => (
+                                <div key={rel.book.id} onClick={() => handleReadMore(rel)} className="group cursor-pointer active:scale-95 transition-transform">
+                                    <div className="aspect-[2/3] bg-zinc-100 dark:bg-zinc-800 rounded-xl overflow-hidden mb-2 relative shadow-sm group-hover:shadow-md transition-all border border-zinc-100 dark:border-zinc-700">
+                                        <BookCover src={rel.book.cover_image_url} title={rel.book.title} author={rel.book.authors[0]} className="w-full h-full group-hover:scale-105 transition-transform duration-500" />
+                                    </div>
+                                    <h4 className="text-xs font-bold leading-tight text-zinc-800 dark:text-zinc-200 group-hover:text-indigo-600 dark:group-hover:text-indigo-400 transition-colors line-clamp-1">{rel.book.title}</h4>
+                                    <p className="text-[10px] text-zinc-400 dark:text-zinc-500 mt-0.5 truncate">{rel.book.authors[0]}</p>
+                                </div>
+                            ))}
+                        </div>
+                    )}
+                  </div>
+               </div>
+            </div>
+          </div>
+        </div>
+      )}
+
+      {showAbout && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+          <div className="absolute inset-0 bg-zinc-900/60 dark:bg-black/80 backdrop-blur-sm transition-opacity" onClick={() => setShowAbout(false)} />
+          <div className="bg-white dark:bg-zinc-900 rounded-3xl shadow-2xl w-full max-w-lg max-h-[90vh] overflow-y-auto relative animate-slide-up z-50 no-scrollbar border border-zinc-200 dark:border-zinc-800">
+            <button onClick={() => { triggerHaptic(); setShowAbout(false); }} className="absolute right-4 top-4 p-2 bg-white/80 dark:bg-black/50 backdrop-blur hover:bg-zinc-100 dark:hover:bg-zinc-800 text-zinc-500 dark:text-zinc-400 rounded-full transition-colors z-10 shadow-sm">
+              <X className="w-5 h-5" />
+            </button>
+            <div className="p-6 sm:p-8 space-y-6">
+              <h3 className="text-2xl font-bold text-zinc-900 dark:text-white">About Serendipity</h3>
+              <div className="space-y-4 text-zinc-600 dark:text-zinc-300 leading-relaxed">
+                <p>
+                  Serendipity is an intelligent book discovery interface powered by the <strong>DeepShelf Engine</strong>.
+                </p>
+                <p>
+                  Unlike traditional keyword search, DeepShelf uses semantic vector embeddings to understand the <em>meaning</em> and <em>feeling</em> of your request. It connects you with books that match your specific wavelength, even if they don't share a single keyword.
+                </p>
+              </div>
+              <div className="space-y-3">
+                <h4 className="text-lg font-bold text-zinc-800 dark:text-zinc-200">How it works:</h4>
+                <ul className="list-disc list-inside text-zinc-600 dark:text-zinc-300 space-y-1">
+                  <li><strong>Semantic Search:</strong> Understands the meaning and context of your queries.</li>
+                  <li><strong>Vector Embeddings:</strong> DeepShelf maps books and queries into a high-dimensional vector space.</li>
+                  <li><strong>Neural Retrieval:</strong> Finds the nearest neighbors to your thought in the library of 100,000+ books.</li>
+                </ul>
+              </div>
+              <p className="text-zinc-600 dark:text-zinc-300 leading-relaxed">
+                Describe your ideal read and let Serendipity uncover your next literary obsession!
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default App;

frontend/src/BookCard.tsx

@@ -0,0 +1,122 @@
+import React from 'react';
+import { ThumbsUp, ThumbsDown, ArrowRight, Sparkles, Bookmark, Check } from 'lucide-react';
+import { BookCover } from './BookCover';
+import type { RecommendationResult } from './types';
+
+interface BookCardProps {
+  result: RecommendationResult;
+  isRead?: boolean;
+  onToggleRead?: (title: string) => void;
+  onClick: () => void;
+  onFeedback: (id: string, type: 'positive' | 'negative') => void;
+}
+
+export function BookCard({ result, isRead, onToggleRead, onClick, onFeedback }: BookCardProps) {
+  const { book, similarity_score } = result;
+  const percentage = Math.round(similarity_score * 100);
+
+  const handleToggleRead = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (onToggleRead) {
+      onToggleRead(book.title);
+    }
+  };
+
+  return (
+    <div 
+      onClick={onClick}
+      className={`group relative bg-white dark:bg-zinc-900/80 backdrop-blur-sm border rounded-3xl p-4 sm:p-5 shadow-sm hover:shadow-xl hover:shadow-indigo-500/5 dark:hover:shadow-indigo-500/10 transition-all duration-300 cursor-pointer hover:-translate-y-0.5 active:scale-[0.99] animate-slide-up h-full flex flex-col sm:flex-row gap-5 overflow-hidden ${isRead ? 'border-indigo-500/50 dark:border-indigo-500/50 ring-1 ring-indigo-500/20' : 'border-zinc-200 dark:border-zinc-800'}`}
+    >
+      {/* Read Status Toggle (Absolute Top Right) */}
+      {onToggleRead && (
+        <button
+          onClick={handleToggleRead}
+          className={`absolute top-3 right-3 z-20 p-2 rounded-full transition-all shadow-sm ${isRead ? 'bg-indigo-600 text-white' : 'bg-white/80 dark:bg-zinc-800/80 text-zinc-400 hover:text-indigo-600 dark:hover:text-indigo-400 border border-zinc-200 dark:border-zinc-700'}`}
+          title={isRead ? "Remove from history" : "Mark as read"}
+        >
+          {isRead ? <Check className="w-4 h-4" /> : <Bookmark className="w-4 h-4" />}
+        </button>
+      )}
+
+      {/* Cover Image Section */}
+      <div className="w-full sm:w-28 aspect-[2/3] bg-zinc-100 dark:bg-zinc-800 rounded-xl overflow-hidden relative shadow-inner shrink-0 border border-zinc-100 dark:border-zinc-700">
+        <BookCover 
+          src={book.cover_image_url} 
+          title={book.title} 
+          author={book.authors?.[0] || 'Unknown Author'}
+          className="w-full h-full transition-transform duration-500 group-hover:scale-105"
+        />
+        
+        {/* Match Badge (Mobile Overlay) */}
+        <div className="absolute top-2 right-2 sm:hidden">
+          <span className="bg-white/90 dark:bg-black/80 backdrop-blur text-indigo-600 dark:text-indigo-400 text-[10px] font-bold px-2 py-1 rounded-full border border-black/5 dark:border-white/10 shadow-sm">
+            {percentage}% Match
+          </span>
+        </div>
+      </div>
+
+      {/* Content Section */}
+      <div className="space-y-2.5 flex-1 min-w-0 flex flex-col">
+        <div className="flex justify-between items-start gap-4">
+          <h2 className="text-xl font-bold leading-tight text-zinc-900 dark:text-zinc-100 group-hover:text-indigo-600 dark:group-hover:text-indigo-400 transition-colors line-clamp-2 font-serif tracking-tight">
+            {book.title}
+          </h2>
+          {/* Desktop Match Badge */}
+          <span className="hidden sm:inline-flex text-xs font-bold text-indigo-600 dark:text-indigo-400 bg-indigo-50 dark:bg-indigo-500/10 border border-indigo-100 dark:border-indigo-500/20 px-2 py-1 rounded-full whitespace-nowrap items-center gap-1">
+            <Sparkles className="w-3 h-3" />
+            {percentage}%
+          </span>
+        </div>
+        
+        <p className="text-zinc-500 dark:text-zinc-400 font-medium text-xs">
+          by <span className="text-zinc-900 dark:text-zinc-200">{book.authors?.join(', ') || 'Unknown Author'}</span>
+        </p>
+
+        <p className="text-zinc-600 dark:text-zinc-400 leading-relaxed text-sm line-clamp-2 sm:line-clamp-3">
+          {book.description || 'No description available.'}
+        </p>
+
+        <div className="pt-2 mt-auto flex items-center justify-between gap-4">
+          {/* Mobile: Simple 'Read more' */}
+          <button className="flex items-center gap-1 text-sm font-bold text-indigo-600 dark:text-indigo-400 group-active:opacity-70">
+            Read more <ArrowRight className="w-4 h-4 transition-transform group-hover:translate-x-1" />
+          </button>
+          
+          {/* Feedback Actions (Desktop Hover / Mobile Always Visible but subtle) */}
+          <div 
+            className="flex gap-1 sm:opacity-0 sm:group-hover:opacity-100 transition-opacity" 
+            onClick={(e) => e.stopPropagation()}
+          >
+            <button 
+              onClick={() => onFeedback(book.id, 'positive')} 
+              className="p-2 hover:bg-green-50 dark:hover:bg-green-900/30 text-zinc-400 hover:text-green-600 dark:hover:text-green-400 rounded-full transition-colors"
+              aria-label="Like recommendation"
+            >
+              <ThumbsUp className="w-4 h-4" />
+            </button>
+            <button 
+              onClick={() => onFeedback(book.id, 'negative')} 
+              className="p-2 hover:bg-red-50 dark:hover:bg-red-900/30 text-zinc-400 hover:text-red-600 dark:hover:text-red-400 rounded-full transition-colors"
+              aria-label="Dislike recommendation"
+            >
+              <ThumbsDown className="w-4 h-4" />
+            </button>
+          </div>
+        </div>
+
+        {/* Genre Tags */}
+        <div className="flex flex-wrap gap-1.5 pt-2">
+          {book.genres?.slice(0, 3).map(genre => (
+            <span 
+              key={genre} 
+              className="text-[10px] uppercase tracking-wider font-bold text-zinc-500 dark:text-zinc-500 border border-zinc-200 dark:border-zinc-700 bg-zinc-50 dark:bg-zinc-800 px-2 py-1 rounded-md truncate max-w-[100px]" 
+              title={genre}
+            >
+              {genre}
+            </span>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/BookCover.tsx

@@ -0,0 +1,75 @@
+import { useState } from 'react';
+import { BookOpen } from 'lucide-react';
+
+// Deterministic color generator based on string
+const getColor = (str: string) => {
+  const colors = [
+    'from-red-500 to-orange-500',
+    'from-orange-500 to-amber-500',
+    'from-amber-500 to-yellow-500',
+    'from-yellow-500 to-lime-500',
+    'from-lime-500 to-green-500',
+    'from-green-500 to-emerald-500',
+    'from-emerald-500 to-teal-500',
+    'from-teal-500 to-cyan-500',
+    'from-cyan-500 to-sky-500',
+    'from-sky-500 to-blue-500',
+    'from-blue-500 to-indigo-500',
+    'from-indigo-500 to-violet-500',
+    'from-violet-500 to-purple-500',
+    'from-purple-500 to-fuchsia-500',
+    'from-fuchsia-500 to-pink-500',
+    'from-pink-500 to-rose-500',
+    'from-slate-500 to-zinc-500',
+  ];
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return colors[Math.abs(hash) % colors.length];
+};
+
+interface BookCoverProps {
+  src?: string | null;
+  title: string;
+  author?: string;
+  className?: string;
+}
+
+export function BookCover({ src, title, author, className = "" }: BookCoverProps) {
+  const [error, setError] = useState(false);
+  const gradient = getColor(title);
+
+  if (src && !error) {
+    return (
+      <img 
+        src={src} 
+        alt={title}
+        onError={() => setError(true)}
+        className={`object-cover ${className}`} 
+      />
+    );
+  }
+
+  // Fallback: Generated Cover
+  return (
+    <div className={`bg-gradient-to-br ${gradient} p-4 flex flex-col justify-between relative overflow-hidden ${className}`}>
+      {/* Texture Overlay */}
+      <div className="absolute inset-0 bg-noise opacity-20 mix-blend-overlay"></div>
+      
+      <div className="relative z-10">
+        <h3 className="text-white font-bold leading-tight text-shadow-sm line-clamp-4" style={{ fontSize: 'clamp(0.75rem, 1vw, 1rem)' }}>
+          {title}
+        </h3>
+      </div>
+      
+      {author && (
+         <p className="relative z-10 text-white/90 text-[10px] font-medium truncate mt-2">
+            {author}
+         </p>
+      )}
+
+      <BookOpen className="absolute bottom-[-10%] right-[-10%] w-[60%] h-[60%] text-white/10 -rotate-12" />
+    </div>
+  );
+}

frontend/src/Loader.tsx

@@ -0,0 +1,50 @@
+import { BookOpen } from 'lucide-react';
+import { useState, useEffect } from 'react';
+
+const LOADING_MESSAGES = [
+  "Scanning literary universe...",
+  "Analyzing plot vectors...",
+  "Connecting thematic dots...",
+  "Filtering hidden gems...",
+  "Synthesizing recommendations..."
+];
+
+export function Loader() {
+  const [messageIndex, setMessageIndex] = useState(0);
+
+  useEffect(() => {
+    const interval = setInterval(() => {
+      setMessageIndex((prev) => (prev + 1) % LOADING_MESSAGES.length);
+    }, 800);
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <div className="flex flex-col items-center justify-center py-24 relative overflow-hidden">
+      
+      {/* Orbiting / Pulsing Effect */}
+      <div className="relative flex items-center justify-center">
+        {/* Core */}
+        <div className="relative z-10 bg-white dark:bg-zinc-800 p-4 rounded-2xl shadow-xl border border-indigo-100 dark:border-indigo-500/30 animate-bounce-slight">
+          <BookOpen className="w-8 h-8 text-indigo-600 dark:text-indigo-400" />
+        </div>
+        
+        {/* Orbital Ring 1 */}
+        <div className="absolute w-24 h-24 border-2 border-indigo-500/20 dark:border-indigo-400/20 rounded-full animate-spin-slow" style={{ borderRadius: '40% 60% 70% 30% / 40% 50% 60% 50%' }}></div>
+        
+        {/* Orbital Ring 2 */}
+        <div className="absolute w-32 h-32 border border-purple-500/20 dark:border-purple-400/20 rounded-full animate-spin-reverse-slower" style={{ borderRadius: '60% 40% 30% 70% / 60% 30% 70% 40%' }}></div>
+        
+        {/* Pulsing Aura */}
+        <div className="absolute inset-0 bg-indigo-500/10 dark:bg-indigo-400/10 rounded-full animate-ping-slow"></div>
+      </div>
+
+      {/* Text */}
+      <div className="mt-8 text-center z-10">
+        <p className="text-sm font-bold bg-clip-text text-transparent bg-gradient-to-r from-indigo-600 to-purple-600 dark:from-indigo-400 dark:to-purple-400 animate-pulse">
+          {LOADING_MESSAGES[messageIndex]}
+        </p>
+      </div>
+    </div>
+  );
+}

frontend/src/api.ts

@@ -0,0 +1,59 @@
+import axios from 'axios';
+import type { RecommendationResult, Book, BookCluster } from './types';
+
+const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:8000';
+
+export const api = {
+  getClusters: async (): Promise<BookCluster[]> => {
+    const response = await axios.get<BookCluster[]>(`${API_URL}/clusters`);
+    return response.data;
+  },
+
+  recommendByQuery: async (query: string): Promise<RecommendationResult[]> => {
+    const response = await axios.post<RecommendationResult[]>(`${API_URL}/recommend/query`, {
+      query,
+      top_k: 12,
+    });
+    return response.data;
+  },
+
+  searchBooks: async (query: string): Promise<{ books: Book[] }> => {
+    const response = await axios.get(`${API_URL}/books/search`, {
+      params: { query, page: 1, page_size: 20 },
+    });
+    return response.data;
+  },
+
+  submitFeedback: async (query: string, bookId: string, type: 'positive' | 'negative') => {
+    await axios.post(`${API_URL}/feedback`, {
+      query,
+      book_id: bookId,
+      feedback_type: type,
+    });
+  },
+
+  explainRecommendation: async (query: string, book: Book, score: number) => {
+    const response = await axios.post(`${API_URL}/explain`, {
+      query_text: query,
+      recommended_book: book,
+      similarity_score: score
+    });
+    return response.data;
+  },
+
+  getRelatedBooks: async (title: string): Promise<RecommendationResult[]> => {
+    const response = await axios.post<RecommendationResult[]>(`${API_URL}/recommend/title`, {
+      title,
+      top_k: 6,
+    });
+    return response.data;
+  },
+
+  recommendPersonalized: async (history: string[]): Promise<RecommendationResult[]> => {
+    const response = await axios.post<RecommendationResult[]>(`${API_URL}/recommend/personalize`, {
+      user_history: history,
+      top_k: 12,
+    });
+    return response.data;
+  }
+};

frontend/src/data/personas.ts

@@ -0,0 +1,65 @@
+export interface Persona {
+  id: string;
+  name: string;
+  emoji: string;
+  description: string;
+  history: string[];
+}
+
+export const DEMO_PERSONAS: Persona[] = [
+  {
+    id: 'scifi_fan',
+    name: 'The Futurist',
+    emoji: '🤖',
+    description: 'Loves cyberpunk, AI, and space opera.',
+    history: [
+      "Neuromancer",
+      "Snow Crash",
+      "Dune",
+      "I, Robot",
+      "Do Androids Dream of Electric Sheep?",
+      "Foundation"
+    ]
+  },
+  {
+    id: 'horror_fan',
+    name: 'The Thrill Seeker',
+    emoji: '👻',
+    description: 'Obsessed with ghosts, psychological terror, and Stephen King.',
+    history: [
+      "It",
+      "The Shining",
+      "Dracula",
+      "Pet Sematary",
+      "The Haunting of Hill House",
+      "Misery"
+    ]
+  },
+  {
+    id: 'romance_fan',
+    name: 'The Hopeless Romantic',
+    emoji: '💘',
+    description: 'Enjoys period dramas, deep emotions, and happy endings.',
+    history: [
+      "Pride and Prejudice",
+      "Jane Eyre",
+      "The Notebook",
+      "Sense and Sensibility",
+      "Me Before You",
+      "Outlander"
+    ]
+  },
+  {
+      id: 'history_buff',
+      name: 'The Time Traveler',
+      emoji: '📜',
+      description: 'Fascinated by WWII, ancient civilizations, and biographies.',
+      history: [
+          "The Diary of a Young Girl",
+          "The Guns of August",
+          "1776",
+          "Sapiens: A Brief History of Humankind",
+          "Alexander Hamilton"
+      ]
+  }
+];

frontend/src/index.css

@@ -0,0 +1,136 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --font-serif: "Crimson Pro", serif;
+  --font-sans: "Inter", sans-serif;
+}
+
+body {
+  font-family: var(--font-sans);
+}
+
+.font-serif {
+  font-family: var(--font-serif);
+}
+
+@layer utilities {
+  .animate-fade-in {
+    animation: fadeIn 0.5s ease-out forwards;
+  }
+  
+  .animate-slide-up {
+    animation: slideUp 0.5s ease-out forwards;
+  }
+
+  .animation-delay-2000 {
+    animation-delay: 2s;
+  }
+  
+  .animation-delay-4000 {
+    animation-delay: 4s;
+  }
+  
+  .animation-delay-500 {
+    animation-delay: 500ms;
+  }
+
+  /* Custom Scrollbar Utilities */
+  .no-scrollbar::-webkit-scrollbar {
+    display: none;
+  }
+  .no-scrollbar {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+  
+  .bg-noise {
+    background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noiseFilter'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noiseFilter)' opacity='0.4'/%3E%3C/svg%3E");
+  }
+  
+  .bg-dot-pattern {
+    background-image: radial-gradient(circle, #6366f1 1.5px, transparent 1.5px);
+    background-size: 32px 32px;
+    opacity: 0.4;
+  }
+  .dark .bg-dot-pattern {
+    opacity: 0.2;
+  }
+}
+
+/* Global Custom Scrollbar */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background-color: #d4d4d8; /* zinc-300 */
+  border-radius: 9999px;
+  border: 2px solid transparent;
+  background-clip: content-box;
+}
+
+.dark ::-webkit-scrollbar-thumb {
+  background-color: #3f3f46; /* zinc-700 */
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background-color: #a1a1aa; /* zinc-400 */
+}
+
+.dark ::-webkit-scrollbar-thumb:hover {
+  background-color: #52525b; /* zinc-600 */
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes slideUp {
+  from { 
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to { 
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes spin-slow {
+  from { transform: rotate(0deg); }
+  to { transform: rotate(360deg); }
+}
+.animate-spin-slow {
+  animation: spin-slow 8s linear infinite;
+}
+
+@keyframes spin-reverse-slower {
+  from { transform: rotate(360deg); }
+  to { transform: rotate(0deg); }
+}
+.animate-spin-reverse-slower {
+  animation: spin-reverse-slower 12s linear infinite;
+}
+
+@keyframes bounce-slight {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(-5px); }
+}
+.animate-bounce-slight {
+  animation: bounce-slight 2s ease-in-out infinite;
+}
+
+@keyframes ping-slow {
+  75%, 100% { transform: scale(2); opacity: 0; }
+}
+.animate-ping-slow {
+  animation: ping-slow 3s cubic-bezier(0, 0, 0.2, 1) infinite;
+}

frontend/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

frontend/src/types.ts

@@ -0,0 +1,25 @@
+export interface Book {
+  id: string;
+  title: string;
+  authors: string[];
+  description?: string;
+  genres: string[];
+  cover_image_url?: string;
+}
+
+export interface RecommendationResult {
+  book: Book;
+  similarity_score: number;
+}
+
+export interface RecommendByQueryRequest {
+  query: string;
+  top_k: number;
+}
+
+export interface BookCluster {
+  id: number;
+  name: string;
+  size: number;
+  top_books: Book[];
+}

frontend/tailwind.config.js

@@ -0,0 +1,12 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  darkMode: 'class',
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}

frontend/tsconfig.app.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

frontend/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

frontend/tsconfig.node.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}

frontend/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+        },
+      },
+    },
+  },
+})

pyproject.toml

@@ -0,0 +1,106 @@
+[project]
+name = "deepshelf-engine"
+version = "0.1.0"
+description = "DeepShelf - Semantic Book Recommendation Engine"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Your Name", email = "your.email@example.com"}
+]
+keywords = [
+    "machine-learning",
+    "nlp",
+    "recommendation-system",
+    "fastapi",
+    "streamlit",
+    "books"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "faiss-cpu>=1.13.0",
+    "numpy>=1.26.4",
+    "pandas>=2.3.3",
+    "pyarrow>=22.0.0",
+    "requests>=2.32.5",
+    "scikit-learn>=1.7.2",
+    "sentence-transformers==2.5.1",
+    "streamlit>=1.40.0",
+    "torch==2.2.2",
+    "transformers==4.38.2",
+    "fastapi>=0.104.1",
+    "uvicorn[standard]>=0.24.0",
+    "pydantic>=2.5.2",
+    "python-dotenv>=1.0.0",
+    "plotly>=5.18.0",
+    "slowapi>=0.1.9",
+    "pytest>=9.0.1",
+    "groq>=0.36.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.1",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.1.0",
+    "black>=23.0.0",
+    "mypy>=1.7.0",
+    "safety>=2.3.0",
+    "pip-audit>=2.6.0",
+    "pre-commit>=3.5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/bookfinder-ai"
+Documentation = "https://github.com/yourusername/bookfinder-ai/tree/main/docs"
+Repository = "https://github.com/yourusername/bookfinder-ai"
+"Bug Tracker" = "https://github.com/yourusername/bookfinder-ai/issues"
+
+[project.scripts]
+bookfinder-web = "src.book_recommender.apps.main_app:main"
+bookfinder-api = "src.book_recommender.api.main:main"
+bookfinder-analytics = "src.book_recommender.apps.analytics_app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/book_recommender"]
+
+
+
+
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E203", "E501"]
+
+[tool.black]
+line-length = 120
+target-version = ["py310", "py311", "py312"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "requests.*"
+ignore_missing_imports = true

requirements-dev.txt

@@ -0,0 +1,9 @@
+# For running tests
+pytest-cov
+
+# For UI testing (optional)
+# streamlit-testing-library
+
+black
+ruff
+mypy

requirements.backend.txt

@@ -0,0 +1,17 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.2.2
+sentence-transformers==2.5.1
+transformers==4.38.2
+pandas
+numpy<2.0.0
+scikit-learn
+pyarrow
+faiss-cpu
+requests
+fastapi
+uvicorn[standard]
+pydantic
+python-dotenv
+slowapi
+groq
+huggingface_hub<1.0

requirements.txt

@@ -0,0 +1,19 @@
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch==2.2.2
+streamlit>=1.40.0
+sentence-transformers==2.5.1
+transformers==4.38.2
+pandas
+numpy
+scikit-learn
+pytest
+pyarrow
+faiss-cpu
+requests
+fastapi
+uvicorn[standard]
+pydantic
+python-dotenv
+slowapi
+groq
+huggingface_hub

scripts/download_data.py

@@ -0,0 +1,82 @@
+import logging
+import os
+import sys
+from pathlib import Path
+
+from huggingface_hub import snapshot_download
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+# Define paths directly to avoid importing from src (which isn't copied yet in Docker build)
+PROCESSED_DATA_DIR = Path("data/processed")
+PROCESSED_DATA_PATH = PROCESSED_DATA_DIR / "books_with_embeddings.parquet"
+EMBEDDINGS_PATH = PROCESSED_DATA_DIR / "embeddings.npy"
+CLUSTERS_CACHE_PATH = PROCESSED_DATA_DIR / "clusters_cache.pkl"
+
+def download_processed_data(repo_id: str):
+    """
+    Downloads processed data files (parquet, npy, pkl) from a private Hugging Face Dataset.
+    
+    Args:
+        repo_id (str): The Hugging Face dataset ID (e.g., 'username/dataset-name').
+    """
+    hf_token = os.getenv("HF_TOKEN")
+    if not hf_token:
+        logger.warning("HF_TOKEN environment variable not found. If the dataset is private, download will fail.")
+
+    logger.info(f"Starting download from Hugging Face Dataset: {repo_id}")
+    logger.info(f"Target directory: {PROCESSED_DATA_DIR}")
+
+    try:
+        # Ensure directory exists
+        PROCESSED_DATA_DIR.mkdir(parents=True, exist_ok=True)
+
+        # Download only specific files to avoid clutter
+        allow_patterns = [
+            "*.parquet",
+            "*.npy",
+            "*.pkl",
+            "*.json"
+        ]
+
+        snapshot_download(
+            repo_id=repo_id,
+            repo_type="dataset",
+            local_dir=PROCESSED_DATA_DIR,
+            local_dir_use_symlinks=False, # Important for Docker/Deployment
+            allow_patterns=allow_patterns,
+            token=hf_token
+        )
+        
+        logger.info("Successfully downloaded all data files.")
+        
+        # Verify files
+        expected_files = [
+            PROCESSED_DATA_PATH,
+            EMBEDDINGS_PATH,
+            CLUSTERS_CACHE_PATH
+        ]
+        
+        missing = [f.name for f in expected_files if not f.exists()]
+        if missing:
+            logger.error(f"Warning: The following expected files are still missing after download: {missing}")
+        else:
+            logger.info("Verification successful: All core data files are present.")
+
+    except Exception as e:
+        logger.error(f"Failed to download data from Hugging Face: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    # Default repo ID - WILL BE OVERRIDDEN by environment variable in production
+    DEFAULT_REPO_ID = "nice-bill/book-recommender-data"
+    
+    repo_id = os.getenv("HF_DATASET_ID", DEFAULT_REPO_ID)
+    
+    if repo_id == "PLACEHOLDER_USERNAME/PLACEHOLDER_DATASET":
+        logger.error("Please set the HF_DATASET_ID environment variable or update the script.")
+        sys.exit(1)
+        
+    download_processed_data(repo_id)

scripts/download_model.py

@@ -0,0 +1,22 @@
+import os
+import sys
+
+from sentence_transformers import SentenceTransformer
+
+# sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+# from src.book_recommender.core import config
+
+MODEL_NAME = "all-MiniLM-L6-v2"
+
+def download_model():
+    """
+    Downloads the sentence-transformer model specified in the config file.
+    This is useful for pre-downloading the model in a Docker build.
+    """
+    print(f"Downloading model: {MODEL_NAME}...")
+    _ = SentenceTransformer(MODEL_NAME)
+    print("Model downloaded successfully.")
+
+
+if __name__ == "__main__":
+    download_model()

scripts/enrich_book_covers.py

@@ -0,0 +1,81 @@
+import pandas as pd
+import requests
+import time
+import logging
+from pathlib import Path
+
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+DATA_DIR = Path("data/raw")
+INPUT_FILE = DATA_DIR / "books_prepared.csv"
+
+def get_openlibrary_cover(title, author):
+    try:
+        # Simple cleaning
+        clean_title = title.replace('&', '').split('(')[0].strip()
+        clean_author = author.split(',')[0].strip() if author else ""
+        
+        query = f"title={clean_title}&author={clean_author}"
+        url = f"https://openlibrary.org/search.json?{query}&limit=1"
+        
+        response = requests.get(url, timeout=5)
+        if response.status_code == 200:
+            data = response.json()
+            if data.get("docs"):
+                doc = data["docs"][0]
+                if "cover_i" in doc:
+                    return f"https://covers.openlibrary.org/b/id/{doc['cover_i']}-L.jpg"
+    except Exception as e:
+        logger.warning(f"Error fetching cover for {title}: {e}")
+    return None
+
+def enrich_data():
+    if not INPUT_FILE.exists():
+        logger.error(f"File not found: {INPUT_FILE}")
+        return
+
+    df = pd.read_csv(INPUT_FILE)
+    logger.info(f"Loaded {len(df)} books.")
+
+    if "cover_image_url" not in df.columns:
+        df["cover_image_url"] = None
+
+    # Filter for rows without covers
+    # We check for NaN or empty string
+    mask = df["cover_image_url"].isna() | (df["cover_image_url"] == "")
+    indices = df[mask].index
+    
+    logger.info(f"Found {len(indices)} books missing covers.")
+    
+    # Process a batch (e.g., 50) to demonstrate improvement without timeout
+    # The user can run this script repeatedly or increase limit
+    BATCH_SIZE = 20
+    count = 0
+    
+    for idx in indices:
+        if count >= BATCH_SIZE:
+            break
+            
+        row = df.loc[idx]
+        title = row['title']
+        author = row['authors']
+        
+        logger.info(f"[{count+1}/{BATCH_SIZE}] Fetching cover for: {title}")
+        cover_url = get_openlibrary_cover(title, author)
+        
+        if cover_url:
+            df.at[idx, 'cover_image_url'] = cover_url
+            logger.info(f"  -> Found: {cover_url}")
+        else:
+            logger.info("  -> No cover found.")
+        
+        time.sleep(0.2) # Polite delay
+        count += 1
+
+    # Save back
+    df.to_csv(INPUT_FILE, index=False)
+    logger.info(f"Saved enriched data to {INPUT_FILE}")
+
+if __name__ == "__main__":
+    enrich_data()

scripts/precompute_clusters.py

@@ -0,0 +1,56 @@
+import logging
+import os
+import pickle
+import sys
+import numpy as np
+import pandas as pd
+
+# Add project root
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+import src.book_recommender.core.config as config
+from src.book_recommender.ml.clustering import cluster_books, get_cluster_names
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+def precompute_clusters():
+    logger.info("--- Starting Cluster Pre-computation ---")
+    
+    # 1. Load Data
+    if not os.path.exists(config.PROCESSED_DATA_PATH) or not os.path.exists(config.EMBEDDINGS_PATH):
+        logger.error("Data files missing. Run data processor and embedder first.")
+        return
+
+    logger.info(f"Loading book data from {config.PROCESSED_DATA_PATH}...")
+    book_data_df = pd.read_parquet(config.PROCESSED_DATA_PATH)
+    
+    logger.info(f"Loading embeddings from {config.EMBEDDINGS_PATH}...")
+    embeddings_arr = np.load(config.EMBEDDINGS_PATH)
+
+    # 2. Cluster
+    n_clusters = config.NUM_CLUSTERS
+    logger.info(f"Clustering {len(book_data_df)} books into {n_clusters} clusters...")
+    
+    clusters_arr, _ = cluster_books(embeddings_arr, n_clusters=n_clusters)
+    
+    # 3. Name Clusters
+    book_data_df["cluster_id"] = clusters_arr
+    names = get_cluster_names(book_data_df, clusters_arr)
+    
+    # 4. Save Cache
+    cache_path = config.PROCESSED_DATA_DIR / "cluster_cache.pkl"
+    logger.info(f"Saving cache to {cache_path}...")
+    
+    try:
+        with open(cache_path, "wb") as f:
+            # Must match the tuple structure expected by api/dependencies.py
+            # (clusters_arr, names, book_data_df)
+            pickle.dump((clusters_arr, names, book_data_df), f)
+        logger.info("Successfully pre-computed and cached clusters.")
+    except Exception as e:
+        logger.error(f"Failed to save cache: {e}")
+
+if __name__ == "__main__":
+    precompute_clusters()

scripts/prepare_100k_data.py

@@ -0,0 +1,71 @@
+import logging
+import os
+import sys
+import pandas as pd
+
+# Setup logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+def prepare_100k_data():
+    """
+    Convert GoodReads_100k_books.csv format to the format expected by data_processor.
+    
+    Input Columns: author, bookformat, desc, genre, img, isbn, isbn13, link, pages, rating, reviews, title, totalratings
+    Target Columns: title, authors, genres, description, tags, rating, cover_image_url
+    """
+    input_path = "data/raw/GoodReads_100k_books.csv"
+    output_path = "data/raw/books_prepared.csv"
+
+    logger.info(f"Loading new 100k dataset from {input_path}...")
+
+    if not os.path.exists(input_path):
+        logger.error(f"Input file not found: {input_path}")
+        return
+
+    try:
+        # Load data
+        df = pd.read_csv(input_path)
+        logger.info(f"Loaded {len(df)} books.")
+        
+        # Rename columns
+        logger.info("Mapping columns...")
+        df = df.rename(columns={
+            "author": "authors",
+            "desc": "description",
+            "genre": "genres",
+            "img": "cover_image_url",
+            "rating": "rating"
+        })
+        
+        # Create tags column (using genres as base if available, else empty)
+        df["tags"] = df["genres"].fillna("")
+        
+        # Select and Reorder
+        target_cols = ["title", "authors", "genres", "description", "tags", "rating", "cover_image_url"]
+        
+        # Ensure all target columns exist
+        for col in target_cols:
+            if col not in df.columns:
+                df[col] = ""
+                logger.warning(f"Column {col} missing in source, filled with empty strings.")
+
+        df = df[target_cols]
+        
+        # Clean up
+        logger.info("Cleaning data...")
+        # Remove rows with no title
+        df = df.dropna(subset=["title"])
+        # Fill NaNs in text columns
+        df[["authors", "genres", "description", "cover_image_url"]] = df[["authors", "genres", "description", "cover_image_url"]].fillna("")
+        
+        logger.info(f"Saving prepared data to {output_path}...")
+        df.to_csv(output_path, index=False)
+        logger.info(f"Successfully prepared {len(df)} books.")
+        
+    except Exception as e:
+        logger.error(f"Error processing data: {e}")
+        raise
+
+if __name__ == "__main__":
+    prepare_100k_data()

scripts/prepare_goodreads_data.py

@@ -0,0 +1,104 @@
+import logging
+import os
+import sys
+
+import pandas as pd
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+
+def prepare_goodreads_data():
+    """
+    Convert Goodreads CSV format to the format expected by data_processor.
+
+    Maps:
+    - Book → title
+    - Author → authors
+    - Avg_Rating → rating
+    - Description → description
+    - Genres → genres
+    - Creates 'tags' from genres
+    - Drops: Unnamed: 0, Num_Ratings, URL
+    """
+    input_path = "data/raw/goodreads_data.csv"
+    output_path = "data/raw/books_prepared.csv"
+
+    logger.info(f"Loading Goodreads data from {input_path}...")
+
+    try:
+        df = pd.read_csv(input_path)
+        logger.info(f"Loaded {len(df)} books")
+        logger.info(f"Original columns: {df.columns.tolist()}")
+
+        if "Unnamed: 0" in df.columns or "" in df.columns:
+            df = df.drop(columns=[col for col in df.columns if "Unnamed" in str(col) or col == ""])
+            logger.info("Dropped unnamed index column")
+
+        logger.info("Renaming columns...")
+        df = df.rename(
+            columns={
+                "Book": "title",
+                "Author": "authors",
+                "Avg_Rating": "rating",
+                "Description": "description",
+                "Genres": "genres",
+            }
+        )
+
+        df["tags"] = ""
+        logger.info("Created 'tags' column (empty - can be populated later)")
+
+        columns_to_keep = ["title", "authors", "genres", "description", "tags", "rating"]
+
+        missing_cols = [col for col in columns_to_keep if col not in df.columns]
+        if missing_cols:
+            logger.error(f"Missing columns after mapping: {missing_cols}")
+            logger.error(f"Available columns: {df.columns.tolist()}")
+            raise ValueError(f"Column mapping failed. Missing: {missing_cols}")
+
+        df = df[columns_to_keep]
+
+        logger.info(f"Final shape: {df.shape}")
+        logger.info(f"Final columns: {df.columns.tolist()}")
+        logger.info(f"Sample row:\n{df.iloc[0]}")
+
+        null_rows = df.isnull().all(axis=1).sum()
+        if null_rows > 0:
+            logger.warning(f"Found {null_rows} completely null rows - will be removed by processor")
+
+        logger.info(f"Saving prepared data to {output_path}...")
+        df.to_csv(output_path, index=False)
+        logger.info(f" Successfully prepared {len(df)} books")
+
+        logger.info("\n Dataset Summary:")
+        logger.info(f"  Total books: {len(df)}")
+        logger.info(f"  Books with ratings: {df['rating'].notna().sum()}")
+        logger.info(f"  Books with descriptions: {(df['description'] != '').sum()}")
+        logger.info(f"  Average rating: {df['rating'].mean():.2f}")
+
+        print("\n Data preparation complete!")
+        print(f"   Input:  {input_path}")
+        print(f"   Output: {output_path}")
+        print("\n Next steps:")
+        print("   1. Update src/config.py line 17:")
+        print("      RAW_DATA_PATH = os.path.join(RAW_DATA_DIR, 'books_prepared.csv')")
+        print("   2. Run: python src/data_processor.py")
+        print("   3. Run: python src/embedder.py")
+        print("   4. Run: streamlit run app.py")
+
+        return df
+
+    except FileNotFoundError:
+        logger.error(f"File not found: {input_path}")
+        logger.error("Make sure goodreads_data.csv exists in data/raw/")
+        raise
+    except Exception as e:
+        logger.error(f"Error processing data: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    prepare_goodreads_data()

src/book_recommender/__init__.py

@@ -0,0 +1,23 @@
+"""BookFinder-AI - Semantic Book Recommendation Engine"""
+
+__version__ = "1.0.0"
+__author__ = "Your Name"
+
+import os
+import sys
+
+# Add the project root to the Python path
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")))
+
+
+# Expose main classes at package level
+from src.book_recommender.ml.clustering import cluster_books, get_cluster_names
+from src.book_recommender.ml.embedder import generate_embedding_for_query
+from src.book_recommender.ml.recommender import BookRecommender
+
+__all__ = [
+    "BookRecommender",
+    "generate_embedding_for_query",
+    "cluster_books",
+    "get_cluster_names",
+]