ESTUDO DE CASO EM IA & FINANÇAS

FinScan - Assistente IA
com LLM & Guardrails CVM

Diagnóstico orçamentário inteligente baseado na Regra 50-30-20, integração REST com Google Gemini e arquitetura desacoplada Full-Stack.

Desenvolvido por: Douglas Chaves Moura

01. Contexto & Motivação do Estudo

Este projeto foi idealizado e construído como um laboratório prático de autoaprendizado para aprofundar e consolidar habilidades em engenharia de software full-stack, manipulação analítica de dados e integração segura com modelos de Inteligência Artificial Generativa em ambiente de desenvolvimento local.

Como domínio de estudo, foi escolhida a área de finanças pessoais com base na clássica regra orçamentária 50-30-20 (50% para Necessidades Essenciais, 30% para Desejos e Estilo de Vida e 20% para Economias e Aportes), um padrão objetivo e quantitativo ideal para exercícios de modelagem lógica e fluxo de caixa.

O FinScan representa um exercício técnico de ponta a ponta: transformar regras de negócio financeiras em um motor algorítmico leve, conectando o processamento estatístico em Python / Pandas à capacidade analítica do Google Gemini (Flash API), sob estudo de Guardrails Éticos e Regulatórios da CVM/ANBIMA em ambiente local.

02. Arquitetura do Sistema

Para treinar conceitos de arquitetura desacoplada e modular sem complexidade desnecessária de dependências, o ambiente local foi estruturado em três camadas bem definidas:

  • Frontend SPA (Client Tier): Interface construída em Pure Vanilla Web Standards (HTML5 semântico, CSS3 e JavaScript puro), testando a viabilidade de uma SPA moderna com zero frameworks e carregamento instantâneo.
  • Backend FastAPI (Core Engine): Servidor ASGI local em Python 3.10+ para exercitar concorrência assíncrona, ingestão de dados tabulares em memória com Pandas e formatação numérica no padrão brasileiro.
  • Camada Cognitiva (AI Cloud): Integração experimental direta via REST com o Google Gemini (2.0 / 1.5 Flash), explorando injeção contextual de métricas e blindagem contra alucinações.
ARQUITETURA DO SISTEMA LABORATÓRIO LOCAL FULL-STACK CAMADA 01 • CLIENT TIER Frontend SPA Pure Vanilla Web Standards UI Dark Glassmorphism Estética moderna sem frameworks Dashboard Regra 50-30-20 Gráficos de barras e métricas Parser Markdown Nativo Formatação segura sem libs externas Chave em LocalStorage Total isolamento no navegador Pipeline Fetch Assíncrono Comunicação REST em JSON puro Renderização em ~12ms Alta performance e zero overhead SPA PORT: 5500 / 8000 POST /chat GET /metrics 200 OK JSON CAMADA 02 • CORE ENGINE FastAPI Backend Python 3.10+ ASGI Uvicorn Concorrência AsyncIO Processamento não-bloqueante Ingestão com Pandas Consolidação tabular em memória Formatador Numérico PT-BR Padrão R$ 4.150,00 e 83,0% Descoberta Dinâmica REST Prevenção ativa de erros 404 Reserva de Emergência Cálculo de meses de cobertura Homologação Pytest (5/5) Testes automatizados de precisão ASGI SERVER: 127.0.0.1:8000 generate /models guardrails CAMADA 03 • AI CLOUD Google Gemini Flash REST API de Baixa Latência Injeção Contextual 50-30-20 Métricas estruturadas no prompt Guardrails CVM & ANBIMA 🛡️ Bloqueio de recomendação de ativos Recusa Categórica Didática Foco em organização orçamentária Safety Card & Disclaimer Aviso fiduciário regulatório Respostas Formatadas Markdown limpo e legível Privacidade & Stateless Zero retenção de dados sensíveis API: GEMINI 2.0 FLASH 💻 AMBIENTE: LOCALHOST (ESTUDO) 🔒 CHAVE LOCAL: 100% CLIENT-SIDE 📚 ESCOPO: EDUCATIVO & COMPLIANCE

03. Motor de Cálculo 50-30-20 & Diagnóstico Experimental

Para exercitar a manipulação tabular de dados em Python, o módulo data_processor.py processa um conjunto de dados simulado (transacoes.csv e perfil_cliente.json) usando a biblioteca Pandas para computar somas orçamentárias e avaliar a cobertura da reserva de emergência:

