Quick Start - risik01/stock-ai GitHub Wiki

โšก Quick Start Guide - Stock AI Trading System

Inizia subito con il Stock AI Trading System! Questa guida ti porterร  dall'installazione alla prima sessione di trading in meno di 15 minuti.

๐ŸŽฏ Obiettivo Quick Start

Al termine di questa guida avrai:

  • โœ… Sistema completamente funzionante
  • โœ… Portfolio virtuale attivo con $10K
  • โœ… News Trading AI operativo
  • โœ… Dashboard web accessibili
  • โœ… Prima sessione di trading simulato

โฑ๏ธ 15-Minute Setup

โšก Step 1: Clone & Setup (3 min)

# Clone repository
git clone https://github.com/risik01/stock-ai.git
cd stock-ai

# Crea virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate    # Windows

# Install dependencies
pip install -r requirements.txt

โšก Step 2: News Dependencies (2 min)

# Install News Trading dependencies
pip install feedparser textblob vaderSentiment nltk beautifulsoup4 lxml

# Download NLTK data
python -c "import nltk; nltk.download('vader_lexicon'); nltk.download('punkt')"

โšก Step 3: Quick Test (5 min)

# Test 1: Data collection
python src/data_collector.py --symbols AAPL --period 1mo

# Test 2: News system
python trading-new/news_trading_cli.py cycle

# Test 3: RL Agent
python src/test_rl.py --quick

# Test 4: Web dashboard
python src/web_dashboard.py &
python trading-new/news_web_dashboard.py &

โšก Step 4: First Trading Session (5 min)

# Avvia trading automatico simulato
python src/main.py --mode simulation --duration 300  # 5 minuti

# Monitora in tempo reale
python src/cli_monitor.py

๐ŸŽฎ Demo Mode - Prova Immediata

๐Ÿš€ Modalitร  Demo Completa

# Avvia tutto in demo mode
./scripts/demo_start.sh

# O manualmente:
python src/main.py --demo --symbols AAPL,GOOGL,TSLA --duration 600

Cosa include Demo Mode:

  • ๐Ÿ“Š Dati Live: Prezzi reali da Yahoo Finance
  • ๐Ÿค– RL Agent: Pre-trained model per decisioni immediate
  • ๐Ÿ“ฐ News Analysis: Sentiment analysis in tempo reale
  • ๐Ÿ’ฐ Virtual Portfolio: $10,000 iniziali
  • ๐Ÿ“ˆ Live Dashboard: Grafici e metriche real-time

๐Ÿ‘€ Cosa Vedere Durante Demo

Terminal Output:

๐Ÿค– RL Agent initialized - Model loaded
๐Ÿ“ฐ News collector started - 6/10 sources active
๐Ÿ’ฐ Portfolio: $10,000 (100% cash)
๐Ÿ“Š Monitoring: AAPL, GOOGL, TSLA

[12:34:56] ๐Ÿ“ˆ AAPL: $175.30 (+0.5%) | Sentiment: +0.2 | Signal: BUY
[12:35:12] ๐Ÿ”ฅ Breaking: Apple earnings beat expectations (Sentiment: +0.7)
[12:35:15] ๐Ÿ’ฐ TRADE: BUY AAPL 28 shares @ $175.30 ($4,908.40)
[12:35:16] ๐Ÿ“Š Portfolio: $5,091.60 cash + $4,908.40 stocks = $10,000.00

Web Dashboard:

๐ŸŽฏ Primi Comandi Essenziali

๐Ÿ“Š Monitoraggio Portfolio

# Status portfolio corrente
python src/portfolio.py --status

# Performance history
python src/portfolio.py --history

# Risk analysis
python src/portfolio.py --risk

Output Example:

๐Ÿ’ฐ PORTFOLIO STATUS
โ”œโ”€โ”€ Total Value: $10,247.50 (+2.48%)
โ”œโ”€โ”€ Cash: $2,150.30 (21.0%)
โ”œโ”€โ”€ Positions: 3 active
โ”‚   โ”œโ”€โ”€ AAPL: 28 shares ($4,908.40, +1.2%)
โ”‚   โ”œโ”€โ”€ GOOGL: 15 shares ($2,189.85, +3.1%)
โ”‚   โ””โ”€โ”€ TSLA: 8 shares ($998.95, -0.8%)
โ””โ”€โ”€ P&L Today: +$97.35 (+0.98%)

๐Ÿ“ฐ News Analysis

# Latest news analysis
python trading-new/news_trading_cli.py news

# Current signals
python trading-new/news_trading_cli.py signals

# Breaking news alerts
python trading-new/news_trading_cli.py alerts

Output Example:

