Skip to content

usage-guide.md

Latest commit

 

History

History
502 lines (359 loc) · 9.74 KB

usage-guide.md

File metadata and controls

502 lines (359 loc) · 9.74 KB

Kullanım Rehberi

Algo Trade Bot'u kurulum, eğitim, backtest ve paper trading için adım adım kullanım.

📋 İçindekiler

  1. Kurulum
  2. Veri İndirme
  3. Feature Engineering
  4. Model Eğitimi
  5. Backtesting
  6. Paper Trading
  7. Monitoring ve Debugging

1. Kurulum

Gereksinimler

  • Python 3.10+
  • pip veya conda
  • Git

Adım 1: Repository'yi Klonla

git clone https://github.com/your-repo/algo-trade-bot.git
cd algo-trade-bot

Adım 2: Virtual Environment (Önerilen)

# venv ile
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# veya conda ile
conda create -n algo-trader python=3.10
conda activate algo-trader

Adım 3: Paketi Kur

# Editable mode (geliştirme için)
pip install -e .

# veya Makefile ile
make install

Adım 4: Kurulumu Doğrula

python -c "from algo_trader import common; print('OK')"

2. Veri İndirme

Binance'ten BTC Verisi

# Varsayılan: Son 2 yıl, 1 saatlik
make ingest

# veya Python ile
python -m algo_trader.data.ingest

CoinGecko'dan Alternatif Veri

make ingest-coingecko

Veri Kontrolü

from algo_trader.common.storage import load_parquet

df = load_parquet("data/raw/btc_1h.parquet")
print(f"Rows: {len(df)}")
print(f"Date range: {df['timestamp'].min()} to {df['timestamp'].max()}")
print(df.head())

Çıktı

data/raw/
└── btc_1h.parquet    # Raw OHLCV verisi

3. Feature Engineering

Feature'ları Oluştur

make features

# veya
python -m algo_trader.data.features

Label'ları Oluştur

make labels

# veya
python -m algo_trader.data.labels

Feature Kontrolü

from algo_trader.common.storage import load_parquet

features = load_parquet("data/raw/btc_1h_features.parquet")
print(f"Features: {features.columns.tolist()}")
print(f"Shape: {features.shape}")  # (N, 37)

labels = load_parquet("data/raw/btc_1h_labels.parquet")
print(f"Labels: {labels.columns.tolist()}")

Feature Listesi

37 teknik gösterge hesaplanır:

Kategori Özellikler
Returns log_return_1, log_return_4, log_return_24
MA sma_24, ema_12, ema_26, close_to_sma_24
Momentum rsi_14, roc_12, roc_24, macd, macd_signal, macd_hist
Volatility rolling_std_24, atr_14, bb_upper, bb_lower, bb_width
Volume volume_sma_24, volume_ratio
Candlestick body_size, upper_shadow, lower_shadow, body_ratio

4. Model Eğitimi

Tam Pipeline

# Tek komutla: ingest → features → labels → train
make pipeline

Adım Adım Eğitim

# 1. Dataset oluştur
make dataset

# 2. Model eğit
make train

# 3. Metrikleri gör
make eval

Python ile Eğitim

from algo_trader.research.train import train_model

result = train_model(
    timeframe="1h",
    target="direction_4",        # 4-bar forward direction
    model_type="sklearn_baseline",
    model_params={"C": 1.0, "balanced": True},
    calibration_method="sigmoid",
)

print(f"Model saved to: {result['model_path']}")
print(f"ROC-AUC: {result['metrics']['roc_auc']:.4f}")

Walk-Forward Validation

Model, kronolojik walk-forward validation ile eğitilir:

|<──── 18 months ────>|<─ 3 mo ─>|
|======= TRAIN =======|=== VAL ===|

                      |<──── 18 months ────>|<─ 3 mo ─>|
                      |======= TRAIN =======|=== VAL ===|

Çıktı Dosyaları

artifacts/
├── registry/
│   └── sklearn_baseline/
│       └── 20260117_143052/
│           ├── model.joblib
│           ├── calibrator.joblib
│           ├── config.json
│           ├── metrics.json
│           └── feature_list.json
└── reports/
    ├── metrics.json
    └── metrics.md

5. Backtesting

Backtest Çalıştır

# En son model ile backtest
make backtest

# Verbose mode
make backtest-verbose

# veya
python -m algo_trader.backtest.engine --run latest_registry --timeframe 1h

Python ile Backtest

from algo_trader.backtest.engine import run_backtest, BacktestConfig
from algo_trader.research.registry import get_latest_model_path

# Model yolu al
model_path = get_latest_model_path("sklearn_baseline")

# Config oluştur
config = BacktestConfig(
    initial_capital=10000,
    fee_bps=5,           # 0.05% işlem ücreti
    slippage_bps=10,     # 0.10% slippage
    execution="NEXT_OPEN",
    max_position_pct=0.20,
    max_drawdown_pct=0.10,
)

# Backtest çalıştır
result = run_backtest(
    model_path=model_path,
    data_path="data/raw/btc_1h.parquet",
    config=config,
)