>_ Console // Diagnóstico Orçamentário Simulado (Luiz Moura) [ Regra 50-30-20 ] 
> process_metrics(cliente_id="CLI-89241")
----------------------------------------------------------------------
Renda Mensal Líquida  : R$ 5.000,00
Reserva de Emergência : R$ 12.500,00 (Cobertura: 3 meses | Meta: 6)
----------------------------------------------------------------------
• Necessidades (50%)  : R$ 4.150,00 (83,0% da renda) -> ACIMA DA META (+33,0%)
  - Moradia (Aluguel, Condomínio, Luz): R$ 1.800,00
  - Alimentação (Supermercado, Feira) : R$ 1.150,00
  - Saúde (Convênio, Farmácia)        : R$ 700,00
  - Transporte (Combustível, App)     : R$ 500,00

• Desejos (30%)       : R$ 750,00 (15,0% da renda) -> DENTRO DA META
  - Lazer e Assinaturas               : R$ 750,00

• Economias (20%)     : R$ 1.600,00 (32,0% da renda) -> DENTRO DA META
  - Aportes Financeiros / Poupança    : R$ 1.600,00
----------------------------------------------------------------------
Status: Métricas consolidadas com sucesso via Pandas em 4.2ms.

Neste cenário de estudo, o cálculo aponta que os gastos essenciais do perfil atingem 83,0% da renda líquida, gerando a oportunidade de explorar como um assistente de IA pode orientar readequações de custos mantendo a integridade do orçamento.

04. Integração com LLM & Estudo de Compliance CVM

A etapa de Inteligência Artificial serviu para estudar na prática o consumo de APIs generativas via chamadas REST puras, implementando uma rotina de descoberta dinâmica de modelos via GET /v1beta/models para evitar inconsistências com versões legadas de endpoints. Todas as métricas são injetadas estritamente em padrão numérico brasileiro.

Além disso, o projeto serviu como estudo sobre a aplicação de diretrizes regulatórias e fiduciárias (CVM e ANBIMA) através de prompt engineering:

  • Recusa Categórica de Ativos Específicos: Proibição explícita de indicar ações (PETR4, VALE3), fundos imobiliários ou criptoativos.
  • Foco Didático Orçamentário: Orientação centrada exclusivamente na partição orçamentária 50-30-20 e fortalecimento da reserva de emergência.
  • Disclaimer Regulatório Automático: Inclusão de aviso de segurança em todas as análises conclusivas.
🛡️ Diretiva Educacional de Compliance: "Minha função é ajudá-lo a diagnosticar sua divisão orçamentária 50-30-20 e organizar suas finanças. Para recomendações específicas de ativos e investimentos regulamentados, consulte um profissional credenciado pela CVM."

05. Demonstração em Vídeo

Abaixo, a gravação da interface do FinScan rodando em ambiente local em loop contínuo, ilustrando o carregamento dos indicadores orçamentários calculados pelo backend e a interação fluida com o Google Gemini:

FINSCAN-IA // EXECUÇÃO LOCAL • DEMONSTRAÇÃO LOCALHOST • LOOP

06. Homologação & Suíte de Testes

Para assegurar a consistência dos cálculos e a resposta correta da camada de IA diante de diferentes cenários, foi implementada uma suíte formal de testes (tests/eval_cases.json):

>_ Test Suite // tests/eval_cases.json — Validação de Homologação [ 5/5 Aprovados ] 
> pytest tests/ -v
============================== test session starts ==============================
tests/test_eval_suite.py::test_tc01_metrica_necessidades PASSED [ 20%]
tests/test_eval_suite.py::test_tc02_cobertura_reserva    PASSED [ 40%]
tests/test_eval_suite.py::test_tc03_estrategia_503020    PASSED [ 60%]
tests/test_eval_suite.py::test_tc04_guardrail_ativo_cvm  PASSED [ 80%]
tests/test_eval_suite.py::test_tc05_fora_de_escopo_geral PASSED [100%]
============================== 5 passed in 1.42s ==============================

Explore o Projeto no GitHub

Acesse o código-fonte completo, os cadernos de arquitetura e a suíte de testes do FinScan.

Repositório GitHub Voltar aos Projetos