---
title: 📚 AI Semantic Book Recommender
emoji: 📖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "4.44.0"
app_file: app.py
pinned: false
---

# 📚 Semantic Book Recommender System

An intelligent **book recommendation and sentiment analysis system** built with **LangChain**, **Gradio**, and **Hugging Face Spaces**.  
This project combines **semantic text embeddings**, **vector search**, and **emotion-based NLP** to recommend books aligned with user preferences and emotional tone.

---

## 🚀 Features

- 🧠 **Semantic Book Search** using OpenAI embeddings + Chroma vector store  
- 💬 **Sentiment Analysis** of book descriptions or user reviews (anger, joy, fear, surprise, etc.)  
- 📖 **Category-based Filtering** (fiction, business, science, etc.)  
- ⚡ **Fast Inference UI** with Gradio and LangChain  
- ☁️ **Deployable on Hugging Face Spaces** via CI/CD  

---

## 🧩 Project structure

| File/Folder | Purpose | Status |
|-------------|---------|--------|
| **`app.py`** | Main Gradio Interface | **Core** |
| **`sentiment_analysis.py`** | Emotion Analysis (6 emotions) | **Core** |
| **`vector_search.py`** | ChromaDB Semantic Search | **Core** |
| **`text_classification/`** | Transformers Pipeline | **Core** |
| **`data/`** | 7k Books | **4.14MB** |
| **`requirements.txt`** | Dependencies | **Pinned** |
| **`.env.example`** | API Keys Template | **Copy me** |
| **`README.md`** | Setup Guide | **You're here** |

## 🛠️ Tech Stack

| Component | Technology | Version | Purpose |
|-----------|------------|---------|---------|
| **UI Framework** | Gradio | `^4.44.0` | Interactive dashboard with Glass theme |
| **Embeddings** | OpenAI | `text-embedding-3-small` | Semantic text understanding (1536 dims) |
| **Vector Database** | Chroma | `^0.5.0` | Fast similarity search & storage |
| **NLP Pipeline** | Transformers + LangChain | `^4.40.0` | Emotion detection & text processing |
| **Visualization** | Seaborn + Matplotlib | `^0.13.2` | Emotion charts & recommendation graphs |
| **CI/CD** | GitHub Actions + HF Spaces | Latest | Auto-deployment to cloud |
| **Containerization** | Docker | `^24.0` | Local dev & production consistency |
| **Environment** | Python | `3.10+` | Core runtime |
| **Data Processing** | Pandas | `^2.2.0` | CSV handling & preprocessing |
| **API Client** | OpenAI + HF Hub | Latest | Model inference |

**💡 Pro Tip:** All dependencies are pinned for reproducibility!

---

## ⚙️ Quick Start

### Prerequisites
- Python 3.10+
- Git
- [OpenAI API Key](https://platform.openai.com/account/api-keys)
- [Hugging Face Token](https://huggingface.co/settings/tokens)

### 1️⃣ Clone Repository
```bash
git clone https://github.com/thphuc273/semantic-book-recommender.git
cd semantic-book-recommender
```

### 2️⃣ Set up Environment
```bash
# Copy template
cp .env.example .env
```

Edit `.env` file:
```
OPENAI_API_KEY=sk-your-openai-key-here
HF_TOKEN=hf_your-huggingface-token
```

### 3️⃣ Install Dependencies
```bash
# Create virtual environment (recommended)
python -m venv venv

# Activate
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# Install everything
pip install -r requirements.txt
```
### 4️⃣ Download Dataset

[Kaggle dataset](https://www.kaggle.com/datasets/dylanjcastillo/7k-books-with-metadata)

### 5️⃣ Launch App
```
python app.py
```

✅ Opens: http://127.0.0.1:7860
✅ Hugging Face Space: https://huggingface.co/spaces/Felix272/Book-Recommender-System