💰 Assistente de Finanças

Assistente inteligente de finanças para grupos utilizando IA generativa, arquitetura MCP (Model Context Protocol), integração com Gemini LLM, banco de dados MySQL e interface conversacional construída com Streamlit.

🎯 Objetivo do Projeto

Projeto desenvolvido como portfólio técnico para demonstrar habilidades em AI Agents, LLM Engineering, Arquitetura Backend, Integração de Dados e Design de Software.

💡 Problema que o Projeto Resolve

Grupos que compartilham despesas — como famílias, repúblicas ou times — frequentemente
perdem o controle dos gastos por falta de uma forma simples de consultar e entender
os dados financeiros. Planilhas são difíceis de navegar e dashboards exigem que o usuário saiba onde clicar.

Este assistente permite que qualquer pessoa do grupo faça perguntas em linguagem natural
como "Quanto gastamos em janeiro?" ou "De quanto foram os nossos gastos com leite este mês?" e receba respostas claras e instantâneas — sem precisar abrir uma planilha ou montar um filtro.

---

✨ Visão Geral

Este projeto demonstra a construção de um Agente de IA completo, capaz de responder perguntas sobre gastos financeiros utilizando dados reais armazenados em banco de dados.

O sistema integra:

• 🤖 Large Language Model (Google Gemini)
• 🧠 Agente inteligente para interpretação das perguntas
• 🔌 MCP Server para acesso estruturado aos dados
• 🗄️ Banco de dados MySQL local (administrado via MySQL Workbench)
• 🎨 Interface conversacional com Streamlit

🧠 O que este projeto demonstra

• Construção de AI Agent end-to-end
• Integração entre LLM e Banco de Dados via MCP (Model Context Protocol)
• Arquitetura MCP com Tool Calling
• Separação clara entre camadas da aplicação
• Organização profissional de projeto Python
• Boas práticas de engenharia de software

---

🎬 Demo

Clique para ver a demo

---

📸 Ver mais capturas de tela

Chat Interface

Sumário de Gastos Gerais

Sumário de Gastos por Item

---

🏗️ Arquitetura do Sistema

📂 Estrutura do Projeto

.
├── app
├── assets
├── database
├── docs
├── llm
├── mcp_server
├── shared
├── tests
└── utils

🛠️ Funcionalidades do Agente

O servidor MCP expõe ferramentas específicas que permitem ao LLM interagir com o banco de dados de forma segura. Abaixo estão as capacidades implementadas em mcp_server/tools/:

Ferramenta (Tool)	Descrição	Tecnologia
Sumário de Despesas	Consolida gastos por item e/ou pelo período solicitado.	Python / MCP SDK
Listagem de Itens	Recupera detalhes de despesas com busca flexível (LIKE).	SQL (MySQL)
Camada de Dados	Interface de conexão e execução de queries parametrizadas.	MySQL Connector
Interpretação Natural	Traduz dados brutos em informações financeiros amigáveis.	Gemini Prompt Eng.

🧠 Design Lógico e Fluxo de Pensamento

• Raciocínio do Agente: O sistema utiliza uma abordagem de Chain of Thought (Cadeia de Pensamento), onde o agente identifica a intenção do usuário, extrai entidades e decide qual Tool MCP é necessária para buscar os dados.

• Engenharia de Prompt: Implementação de técnicas de Few-Shot Prompting e instruções de sistema (System Instructions) para garantir que o LLM mantenha o foco financeiro e formate as respostas com precisão.

• Protocolo MCP: A escolha pelo Model Context Protocol garante que a lógica de acesso aos dados (SQL) esteja desacoplada da lógica do modelo, facilitando a troca de provedores de LLM no futuro.

⚙️ Stack Tecnológica

🤖 IA & LLM

• Google Gemini
• MCP (Model Context Protocol)
• Prompt Engineering

🎨 Frontend

• Streamlit 1.30+
• Custom CSS

🗄️ Backend & Database

• Python 3.13+
• MySQL Connector/Python
• MySQL 8.0

🧪 DevOps & Testing

• Pytest
• Python-Dotenv
• Makefile automation

🔑 Decisões de Engenharia

• Separação entre Agent, MCP Server e Database Layer
• Uso de Tools MCP para evitar acesso direto do LLM ao banco
• Cache do agente com st.cache_resource
• Arquitetura modular preparada para múltiplos modelos LLM
• Organização orientada à escalabilidade e manutenção

---

🚀 Como Executar o Projeto

1️⃣ Clonar o repositório

git clone https://github.com/SEU_USUARIO/finance-agent-mcp.git
cd finance-agent-mcp

2️⃣ Criar ambiente virtual e instalar dependências

make install

Esse comando irá criar o ambiente virtual .venv e instalar todas as dependências necessárias.

3️⃣ Criar variáveis de ambiente

make env

Edite o arquivo .env gerado e preencha-o com suas credenciais:

GEMINI_API_KEY=sua_chave_aqui

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=sua_senha
DB_NAME=personal_finance
TABLE_NAME=transactions

4️⃣ Executar a aplicação

make run

A aplicação estará disponível em http://localhost:8501.

Executar o MCP Server (opcional)

make mcp

Executar testes (recomendada)

make test

---

🗺️ Roadmap

Este projeto está em desenvolvimento ativo. Próximas evoluções planejadas:

• Suporte Multi-LLM, integrando outras APIs (OpenAI GPT-4o, Claude 3.5 Sonnet e Groq) para permitir a escolha do modelo via configuração.
• Novas MCP Tools para análises mais avançadas
• Migração das queries SQL puras para SQLAlchemy (uso de um ORM como o SQLAlchemy ajudaria na sanitização de queries e na prevenção de SQL Injection,)
• Suporte a múltiplos grupos de despesas
• Autenticação de usuários
• Testes de integração para as MCP Tools
• Dashboard estatístico com visualização gráfica das despesas
  (ex: total mensal, categorias mais frequentes, evolução ao longo do tempo)
  • Stack tecnológica planejada: Plotly + Streamlit

---

🔧 Troubleshooting

"Connection refused"

Este erro ocorre quando o serviço MySQL não está em execução. Utilize o comando de acordo com o seu sistema operacional:

 macOS (via Homebrew)

brew services start mysql
# ou, para reiniciar:
brew services restart mysql

🐧 Linux

sudo systemctl start mysql
# ou, para reiniciar:
sudo systemctl restart mysql

⊞ Windows (PowerShell como Administrador)

net start mysql

"Invalid API Key"

• Verifique se a chave Gemini está correta no .env
• Confirme que tem créditos disponíveis na API

---

👩‍💻 Autora

Luciene Godoy
AI Agents | Data Science | Software Engineering | Matemática

Stack: Python • MCP • Google Gemini • MySQL • Streamlit

📄 Licença

Este projeto foi desenvolvido para fins educacionais e demonstração de portfólio.

---