# Sonuçları yazdır
print(f"Total Return: {result['metrics']['total_return']:.2%}")
print(f"Sharpe Ratio: {result['metrics']['sharpe_ratio']:.2f}")
print(f"Max Drawdown: {result['metrics']['max_drawdown']:.2%}")
print(f"Win Rate: {result['metrics']['win_rate']:.2%}")
print(f"Total Trades: {result['metrics']['total_trades']}")

Raporu Görüntüle

make report

# veya
cat artifacts/backtest/report.md

Çıktı Dosyaları

artifacts/backtest/
├── equity_curve.csv    # Zaman serisi
├── trades.csv          # Trade listesi
├── report.json         # Programmatic metrics
└── report.md           # Okunabilir rapor

Backtest Metrikleri

Metrik Açıklama İyi Değer
Total Return Toplam getiri > 0%
CAGR Yıllık bileşik getiri > 10%
Sharpe Ratio Risk-adjusted return > 1.0
Sortino Ratio Downside risk-adjusted > 1.5
Calmar Ratio Return / Max DD > 2.0
Max Drawdown Maksimum düşüş < 10%
Win Rate Kazanma oranı > 50%
Profit Factor Kar / Zarar > 1.3

6. Paper Trading

Ön Gereksinimler

  1. Alpaca Paper Trading Hesabı: alpaca.markets'ten ücretsiz hesap açın
  2. API Keys: Paper trading API anahtarlarını alın

API Credentials Ayarla

# Environment variables (önerilen)
export ALGO_TRADER_ALPACA_API_KEY="your-api-key"
export ALGO_TRADER_ALPACA_API_SECRET="your-api-secret"

# veya .env dosyası oluştur
echo "ALGO_TRADER_ALPACA_API_KEY=your-api-key" >> .env
echo "ALGO_TRADER_ALPACA_API_SECRET=your-api-secret" >> .env

Paper Trading Başlat

# Sürekli çalıştır (scheduler ile)
make paper-run

# veya
python -m algo_trader.live.runner --paper --symbol BTCUSD --timeframe 1h

Not: Adaptif risk/strateji ayarı varsayılan olarak açıktır. Kapatmak için:

python -m algo_trader.live.runner --paper --no-adaptive --symbol BTCUSD --timeframe 1h

Tek Cycle Test

# Tek bir karar döngüsü
make paper-once

# veya
python -m algo_trader.live.runner --paper --once --symbol BTCUSD --timeframe 1h

Durum Kontrolü

make paper-status

# veya
python -m algo_trader.live.runner --status

Pozisyonları Kapat ve Durdur

make paper-stop

# veya
python -m algo_trader.live.runner --paper --flatten

Python ile Paper Trading

from algo_trader.live.runner import LiveRunner

# Runner oluştur
runner = LiveRunner(
    symbol="BTCUSD",
    timeframe="1h",
    model_path="artifacts/registry/sklearn_baseline/latest",
)

# Status kontrol
status = runner.get_status()
print(f"Running: {status['is_running']}")
print(f"Equity: ${status['equity']:,.2f}")
print(f"Position: {status['position']}")

# Tek cycle çalıştır
result = runner.run_once()
print(f"Signal: {result['signal']}")
print(f"Probability: {result['probability']:.2%}")
print(f"Action: {result['action_taken']}")

Live Trading Dosyaları

artifacts/live/
├── state.json          # Mevcut durum
├── decisions.jsonl     # Karar geçmişi
├── alerts.log          # Alert geçmişi
└── runner.lock         # Instance kilidi

7. Monitoring ve Debugging

Logları İzle

# Runner logları (terminal'de)
make paper-run

# Decision geçmişi
cat artifacts/live/decisions.jsonl | tail -20

# Alert geçmişi
cat artifacts/live/alerts.log

Decision Log Formatı

{"timestamp":"2026-01-17T08:01:00Z","signal":"LONG","probability":0.62,"action":"BUY","order_id":"abc123"}
{"timestamp":"2026-01-17T09:01:00Z","signal":"HOLD","probability":0.58,"action":"NONE","order_id":null}

State Kontrolü

import json

with open("artifacts/live/state.json") as f:
    state = json.load(f)

print(f"Equity: ${state['equity_curve'][-1]['equity']:,.2f}")
print(f"Drawdown: {state['current_drawdown']:.2%}")
print(f"Positions: {list(state['positions'].keys())}")

Test Suite Çalıştır

# Tüm testler
make test

# Backtest testleri
make test-backtest

# Belirli test
pytest src/algo_trader/tests/test_features.py -v

Yaygın Sorunlar

1. API Key Hatası

Error: ALGO_TRADER_ALPACA_API_KEY not set

Çözüm: Environment variable'ları ayarlayın (yukarıya bakın)

2. Data Bulunamadı

FileNotFoundError: data/raw/btc_1h.parquet

Çözüm: make ingest ile veri indirin

3. Model Bulunamadı

No model found in registry

Çözüm: make train ile model eğitin

4. Paper Mode Hatası

SAFETY: Live trading URL detected!

Çözüm: ALGO_TRADER_ALPACA_BASE_URL'in paper URL olduğundan emin olun

📝 Özet Komutlar

# Tam kurulum ve pipeline
make install
make pipeline
make backtest

# Paper trading
export ALGO_TRADER_ALPACA_API_KEY="your-key"
export ALGO_TRADER_ALPACA_API_SECRET="your-secret"
make paper-run

# Monitoring
make paper-status
make paper-stop