1- ## 🔥 BookSage AI
1+ # 🔥 ** BookSage AI**
22
3- ** Multi-Method Book Recommendation System**
3+ ** Multi-Method Book Recommendation System** Provide personalized book recommendations by combining ** Collaborative Filtering** and ** Content-Based Filtering** techniques, ensuring high accuracy even when user interaction data is sparse.
4+
5+ [ ![ BookSage AI] ( https://github.com/user-attachments/assets/ab5d829d-76b1-4207-bb08-442a0eacb684 )] ( https://github.com/user-attachments/assets/ab5d829d-76b1-4207-bb08-442a0eacb684 )
6+
7+ ---
8+
9+ ## 🎯 ** Project Goal**
10+ In today’s digital era, readers are overwhelmed with millions of book options across various platforms, making it difficult to find books aligned with their interests, preferences, or past reading history. Traditional search-based discovery methods fall short in providing personalized and engaging reading suggestions.
11+
12+ To address this challenge, the goal is to design and implement a ** personalized hybrid book recommendation system** that leverages both ** collaborative filtering** (based on user behavior and ratings) and ** content-based filtering** (based on book metadata like author, publisher, and year). The system should support:
13+
14+ * Image-based output (for UI-friendly recommendations),
15+ * A fallback mechanism for cold-start scenarios,
16+ * Adjustable weights for hybrid scoring,
17+ * Scalable performance for large datasets.
18+
19+ ---
20+
21+ ## 🌐 ** Live Demo**
22+
23+ 🔗 ** Try the Hybrid Book Recommendation System live:**
24+ 👉 [ https://booksage-ai.onrender.com/ ] ( https://booksage-ai.onrender.com/ )
25+
26+ ---
27+
28+ ## 🧠 ** Core Technologies**
29+
30+ | ** Category** | ** Technology/Resource** |
31+ | ----------------------------| ----------------------------------------------------------------------------------------|
32+ | ** Core Framework** | Python 3.9+, Pandas, NumPy |
33+ | ** Data Processing** | Pandas (Data Cleaning), scikit-learn (Feature Engineering) |
34+ | ** Recommendation Models** | Hybrid System: Collaborative Filtering + Content-Based Filtering |
35+ | ** Collaborative Filtering** | Scipy (csr_matrix), sklearn.neighbors (NearestNeighbors) |
36+ | ** Content-Based Filtering** | sklearn (TfidfVectorizer, cosine_similarity) |
37+ | ** Data Sources** | Book-Crossing Dataset (BX-Books, BX-Users, BX-Ratings) |
38+ | ** Feature Engineering** | TF-IDF (Title+Author+Publisher+Year combined features) |
39+ | ** Model Persistence** | Pickle (Model Serialization) |
40+ | ** Evaluation Metrics** | Implicit (Rating counts, Popularity filtering) |
41+ | ** Deployment Ready** | Modular functions with error handling and fallback mechanisms |
442
5- ![ Image] ( https://github.com/user-attachments/assets/bc72c776-4cc8-4966-a678-00efaee64334 )
643---
744
8- ## 🎯 Project Goal
45+ ## ⚖️ ** Comparison with Standard Systems **
946
10- Provide personalized book recommendations by combining ** Collaborative Filtering** and ** Content-Based Filtering** techniques, ensuring high accuracy even when user interaction data is sparse.
47+ | Feature | BookSage AI | Typical Recommenders |
48+ | ---------| ------------| ----------------------|
49+ | Method Flexibility | ✅ 3 modes + hybrid tuning | ❌ Usually single-method |
50+ | Cold Start Handling | ✅ Popular books fallback | ❌ Often fails |
51+ | Explainability | ✅ Shows scores + metadata | ❌ Black-box results |
52+ | UI Customization | ✅ Adjustable weights/counts | ❌ Fixed parameters |
1153
1254---
1355
14- # 📂 Project Structure for ** BookSage AI**
56+ ## 📂 Project Structure for ** BookSage AI**
1557
1658``` bash
1759BookSage-AI/
1860│
19- ├── app /
61+ ├── src /
2062│ ├── __init__.py
2163│ ├── config.py
2264│ ├── data_loader.py
@@ -52,69 +94,29 @@ BookSage-AI/
5294├── README.md # Project Documentation
5395├── .gitignore # Files/folders to ignore in GitHub repo
5496├── app.png # Demo
97+ ├── demo.webm # Demo Video
5598│
5699└── LICENSE # License
57100```
58101
59102---
60103
61- ## 🧠 Core Technologies
62-
63- | Technology | Purpose |
64- | ---------------------| --------------------------------------------|
65- | Python 3.11 | Core Programming Language |
66- | Streamlit | Frontend Web Application Framework |
67- | Scikit-learn | Machine Learning Model Building |
68- | Pandas, NumPy | Data Manipulation |
69- | Docker | Containerization |
70- | GitHub Actions | CI/CD Automation |
71- | Logging (Python) | Application Monitoring |
72-
73- ---
74-
75- ## 📦 Major Components
76-
77- | Component | Description |
78- | --------------------------------| --------------------------------------------------------------|
79- | Data Loader | Data reading and preprocessing |
80- | Content-Based Recommender | Recommend books based on metadata similarities |
81- | Collaborative Filtering Engine | Recommend books based on user preferences |
82- | Hybrid Recommendation Engine | Combines content-based and collaborative outputs |
83- | Streamlit Frontend | Interactive UI for Book Recommendations |
84- | Centralized Logger | Real-time Monitoring and Debugging Support |
85- | CI/CD Pipeline (GitHub Actions)| Automated Testing, Docker Build, Deployment Automation |
86-
87- ---
88-
89- ## 🌐 Deployment Plan
90-
91- ### Local Development
92-
93- - Virtual Environment setup
94- - Running via ` main run `
95- - Local Logging for debugging
96-
97- ### Dockerized Deployment
98-
99- - Dockerfile included
100- - Docker Build and Run commands
101- - Ideal for consistent environments across development, staging, and production.
102-
103- ### CI/CD Pipeline (Implemented)
104-
105- - ** GitHub Actions Workflow** :
106- - On Push or Pull Request:
107- - Linting and Code Quality Checks
108- - Run Unit Tests (Optional pytest Integration)
109- - Build Docker Image
110- - Push to DockerHub (Private/Public Repo)
111- - Deploy to Cloud (Future ready)
112-
113- > ✅ Future Scope: Auto-deploy to AWS ECS / Azure App Service / GCP Cloud Run.
104+ ### 🧬 ** Architecture Diagram (Mermaid)**
105+ ``` mermaid
106+ graph TD
107+ A[Raw Data] --> B[Data Preprocessing]
108+ B --> C[Collaborative Filtering Model]
109+ B --> D[Content-Based Model]
110+ C --> E[User-Item Matrix]
111+ D --> F[TF-IDF Features]
112+ E --> G[Hybrid Recommender]
113+ F --> G
114+ G --> H[Recommendation via Streamlit]
115+ ```
114116
115117---
116118
117- ## 🛠️ How to Setup (Locally)
119+ ## 🛠️ ** How to Setup (Locally)**
118120
119121``` bash
120122# Clone the Repository
@@ -134,7 +136,7 @@ streamlit run main.py
134136
135137---
136138
137- ## 🐳 How to Setup (Dockerized)
139+ ## 🐳 ** How to Setup (Dockerized)**
138140
139141``` bash
140142# Clone the Repository
@@ -150,33 +152,7 @@ docker run -p 8501:8501 booksage-ai
150152
151153---
152154
153- ## 🛡️ Logging Mechanism
154-
155- - Centralized Logger module with customizable Log Levels
156- - Logs critical events like data loading issues, recommendation failures, server errors
157- - Supports both ** Console Output** and ** File Saving**
158-
159- Example Usage:
160- ``` python
161- from app.logger import get_logger
162- logger = get_logger()
163-
164- logger.info(" User requested new book recommendations."
165- logger.error(" Failed to generate collaborative recommendations."
166- ```
167-
168- ---
169-
170- ## 🧪 Test Setup (Optional)
171-
172- - Currently no pytest implemented.
173- - Future Scope:
174- - Add Unit Tests for each recommender engine.
175- - Integrate Test Execution in CI/CD.
176-
177- ---
178-
179- ## ⚙️ CI/CD Pipeline (Full Flow)
155+ ## ⚙️ ** CI/CD Pipeline (Full Flow)**
180156
181157| Step | Tool | Purpose |
182158| ---------------------------------| ---------------| --------------------------------------|
@@ -187,64 +163,9 @@ logger.error("Failed to generate collaborative recommendations.")
187163| Push Image to DockerHub | GitHub Actions| Automatic Push after Build |
188164| Deploy to Server (future ready) | GitHub Actions| Auto-deploy on Cloud or VPS server |
189165
190- ---
191- ** Sample GitHub Actions Workflow (` .github/workflows/main.yml ` )**
192- ``` yaml
193- name : Docker Image CI-CD
194-
195- on :
196- push :
197- branches : [ "master" ]
198- pull_request :
199- branches : [ "master" ]
200-
201- jobs :
202- build :
203-
204- runs-on : ubuntu-latest
205-
206- steps :
207- - name : Checkout code
208- uses : actions/checkout@v3
209-
210- - name : Set up Python
211- uses : actions/setup-python@v4
212- with :
213- python-version : ' 3.x'
214-
215- - name : Set up Docker Buildx
216- uses : docker/setup-buildx-action@v2
217-
218- - name : Cache Docker layers
219- uses : actions/cache@v3
220- with :
221- path : /tmp/.buildx-cache
222- key : ${{ runner.os }}-buildx-${{ github.sha }}
223- restore-keys : |
224- ${{ runner.os }}-buildx-
225-
226- name : Build Docker image
227- run : docker build -t BookSage-AI .
228-
229- - name : Test the application (Run tests inside container)
230- run : docker run --rm BookSage-AI pytest tests/
231- ` ` `
232-
233166---
234167
235- ## 📑 Extra Features
236-
237- | Feature | Details |
238- |-----------------------------|------------------------------------------------------|
239- | Adjustable Weighting | User can adjust importance between Collaborative vs Content-Based results dynamically |
240- | Popularity Fallback System | If recommendation engines fail, fallback to Top-rated Books |
241- | Modular Code Structure | Easier Maintenance and Testing |
242- | Scalability Ready | Optimized for future Cloud Hosting |
243-
244- ---
245-
246-
247- # 🚀 Conclusion
168+ ## 🚀 ** Conclusion**
248169
249170The ** Hybrid Book Recommendation System** is a ** production-ready, scalable** , and ** cloud-deployable** application blending the strengths of multiple recommendation techniques, backed by a complete CI/CD pipeline ensuring continuous improvement and smooth deployments.
250171
@@ -256,7 +177,7 @@ The **Hybrid Book Recommendation System** is a **production-ready, scalable**, a
256177📧 ** Email:** iconicemon01@gmail.com
257178💬 ** WhatsApp:** [ +8801834363533] ( https://wa.me/8801834363533 )
258179🔗 ** GitHub:** [ Md-Emon-Hasan] ( https://github.com/Md-Emon-Hasan )
259- 🔗 **LinkedIn:** [Md Emon Hasan](https://www.linkedin.com/in/md-emon-hasan)
180+ 🔗 ** LinkedIn:** [ Md Emon Hasan] ( https://www.linkedin.com/in/md-emon-hasan-695483237/ )
260181🔗 ** Facebook:** [ Md Emon Hasan] ( https://www.facebook.com/mdemon.hasan2001/ )
261182
262- ---
183+ ---
0 commit comments