README.md

metadata

title: Vibe Reader
emoji: 🌖
colorFrom: pink
colorTo: purple
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

📚 The Vibe Reader

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.

Data Collection Pipeline

Reddit Posts (1,500+ with images)
         │
         ▼
┌─────────────────────────────────┐
│  1. scrape_subreddit.py         │  ← Reddit API (PRAW)
│     Collect posts + comments    │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  2. extract_vibes.py            │  ← Nebius VLM (Gemma 3 27B)
│     Analyze images → vibe JSON  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  3. extract_books.py            │  ← Anthropic LLM (Claude Haiku)
│     Parse comments → book list  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  4. fetch_google_books.py       │  ← Google Books API
│     Enrich with metadata        │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  5. build_vector_index.py       │  ← 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	Nebius Qwen 3 30B
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:

{
  "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     │
└─────────────────┘   └─────────────────┘   └─────────────────┘

Project Structure

vibe-reader/
├── app/                        # Main application
│   ├── app.py                  # Gradio interface
│   ├── agent.py                # LangGraph workflow with interrupts
│   ├── prompts.py              # LLM prompt templates
│   ├── utils.py                # Helper functions
│   └── custom.css              # Styling
├── google_books_mcp_2/         # Google Books MCP server
│   └── app.py                  # Gradio MCP implementation
├── modal_app/                  # Vector store deployment
│   ├── build_vector_index.py   # Index builder
│   └── vector_store.py         # Modal serverless endpoint
├── scripts/                    # Data pipeline
│   ├── scrape_subreddit.py     # Reddit data collection
│   ├── extract_vibes.py        # VLM vibe extraction
│   ├── extract_books.py        # LLM book extraction
│   ├── fetch_google_books.py   # Metadata enrichment
│   └── clean_vibes.py          # Data cleaning
└── docs/                       # Documentation
    ├── DATA_PIPELINE.md        # Detailed pipeline guide
    ├── ARCHITECTURE.md         # System design
    └── AGENT_FLOW.md           # LangGraph workflow

🔌 MCP Server Integration

The Vibe Reader uses two MCP servers 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

ElevenLabs MCP Server

Generates ambient soundtracks that match your reading vibe:

• AI-composed background music
• Mood-matched audio generation
• 30-second ambient tracks

---

⚙️ Configuration

Copy .env.example to .env and configure:

# 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."*