Aviso: projeto educacional de portfólio. Os resultados dependem dos dados e das hipóteses adotadas e não representam recomendação de investimento.

01 · O problema

Aplicar conceitos de Engenharia Econômica — Markowitz, carteira tangente, CML, Beta e CAPM — exige baixar séries históricas, montar a matemática e interpretar o resultado. Para estudantes e curiosos, essa barreira costuma impedir ver a teoria em ação com dados reais.

O desafio técnico do projeto era diferente: fazer um agente de IA que nunca invente um número. Modelos de linguagem são ótimos para interpretar e explicar, mas péssimos para calcular com precisão conversível — o projeto existe para demonstrar como construir essa fronteira de forma sólida.

02 · A solução

O InvestIA é uma POC conversacional que responde perguntas do tipo "analise PETR4.SA", "otimize uma carteira com PETR4, VALE3 e ITUB4", "mostre a CML" ou "calcule o Beta e o CAPM" comparando ativos.

O LLM interpreta a pergunta, escolhe as ferramentas e explica os resultados. Os cálculos — retorno, volatilidade, covariância, otimização long-only, Sharpe, CML e CAPM — são feitos por funções Python determinísticas com testes unitários, que devolvem JSON estruturado para a interface:

Pergunta → agente LangChain → 4 ferramentas → finance.py (código determinístico) → Generative UI com cards e gráficos

As 4 ferramentas

Ferramenta	O que retorna
`consultar_acao`	Preço recente, retorno anualizado, volatilidade, Beta, CAPM e histórico para gráfico
`otimizar_carteira_markowitz`	Carteira de maior Sharpe (tangente), mínima variância, fronteira eficiente e matriz de correlação
`calcular_cml`	Linha do Mercado de Capitais a partir da carteira tangente e da taxa livre de risco
`calcular_capm_beta`	Beta por ativo contra o IBOVESPA e a Security Market Line (SML)

03 · Como funciona

O usuário pergunta em linguagem natural.
O agente seleciona e chama a ferramenta apropriada (com tickers normalizados para o padrão brasileiro .SA).
finance.py busca os dados em fontes oficiais: preços ajustados via yfinance e meta Selic (série 432) da API SGS do Banco Central como proxy da taxa livre de risco. O IBOVESPA (^BVSP) é o proxy de mercado.
Os indicadores são calculados em Python e devolvidos como JSON.
O frontend React renderiza o resultado em cards, tabelas e gráficos (Recharts): série de preços, pesos da carteira, fronteira eficiente, CML e SML — sempre com a janela, a fonte e a data dos dados visíveis.

Os cálculos respeitam convenções documentadas no código: retornos simples sobre preços ajustados, anualização por 252 dias, Beta por covariância dos excess returns e otimização SLSQP com pesos 0 ≤ w ≤ 1 e soma igual a 1.

04 · Decisões de engenharia

O LLM não é a calculadora

Essa é a regra central. Toda fórmula vive em backend/finance.py, coberta por testes unitários (test_finance.py). O LLM recebe só o JSON consolidado e explica — permitindo reprodutibilidade e eliminando "números inventados".

Transparência metodológica

Cada resposta informa a janela histórica, a data do último pregão, o benchmark (IBOVESPA), a fonte (Yahoo Finance + BCB SGS) e a taxa livre de risco usada. O frontend deixa isso visível ao lado de cada gráfico.

Robustez contra dados ruins

Mínimo de 60 observações alinhadas para estimar Beta.
Ticker inválido ou sem histórico → erro explicativo, nunca valores fabricados.
Variância de mercado ~0 → cálculo interrompido com mensagem clara.
Otimização sem convergência → erro, não pesos inválidos apresentados como solução.

Design da interface (Generative UI)

Resultados de ferramentas são renderizados por ToolResultView, com um renderer por tipo: cards de preço/risco/retorno, gráfico de preços, alocação de pesos, fronteira eficiente, CML e SML. Verde/vermelho no UI descreve apenas o sinal do indicador, nunca recomendação de compra/venda.

Segurança e operação

A chave do OpenRouter fica somente no backend; o browser só consome a API do LangGraph via contrato useStream.
Deploy previsto em Cloud Run com persistência gerenciada (PostgreSQL) para conversas — nunca o filesystem efêmero da instância.

05 · Demonstração

Na parte de cima da página você vê a demonstração em vídeo do fluxo completo: o agente interpretando a pergunta, acionando as ferramentas e apresentando a análise da carteira de Markowitz. Há também um clipe curto com os gráficos gerados pela Generative UI (preços, alocação, fronteira eficiente/CML e SML/Beta). Os vídeos também estão no YouTube: youtu.be/5QPl1loX3dU ↗ e youtu.be/aBpjBw6t82U ↗.

Estas são as perguntas de exemplo que a POC responde:

"Consulte PETR4.SA para o período de 2 anos e explique o beta."
"Otimize uma carteira com PETR4.SA, VALE3.SA e ITUB4.SA usando Markowitz."
"Mostre a CML para essa carteira e explique o peso do ativo sem risco."
"Calcule o beta e o retorno esperado pelo CAPM de PETR4.SA e VALE3.SA."

06 · Resultados e limitações

O que já existe

Código determinístico testado: Beta em séries sintéticas, anualização, soma dos pesos, limites long-only, fórmula CAPM e inclinação da CML.
4 tipos de visualização funcionando: preços, alocação, fronteira eficiente/CML e SML/Beta.
Avisos de limitação em todas as respostas (escopo educacional).

Limitações conhecidas

Limitação	Detalhe
Fonte de dados	`yfinance` usa interfaces não oficiais; para uso público/comercial seria preciso provedor licenciado
Selic	A série 432 é a meta Selic (%), não a rentabilidade efetiva diária de um título
Carteira tangente	É estimada apenas entre os ativos informados, não é a carteira de mercado
Sem persistência	Sem autenticação, carteiras salvas, backtesting ou recomendação personalizada na POC
Deploy	Em andamento — o frontend e a API ainda não estão publicados em produção

Este projeto demonstra, na prática, como avaliar a alternativa certa para cada problema: agente + ferramentas determinísticas + dados confiáveis, com a fronteira entre "o que o modelo faz" e "o que o código faz" bem definida.

InvestIA