#!/usr/bin/env python3
"""
VBP (Volatility Breakout Predictor) Strategy Module
====================================================
Machine learning strategy for predicting volatility breakouts.

The VBP strategy identifies potential breakout setups by detecting:
1. Volatility compression (squeeze indicators)
2. Historical volatility patterns
3. Range contraction followed by expansion

Key Components:
- VBPFeatureEngineer: Extracts volatility-based features (ATR, BB, KC, squeeze)
- VolatilityCNN: 1D CNN with self-attention for temporal pattern encoding
- VBPModel: Complete model combining CNN encoder with XGBoost classifier
- VBPTrainer: Training system with balanced sampling and walk-forward CV

Strategy Theory:
Breakouts typically occur after periods of low volatility (compression).
The model learns to identify these compression patterns and predict:
1. Whether a breakout will occur
2. Direction (bullish/bearish)
3. Magnitude (in ATR units)

Class Imbalance Handling:
Since breakouts are rare events (~5-10% of data), the module implements:
- Oversampling of breakout samples (3x default)
- Class weight balancing in XGBoost
- F1 score optimization for minority classes

Usage Example:
    from src.models.strategies.vbp import (
        VBPModel,
        VBPModelConfig,
        VBPTrainer,
        VBPTrainerConfig,
        VBPFeatureEngineer
    )

    # Configure and create model
    config = VBPModelConfig(
        sequence_length=50,
        xgb_n_estimators=200,
        use_gpu=True
    )
    model = VBPModel(config)

    # Train on OHLCV data
    model.fit(df_train)

    # Get predictions
    predictions = model.predict(df_test)
    for pred in predictions:
        print(f"Signal: {pred.signal}, Prob: {pred.breakout_probability:.2f}")

    # Or use trainer for walk-forward validation
    trainer = VBPTrainer(VBPTrainerConfig())
    metrics = trainer.walk_forward_train('XAUUSD', df)

Author: ML-Specialist (NEXUS v4.0)
Version: 1.0.0
Created: 2026-01-25
"""

# Feature Engineering
from .feature_engineering import (
    VBPFeatureEngineer,
    VBPFeatureConfig,
)

# CNN Encoder
from .cnn_encoder import (
    VolatilityCNN,
    CNNEncoderConfig,
    Conv1DBlock,
    SelfAttention1D,
    MultiScaleVolatilityCNN,
)

# Complete Model
from .model import (
    VBPModel,
    VBPModelConfig,
    VBPPrediction,
    NeuralHead,
)

# Training
from .trainer import (
    VBPTrainer,
    VBPTrainerConfig,
    VBPMetrics,
    VBPDataset,
)


__all__ = [
    # Feature Engineering
    'VBPFeatureEngineer',
    'VBPFeatureConfig',

    # CNN Encoder
    'VolatilityCNN',
    'CNNEncoderConfig',
    'Conv1DBlock',
    'SelfAttention1D',
    'MultiScaleVolatilityCNN',

    # Model
    'VBPModel',
    'VBPModelConfig',
    'VBPPrediction',
    'NeuralHead',

    # Training
    'VBPTrainer',
    'VBPTrainerConfig',
    'VBPMetrics',
    'VBPDataset',
]


__version__ = '1.0.0'
__author__ = 'ML-Specialist (NEXUS v4.0)'
