Expense Tracker

Gerenciamento automatizado de despesas com backend Supabase e suporte a categorias hierárquicas.

GitHubExperimente este MCPPatrocinado

Documentação

Backend do Expense Tracker

Sistema de rastreamento de despesas com inteligência artificial, interface em linguagem natural, categorização inteligente e sincronização em tempo real.

Arquitetura

O sistema utiliza uma arquitetura de dois servidores:

  1. Servidor MCP: Ferramentas principais de rastreamento de despesas expostas via Model Context Protocol
  2. Servidor Gemini AI: Servidor FastAPI que fornece interface de chat com autenticação

Recursos

  • 🤖 Gerenciamento de despesas em linguagem natural via Gemini AI
  • 🧠 Categorização inteligente usando embeddings e busca por similaridade
  • 🔐 Autenticação JWT com Supabase
  • 📊 Categorias hierárquicas para organização
  • 🏷️ Sistema de tags predefinidas
  • 📈 Sincronização de dados em tempo real
  • 🔄 Sistema de aprendizado que melhora com o tempo

Início Rápido

Pré-requisitos

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Configuração do Ambiente

cp .env.example .env
# Add your credentials:
# - SUPABASE_URL
# - SUPABASE_KEY
# - GOOGLE_API_KEY (for Gemini)

Configuração do Banco de Dados

Execute os scripts SQL no seu Editor SQL do Supabase:

# Core tables
scripts/create_tables.sql
# Embeddings support
scripts/create_embeddings_schema.sql

Executar Ambos os Servidores

Terminal 1 - Servidor MCP:

python run_mcp.py

Terminal 2 - Servidor Gemini AI:

uvicorn app.servers.gemini.main:app --reload --port 8000

Inicializar Dados

# Populate categories
python scripts/populate_hierarchical_categories.py

# Populate predefined tags
python scripts/populate_predefined_tags.py

Endpoints da API

Interface de Chat

  • POST /chat - Enviar comandos em linguagem natural
  • POST /auth/refresh - Atualizar token JWT

Ferramentas MCP (via chat)

  • Criar despesas a partir de linguagem natural
  • Categorizar transações automaticamente
  • Obter resumos de gastos
  • Analisar assinaturas
  • Visualizar transações recentes

Cliente Flutter

consulte https://github.com/keyurgit45/expense-tracker-client

Testes

# Run all tests with mocks
ENVIRONMENT=test pytest tests/ -v

# Run specific components
ENVIRONMENT=test pytest tests/test_mcp_tools.py -v
ENVIRONMENT=test pytest tests/test_categorization.py -v

Estrutura do Projeto

backend/
├── app/
│   ├── core/              # Business logic
│   ├── servers/
│   │   ├── gemini/       # AI chat server
│   │   └── mcp/          # MCP tool server
│   └── shared/           # Shared configs
├── scripts/              # Utilities
└── tests/               # Test suite

Categorização com IA

O sistema utiliza uma abordagem híbrida:

  1. Gera embeddings para transações usando Sentence Transformers
  2. Encontra transações anteriores semelhantes usando pgvector
  3. Usa votação ponderada para prever categorias
  4. Recorre à correspondência baseada em regras
  5. Aprende com as confirmações dos usuários

Desenvolvimento

  • Documentação da API: http://localhost:8000/docs
  • Integração com frontend: Configure CORS no servidor Gemini
  • As ferramentas MCP podem ser testadas diretamente via interface de chat