💰 Financial Agent — Gestor Financeiro Pessoal

Assistente financeiro pessoal com IA (Groq + Llama 4 Scout), acessível via Telegram Bot, rodando 24/7 na Oracle Cloud Free Tier.

---

🚀 Funcionalidades

• 💬 Registro de transações em linguagem natural via Telegram
• ✅ Confirmação antes de registrar — sem registros silenciosos
• 🤖 Consultas inteligentes sobre os dados ("quanto gastei esse mês?")
• 📄 Leitura de extratos PDF e comprovantes por foto
• 🔍 Detecção automática de duplicatas
• 💱 Suporte a múltiplas moedas (integração Wise)
• 📅 Agenda de vencimentos com alertas proativos
• 📊 Dashboard interativo (Plotly Dash + Bootstrap)
• 🔔 Scheduler com alertas automáticos via Telegram
• 📈 Relatório mensal automático de fechamento
• 🏦 Suporte a múltiplas instituições
• ⚠️ Auditoria de saldo e detecção de anomalias

---

🏦 Instituições Suportadas

• Itaú, Nubank, Santander, C6 Bank
• Inter, Bradesco, BTG, Wise
• Pluxee (vale refeição e alimentação)

---

🛠️ Stack Tecnológica

Componente	Tecnologia
IA / LLM	Groq + Llama 4 Scout
Visão	Llama 4 Scout Vision
Bot	python-telegram-bot
Banco de dados	SQLite + SQLAlchemy
Leitura PDF	pdfplumber
Dashboard	Plotly Dash + Bootstrap
Scheduler	APScheduler
Cotações	AwesomeAPI
Container	Docker
Servidor	Oracle Cloud Free Tier

---

⚙️ Requisitos

• Python 3.11+
• Docker
• Groq API Key (gratuita em console.groq.com)
• Telegram Bot Token (via @BotFather)
• Telegram Chat ID (seu ID pessoal)

---

📦 Instalação

1. Clone o repositório:

git clone https://github.com/dgrej/financial-agent.git
cd financial-agent

2. Crie o ambiente virtual:

python3 -m venv .venv
source .venv/bin/activate

3. Instale as dependências:

pip install -r requirements.txt

4. Configure as variáveis de ambiente:

cp .env.example .env
nano .env  # adicione suas chaves

5. Execute o bot:

python3 main.py

---

🐳 Docker

docker build -t financial-agent .
docker run -d --restart always --name financial-agent \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  -p 8050:8050 \
  financial-agent

---

💬 Uso do Bot

Linguagem natural:

"Comprei café débito Nubank R$ 8,50"
"Pix do Itaú pro C6 R$ 250"
"Paguei a fatura do Nubank R$ 173"
"Novo boleto conta de luz R$ 150 vence dia 15"
"Quanto gastei com alimentação esse mês?"
"Qual cartão tem mais limite disponível?"

Comandos:

/start        — mensagem de boas-vindas
/saldo        — saldo por instituição
/vencimentos  — próximos vencimentos
/lancamentos  — lançamentos de hoje
/auditar      — auditar saldo
/excluir [ID] — excluir lançamento
/editar [ID]  — editar lançamento
/dashboard    — link do dashboard
/ajuda        — todos os comandos

Envie arquivos:

• PDF de extrato bancário → extração automática
• Foto de comprovante PIX → registro automático

---

🔔 Alertas Automáticos (Scheduler)

O bot envia notificações proativas via Telegram:

Alerta	Horário
Vencimentos do dia, amanhã e próximos 7 dias	08:00 diário
Saldo baixo (abaixo de R$ 500)	09:00 diário
Gastos acima da média por categoria	08:30 segunda-feira
Renovação automática de agenda recorrente	00:00 diário
Relatório mensal de fechamento	20:00 último dia do mês

---

📊 Dashboard

Acesse pelo navegador:

http://SEU_IP_SERVIDOR:8050

Abas disponíveis:

• Visão Geral — KPIs, evolução do saldo, heatmap, categorias, fechamento do mês anterior
• Contas — saldos e faturas por instituição com gauge de uso
• Calendário — agenda e lançamentos no calendário mensal
• Lançamentos — tabela completa com filtros

---

🔐 Segurança

• Arquivo .env nunca commitado no repositório
• .gitignore protege dados sensíveis
• Banco SQLite excluído do repositório
• Revogue o token caso exposto

---

📁 Estrutura do Projeto

financeiro/
├── main.py                 # Ponto de entrada
├── scheduler.py            # Jobs automáticos (alertas + relatórios)
├── Dockerfile
├── requirements.txt
├── .env.example
├── .gitignore
├── README.md
├── CHANGELOG.md
├── bot/
│   ├── telegram.py         # Inicialização do bot
│   └── handlers.py         # Handlers de mensagens e callbacks
├── core/
│   ├── database.py         # Funções de banco de dados
│   └── models.py           # Modelos SQLAlchemy
├── agents/
│   ├── financeiro.py       # Agente IA (interpretação + consultas)
│   └── prompts.md
├── dashboard/
│   └── app.py              # Dashboard Plotly Dash
├── reports/
│   └── generator.py
└── data/                   # Excluído do git (.gitignore)
    └── financeiro.db

---

🗺️ Roadmap

• Transações financeiras core
• Interface Telegram Bot
• Leitura de PDF e imagem
• Detecção de duplicatas
• Multi-moeda (Wise)
• Agenda de vencimentos
• Confirmação antes de registrar
• Consultas inteligentes em linguagem natural
• Alertas proativos automáticos
• Dashboard interativo Bootstrap
• Relatório mensal automático
• Integração com agente de investimentos
• Resumo diário automático matinal
• GitHub Actions CI/CD

---

📄 Licença

MIT License — sinta-se livre para usar e contribuir!

---

🤝 Contribuição

Pull requests são bem-vindos!