Spaces:
Sleeping
Sleeping
| title: Semantic Book Recommender | |
| emoji: 📚 | |
| colorFrom: blue | |
| colorTo: purple | |
| sdk: gradio | |
| sdk_version: 5.33.1 | |
| app_file: app.py | |
| pinned: false | |
| license: mit | |
| # Smart Book Recommender 📚 | |
| An intelligent book recommendation system with dual search modes: semantic understanding and flexible literal matching. Features emotional tone analysis, category filtering, and a responsive web interface built with LangChain, ChromaDB, and Gradio. | |
| ## 🚀 [Try the Live Demo](https://huggingface.co/spaces/nonsodev/semantic-book-recommender) | |
|  | |
| ## ✨ Key Features | |
| ### 🔍 **Dual Search Modes** | |
| - **Semantic Search**: AI-powered understanding of natural language queries (e.g., "fantasy adventure with magic") | |
| - **Literal Search**: Flexible keyword matching with partial word support (e.g., "harry" → Harry Potter books) | |
| ### 🎯 **Smart Filtering** | |
| - **Category Filtering**: Browse by specific book genres | |
| - **Emotional Tone Matching**: Find books by emotional experience (Happy, Surprising, Angry, Suspenseful, Sad) | |
| - **Intelligent Sorting**: Results ranked by relevance and emotional scores | |
| ### 🎨 **Modern Interface** | |
| - Responsive card-based design with book covers | |
| - Star ratings and reader statistics | |
| - Direct download links when available | |
| - Dark theme optimized for reading | |
| ### ⚡ **Performance Optimized** | |
| - Cached embedding models for fast startup | |
| - Efficient ChromaDB vector database | |
| - Fallback image handling for missing covers | |
| - Robust error handling and regex search | |
| ## Installation | |
| ### Prerequisites | |
| - Python 3.8+ | |
| - pip package manager | |
| ### Quick Setup | |
| 1. **Clone the repository** | |
| ```bash | |
| git clone https://github.com/nonsodev/semantic-book-recommender.git | |
| cd semantic-book-recommender | |
| ``` | |
| 2. **Install dependencies** | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 3. **Ensure required data files** | |
| ``` | |
| ├── final_book_df.csv # Main book dataset | |
| ├── tagged_description.txt # Book descriptions for embedding | |
| └── chroma_books/ # Vector database (auto-created) | |
| ``` | |
| 4. **Run the application** | |
| ```bash | |
| python app.py | |
| ``` | |
| ## Usage Guide | |
| ### Search Modes | |
| #### 🧠 **Semantic Search** | |
| Perfect for describing what you want in natural language: | |
| - "Dark fantasy with dragons and magic" | |
| - "Romantic comedy set in Paris" | |
| - "Thrilling mystery in Victorian London" | |
| - "Science fiction about artificial intelligence" | |
| #### 🔤 **Literal Search** | |
| Best for finding specific titles or authors: | |
| - "harry" → finds Harry Potter books | |
| - "tolkien" → finds J.R.R. Tolkien works | |
| - "game thrones" → finds Game of Thrones | |
| - "stephen king" → finds Stephen King novels | |
| ### Advanced Features | |
| #### **Category Filtering** | |
| Narrow results by genre: | |
| - Fiction, Non-fiction, Fantasy, Romance, Mystery, etc. | |
| #### **Emotional Tone Matching** | |
| Find books by mood: | |
| - **Happy**: High joy scores | |
| - **Surprising**: High surprise scores | |
| - **Angry**: High anger scores | |
| - **Suspenseful**: High fear scores | |
| - **Sad**: High sadness scores | |
| ## How It Works | |
| ### 🔬 **Semantic Search Engine** | |
| ```python | |
| # Uses sentence-transformers for embedding generation | |
| embeddings = HuggingFaceEmbeddings( | |
| model_name="sentence-transformers/all-MiniLM-L6-v2", | |
| model_kwargs={'device': 'cpu'}, | |
| encode_kwargs={'normalize_embeddings': True} | |
| ) | |
| # ChromaDB for efficient similarity search | |
| db_books = Chroma.from_documents( | |
| documents, embedding=embeddings, | |
| collection_name="books", persist_directory="chroma_books" | |
| ) | |
| ``` | |
| ### 🔍 **Flexible Literal Search** | |
| ```python | |
| # Intelligent regex pattern matching | |
| def retrieve_literal_recommendations(query, category=None, tone=None): | |
| # Creates flexible patterns for partial word matching | |
| # Handles special characters and multiple word combinations | |
| # Falls back to simple string matching if regex fails | |
| ``` | |
| ### 🎭 **Emotional Intelligence** | |
| Books are analyzed and scored across five emotional dimensions: | |
| - **Joy**: Happiness, humor, uplifting content | |
| - **Surprise**: Plot twists, unexpected elements | |
| - **Anger**: Conflict, tension, dramatic intensity | |
| - **Fear**: Suspense, thriller elements, mystery | |
| - **Sadness**: Emotional depth, tragic elements | |
| ### 🎨 **Smart UI Components** | |
| ```python | |
| def create_book_card_html(row): | |
| # Responsive card design with: | |
| # - Book cover with fallback handling | |
| # - Star ratings visualization | |
| # - Author formatting (handles multiple authors) | |
| # - Truncated descriptions with full content | |
| # - Download links when available | |
| ``` | |
| ## Project Structure | |
| ``` | |
| semantic-book-recommender/ | |
| ├── app.py # Main application (your updated file) | |
| ├── requirements.txt # Python dependencies | |
| ├── final_book_df.csv # Book dataset with metadata | |
| ├── tagged_description.txt # Book descriptions for embedding | |
| ├── chroma_books/ # ChromaDB vector database | |
| ├── demo.png # Interface screenshot | |
| └── README.md # This file | |
| ``` | |
| ## Configuration | |
| ### **Embedding Models** | |
| Switch between models for different performance profiles: | |
| ```python | |
| # Fast and efficient (default) | |
| "sentence-transformers/all-MiniLM-L6-v2" | |
| # Higher quality, slower | |
| "sentence-transformers/all-mpnet-base-v2" | |
| # Multilingual support | |
| "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2" | |
| ``` | |
| ### **Search Parameters** | |
| Customize recommendation behavior: | |
| ```python | |
| def retrieve_semantic_recommendations( | |
| query: str, | |
| initial_top_k: int = 50, # Initial retrieval size | |
| final_top_k: int = 8, # Final recommendations shown | |
| category: str = None, # Category filter | |
| tone: str = None # Emotional tone filter | |
| ) | |
| ``` | |
| ### **UI Customization** | |
| Modify card display and styling: | |
| ```python | |
| # Book card dimensions | |
| style="width: 80px; height: 120px" | |
| # Description truncation | |
| -webkit-line-clamp: 4 | |
| # Rating display | |
| create_star_rating(rating) # ★★★★☆ format | |
| ``` | |
| ## Data Schema | |
| ### Book Dataset Columns | |
| ```python | |
| # Core metadata | |
| 'isbn13', 'title_and_subtitle', 'authors', 'categories' | |
| # Visual elements | |
| 'thumbnail', 'large_thumbnail' | |
| # Ratings and metrics | |
| 'average_rating', 'ratings_count' | |
| # Content | |
| 'description' | |
| # Emotional scores | |
| 'joy', 'surprise', 'anger', 'fear', 'sadness' | |
| # Access | |
| 'url' # Download/purchase links | |
| ``` | |
| ## API Reference | |
| ### **Main Functions** | |
| ```python | |
| # Semantic search with AI understanding | |
| retrieve_semantic_recommendations(query, category, tone, initial_top_k, final_top_k) | |
| # Literal search with flexible matching | |
| retrieve_literal_recommendations(query, category, tone, final_top_k) | |
| # HTML card generation | |
| create_book_card_html(row) | |
| # Main Gradio interface function | |
| recommend_books(query, category, tone, search_type) | |
| ``` | |
| ## Dependencies | |
| ```python | |
| # Core ML and Vector Database | |
| langchain-chroma>=0.1.0 | |
| langchain-huggingface>=0.0.3 | |
| langchain-community>=0.2.0 | |
| sentence-transformers>=2.2.0 | |
| # Data Processing | |
| pandas>=1.5.0 | |
| numpy>=1.21.0 | |
| # Web Interface | |
| gradio>=4.0.0 | |
| # Text Processing | |
| regex>=2022.0.0 | |
| ``` | |
| ## Performance Tips | |
| ### **Startup Optimization** | |
| ```python | |
| # Model caching for faster restarts | |
| os.environ["HF_HOME"] = "/tmp/hf_cache" | |
| os.environ["TRANSFORMERS_CACHE"] = "/tmp/hf_cache" | |
| ``` | |
| ### **Search Optimization** | |
| - Use semantic search for exploratory queries | |
| - Use literal search for known titles/authors | |
| - Combine category and tone filters for precision | |
| - Try variations if initial results aren't satisfactory | |
| ### **Memory Management** | |
| - ChromaDB persists to disk automatically | |
| - Embeddings cached after first load | |
| - Efficient pandas operations for filtering | |
| ## Contributing | |
| 1. **Fork** the repository | |
| 2. **Create** a feature branch (`git checkout -b feature/amazing-feature`) | |
| 3. **Commit** changes (`git commit -m 'Add amazing feature'`) | |
| 4. **Push** to branch (`git push origin feature/amazing-feature`) | |
| 5. **Open** a Pull Request | |
| ### Development Areas | |
| - [ ] Additional emotional dimensions | |
| - [ ] Multi-language support | |
| - [ ] User preference learning | |
| - [ ] Social features (reviews, ratings) | |
| - [ ] Advanced filtering (publication year, page count) | |
| ## Troubleshooting | |
| ### **Common Issues** | |
| **ChromaDB not found:** | |
| ```bash | |
| # The app will auto-create from tagged_description.txt | |
| # Ensure this file exists in the project root | |
| ``` | |
| **Model download slow:** | |
| ```bash | |
| # Models cache automatically after first download | |
| # Subsequent starts will be much faster | |
| ``` | |
| **No search results:** | |
| ```bash | |
| # Try switching between search modes | |
| # Reduce filter constraints (category/tone) | |
| # Use broader search terms | |
| ``` | |
| ## License | |
| This project is licensed under the MIT License - see the LICENSE file for details. | |
| ## Acknowledgments | |
| - **Sentence Transformers** for powerful embedding models | |
| - **ChromaDB** for efficient vector storage and retrieval | |
| - **Gradio** for creating accessible ML interfaces | |
| - **LangChain** for seamless AI integration | |
| - **HuggingFace** for model hosting and ecosystem | |
| --- | |
| ## 🎯 Example Queries to Try | |
| ### Semantic Search | |
| - "Epic fantasy with complex magic systems" | |
| - "Cozy mystery in a small town setting" | |
| - "Hard science fiction about space exploration" | |
| - "Historical romance during the Regency era" | |
| ### Literal Search | |
| - "agatha christie" (find Agatha Christie novels) | |
| - "dune" (find Dune series books) | |
| - "pride prejudice" (find Pride and Prejudice) | |
| - "lord rings" (find Lord of the Rings) | |
| **Happy Reading! 📖✨** |