Communitygithub.com

vishnup22/FinSight-AI

Análise de alocação de portfólio para 2 a 10 ações dos EUA e/ou da Índia usando FinSight-AI. Calcula pesos ótimos com ponderação igual vs. max-Sharpe, matriz de correlação e métricas de risco do portfólio.

O que é FinSight-AI?

Este skill utiliza a API FinSight-AI (backend local) para realizar otimização de portfólio. O usuário fornece uma lista de tickers (2–10) e o skill submete um job que calcula duas estratégias de alocação: ponderação igual e a carteira de máximo Índice de Sharpe. O resultado inclui matriz de correlação entre os ativos, métricas de risco (volatilidade anual, VaR diário a 95%) e uma comparação detalhada. O skill foi projetado para agentes como Claude Code que se conectam a um backend Python rodando em `localhost:8000`. Ele é útil para investidores que desejam uma análise quantitativa rápida de diversificação e otimização, sem a necessidade de análises narrativas por ação. A saída é apresentada em formato markdown com tabelas e uma recomendação final de 2–3 frases.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vishnup22/FinSight-AI/tree/HEAD/skills/portfolio

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

CampoCaminhoObservações
Tickers usadostickersPode diferir da entrada se alguns não tiverem dados
Linhas de preçosprice_rowsNúmero de dias de negociação sobrepostos
Pesos iguaisequal_weight.weights{ticker: decimal} — multiplique por 100 para %
Retorno igualequal_weight.annual_return_pctJá em %
Volatilidade igualequal_weight.annual_volatility_pctJá em %
Sharpe igualequal_weight.sharpe_ratioAnualizado, livre de risco = 5%
VaR igualequal_weight.var_95_daily_pctJá em %, diário
Pesos ótimosoptimal.weights{ticker: decimal} — multiplique por 100 para %
Retorno ótimooptimal.annual_return_pctJá em %
Volatilidade ótimaoptimal.annual_volatility_pctJá em %
Sharpe ótimooptimal.sharpe_ratioAnualizado, livre de risco = 5%
VaR ótimooptimal.var_95_daily_pctJá em %, diário
Otimizador bem-sucedidooptimal.optimizer_successbool
Mensagem do otimizadoroptimal.optimizer_messageRelevante apenas se success = false
Matriz de correlaçãocorrelation_matrixDicionário aninhado {ticker: {ticker: corr}}
VaR do portfólioportfolio_var_95_daily_pctVaR 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çãoAção
Erro de nível superior no resultadoExplique o problema; peça ao usuário para verificar os tickers e tentar novamente
Um ticker removido da lista tickersObserve que ele tinha histórico de preços insuficiente ou não sobreposto
optimizer_success = falseExplique a substituição pelos pesos iguais; ainda mostre as métricas
Único ticker .NS/.BOObserve o risco cambial; mostre-o na matriz de correlação normalmente

Habilidades Relacionadas