Método GARCH — previsão de volatilidade + dimensionamento de posições
Este skill responde à pergunta que o varejo nunca faz e que todo fundo faz diariamente: quanto?
Ele NÃO prevê direção. O GARCH prevê a magnitude dos movimentos — quão violento o próximo dia provavelmente será, não para onde vai. Diga isso ao usuário sempre que apresentar resultados.
As três ferramentas
Todos os scripts estão em scripts/ e são executados com uv run (as dependências são resolvidas automaticamente por meio de metadados inline — nada de pip-install).
1. garch_forecast.py — a previsão
GARCH(1,1) com janela progressiva, zero visão futura (parâmetros reestimados a cada 21 dias em uma janela em expansão; a recursão avança entre reajustes usando apenas dados passados).
uv run scripts/garch_forecast.py --csv precos.csv --json
uv run scripts/garch_forecast.py --ticker BTC-USD --json
Saída: previsão de volatilidade de 1 dia (diária + anualizada), percentil de volatilidade em relação ao ano anterior, regime (calmo / normal / tempestade).
2. vol_target.py — o tamanho
A ideia completa: tamanho = volatilidade_alvo / volatilidade_prevista, limitado a [0.25x, 2.0x].
uv run scripts/vol_target.py --csv precos.csv --target-vol 15 --json
Saída: multiplicador de tamanho de posição. "Execute 0.6x da sua base" — essa é a resposta.
3. compare.py — o teste honesto
Executa os mesmos sinais duas vezes — tamanho fixo vs. targeting de volatilidade — e mostra ambas as curvas de equidade mais estatísticas lado a lado. Acompanha uma demonstração de crossover EMA 9/21; aceita qualquer estratégia via --signals meus_sinais.csv (colunas: data, sinal em {-1,0,1}).
uv run scripts/compare.py --csv precos.csv --target-vol 58 --chart equidade.png --json
uv run scripts/compare.py --csv precos.csv --signals meus_sinais.csv
Saída: CAGR, volatilidade anualizada, Sharpe, drawdown máximo, pior mês, equidade final — ambas as versões — mais o gráfico da curva de equidade com regimes de tempestade sombreados.
Contrato JSON
Todo script suporta --json. Estrutura central da saída:
{
"as_of": "2026-05-23",
"forecast_vol_annualized_pct": 41.2,
"vol_percentile_1y": 78.0,
"regime": "tempestade",
"position_size_multiplier": 0.6,
"note": "GARCH prevê magnitude (volatilidade), não direção."
}
Três padrões de composição
A. Camada de dimensionamento — acople a qualquer estratégia existente. Sua estratégia decide se; este skill decide quanto. Pegue o sinal da estratégia, multiplique por position_size_multiplier, pronto.
B. Limitador de risco — kill-switch independente. Se regime == "tempestade", corte toda a exposição para o multiplicador, independentemente do que seus sinais disserem. Funciona com qualquer agente que gerencie posições.
C. Estrutura de comparação — antes de confiar em qualquer estratégia, execute-a através de compare.py e verifique se o targeting de volatilidade melhora seu Sharpe / drawdown. Se o dimensionamento não ajudar, a vantagem da estratégia pode ser muito fraca para sobreviver a condições reais.
Composição limpa com skills de direção de regime (por exemplo, classificadores de alta/baixa estilo Markov): a saída deles responde para onde, este responde quanto. Multiplique os dois.
Padrões e convenções
- Cripto:
--periods-per-year 365(padrão). Ações:--periods-per-year 252. - Volatilidade alvo: 15% é um padrão conservador sensato. Para uma comparação ajustada ao risco contra uma estratégia sem alavancagem, defina a volatilidade alvo aproximadamente igual à volatilidade realizada da própria estratégia.
- Dados: ticker yfinance (precisa de internet) ou qualquer CSV com colunas de data + fechamento — insere-se em qualquer pipeline que o usuário já execute.
- Histórico mínimo: ~510 observações diárias antes da primeira previsão.
Regras de honestidade (não negociáveis)
- Nunca apresente a saída GARCH como uma chamada de direção.
- Nunca oculte os números de drawdown ou pior mês ao relatar uma comparação.
- Se o targeting de volatilidade NÃO melhorar a estratégia do usuário, diga isso claramente — esse resultado é igualmente valioso.