README.md

metadata

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

---

✨ 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, 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.