README.md

---
title: BookMatch AI - Python | GeminiAPI
emoji: 📚
colorFrom: purple
colorTo: blue
sdk: docker
app_port: 7860
license: mit
pinned: true
short_description: Assistente literário com IA, Python e Flask.
---

# 📚 BookMatch AI

**Seu Assistente Literário Inteligente.**

O **BookMatch AI** é uma aplicação web interativa que utiliza Inteligência Artificial Generativa para oferecer recomendações de livros personalizadas e conversas profundas sobre literatura. Desenvolvido como um projeto de portfólio Full-Stack, ele demonstra a integração prática entre **Python**, **Flask** e a **Google Gemini API**.

👉 **[Teste a aplicação ao vivo no Hugging Face Spaces](https://huggingface.co/spaces/vioott/BookMatchAI-Python-GeminiAPI)**

---

## ✨ Funcionalidades Principais

*   **🤖 Seleção Dinâmica de IA:** O sistema consulta a API do Google em tempo real para listar e utilizar os modelos Gemini mais recentes (como *Gemini 2.5 Flash*, *2.0 Flash*, etc.), adaptando-se automaticamente a atualizações da Google.
*   **👤 Perfil Personalizado:** Criação de perfil com nome e preferências de gênero literário (Terror, Romance, Ficção, etc.) que influenciam a personalidade e as respostas da IA.
*   **💬 Chat Interativo:** Interface de chat moderna e responsiva para conversar sobre livros, autores e histórias.
*   **⚡ Performance Otimizada:** Implementação de **Cache (TTL)** para evitar chamadas redundantes à API e garantir carregamento rápido da lista de modelos.
*   **🛡️ Logs:** Tratamento avançado de erros (incluindo esgotamento de cota da API) e sistema de logs persistentes que mantém o histórico de conversas e preferências mesmo após reinício do servidor.
*   **🎨 UI/UX Profissional:** Modal de boas-vindas informativo, feedback visual de carregamento ("Aguarde..."), validação de formulários e design responsivo.

## 🛠️ Stack Tecnológica

*   **Backend:** Python 3.10+, Flask (Microframework Web).
*   **Inteligência Artificial:** Google Gemini API (`google-generativeai`).
*   **Frontend:** HTML5, CSS3 (com design system próprio e responsivo), JavaScript.
*   **Infraestrutura:** Docker (Containerização), Gunicorn (Servidor WSGI), Hugging Face Spaces (Hospedagem).
*   **Bibliotecas Chave:**
    *   `google-generativeai`: Integração com LLMs.
    *   `cachetools`: Cache em memória para otimização.
    *   `python-dotenv`: Gerenciamento seguro de variáveis de ambiente.

## 🚀 Como Executar Localmente

1. Clone o repositório e entre na pasta do projeto.
```
git clone https://github.com/ioott/bookmatch-ai-python-geminiAPI.git
cd bookmatch-ai-python-geminiAPI
```

2. Crie e ative um ambiente virtual.
```
python -m venv venv
# No Windows: venv\Scripts\activate
# No Linux/Mac: source venv/bin/activate
```

3. Instale as bibliotecas necessárias.
```
pip install -r requirements.txt
```

4. Crie um arquivo `.env` com sua chave da API Gemini:

   ```
   GOOGLE_API_KEY=sua-chave-aqui
   ```

5.  **Execute a aplicação:**
    ```
    python app.py
    ```
    Acesse `http://localhost:5000` no seu navegador.

## 📂 Estrutura do Projeto

*   `app.py`: Ponto de entrada da aplicação Flask.
*   `routes/`: Módulos de rotas (Home, Chat, Perfil) seguindo padrão MVC.
*   `services/`: Lógica de negócio e integração com a IA (`genai_service.py`).
*   `templates/`: Arquivos HTML Jinja2.
*   `static/`: Arquivos CSS e assets.
*   `logs.py`: Sistema customizado de persistência de dados em arquivo.

## 🧠 Sobre o projeto

Este projeto foi criado como solução para o exercício "Implementando um 'If Mágico' em uma Aplicação de E-commerce", do curso "IA para Programação com Python", da [Trybe](https://www.betrybe.com/), para explorar aplicações de IA generativa na recomendação literária, com foco em UX, personalização e uso real de modelos LLM.

---

Desenvolvido por **Vania Ioott** – Full-Stack Developer & AI Enthusiast.