📚 Semantic Book Recommender

A book recommendation engine that uses vector similarity search and emotion analysis to find books matching a natural-language description. Filter results by category and emotional tone through an interactive Gradio web interface.

Features

• Semantic search — describe what you want to read in plain English and get relevant recommendations powered by sentence-transformer embeddings and ChromaDB
• Emotion-based filtering — sort results by emotional tone (happy, sad, suspenseful, surprising, angry) using pre-computed sentiment scores
• Category filtering — narrow results to Fiction, Nonfiction, or other category groups
• Interactive UI — browse recommendations with cover art in a Gradio gallery

Setup

Prerequisites

• Python 3.10+
• pip

Installation

# Clone the repository
git clone https://github.com/lukedev45/book-recommender.git
cd book-recommender

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration

Copy the environment template (no secrets are required currently):

cp .env.example .env

Usage

Launch the Gradio dashboard:

python -m src.app

Open the URL printed in the terminal (typically http://127.0.0.1:7860) and enter a description like "A story about forgiveness", optionally selecting a category and emotional tone.

Project Structure

book-recommender/
├── data/                       # Processed datasets
│   ├── books_cleaned.csv
│   ├── books_with_categories.csv
│   ├── books_with_emotions.csv
│   └── tagged_description.txt
├── notebooks/                  # Analysis notebooks (EDA, NLP, embeddings)
│   ├── data-exploration.ipynb
│   ├── sentiment-analysis.ipynb
│   ├── text_classification.ipynb
│   └── vector_search.ipynb
├── src/                        # Application source code
│   ├── __init__.py
│   ├── app.py                  # Gradio UI entrypoint
│   ├── config.py               # Paths, constants, settings
│   ├── data_loader.py          # CSV loading & thumbnail prep
│   └── recommender.py          # Vector DB & recommendation logic
├── static/                     # Static assets
│   └── cover-not-found.jpg
├── .env.example
├── .gitignore
├── README.md
└── requirements.txt

Data Pipeline

The datasets in data/ were produced by the Jupyter notebooks in notebooks/:

1. Data Exploration (data-exploration.ipynb) — cleans the raw Google Books dataset → books_cleaned.csv
2. Text Classification (text_classification.ipynb) — assigns simplified category labels → books_with_categories.csv
3. Sentiment Analysis (sentiment-analysis.ipynb) — computes per-book emotion scores → books_with_emotions.csv
4. Vector Search (vector_search.ipynb) — generates tagged_description.txt with ISBN-prefixed descriptions for embedding search