---
title: Vibe Reader
emoji: 🌖
colorFrom: pink
colorTo: purple
video_url: https://drive.google.com/file/d/1jOWFS0rabZ5xz2cGjxOeH2aehER5vcDX/view?usp=drive_link
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
short_description: Describe your new favorite book through vibes
tags:
- mcp-in-action-track-creative
- anthropic
- nebius
- modal
- elevenlabs
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/68e96851533d31433431a2ec/ESKQKv-qfPO3p0XB8j4rf.webp
---

# 📚 The Vibe Reader

## Demo video link: https://drive.google.com/file/d/1jOWFS0rabZ5xz2cGjxOeH2aehER5vcDX/view?usp=sharing
## Social media post: https://x.com/notesfromcleo/status/1995278197840400619

> *Upload images that capture a mood. Get books that feel the same way.*

The Vibe Reader is an AI-powered book recommendation engine that understands **aesthetics, not just genres**. Upload a mood board, a painting, a cozy photo, or any image that captures the feeling you want from your next read—and discover books that match that vibe.

**🏆 Built for the HuggingFace x Gradio MCP Hackathon**

## 🎯 The Problem

Traditional book recommendations fail when you can't articulate what you want:

- **"I want something that feels like a rainy afternoon in an old library"** — Good luck searching that on Goodreads
- **Genre fatigue**: You don't want "fantasy" or "romance"—you want a *specific feeling*
- **Visual inspiration**: You found the perfect aesthetic on Pinterest but can't translate it to books
- **Discovery paralysis**: Too many options, no way to filter by *vibe*

## ✨ The Solution

The Vibe Reader bridges the gap between visual aesthetics and literary recommendations:

1. **🎨 Upload Your Vibe** — Share 1-5 images that capture the mood you're seeking
2. **🔮 AI Analysis** — Vision AI extracts aesthetic keywords, mood, themes, and tropes
3. **💬 Conversational Refinement** — Chat to fine-tune the vibe description
4. **📚 Semantic Search** — Query a vector database of 50k+ book-vibe associations
5. **🎯 Smart Narrowing** — Answer quick either/or questions to find your perfect match
6. **🎵 Bonus: Vibe Soundtrack** — Get an AI-generated ambient track for your reading session

---

## 📊 The Dataset: Building a Vibe-to-Book Knowledge Base

A core contribution of this project is the **data pipeline** that transforms Reddit's r/BooksThatFeelLikeThis community into a structured, searchable recommendation dataset.
1
### Data Collection Pipeline (not included in the Space)

```
Reddit Posts (1,500+ with images)
         │
         ▼
┌─────────────────────────────────┐
│  1. scrape_subreddit        │  ← Reddit API (PRAW)
│     Collect posts + comments    │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  2. extract_vibes           │  ← Nebius VLM (Gemma 3 27B)
│     Analyze images → vibe JSON  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  3. extract_books           │  ← Anthropic LLM (Claude Haiku)
│     Parse comments → book list  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  4. fetch_google_books      │  ← Google Books API
│     Enrich with metadata        │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  5. build_vector_index      │  ← Nebius Embeddings (Qwen3-Embedding-8B)
│     Generate embeddings + FAISS │
└─────────────────────────────────┘
         │
         ▼
    Vector Store (Modal)
    50k+ book-vibe associations
```

### What Each Step Produces

| Step | Input | Output | AI Used |
|------|-------|--------|---------|
| **Scrape** | r/BooksThatFeelLikeThis | Posts with images + nested comments | — |
| **Extract Vibes** | Post images | Structured vibe JSON (aesthetics, mood, themes, tropes) | **Nebius** Gemma 3 27B |
| **Extract Books** | Comment threads | Book titles + authors |  **Anthropic** Claude Haiku  4.5 |
| **Fetch Metadata** | Book list | Covers, descriptions, ISBNs, ratings | Google Books API |
| **Build Index** | Vibes + Books | FAISS vector index | **Nebius** Qwen3-Embedding-8B |

### Vibe Data Structure

Each post is annotated with rich vibe metadata:

```json
{
  "aesthetic_genre_keywords": ["Dark Academia", "Gothic", "Victorian"],
  "mood_atmosphere": ["Melancholic", "Mysterious", "Atmospheric"],
  "core_themes": ["Isolation", "Obsession", "Hidden knowledge"],
  "tropes": ["Unreliable narrator", "Secret society", "Forbidden library"],
  "feels_like": "A haunting exploration of obsession set in the dusty halls of an ancient university, where every shadow holds secrets and the pursuit of knowledge comes at a terrible price..."
}
```

---

## 🏗️ Runtime Architecture

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Gradio UI      │────▶│  LangGraph Agent │────▶│  Modal Vector   │
│  (Upload/Chat)  │     │  (Orchestration) │     │  Store (FAISS)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│  Nebius VLM     │   │  Google Books   │   │  ElevenLabs     │
│  (Gemma 3 27B)  │   │  MCP Server     │   │  MCP Server     │
└─────────────────┘   └─────────────────┘   └─────────────────┘
```





## 🔌 MCP Server Integration

The Vibe Reader uses **one MCP server** built with Gradio:

### Google Books MCP Server
Provides book metadata enrichment via the Gradio MCP protocol:
- Search by title + author
- Retrieve covers, descriptions, ISBNs
- Deployed on Hugging Face Spaces

## Other integrations

### ElevenLabs API
Generates ambient soundtracks that match your reading vibe:
- AI-composed background music
- Mood-matched audio generation
- 1min30-second ambient tracks

---

## ⚙️ Configuration

Required variables if you want to run this elsewhere:

```bash
# Required: Nebius API for VLM + LLM + Embeddings
NEBIUS_API_KEY=your_key_here

# Required: Modal vector store URL
MODAL_VECTOR_STORE_URL=https://your-modal-app.modal.run/search

# Required: Google Books MCP
GOOGLE_BOOKS_MCP_URL=https://your-space.hf.space

# Optional: ElevenLabs for soundtracks
ELEVENLABS_API_KEY=your_key_here

```

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- **[r/BooksThatFeelLikeThis](https://reddit.com/r/BooksThatFeelLikeThis)** — The incredible community whose posts power our dataset
- **[Gradio MCP Hackathon](https://gradio.app)** 
- **[Nebius](https://nebius.com)** — VLM, LLM, and embedding models for data annotation and runtime inference
- **[ElevenLabs](https://elevenlabs.io)** — AI soundtrack generation
- **[Modal](https://modal.com)** — Serverless vector store deployment
- **[Google Books API](https://developers.google.com/books)** — Book metadata enrichment

---

Made with 📚 for the Gradio MCP Hackathon

*"Every book has a vibe. Now you can search by it."*