💬 Orçamento Conversacional — Gestão financeira pessoal por linguagem natural, direto no Telegram

Registre despesas como quem manda mensagem para um amigo — sem formulário, sem planilha. Um agente de IA (Google Gemini, orquestrado pelo Nanobot) interpreta a mensagem, extrai valor, categoria, método de pagamento e data, e grava tudo em um banco PostgreSQL. Quando você quiser, ele te devolve um relatório em PDF com dashboard completo ou gera recomendações financeiras personalizadas para economizar.

Você:  Gastei 35 no almoço hoje, no pix
Bot:   Registrado: R$ 35,00 em alimentação (almoço, no pix).

Índice

• Visão Geral

• Funcionalidades

• Arquitetura

• Requisitos

• Como Executar

• Comandos

• Estrutura do Projeto

• Documentação Técnica

• Licença

Related MCP server: expense-tracker-postgres-mcp

Visão Geral

Este é um protótipo de pesquisa que investiga a viabilidade de uma interface 100% conversacional para controle financeiro pessoal, com foco em jovens adultos (18–29 anos). A ideia central: em vez de adaptar o usuário à estrutura de um app, o sistema se adapta à forma como a pessoa já fala naturalmente sobre seus gastos.

Todo o pipeline roda em containers Docker — não é preciso instalar Python, Postgres ou o Nanobot na máquina. O modelo de linguagem (Google Gemini) roda na nuvem, então não há download nem execução de modelo local.

Funcionalidades

Arquitetura

O servidor de ferramentas roda dentro do container do Nanobot, via stdio, em um ambiente Python isolado (/opt/mcpvenv) — necessário porque o SDK mcp usado pelas ferramentas conflita em versão com o exigido pelo próprio nanobot-ai. Detalhes em Documentação Técnica.

Requisitos

• Docker e Docker Compose (Docker Desktop no Windows/Mac, Docker Engine no Linux) — é a única dependência real

• Uma conta no Telegram, para criar o bot

• Uma chave de API do Google Gemini (gratuita, sem cartão de crédito — free tier cobre o uso deste projeto)

Não precisa instalar Python, Postgres ou o Nanobot separadamente — tudo roda em container.

Como Executar

# 1. Copie o modelo de variáveis de ambiente
cp .env.example .env

# 2. Edite o .env com seu TELEGRAM_TOKEN e GEMINI_API_KEY
#    (veja como conseguir os dois na Documentação Técnica)

# 3. Suba tudo
make up
# equivalente: docker compose up -d --build

# 4. Confira se os dois serviços estão de pé
make ps
# equivalente: docker compose ps

Procure seu bot no Telegram pelo username criado no BotFather e mande uma mensagem. O passo a passo completo — de onde tirar o token do bot e a chave do Gemini até o troubleshooting de cada erro comum — está na Documentação Técnica.

Comandos

Atalhos definidos no Makefile (opcional — todo comando make tem o docker compose equivalente ao lado, caso você não tenha make instalado, comum no Windows fora do WSL).

Casos que não têm atalho no Makefile e usam docker compose direto:

Estrutura do Projeto

orcamento-conversacional/
├── docker-compose.yml       # Orquestra os containers postgres + nanobot
├── Makefile                 # Atalhos dos comandos acima
├── requirements.txt         # Dependências Python do servidor MCP
├── .env.example             # Modelo de variáveis de ambiente
│
├── db/
│   ├── schema.sql            # Schema para instalação nova (banco vazio)
│   ├── migration_002_metodo_pagamento.sql   # Migração segura para bancos já existentes
│   └── connection.py         # Pool de conexão com o Postgres
│
├── mcp_server/               # Ferramentas do agente + geração de relatório PDF e recomendações
│   ├── expense_tools.py       # As 5 tools: registrar, listar, resumir, gerar PDF, gerar recomendação
│   ├── dashboard_builder.py   # Página 1 do relatório (panorama por categoria)
│   ├── dashboard_pagamento.py # Página 2 do relatório (panorama por método de pagamento)
│   ├── dashboard_gastos_dia.py# Página 3 do relatório (tabela de gastos por dia)
│   ├── dash_style.py          # Paleta de cores, nomes e ícones (categorias/métodos)
│   ├── icons.py                # Ícones vetoriais desenhados no PDF
│   └── Dockerfile
│
└── nanobot_config/
    ├── config.docker.json     # Config ativa quando roda via Docker
    ├── config.json             # Config para instalação local (sem Docker)
    ├── SOUL.md                 # Instruções de comportamento do agente
    ├── AGENTS.md                # Regras gerais complementares
    └── Dockerfile

Detalhamento completo de cada arquivo, da arquitetura interna e do schema do banco: Documentação Técnica.

Documentação Técnica

Este README cobre o essencial para rodar o projeto. Para o passo a passo detalhado — incluindo:

• Como conseguir o token do bot no BotFather (com prints do que esperar)

• Como conseguir e configurar a chave da API do Gemini

• Lista completa de problemas comuns e como resolver cada um

• Detalhamento de arquitetura (por que o MCP roda num venv isolado, por que existem dois arquivos de config do Nanobot)

• Instalação local sem Docker

• Referência de cada ferramenta (tool) do agente

veja DOCUMENTACAO_TECNICA.md.

Licença

Distribuído sob a licença definida em LICENSE.