How swuzz123/book-recommendation works
Project Type and Purpose
• This is a full‐stack, explainable book recommendation system powered by large language models (LLMs), semantic embeddings, zero‐shot classification, and emotion detection.
• Users interact via a Gradio dashboard; behind the scenes, the app ingests book metadata, transforms and indexes it, and exposes an API to answer natural‐language queries and return personalized book suggestions.
File‐Structure Analysis
• Root
• .gitignore, README.md, requirements.txt, .env (runtime configuration for HF_TOKEN)
• app/
• gradio-dashboard.py → entry point for the interactive UI and orchestrator of backend functions
• demo/
• demo_app.mp4, UI_demo.png, demo GIF → screenshots/videos for documentation
• src/
• Jupyter notebooks for each pipeline stage:
– data‐exploration.ipynb (cleaning & feature engineering → books_cleaned.csv)
– vector‐search.ipynb (Hugging Face embeddings + ChromaDB storage)
– text‐classification.ipynb (zero‐shot genre classification → books_with_categories.csv)
– sentiment‐analysis.ipynb (emotion detection → books_with_emotions.csv)
– tagged_description.txt (preprocessed text snippets)
README Insights
• Four major processing stages: data cleaning, semantic embedding & retrieval, genre classification, emotion analysis
• Core technologies: Python 3.10+, Hugging Face transformers + embeddings, LangChain, ChromaDB, Gradio
• External dependency: Hugging Face API (authenticated via HF_TOKEN)
• Final user interface: a Gradio web app that ties all processing modules together
a. Main Components
• User Interface (Gradio Dashboard)
• Orchestrator / API Layer (app/gradio-dashboard.py)
• Data Processing Modules:
– Embedding Service (sentence-transformers + LangChain splitter)
– Vector Store (ChromaDB)
– Genre Classification Service (zero-shot bart-large-mnli)
– Emotion Detection Service (fine-tuned RoBERTa)
• Data Stores:
– Cleaned CSVs (books_cleaned.csv, books_with_categories.csv, books_with_emotions.csv)
– Chroma vector database
• External Services:
– Hugging Face model hub
– (Optionally) source Kaggle dataset
b. Relationships & Data Flow
1. User submits natural-language query via Gradio UI
2. Orchestrator retrieves relevant embeddings from ChromaDB
3. Maps vectors to book metadata (CSV storage)
4. Calls zero-shot classification to label genre
5. Calls emotion-detection to score tone
6. Aggregates results and returns ranked recommendations to UI
c. Architectural Patterns
• Modular pipeline structure (separate concerns for embedding, classification, emotion)
• Service‐oriented approach within a monolith (each “service” can be refactored to microservice)
• Vector-search as a specialized data layer
• Layered pattern: Presentation (UI) → Application (orchestrator) → Domain services → Persistence
d. Key Technologies & Libraries
• Python + Gradio for UI & orchestration
• Hugging Face Transformers for LLM tasks
• sentence-transformers + LangChain for text splitting and embedding
• ChromaDB for vector storage & retrieval
• pandas/CSV for tabular metadata storage