Portfólio — otimização com ponderação igual vs. max-Sharpe
Consulte reference.md para formatos de tickers.
Pré-requisitos
GET http://localhost:8000/health
Deve retornar {"status": "ok"}. Caso contrário: informe ao usuário para executar python backend/run.py.
Etapa 1 — Analisar tickers
- Extraia todos os símbolos de ticker da mensagem. Converta para maiúsculas e remova espaços.
- Mínimo 2, máximo 10. Duplicatas são rejeitadas pela API — deduplique silenciosamente e anote.
- Se menos de 2 tickers forem fornecidos, peça mais antes de prosseguir.
Etapa 2 — Enviar job de portfólio
POST http://localhost:8000/api/v1/portfolio
Content-Type: application/json
{"tickers": ["T1", "T2", "..."], "query": "Otimizar alocação para o máximo retorno ajustado ao risco."}
Resposta: {"job_id": "<uuid>", "status": "pending", "message": "..."}
Informe ao usuário:
Job de portfólio enviado para {n} tickers. Buscando histórico de preços de 1 ano e otimizando… normalmente 15–30 s.
Etapa 3 — Verificar status
GET http://localhost:8000/api/v1/status/{job_id}
A cada 5 s até completed ou failed.
Etapa 4 — Obter resultado
GET http://localhost:8000/api/v1/result/{job_id}
Caso de erro
Se o resultado contiver uma chave error de nível superior (ex.: "Pelo menos dois tickers com histórico de preços sobreposto são necessários"), explique o problema em linguagem clara e pare:
A otimização de portfólio requer pelo menos dois tickers com histórico de negociação sobreposto no último ano. Verifique se todos os tickers são válidos e têm histórico suficiente.
Mapa de campos
| Campo | Caminho | Observações |
|---|---|---|
| Tickers usados | tickers | Pode diferir da entrada se alguns não tiverem dados |
| Linhas de preços | price_rows | Número de dias de negociação sobrepostos |
| Pesos iguais | equal_weight.weights | {ticker: decimal} — multiplique por 100 para % |
| Retorno igual | equal_weight.annual_return_pct | Já em % |
| Volatilidade igual | equal_weight.annual_volatility_pct | Já em % |
| Sharpe igual | equal_weight.sharpe_ratio | Anualizado, livre de risco = 5% |
| VaR igual | equal_weight.var_95_daily_pct | Já em %, diário |
| Pesos ótimos | optimal.weights | {ticker: decimal} — multiplique por 100 para % |
| Retorno ótimo | optimal.annual_return_pct | Já em % |
| Volatilidade ótima | optimal.annual_volatility_pct | Já em % |
| Sharpe ótimo | optimal.sharpe_ratio | Anualizado, livre de risco = 5% |
| VaR ótimo | optimal.var_95_daily_pct | Já em %, diário |
| Otimizador bem-sucedido | optimal.optimizer_success | bool |
| Mensagem do otimizador | optimal.optimizer_message | Relevante apenas se success = false |
| Matriz de correlação | correlation_matrix | Dicionário aninhado {ticker: {ticker: corr}} |
| VaR do portfólio | portfolio_var_95_daily_pct | VaR diário do portfólio ótimo, já em % |
Etapa 5 — Interpretar e apresentar
Pesos
Converta pesos decimais em porcentagens (peso * 100, 1 casa decimal).
Se algum peso for 0,0% no portfólio ótimo, observe que o otimizador excluiu esse ativo (retorno insuficiente ou alta correlação com outros).
Índice de Sharpe
- < 0: o portfólio retorna menos que a taxa livre de risco (5%); reconsidere a composição.
- 0–1: retorno ajustado ao risco ruim.
- 1–2: bom.
-
2: excelente.
Compare o Sharpe com ponderação igual vs. Sharpe ótimo. Se o Sharpe ótimo for maior, os pesos concentrados são justificados. Se forem semelhantes (diferença < 0,1), o portfólio com ponderação igual é quase tão eficiente e mais simples de rebalancear.
Matriz de correlação
Interprete as correlações aos pares:
-
0,80: altamente correlacionados — esses dois ativos se movem quase juntos; manter ambos adiciona pouca diversificação.
- 0,50–0,80: correlação moderada — algum co-movimento, benefício parcial de diversificação.
- < 0,30: baixa correlação — bom par de diversificação.
- Próximo de 0 ou negativo: forte diversificador.
Identifique o par mais correlacionado e o par menos correlacionado e destaque-os na narrativa.
VaR
VaR diário com confiança de 95%: no pior 1 em 20 dias de negociação, o portfólio historicamente perdeu aproximadamente {portfolio_var_95_daily_pct}%. Anualize uma estimativa aproximada apenas se útil: multiplique o VaR diário por √252 ≈ 15,9 para aproximar o VaR anual (observe que é uma aproximação grosseira).
Falha do otimizador
Se optimal.optimizer_success = false, diga:
O otimizador não convergiu ({optimal.optimizer_message}). Os pesos ótimos foram substituídos pelos pesos iguais — trate a coluna "Ótimo" como ponderação igual.
Ações indianas no portfólio
Se algum ticker terminar em .NS ou .BO, observe que ativos denominados em INR introduzem risco cambial para investidores baseados em USD. A matriz de correlação reflete retornos em moeda local e não captura a volatilidade INR/USD.
Etapa 6 — Recomendação
Após apresentar os dados, forneça uma recomendação de 2–3 frases:
- Diga se deve usar ponderação igual ou pesos ótimos e por quê (comparação de Sharpe).
- Nomeie as 1–2 principais participações no portfólio ótimo e o que impulsiona seu peso.
- Observe qualquer preocupação de diversificação (pares altamente correlacionados) ou consideração cambial.
Saída
# Análise de Portfólio — {tickers separados por vírgula}
Histórico de preços: {price_rows} dias de negociação sobrepostos (≈ {price_rows/252:.1f} anos)
---
## Comparação de Alocação
| Ticker | Ponderação igual | Peso ótimo |
|----------|----------------|------------|
| {ticker} | {ew*100:.1f}% | {ow*100:.1f}% |
| … | … | … |
---
## Métricas do Portfólio
| Métrica | Ponderação igual | Ótimo (max Sharpe) |
|--------------------------|----------------|--------------------|
| Retorno anual esperado | {eq_ret}% | {opt_ret}% |
| Volatilidade anual | {eq_vol}% | {opt_vol}% |
| Índice de Sharpe | {eq_sh} | {opt_sh} |
| VaR (95%, 1 dia) | {eq_var}% | {opt_var}% |
{Se optimizer_success = false:
> ⚠ O otimizador não convergiu ({optimizer_message}) — os pesos ótimos são iguais aos pesos iguais.}
---
## Matriz de Correlação
| Ticker | {t1} | {t2} | … |
|--------|------|------|---|
| {t1} | 1,00 | … | … |
| … | … | … | … |
**Par mais correlacionado:** {t_a} / {t_b} com {corr:.2f} — benefício limitado de diversificação.
**Par menos correlacionado:** {t_c} / {t_d} com {corr:.2f} — maior benefício de diversificação.
---
## Recomendação
{2–3 frases: escolha entre igual e ótimo, justificativa das principais participações, qualquer ressalva de diversificação ou câmbio.}
{Se houver tickers .NS/.BO:
> ⚠ Ações indianas ({lista}) são denominadas em INR. A matriz de correlação reflete retornos em moeda local e não captura o risco cambial INR/USD para investidores baseados em USD.}
Recuperação de erros
| Situação | Ação |
|---|---|
| Erro de nível superior no resultado | Explique o problema; peça ao usuário para verificar os tickers e tentar novamente |
Um ticker removido da lista tickers | Observe que ele tinha histórico de preços insuficiente ou não sobreposto |
optimizer_success = false | Explique a substituição pelos pesos iguais; ainda mostre as métricas |
Único ticker .NS/.BO | Observe o risco cambial; mostre-o na matriz de correlação normalmente |