# 📘 Book Recommender

## 📝 Description
This project builds a **Book Recommendation System** powered by **Generative AI** and the **Model Context Protocol (MCP)**.  
It uses real data from the **Goodreads dataset** (via Kaggle) and combines Python-based data processing with an AI agent capable of understanding user prompts, translating genres, and recommending books based on **genre**, **page count**, and **ratings**.

The project was developed collaboratively to practice version control, team workflows, and AI tool integration in a real-world Data Science scenario.

---

## ⚙️ Technologies and Tools Used
- **Python 3.11**
- **pandas** – data manipulation  
- **numpy** – numerical operations  
- **tqdm** – progress tracking  
- **OpenAI API** – language model for the AI agent  
- **LangGraph** – for building the ReAct-style reasoning agent  
- **MCP (Model Context Protocol)** – connects the AI agent to external tools  
- **Jupyter Notebook** – exploratory data analysis and prototyping  

---

## 💻 How to Run the Project

Step-by-step instructions to run it locally:

```
# Clone the repository
git clone https://github.com/nalugomesv/book-recommender.git

# Enter the project folder
cd book-recommender

# (Optional) Create a virtual environment
python -m venv .venv
.\.venv\Scripts\activate    # Windows
# or
source .venv/bin/activate   # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Run the core script
python -m src.buscador --genero "romance" --paginas 120

# Or search by title
python -m src.buscador --titulo "Dune"
```
---

## 🧩 Project Structure
.

├── src/

│   ├── buscador.py         # Core search functions (genre,  pages, title)

│   └── server_mcp.py       # Local MCP server exposing tools to the AI agente

├── notebooks/              # Exploratory and test notebooks

├── data/                   # Dataset (not versioned)

├── outputs/                # Generated artifacts (ignored)

├── .env.example            # Environment variable example

├── requirements.txt        # Dependencies

└── README.md               # Project documentation

---

## 👥 Collaborators

⦁	Ana Luiza Gomes Vieira (@nalugomesv)
⦁	Arthur Mendes Fernandes (@thuplex)

---

## 🎯 Future Improvements

- Add more filtering options (author, publication year, etc.)
- Integrate external MCP APIs (HTTP/SSE)
- Add evaluation metrics (Precision@K, MAP)
- Improve LLM reasoning prompts for more accurate recommendations

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).

---

## 🧠 Acknowledgments

This project was inspired by the **PrograMaria – Data & Generative AI Sprint**,  
specifically the *Workshop on Predictive Query Models (MCP)* and *Book Recommendation System using Generative AI*.