๐Ÿ“ฐ NEWS ANALYSIS (Last Hour)
โ”œโ”€โ”€ Articles: 47 collected from 6 sources
โ”œโ”€โ”€ Breaking News: 3 items
โ”œโ”€โ”€ Sentiment Score: +0.15 (Slightly Positive)
โ””โ”€โ”€ Trading Signals: 2 BUY, 1 SELL

๐ŸŽฏ ACTIVE SIGNALS
โ”œโ”€โ”€ AAPL: BUY (Sentiment: +0.3, Confidence: 0.8)
โ”œโ”€โ”€ TSLA: SELL (Sentiment: -0.2, Confidence: 0.7)
โ””โ”€โ”€ GOOGL: HOLD (Sentiment: +0.1, Confidence: 0.5)

๐Ÿค– RL Agent Control

# Agent status
python src/rl_agent.py --status

# Force retrain (if needed)
python src/train_rl.py --episodes 100

# Model performance
python src/rl_agent.py --performance

๐ŸŒ Dashboard Walkthrough

๐Ÿ“Š Main Dashboard (http://localhost:5000)

Sezioni Principali:

  1. ๐Ÿ  Overview: Portfolio value, daily P&L, win rate
  2. ๐Ÿ“ˆ Charts: Price charts con segnali RL
  3. ๐Ÿ’ฐ Portfolio: Posizioni correnti e allocation
  4. ๐Ÿ“Š Performance: Metriche storiche e benchmark
  5. โš™๏ธ Settings: Configurazione live

Key Metrics da Monitorare:

  • Total Portfolio Value: Valore totale investimenti
  • Daily Return: Performance giornaliera
  • Sharpe Ratio: Rendimento aggiustato per rischio
  • Max Drawdown: Massima perdita dal picco
  • Win Rate: Percentuale trades profittevoli

๐Ÿ“ฐ News Dashboard (http://localhost:5001)

Sezioni:

  1. ๐Ÿ“ฐ Live Feed: Stream notizie in tempo reale
  2. ๐ŸŽฏ Signals: Segnali trading basati su news
  3. ๐Ÿ“Š Sentiment: Grafici sentiment per simbolo
  4. ๐Ÿšจ Alerts: Breaking news e eventi critici
  5. ๐Ÿ“ˆ Impact: Correlazione news-prezzi

Funzionalitร  Interattive:

  • Real-time Updates: Aggiornamento automatico ogni 30s
  • Symbol Filtering: Filtra per simboli specifici
  • Sentiment Timeline: Storia sentiment per simbolo
  • News Source Toggle: Abilita/disabilita fonti specifiche

๐ŸŽฎ Modalitร  Operative

๐Ÿ”’ Simulation Mode (Default)

# Trading simulato - zero rischi
python src/main.py --mode simulation

# Caratteristiche:
# โœ… Portfolio virtuale ($10K)
# โœ… Prezzi reali di mercato
# โœ… Trades registrati ma non eseguiti
# โœ… Performance tracking completo

๐Ÿ“Š Backtest Mode

# Test su dati storici
python src/main.py --mode backtest --start 2023-01-01 --end 2023-12-31

# Risultati:
# โœ… Performance vs Buy & Hold
# โœ… Maximum Drawdown analysis
# โœ… Sharpe Ratio calculation
# โœ… Trade statistics

๐Ÿ‘๏ธ Watch Mode

# Solo monitoraggio, no trading
python src/main.py --mode watch --symbols AAPL,GOOGL,MSFT

# Output:
# โœ… Prezzi live
# โœ… Segnali generati
# โœ… News sentiment
# โœ… Nessun trade eseguito

๐ŸŽฏ Paper Trading Mode

# Trading realistico con denaro virtuale
python src/main.py --mode paper --cash 50000

# Simula:
# โœ… Latency di mercato
# โœ… Slippage dei prezzi
# โœ… Transaction costs
# โœ… Market hours restrictions

๐Ÿ› ๏ธ Personalizzazione Rapida

๐ŸŽฏ Scegli i Tuoi Simboli

# Edita config/settings.json
nano config/settings.json

{
    "data_collector": {
        "symbols": ["AAPL", "GOOGL", "MSFT", "TSLA", "AMZN", "NVDA"],
        "period": "2y",
        "interval": "1d"
    }
}

๐Ÿ’ฐ Personalizza Portfolio

{
    "portfolio": {
        "initial_cash": 50000,        // $50K invece di $10K
        "max_position_size": 0.15,    // Max 15% per posizione
        "transaction_cost": 0.0005,   // 0.05% transaction cost
        "stop_loss": 0.05             // Stop-loss a 5%
    }
}

๐Ÿ“ฐ Configura News Sources

{
    "news": {
        "sources": {
            "yahoo_finance": true,
            "cnbc": true,
            "reuters": true,
            "bloomberg": false,    // Disabilita se non necessario
            "marketwatch": true
        },
        "update_interval": 300,    // Ogni 5 minuti
        "sentiment_threshold": 0.1  // Soglia per segnali
    }
}

๐Ÿ“Š Primi Risultati - Cosa Aspettarsi

โœ… Successo Indicators

Dopo 1 ora di trading:

  • ๐Ÿ“Š Portfolio Value: Oscillazioni tra -2% e +3%
  • ๐Ÿค– RL Decisions: 5-15 segnali generati
  • ๐Ÿ“ฐ News Analysis: 20-50 articoli processati
  • ๐Ÿ’ฐ Trades: 1-3 trades eseguiti
  • ๐Ÿ“ˆ Performance: Tracking accurato

Log Output Tipico:

[14:30:15] ๐Ÿ“Š Market Open - Starting analysis
[14:30:45] ๐Ÿ“ฐ Collected 23 news articles
[14:31:02] ๐Ÿค– RL Signal: AAPL BUY (confidence: 0.72)
[14:31:05] ๐Ÿ“ˆ News Sentiment: AAPL +0.3 (positive)
[14:31:08] ๐Ÿ’ฐ TRADE: BUY AAPL 15 shares @ $175.42
[14:31:10] ๐ŸŽฏ Portfolio: +0.15% today

โš ๏ธ Warning Signs da Controllare

  • RSS Errors: >50% fonti fallite
  • Model Errors: RL agent non risponde
  • Data Gaps: Prezzi non aggiornati
  • Memory Issues: Usage >80%
  • Performance: Cycle time >30s

๐ŸŽฏ Configurazioni Raccomandate

๐Ÿ”ฐ Principiante

{
    "symbols": ["AAPL", "GOOGL", "MSFT"],
    "initial_cash": 10000,
    "max_position_size": 0.2,
    "mode": "simulation",
    "risk_tolerance": "low"
}

๐Ÿ“ˆ Intermediate

{
    "symbols": ["AAPL", "GOOGL", "MSFT", "TSLA", "AMZN", "NVDA"],
    "initial_cash": 25000,
    "max_position_size": 0.15,
    "mode": "paper",
    "risk_tolerance": "medium"
}

๐Ÿš€ Advanced

{
    "symbols": ["AAPL", "GOOGL", "MSFT", "TSLA", "AMZN", "NVDA", "META", "NFLX"],
    "initial_cash": 100000,
    "max_position_size": 0.1,
    "mode": "paper",
    "risk_tolerance": "high",
    "enable_shorting": true
}

๐Ÿš€ Prossimi Passi

Dopo il Quick Start, esplora:

๐Ÿ“š Approfondimenti

  1. RL Agent Overview - Capire l'AI trading
  2. News Trading Overview - Sentiment analysis
  3. Configuration Files - Setup avanzato
  4. Performance Analysis - Ottimizzare risultati

๐Ÿ› ๏ธ Customizzazione

  1. Nuove Strategie: Sviluppa algoritmi custom
  2. Additional Data: Integra piรน fonti dati
  3. Risk Management: Implementa stop-loss avanzati
  4. Alert System: Setup notifiche Discord/Slack

๐Ÿ“Š Produzione

  1. Live Trading: Migrazione a broker reale
  2. Cloud Deployment: Deploy su AWS/GCP
  3. Monitoring: Setup alerting professionale
  4. Scaling: Multiple accounts/strategies

๐Ÿ†˜ Quick Troubleshooting

โŒ Errori Comuni

# Problema: ModuleNotFoundError
pip install -r requirements.txt

# Problema: Portfolio non si carica
rm data/current_portfolio.pkl
python src/portfolio.py --reset

# Problema: News feeds non funzionano
python trading-new/news_rss_collector.py --debug

# Problema: RL Agent errori
python src/train_rl.py --episodes 50 --force

๐Ÿ”ง Reset Completo

# Reset tutto ai defaults
rm -rf data/cache/*
rm data/current_portfolio.pkl data/rl_model.pkl
cp config/settings.json.example config/settings.json
python src/main.py --init

๐ŸŽ‰ Congratulazioni!

๐Ÿš€ Il tuo Stock AI Trading System รจ ora operativo!

  • โœ… Sistema funzionante in meno di 15 minuti
  • โœ… Portfolio virtuale attivo
  • โœ… News trading automatico
  • โœ… Dashboard live accessibili
  • โœ… Pronto per trading simulato

Next: Esplora le funzionalitร  avanzate e personalizza il sistema secondo le tue esigenze!

Happy Trading! ๐Ÿ“ˆ๐Ÿ’ฐ