#!/usr/bin/env python3
"""
Price-Focused Attention Architecture Module
============================================

This module provides a time-agnostic self-attention architecture
for analyzing price movement sequences in financial markets.

Key Design Principles:
1. Time-Agnostic: No real timestamps, only sequence positions
2. Price-Focused: Operates on returns and price derivatives
3. Multi-Head: 8 attention heads for diverse pattern learning
4. Transformer-Style: 4 layers of self-attention with feed-forward

Main Components:
- PriceFocusedAttention: Main transformer encoder model
- MultiHeadAttention: Core multi-head attention mechanism
- LearnablePositionalEncoding: Time-agnostic position embeddings
- AttentionExtractor: Utilities for attention analysis

Architecture Defaults:
- d_model: 256 (model dimension)
- n_heads: 8 (attention heads)
- d_k: 32 (key/query dimension per head)
- n_layers: 4 (transformer encoder layers)
- d_ff: 1024 (feed-forward dimension)
- dropout: 0.1
- max_seq_len: 512

Example Usage:
    >>> from src.models.attention import (
    ...     PriceFocusedAttention,
    ...     PriceAttentionConfig,
    ...     AttentionExtractor,
    ...     compute_return_features
    ... )
    >>>
    >>> # Configure the model
    >>> config = PriceAttentionConfig(
    ...     d_model=256,
    ...     n_heads=8,
    ...     n_layers=4
    ... )
    >>>
    >>> # Create model
    >>> model = PriceFocusedAttention(config, input_features=4)
    >>>
    >>> # Prepare input (returns-based features)
    >>> import torch
    >>> prices = torch.randn(32, 100, 4)  # OHLC
    >>> features = compute_return_features(prices)
    >>>
    >>> # Forward pass
    >>> output, attentions = model(features)
    >>> print(f"Output shape: {output.shape}")  # (32, 100, 256)
    >>>
    >>> # Extract and visualize attention
    >>> extractor = AttentionExtractor()
    >>> scores = extractor.get_attention_scores(model, features)
    >>> extractor.visualize_attention(scores, save_path='attention.png')

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

# Core attention mechanism
from .multi_head_attention import (
    MultiHeadAttention,
    ScaledDotProductAttention,
    create_causal_mask,
    create_padding_mask,
)

# Positional encoding
from .positional_encoding import (
    LearnablePositionalEncoding,
    SinusoidalPositionalEncoding,
    RelativePositionalEncoding,
)

# Main price-focused attention model
from .price_attention import (
    PriceFocusedAttention,
    PriceAttentionConfig,
    PriceAttentionEncoder,
    PriceAttentionEncoderLayer,
    FeedForwardBlock,
    compute_return_features,
)

# Attention analysis and extraction
from .attention_extractor import (
    AttentionExtractor,
    AttentionScores,
    extract_attention_for_analysis,
)


__all__ = [
    # Core attention
    'MultiHeadAttention',
    'ScaledDotProductAttention',
    'create_causal_mask',
    'create_padding_mask',

    # Positional encoding
    'LearnablePositionalEncoding',
    'SinusoidalPositionalEncoding',
    'RelativePositionalEncoding',

    # Price-focused attention
    'PriceFocusedAttention',
    'PriceAttentionConfig',
    'PriceAttentionEncoder',
    'PriceAttentionEncoderLayer',
    'FeedForwardBlock',
    'compute_return_features',

    # Attention extraction
    'AttentionExtractor',
    'AttentionScores',
    'extract_attention_for_analysis',
]


# Module version
__version__ = '1.0.0'
