A camada de calculo do Finance Brain: uma biblioteca quantitativa para pairs trading baseado em cointegracao, exposta como servidor MCP. E a camada que decide e dimensiona com estatistica; o LLM (os agentes do Finance Brain) apenas opina e narra. Um backtest que mente e pior que nenhum, entao correcao e disciplina anti-lookahead vem antes de tudo.
Espelha a arquitetura e o envelope de retorno {"ok": ..., "data": ...} do servidor de dados Scout
(mcp-market-research): cada ferramenta e uma casca fina e sem estado sobre um nucleo puro e
testavel offline. Apenas o carregador de dados, o servidor e o healthcheck tocam a rede.
Da analise critica de TradingAgents e ai-hedge-fund (em finance-brain/ANALISE_REPOS.md), a
lacuna que nenhum dos dois preencheu foi validacao out-of-sample seria com custos realistas.
Backtests sem custos e sem separacao treino/teste superestimam retorno e enganam. Esta camada existe
exatamente para fazer isso direito.
Toda decisao no instante t usa apenas informacao disponivel ate t. Imposto em codigo e coberto
por testes:
- Apenas estatistica movel (rolling). O z-score usa media/desvio em janela movel
(
model/spread.py), nunca a serie inteira. Alterarspread[t+k]nao pode mudarz[t]parat < t+k. - Defasagem de execucao D+1. O backtest faz
positions = signals.shift(1)antes de aplicar os retornos (backtest/engine.py). Decisao e execucao nunca compartilham o mesmo preco;equity[t]depende apenas de precos e sinais atet. - Calibracao so no TREINO. Selecao do par, hedge ratio e limiares sao fixados na fatia de treino;
a fatia de teste fica intocada ate a aplicacao (
validation/walk_forward.py). Metricas in-sample e out-of-sample sao reportadas separadamente — a diferenca entre elas e o indice de overfitting. - Hedge ratio movel causal. O beta rolling opcional usa apenas a janela passada.
Nunca opcionais. commission_bps + slippage_bps sao cobrados em cada perna de toda abertura
e fechamento (quatro incidencias por round-trip), e um carrego diario de aluguel do short
(borrow_rate_annual / 252) e debitado sobre a perna vendida enquanto a posicao esta aberta. Ligar
os custos sempre reduz o retorno final — ha um teste que afirma exatamente isso.
O relatorio de performance sinaliza Sharpe > 3 ou win rate > 90% como provavel sinal de overfitting ou vazamento de lookahead. Resultado bom demais tem de ser barulhento, nao comemorado.
| Modulo | Arquivo | Responsabilidade |
|---|---|---|
| 1 | data/loader.py |
Baixa (yfinance, ajustado), alinha (intersecao de datas), cacheia em parquet |
| 2a | selection/correlation.py |
Pre-filtro barato por correlacao (de retornos, nao de niveis) |
| 2b | selection/cointegration.py |
Engle-Granger + correcao de multiplos testes (Bonferroni) |
| 3 | model/hedge_ratio.py |
Beta OLS estatico (+ beta rolling causal opcional) |
| 4 | model/spread.py |
Spread e z-score rolling |
| 5 | signals/rules.py |
Sinais com estado: entrada/saida/stop |
| 6 | backtest/engine.py |
P&L dia a dia com defasagem D+1, custos e contabilidade de duas pernas |
| 7 | validation/walk_forward.py |
Split temporal e walk-forward (in-sample vs out-of-sample) |
| 8 | risk/sizing.py |
Half-life, sizing por alvo de volatilidade, limites de risco |
| 9 | metrics/performance.py |
Sharpe, Sortino, drawdown, CAGR, vs-benchmark, avisos |
| Ferramenta | O que faz |
|---|---|
test_cointegration(ticker_a, ticker_b, start, end) |
Engle-Granger: p-valor, hedge ratio, cointegrado? |
find_pairs(tickers, start, end, min_corr=0.8, alpha=0.05, bonferroni=True) |
Pre-filtro por correlacao + cointegracao com Bonferroni; pares ranqueados |
analyze_spread(ticker_a, ticker_b, start, end, window=60) |
Hedge ratio, half-life, z-score atual, estatisticas do spread |
run_pairs_backtest(ticker_a, ticker_b, start, end, split_date, ...) |
Backtest com custos e D+1; in-sample vs out-of-sample, resumo de equity/trades, avisos, benchmark buy-and-hold (SPY) |
walk_forward(ticker_a, ticker_b, start, end, train_window, test_window, step, ...) |
Tabela de performance treino vs teste por janela |
performance_metrics(returns, periods_per_year=252) |
Metricas completas para uma serie de retornos arbitraria |
estimate_half_life(ticker_a, ticker_b, start, end, window=60) |
Half-life da reversao (Ornstein-Uhlenbeck / AR(1)) |
position_size(capital, n_active_pairs, vol_target=0.10, realized_vol=None) |
Capital por par com alvo de volatilidade |
risk_limits(capital, pair_vol, vol_target=0.10, correlation=None, ...) |
Limites de posicao por volatilidade/correlacao |
Series longas voltam como resumo (estatisticas + head/tail) para manter o payload enxuto; a biblioteca guarda a serie completa internamente.
Pre-requisitos: Python 3.11+ e uv.
uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python
# Suite de testes offline (a definicao de pronto: 44 testes, inclui anti-lookahead)
.venv/bin/python -m pytest -q
# Smoke test ao vivo (precisa de rede para o yfinance)
.venv/bin/python -m analytics.healthcheck # padrao: KO vs PEP
.venv/bin/python -m analytics.healthcheck KO PEP 2021-01-01 2024-01-01Scripts de console (apos instalar): mcp-analytics (o servidor) e analytics-healthcheck.
claude mcp add analytics -- /caminho/para/mcp-analytics/.venv/bin/python -m analytics.server.appO nucleo e composto de funcoes puras sobre pandas, testaveis sem rede:
from analytics.selection.cointegration import test_cointegration
from analytics.data.loader import load_prices
prices = load_prices(["KO", "PEP"], "2021-01-01", "2024-01-01")
result = test_cointegration(prices["KO"], prices["PEP"])
# {"pvalue": 0.27, "hedge_ratio": 0.26, "is_cointegrated": False}src/analytics/
data/ # Modulo 1: carregamento e alinhamento de precos ajustados
selection/ # Modulos 2a/2b: correlacao e cointegracao (Bonferroni)
model/ # Modulos 3/4: hedge ratio e spread/z-score
signals/ # Modulo 5: regras de entrada/saida/stop
backtest/ # Modulo 6: engine com custos e defasagem D+1
validation/ # Modulo 7: split temporal e walk-forward
risk/ # Modulo 8: half-life, sizing, limites
metrics/ # Modulo 9: metricas de performance e avisos
server/app.py # servidor MCP (FastMCP) expondo as ferramentas
healthcheck.py
tests/ # testes unitarios por modulo, incluindo os anti-lookahead obrigatorios
MIT.
Documento e ferramenta de pesquisa para paper trading. Nao constitui recomendacao de investimento.