#!/usr/bin/env python3
"""
PVA (Price Variation Attention) Strategy Module
================================================

A time-agnostic machine learning strategy for price movement prediction
that combines transformer-based attention with XGBoost prediction heads.

Key Components:
- PVAFeatureEngineer: Return-based feature computation
- PVAModel: Complete model with attention encoder + XGBoost head
- PVATrainer: Training pipeline with walk-forward validation

Architecture Overview:
    OHLCV Data
        |
        v
    [PVAFeatureEngineer]
    - Multi-period returns
    - Acceleration (return derivatives)
    - Volatility of returns
    - Skewness/Kurtosis
    - Price-derived features
        |
        v
    [Sequence Preparation]
    (seq_len, n_features)
        |
        v
    [PVAModel]
    ├── PriceFocusedAttention Encoder (4 layers, 256 dim)
    └── XGBoost Prediction Head
        |
        v
    Output: (direction, magnitude, confidence)

Design Principles:
1. Time-Agnostic: No temporal features (hour, day, session)
2. Price-Focused: All features derived from price returns
3. Interpretable: Attention scores available for analysis
4. Robust: XGBoost head for reliable predictions

Usage Example:
    >>> from src.models.strategies.pva import (
    ...     PVAModel, PVAConfig, PVATrainer, PVAFeatureEngineer
    ... )
    >>>
    >>> # Quick training
    >>> trainer = PVATrainer()
    >>> model, metrics = trainer.train('XAUUSD', '2023-01-01', '2024-12-31')
    >>>
    >>> # Make predictions
    >>> prediction = model.predict(X_test)
    >>> print(f"Direction: {prediction.direction}")
    >>> print(f"Magnitude: {prediction.magnitude}")
    >>> print(f"Confidence: {prediction.confidence}")
    >>>
    >>> # Walk-forward validation
    >>> results = trainer.walk_forward_train('XAUUSD', n_folds=5)
    >>> print(f"Avg accuracy: {results.avg_direction_accuracy:.4f}")

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

# Feature Engineering
from .feature_engineering import (
    PVAFeatureEngineer,
    PVAFeatureConfig,
    compute_pva_features,
)

# Model
from .model import (
    PVAModel,
    PVAConfig,
    PVAPrediction,
    create_pva_model,
)

# Trainer
from .trainer import (
    PVATrainer,
    PVATrainerConfig,
    TrainingMetrics,
    WalkForwardResult,
    train_pva_model,
)


__all__ = [
    # Feature Engineering
    'PVAFeatureEngineer',
    'PVAFeatureConfig',
    'compute_pva_features',

    # Model
    'PVAModel',
    'PVAConfig',
    'PVAPrediction',
    'create_pva_model',

    # Trainer
    'PVATrainer',
    'PVATrainerConfig',
    'TrainingMetrics',
    'WalkForwardResult',
    'train_pva_model',
]

__version__ = '1.0.0'
