Spaces:
Sleeping
Sleeping
| 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. |