📈 Stock Scout

AI-powered stock recommendation system combining technical analysis, fundamental scoring, and machine learning (XGBoost) to identify high-probability trading opportunities in US equities.

---

---

🎯 What Makes This Different?

1. ML-Powered Confidence Scoring 🤖

• XGBoost model trained on 231 historical signals (5-day forward returns)
• 61% improvement over baseline logistic regression (AUC 0.534 vs 0.332)
• Time-tested: Successfully identified AAPL with 69.4% confidence before actual price move
• Confidence tiers: High (🟢 >50%), Medium (🟡 30-50%), Low (🔴 <30%)
• Explainable AI: SHAP values show which factors drive each prediction

2. Comprehensive Multi-Source Data 📊

• 10 data providers: Yahoo Finance, Alpha Vantage, Finnhub, Polygon, Tiingo, FMP, SimFin, Marketstack, Nasdaq Data Link, EODHD
• Automatic fallback: If one provider fails, seamlessly switches to next
• Price verification: Cross-validates prices across multiple sources
• Reliability scoring: Tracks data completeness and source agreement

3. Advanced Technical & Fundamental Analysis 📈

3. Advanced Technical & Fundamental Analysis 📈

Technical Indicators:

• Moving averages (20/50/200), RSI, ATR, MACD, ADX
• Momentum consistency, volume surge detection
• Near 52-week high positioning
• Overextension vs MA_50 (pullback detection)
• Reward/risk ratio calculation

Fundamental Scoring (Transparent Breakdown):

• Quality (High/Medium/Low): ROE, ROIC, Gross Margin
• Growth (Fast/Moderate/Slow): Revenue YoY, EPS YoY
• Valuation (Cheap/Fair/Expensive): P/E, P/S ratios
• Leverage (Low/Medium/High): Debt-to-Equity
• Color-coded labels in UI for instant assessment

Risk Management:

• Earnings blackout window (7 days default)
• Beta filtering vs SPY/QQQ
• Sector diversification caps
• ATR-based position sizing
• Min/max position constraints

---

🚀 Quick Start

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• API keys for data providers (optional but recommended)

Installation

# Clone repository
git clone https://github.com/asafamos/stock-scout.git
cd stock-scout

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration

Create a .env file with your API keys (optional):

ALPHA_VANTAGE_API_KEY=your_key_here
FINNHUB_API_KEY=your_key_here
POLYGON_API_KEY=your_key_here
TIINGO_API_KEY=your_key_here
FMP_API_KEY=your_key_here
# ... (see .env.example for full list)

Run

streamlit run stock_scout.py

Open browser at: http://localhost:8501

---

📊 ML Model Performance

Model Architecture (v3)

• Ensemble: HistGradientBoosting (45%) + RandomForest (35%) + LogisticRegression (20%)
• Features: 34 engineered features across 7 categories
• Calibration: Isotonic regression for reliable probabilities
• Validation: Time-Series Cross-Validation (5 folds)

Feature Categories (34 total)

Category	Count	Examples
Technical	5	RSI, ATR_Pct, Returns (5d/10d/20d)
Volatility	4	VCP_Ratio, Tightness, MA_Alignment
Volume Basic	3	Volume_Surge, Up_Down_Ratio
Market Regime	4	Market_Regime, Volatility, Trend
Sector Relative	3	Sector_RS, Sector_Momentum
Volume Advanced	5	Volume_Trend, Accumulation signals
Price Action	9	52w positioning, Support/Resistance

Validation Metrics

• Out-of-Sample AUC: Check models/model_20d_v3.pkl.metadata.json
• Precision@20: Top 20 predictions accuracy
• Lift: Improvement over random baseline

Key Files

• core/feature_registry.py - Single source of truth for 34 features
• core/ml_integration.py - Model loading with validation
• scripts/train_rolling_ml_20d.py - Training script
• models/model_20d_v3.pkl - Latest trained model

---

🏗️ Architecture

stock-scout-2/
├── stock_scout.py              # Main Streamlit app
├── models/model_20d_v3.pkl     # Latest ML model bundle (sklearn)
├── backtest_recommendations.py # Historical signal generator
├── train_recommender.py        # Model training script
├── core/                       # Business logic
│   ├── config.py               # Configuration management
│   ├── data_sources_v2.py      # Multi-provider data fetching (canonical)
│   ├── data/                   # Unified data API
│   ├── classification.py       # Risk classification (Core/Speculative)
│   ├── portfolio.py            # Position sizing & allocation
│   ├── scoring/                # Scoring modules
│   └── legacy/                 # Deprecated modules (do not use)
├── tools/                      # Debug, audit, benchmark scripts
└── tests/                      # Unit tests

---

📖 Documentation

• SUMMARY_HE.md - Hebrew summary of ML improvements
• MODEL_COMPARISON.md - XGBoost vs Logistic performance
• PRODUCTION_INTEGRATION.md - Deployment guide
• INTEGRATION_SUCCESS.md - Usage examples & monitoring
• ARCHITECTURE.md - System design overview
• DATA_SOURCES_REPORT.md - Provider capabilities

---

🔧 Advanced Usage

Meteor Mode (Aggressive Discovery)

• Purpose: Emphasizes tight VCP contractions, strong RS, and pocket pivots for large-universe momentum scouting.
• Env vars:
  • METEOR_MODE=1: Enable momentum-friendly RSI mapping and Meteor filters.
  • MIN_MCAP/MAX_MCAP: Universe market-cap bounds (e.g., 300000000 → 15000000000).
  • EARNINGS_THRESHOLD: Optional blackout window in days (default 7).
• Core signals: VCP_Ratio (ATR10/ATR30), Dist_From_52w_High, RS_21d/RS_63d, Pocket_Pivot_Ratio, Volume_Surge_Ratio.
• RS ranking: Early blended pass across full universe: 0.7*RS_63d + 0.3*RS_21d, filter top 20% before deep scans.
• Runner example:

python run_2000_meteor_scan.py

Outputs CSV at reports/meteor_results_YYYYMMDD.csv including Meteor_Confidence_Score.

Backtesting on Custom Date Range

python backtest_recommendations.py \
    --use-finnhub \
    --limit 500 \
    --start 2024-01-01 \
    --end 2024-12-31 \
    --horizons 5,10,20

Retraining the ML Model

# Generate new signals
python backtest_recommendations.py --use-finnhub --limit 500

# Train model
python train_recommender.py \
    --signals backtest_signals_latest.csv \
    --horizon 5 \
    --model xgboost \
    --cv

# Validate on known movers
python time_test_validation.py \
    --model models/model_20d_v3.pkl \
    --cases cases_example.csv

Running Tests

pytest tests/ -v

---

🎨 UI Features

• Modern design system with dark mode support
• Hebrew RTL support for local market
• Interactive charts (Plotly)
• CSV export with ML scores
• Real-time filtering by risk level, sector, score range
• Confidence badges showing ML probability
• Data quality indicators for each stock

---

⚠️ Disclaimer

This is not investment advice. Stock Scout is a research and educational tool. Always:

• Conduct your own due diligence
• Understand the risks involved in trading
• Never invest more than you can afford to lose
• Consult with a licensed financial advisor

Past performance does not guarantee future results.

---

📄 License

MIT License - see LICENSE file for details.

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📧 Contact

Author: Asaf
Repository: github.com/asafamos/stock-scout

---

Built with ❤️ using Python, Streamlit, XGBoost, and lots of data