README.md

metadata

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:

{
  "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:

# 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 for details.

---

🙏 Acknowledgments

• r/BooksThatFeelLikeThis — The incredible community whose posts power our dataset
• Gradio MCP Hackathon
• Nebius — VLM, LLM, and embedding models for data annotation and runtime inference
• ElevenLabs — AI soundtrack generation
• Modal — Serverless vector store deployment
• Google Books API — Book metadata enrichment

---

Made with 📚 for the Gradio MCP Hackathon

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