dfm-python 0.6.13__py3-none-any.whl → 0.7.0__py3-none-any.whl

dfm_python/__init__.py

@@ -63,7 +63,7 @@ Note: DFMConfig uses frequency dict to specify series (column names -> frequenci
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.6.13"
+__version__ = "0.7.0"
 
 # ============================================================================
 # PUBLIC API DEFINITION
@@ -98,6 +98,7 @@ from .utils.metric import calculate_rmse
 # Users can import these directly from dfm_python
 from .dataset.dfm_dataset import DFMDataset
 from .dataset.ddfm_dataset import DDFMDataset
+from .dataset.afm_dataset import AFMDataset
 
 # Model implementations
 from .models.base import BaseFactorModel
@@ -109,6 +110,12 @@ try:
 except ImportError:
     DDFM = None
 
+# AFM high-level API (Attention Factor Model; PyTorch is mandatory)
+try:
+    from .models.afm.afm import AFM
+except ImportError:
+    AFM = None
+
 __all__ = [
     # Core classes
     'DFM',
@@ -121,14 +128,16 @@ __all__ = [
     'BaseResult', 'DFMResult', 'DDFMResult', 'calculate_rmse',
 ]
 
-# DDFM high-level API (PyTorch is mandatory)
+# DDFM / AFM high-level API (PyTorch is mandatory)
 __all__.extend([
     'DDFM',  # High-level API class
+    'AFM',   # Attention Factor Model
 ])
 
 # Dataset classes
 __all__.extend([
     'DFMDataset',  # DFM Dataset class
     'DDFMDataset',  # DDFM Dataset class
+    'AFMDataset',  # AFM Dataset class
 ])
 

dfm_python/config/__init__.py

@@ -8,9 +8,9 @@ Note: Series are specified via frequency dict mapping column names to frequencie
 """
 
 from .schema import (
-    BaseModelConfig, DFMConfig, DDFMConfig,
-    BaseResult, DFMResult, DDFMResult,
-    DFMStateSpaceParams, DDFMStateSpaceParams,
+    BaseModelConfig, DFMConfig, DDFMConfig, AFMConfig,
+    BaseResult, DFMResult, DDFMResult, AFMResult,
+    DFMStateSpaceParams, DDFMStateSpaceParams, AFMModelState,
 )
 # DEFAULT_BLOCK_NAME is imported lazily where needed to avoid circular imports
 from .constants import (
@@ -97,11 +97,11 @@ __all__ = [
     'BaseModelConfig', 'BaseResult',
     # 'DEFAULT_BLOCK_NAME',  # Removed to avoid circular import
     # Model-specific configs (from schema.py)
-    'DFMConfig', 'DDFMConfig',
+    'DFMConfig', 'DDFMConfig', 'AFMConfig',
     # State-space parameters
-    'DFMStateSpaceParams', 'DDFMStateSpaceParams',
+    'DFMStateSpaceParams', 'DDFMStateSpaceParams', 'AFMModelState',
     # Model-specific results (from results.py)
-    'DFMResult', 'DDFMResult',
+    'DFMResult', 'DDFMResult', 'AFMResult',
     # Utilities
     'validate_frequency',
     # IO

dfm_python/config/constants.py

@@ -344,6 +344,53 @@ COMPUTATION_ERROR_TYPES = (RuntimeError, ValueError, TypeError, AttributeError,
 DEFAULT_KDFM_AR_ORDER = 1  # Default AR order (VAR lag order p) for KDFM
 DEFAULT_KDFM_MA_ORDER = 0  # Default MA order (MA lag order q) for KDFM (0 = pure VAR)
 
+# ============================================================================
+# iVDFM Defaults
+# ============================================================================
+
+# iVDFM dimension defaults
+DEFAULT_IVDFM_LATENT_DIM = 3  # Default number of factors
+DEFAULT_IVDFM_AUX_DIM = 1  # Default auxiliary variable dimension
+
+# iVDFM regime (K=1 = baseline iVDFM, no regime structure)
+DEFAULT_IVDFM_NUM_REGIMES = 1  # Number of discrete regimes; 1 = baseline iVDFM
+DEFAULT_IVDFM_REGIME_TEMPERATURE = 1.0  # Softmax temperature for π; τ < 1 sharpens (local commitment)
+DEFAULT_IVDFM_MIXING = False  # If True, apply global post-factor mixing f -> M f (identity init) before decode
+
+# iVDFM network architecture defaults
+DEFAULT_IVDFM_ENCODER_HIDDEN_DIM = 200  # Default encoder hidden dimension
+DEFAULT_IVDFM_ENCODER_N_HIDDEN_LAYERS = 2  # Default encoder hidden layers
+DEFAULT_IVDFM_DECODER_TYPE = "mlp"  # Default: 'linear', 'residual', or 'mlp' (mlp = current behavior)
+DEFAULT_IVDFM_DECODER_HIDDEN_DIM = 200  # Default decoder hidden dimension
+DEFAULT_IVDFM_DECODER_N_HIDDEN_LAYERS = 2  # Default decoder hidden layers
+DEFAULT_IVDFM_PRIOR_HIDDEN_DIM = 100  # Default prior network hidden dimension
+DEFAULT_IVDFM_PRIOR_N_HIDDEN_LAYERS = 1  # Default prior network hidden layers
+
+# iVDFM dynamics and distribution defaults
+DEFAULT_IVDFM_FACTOR_ORDER = 1  # Default AR order for factors
+DEFAULT_IVDFM_INNOVATION_DIST = 'laplace'  # Default innovation distribution
+DEFAULT_IVDFM_DECODER_VAR = 0.01  # Default decoder variance
+DEFAULT_IVDFM_ACTIVATION = 'lrelu'  # Default activation function
+DEFAULT_IVDFM_SLOPE = 0.1  # Default leaky ReLU slope
+
+# iVDFM training defaults
+DEFAULT_IVDFM_BATCH_SIZE = 32  # Default batch size
+DEFAULT_IVDFM_MAX_EPOCHS = 100  # Default maximum epochs
+DEFAULT_IVDFM_AUX_VARIABLE_TYPE = 'time'  # Default auxiliary variable type
+
+# iVDFM optimizer defaults
+DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY = 0.0  # Default weight decay for optimizer
+DEFAULT_IVDFM_OPTIMIZER_MOMENTUM = 0.9  # Default momentum for SGD
+
+# iVDFM scheduler defaults
+DEFAULT_IVDFM_SCHEDULER_TYPE = 'step'  # Default scheduler type: 'step', 'plateau', 'cosine', 'exponential', None
+DEFAULT_IVDFM_SCHEDULER_STEP_SIZE = None  # Default step_size for StepLR (auto: max_epochs // 3)
+DEFAULT_IVDFM_SCHEDULER_GAMMA = 0.5  # Default gamma for StepLR/ExponentialLR
+DEFAULT_IVDFM_SCHEDULER_PATIENCE = 10  # Default patience for ReduceLROnPlateau
+DEFAULT_IVDFM_SCHEDULER_FACTOR = 0.1  # Default factor for ReduceLROnPlateau
+DEFAULT_IVDFM_SCHEDULER_MIN_LR = 0.0  # Default min_lr for ReduceLROnPlateau
+DEFAULT_IVDFM_EARLY_STOP_PATIENCE = 20  # Default patience for early stopping (epochs without improvement)
+
 # ============================================================================
 # Tutorial Defaults
 # ============================================================================
@@ -410,11 +457,35 @@ FREQUENCY_HIERARCHY: Dict[str, int] = {
 # For frequency gaps larger than this, the missing data approach is used instead
 MAX_TENT_SIZE: int = 12
 
+# ============================================================================
+# AFM (Attention Factor Model) defaults
+# ============================================================================
+DEFAULT_AFM_NUM_FACTORS = 5          # K latent factors
+DEFAULT_AFM_FACTOR_MODEL = 'attention'  # 'attention' | 'pca'
+DEFAULT_AFM_TRADING = 'longconv'     # 'longconv' | 'ou'
+DEFAULT_AFM_EMBED_DIM = 32           # characteristic embedding dimension d
+DEFAULT_AFM_HIST_LEN = 20            # residual-history length s for the filter
+DEFAULT_AFM_N_KERNELS = 32           # number of long convolutions
+DEFAULT_AFM_RIDGE = 1e-2             # ridge penalty for closed-form loadings
+DEFAULT_AFM_SQUASH_LAMBDA = 1e-3     # LongConv Squash kernel regularizer strength
+DEFAULT_AFM_PCA_WINDOW = 252         # trailing window for the PCA benchmark
+DEFAULT_AFM_REESTIM = 21             # PCA re-estimation stride
+DEFAULT_AFM_LAMBDA_VAR = 0.1         # explained-variance regularizer weight
+DEFAULT_AFM_TURNOVER_COST = 5e-4     # 5bps per unit turnover (paper)
+DEFAULT_AFM_SHORT_COST = 1e-4        # 1bp shorting cost (paper)
+DEFAULT_AFM_MAX_EPOCHS = 50          # training epochs
+
 # ============================================================================
 # Export all constants
 # ============================================================================
 
 __all__ = [
+    # AFM
+    'DEFAULT_AFM_NUM_FACTORS', 'DEFAULT_AFM_FACTOR_MODEL', 'DEFAULT_AFM_TRADING',
+    'DEFAULT_AFM_EMBED_DIM', 'DEFAULT_AFM_HIST_LEN', 'DEFAULT_AFM_N_KERNELS',
+    'DEFAULT_AFM_RIDGE', 'DEFAULT_AFM_SQUASH_LAMBDA', 'DEFAULT_AFM_PCA_WINDOW',
+    'DEFAULT_AFM_REESTIM', 'DEFAULT_AFM_LAMBDA_VAR', 'DEFAULT_AFM_TURNOVER_COST',
+    'DEFAULT_AFM_SHORT_COST', 'DEFAULT_AFM_MAX_EPOCHS',
     # Convergence
     'DEFAULT_CONVERGENCE_THRESHOLD',
     'DEFAULT_EM_THRESHOLD',
@@ -564,6 +635,25 @@ __all__ = [
     # KDFM defaults
     'DEFAULT_KDFM_AR_ORDER',
     'DEFAULT_KDFM_MA_ORDER',
+    # iVDFM defaults
+    'DEFAULT_IVDFM_LATENT_DIM',
+    'DEFAULT_IVDFM_AUX_DIM',
+    'DEFAULT_IVDFM_ENCODER_HIDDEN_DIM',
+    'DEFAULT_IVDFM_ENCODER_N_HIDDEN_LAYERS',
+    'DEFAULT_IVDFM_NUM_REGIMES',
+    'DEFAULT_IVDFM_DECODER_TYPE',
+    'DEFAULT_IVDFM_DECODER_HIDDEN_DIM',
+    'DEFAULT_IVDFM_DECODER_N_HIDDEN_LAYERS',
+    'DEFAULT_IVDFM_PRIOR_HIDDEN_DIM',
+    'DEFAULT_IVDFM_PRIOR_N_HIDDEN_LAYERS',
+    'DEFAULT_IVDFM_FACTOR_ORDER',
+    'DEFAULT_IVDFM_INNOVATION_DIST',
+    'DEFAULT_IVDFM_DECODER_VAR',
+    'DEFAULT_IVDFM_ACTIVATION',
+    'DEFAULT_IVDFM_SLOPE',
+    'DEFAULT_IVDFM_BATCH_SIZE',
+    'DEFAULT_IVDFM_MAX_EPOCHS',
+    'DEFAULT_IVDFM_AUX_VARIABLE_TYPE',
     # Tutorial defaults
     'TUTORIAL_MAX_PERIODS',
     'TUTORIAL_MAX_EPOCHS',

dfm_python/config/schema/__init__.py

@@ -7,13 +7,13 @@ This package contains:
 Note: Series are specified via frequency dict mapping column names to frequencies.
 """
 
-from .model import BaseModelConfig, DFMConfig, DDFMConfig
-from .results import BaseResult, DFMResult, DDFMResult
-from .params import DFMStateSpaceParams, DDFMStateSpaceParams
+from .model import BaseModelConfig, DFMConfig, DDFMConfig, iVDFMConfig, AFMConfig
+from .results import BaseResult, DFMResult, DDFMResult, iVDFMResult, AFMResult
+from .params import DFMStateSpaceParams, DDFMStateSpaceParams, iVDFMModelState, AFMModelState
 
 __all__ = [
-    'BaseModelConfig', 'DFMConfig', 'DDFMConfig',
-    'BaseResult', 'DFMResult', 'DDFMResult',
-    'DFMStateSpaceParams', 'DDFMStateSpaceParams',
+    'BaseModelConfig', 'DFMConfig', 'DDFMConfig', 'iVDFMConfig', 'AFMConfig',
+    'BaseResult', 'DFMResult', 'DDFMResult', 'iVDFMResult', 'AFMResult',
+    'DFMStateSpaceParams', 'DDFMStateSpaceParams', 'iVDFMModelState', 'AFMModelState',
 ]
 

dfm_python/config/schema/model.py

@@ -48,6 +48,15 @@ from ..constants import (
     DEFAULT_BATCH_SIZE,
     DEFAULT_DDFM_WINDOW_SIZE,
     DEFAULT_GRAD_CLIP_VAL,
+    DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY,
+    DEFAULT_IVDFM_OPTIMIZER_MOMENTUM,
+    DEFAULT_IVDFM_SCHEDULER_TYPE,
+    DEFAULT_IVDFM_SCHEDULER_STEP_SIZE,
+    DEFAULT_IVDFM_SCHEDULER_GAMMA,
+    DEFAULT_IVDFM_SCHEDULER_PATIENCE,
+    DEFAULT_IVDFM_SCHEDULER_FACTOR,
+    DEFAULT_IVDFM_SCHEDULER_MIN_LR,
+    DEFAULT_IVDFM_EARLY_STOP_PATIENCE,
     DEFAULT_REGULARIZATION_SCALE,
     DEFAULT_STRUCTURAL_REG_WEIGHT,
     DEFAULT_CONVERGENCE_THRESHOLD,
@@ -68,8 +77,42 @@ from ..constants import (
     DEFAULT_CLOCK_FREQUENCY,
     DEFAULT_KDFM_AR_ORDER,
     DEFAULT_KDFM_MA_ORDER,
+    DEFAULT_AFM_NUM_FACTORS,
+    DEFAULT_AFM_FACTOR_MODEL,
+    DEFAULT_AFM_TRADING,
+    DEFAULT_AFM_EMBED_DIM,
+    DEFAULT_AFM_HIST_LEN,
+    DEFAULT_AFM_N_KERNELS,
+    DEFAULT_AFM_RIDGE,
+    DEFAULT_AFM_SQUASH_LAMBDA,
+    DEFAULT_AFM_PCA_WINDOW,
+    DEFAULT_AFM_REESTIM,
+    DEFAULT_AFM_LAMBDA_VAR,
+    DEFAULT_AFM_TURNOVER_COST,
+    DEFAULT_AFM_SHORT_COST,
+    DEFAULT_AFM_MAX_EPOCHS,
     FREQUENCY_HIERARCHY,
     DEFAULT_HIERARCHY_VALUE,
+    DEFAULT_IVDFM_LATENT_DIM,
+    DEFAULT_IVDFM_AUX_DIM,
+    DEFAULT_IVDFM_ENCODER_HIDDEN_DIM,
+    DEFAULT_IVDFM_ENCODER_N_HIDDEN_LAYERS,
+    DEFAULT_IVDFM_NUM_REGIMES,
+    DEFAULT_IVDFM_REGIME_TEMPERATURE,
+    DEFAULT_IVDFM_MIXING,
+    DEFAULT_IVDFM_DECODER_TYPE,
+    DEFAULT_IVDFM_DECODER_HIDDEN_DIM,
+    DEFAULT_IVDFM_DECODER_N_HIDDEN_LAYERS,
+    DEFAULT_IVDFM_PRIOR_HIDDEN_DIM,
+    DEFAULT_IVDFM_PRIOR_N_HIDDEN_LAYERS,
+    DEFAULT_IVDFM_FACTOR_ORDER,
+    DEFAULT_IVDFM_INNOVATION_DIST,
+    DEFAULT_IVDFM_DECODER_VAR,
+    DEFAULT_IVDFM_ACTIVATION,
+    DEFAULT_IVDFM_SLOPE,
+    DEFAULT_IVDFM_BATCH_SIZE,
+    DEFAULT_IVDFM_MAX_EPOCHS,
+    DEFAULT_IVDFM_AUX_VARIABLE_TYPE,
 )
 
 
@@ -136,6 +179,7 @@ class BaseModelConfig:
     # ========================================================================
     clock: str = 'm'  # Required: Base frequency for latent factors (global clock): 'd', 'w', 'm', 'q', 'sa', 'a' (defaults to 'm' for monthly)
     target_scaler: Optional[ScalerType] = None  # Fitted sklearn scaler instance (StandardScaler, RobustScaler, etc.) for target series only. Must be a fitted scaler object (call .fit() on target data first). Pass scaler object directly, not string. Feature series are assumed to be manually preprocessed. If None, target series are assumed to be already in the desired scale.
+    scaler: Optional[str] = None  # Scaler type as string: 'standard', 'robust', 'minmax', 'maxabs', 'quantile', or null. Applied to targets only (not context/auxiliary variables). For iVDFM, this is the preferred way to specify scaler (like DDFM pattern).
     
     def __post_init__(self):
         """Validate basic model structure.
@@ -626,6 +670,291 @@ class DDFMConfig(BaseModelConfig):
         )
 
 
+@dataclass
+class iVDFMConfig(BaseModelConfig):
+    """Identifiable Variational Dynamic Factor Model configuration.
+    
+    Uses 'scaler' (string) pattern like DDFM, not 'target_scaler' (instance).
+    Scaler is applied to targets only, not to context/auxiliary variables.
+    """
+    """Identifiable Variational Dynamic Factor Model configuration.
+    
+    This configuration class extends BaseModelConfig with parameters specific
+    to iVDFM models trained using variational inference with identifiable
+    innovation priors.
+    
+    Note: iVDFM does NOT use block structure. Use num_factors directly to specify
+    the number of factors.
+    
+    The configuration can be built from:
+    - Main settings (training parameters) from config files
+    - Series definitions via frequency dict (column names -> frequencies)
+    """
+    # ========================================================================
+    # Model Structure
+    # ========================================================================
+    num_factors: Optional[int] = None  # Number of factors (inferred from config if None)
+    window: Optional[int] = None  # Sliding window length for training. If None, uses full T (full series as one sequence). Default: None.
+    stride: int = 1  # Step size for sliding windows. stride=1 means overlapping windows, stride=window means non-overlapping.
+    context: Optional[Union[List[str], List[int]]] = None  # Column names (DataFrame) or indices (array) for exogenous context variables. These are concatenated with time features.
+    time_context: int = 1  # Dimension of time-based context features. Always included. time_context=1: time step only, time_context>1: adds periodic sine features.
+    
+    # ========================================================================
+    # Neural Network Architecture
+    # ========================================================================
+    encoder_hidden_dim: Union[int, List[int]] = DEFAULT_IVDFM_ENCODER_HIDDEN_DIM  # Encoder architecture
+    encoder_n_hidden_layers: int = DEFAULT_IVDFM_ENCODER_N_HIDDEN_LAYERS  # Number of encoder hidden layers
+    decoder_type: str = DEFAULT_IVDFM_DECODER_TYPE  # 'linear', 'residual', or 'mlp'
+    decoder_hidden_dim: Union[int, List[int]] = DEFAULT_IVDFM_DECODER_HIDDEN_DIM  # Decoder MLP (residual/mlp)
+    decoder_n_hidden_layers: int = DEFAULT_IVDFM_DECODER_N_HIDDEN_LAYERS  # Decoder hidden layers (residual/mlp)
+    prior_hidden_dim: Union[int, List[int]] = DEFAULT_IVDFM_PRIOR_HIDDEN_DIM  # Prior network architecture
+    prior_n_hidden_layers: int = DEFAULT_IVDFM_PRIOR_N_HIDDEN_LAYERS  # Number of prior network hidden layers
+    activation: str = DEFAULT_IVDFM_ACTIVATION  # Activation function
+    slope: float = DEFAULT_IVDFM_SLOPE  # Leaky ReLU slope
+    
+    # ========================================================================
+    # Dynamics and Distribution Parameters
+    # ========================================================================
+    num_regimes: int = DEFAULT_IVDFM_NUM_REGIMES  # K; 1 = baseline iVDFM (one global dynamics, one decoder)
+    regime_temperature: float = DEFAULT_IVDFM_REGIME_TEMPERATURE  # Softmax τ for π; τ < 1 = sharper (local commitment)
+    factor_order: int = DEFAULT_IVDFM_FACTOR_ORDER  # AR order for factors
+    innovation_distribution: str = DEFAULT_IVDFM_INNOVATION_DIST  # Innovation distribution type
+    decoder_var: float = DEFAULT_IVDFM_DECODER_VAR  # Decoder variance
+    beta_kl: float = 1.0  # Weight for KL term in ELBO: ELBO = recon_loss + beta_kl * kl_loss. β<1 reduces KL pressure.
+    use_layer_norm: bool = False  # Whether to use layer normalization in encoder/decoder networks
+    mixing: bool = DEFAULT_IVDFM_MIXING  # If True, global post-factor mixing f -> M f before decode (identity init)
+    
+    # ========================================================================
+    # Training Parameters
+    # ========================================================================
+    learning_rate: float = DEFAULT_LEARNING_RATE  # Learning rate
+    optimizer: str = 'Adam'  # Optimizer type
+    optimizer_weight_decay: float = DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY  # Weight decay (L2 regularization)
+    optimizer_momentum: float = DEFAULT_IVDFM_OPTIMIZER_MOMENTUM  # Momentum for SGD
+    batch_size: int = DEFAULT_IVDFM_BATCH_SIZE  # Batch size
+    max_epochs: int = DEFAULT_IVDFM_MAX_EPOCHS  # Maximum epochs
+    tolerance: float = DEFAULT_TOLERANCE  # Convergence tolerance
+    patience: Optional[int] = DEFAULT_IVDFM_EARLY_STOP_PATIENCE  # Early stopping patience (epochs without improvement). None to disable.
+    seed: Optional[int] = None  # Random seed
+    
+    # ========================================================================
+    # Scheduler Parameters
+    # ========================================================================
+    scheduler_type: Optional[str] = DEFAULT_IVDFM_SCHEDULER_TYPE  # Scheduler type: 'step', 'plateau', 'cosine', 'exponential', None
+    scheduler_step_size: Optional[int] = DEFAULT_IVDFM_SCHEDULER_STEP_SIZE  # Step size for StepLR (None = auto: max_epochs // 3)
+    scheduler_gamma: float = DEFAULT_IVDFM_SCHEDULER_GAMMA  # Gamma for StepLR/ExponentialLR
+    scheduler_patience: int = DEFAULT_IVDFM_SCHEDULER_PATIENCE  # Patience for ReduceLROnPlateau
+    scheduler_factor: float = DEFAULT_IVDFM_SCHEDULER_FACTOR  # Factor for ReduceLROnPlateau
+    scheduler_min_lr: float = DEFAULT_IVDFM_SCHEDULER_MIN_LR  # Min learning rate for ReduceLROnPlateau
+    
+    def __post_init__(self):
+        """Validate iVDFM configuration."""
+        super().__post_init__()  # Validate base config
+        
+        from ...utils.errors import ConfigurationError
+        
+        # Validate window
+        if self.window is not None and self.window < 1:
+            raise ConfigurationError(
+                f"window must be >= 1, got {self.window}"
+            )
+        
+        # Validate time_context
+        if self.time_context < 1:
+            raise ConfigurationError(
+                f"time_context must be >= 1, got {self.time_context}"
+            )
+        
+        # Validate patience if provided
+        if self.patience is not None and self.patience < 1:
+            raise ConfigurationError(
+                f"patience must be >= 1 or None (to disable), got {self.patience}"
+            )
+        
+        # Validate num_factors if provided
+        if self.num_factors is not None and self.num_factors < 1:
+            raise ConfigurationError(
+                f"num_factors must be >= 1, got {self.num_factors}"
+            )
+        
+        # Validate factor_order
+        if self.factor_order < 1:
+            raise ConfigurationError(
+                f"factor_order must be >= 1, got {self.factor_order}"
+            )
+        
+        # Validate innovation_distribution
+        valid_dists = {'laplace', 'gaussian', 'student_t', 'gamma', 'beta', 'exponential'}
+        if self.innovation_distribution not in valid_dists:
+            raise ConfigurationError(
+                f"innovation_distribution must be one of {valid_dists}, got '{self.innovation_distribution}'"
+            )
+        
+        # Validate num_regimes
+        if self.num_regimes < 1:
+            raise ConfigurationError(
+                f"num_regimes must be >= 1, got {self.num_regimes}"
+            )
+        # Validate regime_temperature
+        if self.regime_temperature <= 0.0:
+            raise ConfigurationError(
+                f"regime_temperature must be > 0, got {self.regime_temperature}"
+            )
+        # Validate decoder_type
+        if self.decoder_type not in ("linear", "residual", "mlp"):
+            raise ConfigurationError(
+                f"decoder_type must be 'linear', 'residual', or 'mlp', got '{self.decoder_type}'"
+            )
+        
+        # Validate activation
+        valid_activations = {'relu', 'lrelu', 'tanh', 'sigmoid'}
+        if self.activation not in valid_activations:
+            raise ConfigurationError(
+                f"activation must be one of {valid_activations}, got '{self.activation}'"
+            )
+        
+        # Validate beta_kl
+        if self.beta_kl < 0:
+            raise ConfigurationError(
+                f"beta_kl must be >= 0, got {self.beta_kl}"
+            )
+        
+        # Validate optimizer
+        from ..constants import VALID_OPTIMIZERS
+        if self.optimizer not in VALID_OPTIMIZERS:
+            raise ConfigurationError(
+                f"optimizer must be one of {VALID_OPTIMIZERS}, got '{self.optimizer}'"
+            )
+        
+        # Validate scheduler_type
+        valid_schedulers = {'step', 'plateau', 'cosine', 'exponential', None}
+        if self.scheduler_type not in valid_schedulers:
+            raise ConfigurationError(
+                f"scheduler_type must be one of {valid_schedulers}, got '{self.scheduler_type}'"
+            )
+        
+        # Validate scheduler parameters
+        if self.scheduler_gamma <= 0 or self.scheduler_gamma > 1:
+            raise ConfigurationError(
+                f"scheduler_gamma must be in (0, 1], got {self.scheduler_gamma}"
+            )
+        
+        if self.scheduler_patience < 0:
+            raise ConfigurationError(
+                f"scheduler_patience must be >= 0, got {self.scheduler_patience}"
+            )
+        
+        if self.scheduler_factor <= 0 or self.scheduler_factor > 1:
+            raise ConfigurationError(
+                f"scheduler_factor must be in (0, 1], got {self.scheduler_factor}"
+            )
+        
+        if self.scheduler_min_lr < 0:
+            raise ConfigurationError(
+                f"scheduler_min_lr must be >= 0, got {self.scheduler_min_lr}"
+            )
+    
+    @classmethod
+    def _extract_ivdfm(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract iVDFM-specific parameters from config dict."""
+        from ..constants import (
+            DEFAULT_IVDFM_LATENT_DIM,
+            DEFAULT_IVDFM_AUX_DIM,
+            DEFAULT_IVDFM_ENCODER_HIDDEN_DIM,
+            DEFAULT_IVDFM_ENCODER_N_HIDDEN_LAYERS,
+            DEFAULT_IVDFM_NUM_REGIMES,
+            DEFAULT_IVDFM_REGIME_TEMPERATURE,
+            DEFAULT_IVDFM_MIXING,
+            DEFAULT_IVDFM_DECODER_TYPE,
+            DEFAULT_IVDFM_DECODER_HIDDEN_DIM,
+            DEFAULT_IVDFM_DECODER_N_HIDDEN_LAYERS,
+            DEFAULT_IVDFM_PRIOR_HIDDEN_DIM,
+    DEFAULT_IVDFM_PRIOR_N_HIDDEN_LAYERS,
+            DEFAULT_IVDFM_FACTOR_ORDER,
+            DEFAULT_IVDFM_INNOVATION_DIST,
+            DEFAULT_IVDFM_DECODER_VAR,
+            DEFAULT_IVDFM_ACTIVATION,
+            DEFAULT_IVDFM_SLOPE,
+            DEFAULT_IVDFM_BATCH_SIZE,
+            DEFAULT_IVDFM_MAX_EPOCHS,
+            DEFAULT_IVDFM_AUX_VARIABLE_TYPE,
+            DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY,
+            DEFAULT_IVDFM_OPTIMIZER_MOMENTUM,
+            DEFAULT_IVDFM_SCHEDULER_TYPE,
+            DEFAULT_IVDFM_SCHEDULER_STEP_SIZE,
+            DEFAULT_IVDFM_SCHEDULER_GAMMA,
+            DEFAULT_IVDFM_SCHEDULER_PATIENCE,
+            DEFAULT_IVDFM_SCHEDULER_FACTOR,
+            DEFAULT_IVDFM_SCHEDULER_MIN_LR,
+        )
+        
+        ivdfm_params = cls._extract_params(data, {
+            'num_factors': None,
+            'window': None,  # Default: None (uses full T - full series as one sequence)
+            'stride': 1,  # Default: stride=1 (overlapping windows)
+            'context': None,
+            'time_context': 1,  # Default: time step only
+            'encoder_hidden_dim': DEFAULT_IVDFM_ENCODER_HIDDEN_DIM,
+            'encoder_n_hidden_layers': DEFAULT_IVDFM_ENCODER_N_HIDDEN_LAYERS,
+            'num_regimes': DEFAULT_IVDFM_NUM_REGIMES,
+            'regime_temperature': DEFAULT_IVDFM_REGIME_TEMPERATURE,
+            'decoder_type': DEFAULT_IVDFM_DECODER_TYPE,
+            'decoder_hidden_dim': DEFAULT_IVDFM_DECODER_HIDDEN_DIM,
+            'decoder_n_hidden_layers': DEFAULT_IVDFM_DECODER_N_HIDDEN_LAYERS,
+            'prior_hidden_dim': DEFAULT_IVDFM_PRIOR_HIDDEN_DIM,
+            'prior_n_hidden_layers': DEFAULT_IVDFM_PRIOR_N_HIDDEN_LAYERS,
+            'activation': DEFAULT_IVDFM_ACTIVATION,
+            'slope': DEFAULT_IVDFM_SLOPE,
+            'factor_order': DEFAULT_IVDFM_FACTOR_ORDER,
+            'innovation_distribution': DEFAULT_IVDFM_INNOVATION_DIST,
+            'decoder_var': DEFAULT_IVDFM_DECODER_VAR,
+            'beta_kl': 1.0,
+            'use_layer_norm': False,
+            'mixing': DEFAULT_IVDFM_MIXING,
+            'learning_rate': DEFAULT_LEARNING_RATE,
+            'optimizer': 'Adam',
+            'optimizer_weight_decay': DEFAULT_IVDFM_OPTIMIZER_WEIGHT_DECAY,
+            'optimizer_momentum': DEFAULT_IVDFM_OPTIMIZER_MOMENTUM,
+            'batch_size': DEFAULT_IVDFM_BATCH_SIZE,
+            'max_epochs': DEFAULT_IVDFM_MAX_EPOCHS,
+            'tolerance': DEFAULT_TOLERANCE,
+            'patience': DEFAULT_IVDFM_EARLY_STOP_PATIENCE,
+            'seed': None,
+            'scheduler_type': DEFAULT_IVDFM_SCHEDULER_TYPE,
+            'scheduler_step_size': DEFAULT_IVDFM_SCHEDULER_STEP_SIZE,
+            'scheduler_gamma': DEFAULT_IVDFM_SCHEDULER_GAMMA,
+            'scheduler_patience': DEFAULT_IVDFM_SCHEDULER_PATIENCE,
+            'scheduler_factor': DEFAULT_IVDFM_SCHEDULER_FACTOR,
+            'scheduler_min_lr': DEFAULT_IVDFM_SCHEDULER_MIN_LR,
+            'scaler': None,  # Scaler string: 'standard', 'robust', 'minmax', 'maxabs', 'quantile', or null
+        })
+        
+        return ivdfm_params
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'iVDFMConfig':
+        """Create iVDFMConfig from dictionary.
+        
+        Parameters
+        ----------
+        data : Dict[str, Any]
+            Configuration dictionary
+            
+        Returns
+        -------
+        iVDFMConfig
+            iVDFM configuration instance
+        """
+        # Extract base params
+        base_params = cls._extract_base(data)
+        
+        # Extract iVDFM-specific params
+        ivdfm_params = cls._extract_ivdfm(data)
+        
+        # Combine and create config
+        return cls(**base_params, **ivdfm_params)
+
+
 # ============================================================================
 # Validation Functions
 # ============================================================================
@@ -662,6 +991,79 @@ def validate_frequency(frequency: str) -> str:
             f"Common frequencies: 'd' (daily), 'w' (weekly), 'm' (monthly), "
             f"'q' (quarterly), 'sa' (semi-annual), 'a' (annual)."
         )
-    
+
     return frequency
 
+
+@dataclass
+class AFMConfig(BaseModelConfig):
+    """Attention Factor Model configuration (Epstein et al., 2025).
+
+    Cross-sectional conditional factor model + residual trading policy. Like
+    iVDFM, AFM does not use block structure and is constructed directly via
+    ``AFMConfig.from_dict(OmegaConf.to_container(cfg))`` rather than through the
+    block-requiring YAML adapter.
+    """
+    num_factors: Optional[int] = None      # K latent factors
+    factor_model: str = DEFAULT_AFM_FACTOR_MODEL  # 'attention' (learned) | 'pca'
+    trading: str = DEFAULT_AFM_TRADING     # 'longconv' (learned) | 'ou' (Avellaneda-Lee)
+    embed_dim: int = DEFAULT_AFM_EMBED_DIM  # characteristic embedding dim d
+    hist_len: int = DEFAULT_AFM_HIST_LEN   # residual-history length s for the filter
+    n_kernels: int = DEFAULT_AFM_N_KERNELS  # number of long convolutions
+    ridge: float = DEFAULT_AFM_RIDGE       # ridge penalty for closed-form loadings
+    squash_lambda: float = DEFAULT_AFM_SQUASH_LAMBDA  # LongConv Squash regularizer
+    pca_window: int = DEFAULT_AFM_PCA_WINDOW  # trailing window for the PCA benchmark
+    reestim: int = DEFAULT_AFM_REESTIM     # PCA re-estimation stride
+    lambda_var: float = DEFAULT_AFM_LAMBDA_VAR  # explained-variance regularizer weight
+    turnover_cost: float = DEFAULT_AFM_TURNOVER_COST  # 5bps per unit turnover (paper)
+    short_cost: float = DEFAULT_AFM_SHORT_COST  # 1bp shorting cost (paper)
+    risk_free: float = 0.0
+    learning_rate: float = DEFAULT_LEARNING_RATE
+    max_epochs: int = DEFAULT_AFM_MAX_EPOCHS
+    patience: Optional[int] = None
+    seed: Optional[int] = None
+
+    def __post_init__(self):
+        super().__post_init__()
+        from ...utils.errors import ConfigurationError
+        if self.num_factors is not None and self.num_factors < 1:
+            raise ConfigurationError(f"num_factors must be >= 1, got {self.num_factors}")
+        if self.factor_model not in ('attention', 'pca'):
+            raise ConfigurationError(
+                f"factor_model must be 'attention' or 'pca', got '{self.factor_model}'")
+        if self.trading not in ('longconv', 'ou'):
+            raise ConfigurationError(
+                f"trading must be 'longconv' or 'ou', got '{self.trading}'")
+        if self.hist_len < 1:
+            raise ConfigurationError(f"hist_len must be >= 1, got {self.hist_len}")
+        if self.embed_dim < 1:
+            raise ConfigurationError(f"embed_dim must be >= 1, got {self.embed_dim}")
+
+    @classmethod
+    def _extract_afm(cls, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract AFM-specific parameters from a config dict."""
+        return cls._extract_params(data, {
+            'num_factors': None,
+            'factor_model': DEFAULT_AFM_FACTOR_MODEL,
+            'trading': DEFAULT_AFM_TRADING,
+            'embed_dim': DEFAULT_AFM_EMBED_DIM,
+            'hist_len': DEFAULT_AFM_HIST_LEN,
+            'n_kernels': DEFAULT_AFM_N_KERNELS,
+            'ridge': DEFAULT_AFM_RIDGE,
+            'squash_lambda': DEFAULT_AFM_SQUASH_LAMBDA,
+            'pca_window': DEFAULT_AFM_PCA_WINDOW,
+            'reestim': DEFAULT_AFM_REESTIM,
+            'lambda_var': DEFAULT_AFM_LAMBDA_VAR,
+            'turnover_cost': DEFAULT_AFM_TURNOVER_COST,
+            'short_cost': DEFAULT_AFM_SHORT_COST,
+            'risk_free': 0.0, 'learning_rate': DEFAULT_LEARNING_RATE,
+            'max_epochs': DEFAULT_AFM_MAX_EPOCHS, 'patience': None, 'seed': None,
+        })
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'AFMConfig':
+        """Create AFMConfig from a dictionary."""
+        base_params = cls._extract_base(data)
+        afm_params = cls._extract_afm(data)
+        return cls(**base_params, **afm_params)
+