cursus.steps.hyperparams¶

Hyperparameters module.

This module contains hyperparameter classes for different model types, providing type-safe hyperparameter management with validation and serialization capabilities.

class ModelHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='base_model', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, **extra_data)[source]¶

Bases: BaseModel

Base model hyperparameters for training tasks.

Fields are organized into three tiers: 1. Tier 1: Essential User Inputs - fields that users must explicitly provide 2. Tier 2: System Inputs with Defaults - fields with reasonable defaults that can be overridden 3. Tier 3: Derived Fields - fields calculated from other fields (private attributes with properties)

categorize_fields()[source]¶

Categorize all fields into three tiers: 1. Tier 1: Essential User Inputs - fields with no defaults (required) 2. Tier 2: System Inputs - fields with defaults (optional) 3. Tier 3: Derived Fields - properties that access private attributes

Returns:: Dict with keys ‘essential’, ‘system’, and ‘derived’ mapping to lists of field names
Return type:: Dict[str, List[str]]

classmethod from_base_hyperparam(base_hyperparam, **kwargs)[source]¶

Create a new hyperparameter instance from a base hyperparameter. This is a virtual method that all derived classes can use to inherit from a parent config.

Parameters:

base_hyperparam (ModelHyperparameters) – Parent ModelHyperparameters instance
**kwargs (Any) – Additional arguments specific to the derived class

Returns:

A new instance of the derived class initialized with parent fields and additional kwargs

Return type:

ModelHyperparameters

get_config()[source]¶

Get the complete configuration dictionary.

get_public_init_fields()[source]¶

Get a dictionary of public fields suitable for initializing a child hyperparameter. Only includes fields that should be passed to child class constructors. Both essential user inputs and system inputs with defaults or user-overridden values are included to ensure all user customizations are properly propagated.

Returns:: Dictionary of field names to values for child initialization
Return type:: Dict[str, Any]

property input_tab_dim: int¶: Get input tabular dimension derived from tab_field_list.

property is_binary: bool¶: Determine if this is a binary classification task based on num_classes.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

property num_classes: int¶: Get number of classes derived from multiclass_categories.

print_hyperparam()[source]¶

Print complete hyperparameter information organized by tiers. This method automatically categorizes fields by examining their characteristics.

serialize_config()[source]¶

Serialize configuration for SageMaker.

validate_dimensions()[source]¶

Validate model dimensions and configurations

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[str | int]¶

categorical_features_to_encode: List[str]¶

model_class: str¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class BimodalModelHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='multimodal_bert', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, tokenizer, text_name, lr_decay=0.05, momentum=0.9, weight_decay=0.0, adam_epsilon=1e-08, warmup_steps=300, run_scheduler=True, val_check_interval=0.25, gradient_clip_val=1.0, fp16=False, use_gradient_checkpointing=False, early_stop_metric='val_loss', early_stop_patience=3, load_ckpt=False, smooth_factor=0.0, count_threshold=0, text_field_overwrite=False, chunk_trancate=True, max_total_chunks=3, max_sen_len=512, fixed_tokenizer_length=True, text_input_ids_key='input_ids', text_attention_mask_key='attention_mask', text_processing_steps=['dialogue_splitter', 'html_normalizer', 'emoji_remover', 'text_normalizer', 'dialogue_chunker', 'tokenizer'], num_channels=[100, 100], num_layers=2, dropout_keep=0.1, kernel_size=[3, 5, 7], is_embeddings_trainable=True, pretrained_embedding=True, reinit_layers=2, reinit_pooler=True, hidden_common_dim=100)[source]¶

Bases: ModelHyperparameters

Hyperparameters for bimodal model training (text + tabular), extending the base ModelHyperparameters.

get_public_init_fields()[source]¶

Override get_public_init_fields to include bimodal-specific derived fields. Gets a dictionary of public fields suitable for initializing a child config.

get_trainer_config()[source]¶

Get trainer configuration dictionary for PyTorch Lightning. This combines various trainer-related settings.

Returns:: Configuration dictionary for trainer
Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_config_dict: Dict[str, Any]¶: Get complete model configuration dictionary derived from hyperparameters.

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

property tokenizer_config: Dict[str, Any]¶: Get tokenizer configuration dictionary derived from hyperparameters.

validate_bimodal_hyperparameters()[source]¶

Validate bimodal model-specific hyperparameters and initialize derived fields.

tokenizer: str¶

text_name: str¶

model_class: str¶

lr_decay: float¶

momentum: float¶

weight_decay: float¶

adam_epsilon: float¶

warmup_steps: int¶

run_scheduler: bool¶

val_check_interval: float¶

gradient_clip_val: float¶

fp16: bool¶

use_gradient_checkpointing: bool¶

early_stop_metric: str¶

early_stop_patience: int¶

load_ckpt: bool¶

smooth_factor: float¶

count_threshold: int¶

text_field_overwrite: bool¶

chunk_trancate: bool¶

max_total_chunks: int¶

max_sen_len: int¶

fixed_tokenizer_length: bool¶

text_input_ids_key: str¶

text_attention_mask_key: str¶

text_processing_steps: List[str]¶

num_channels: List[int]¶

num_layers: int¶

dropout_keep: float¶

kernel_size: List[int]¶

is_embeddings_trainable: bool¶

pretrained_embedding: bool¶

reinit_layers: int¶

reinit_pooler: bool¶

hidden_common_dim: int¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class TriModalHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='trimodal_bert', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, primary_text_name, secondary_text_name, text_name=None, lr_decay=0.05, momentum=0.9, weight_decay=0.0, adam_epsilon=1e-08, warmup_steps=300, run_scheduler=True, val_check_interval=0.25, early_stop_metric='val_loss', early_stop_patience=3, load_ckpt=False, gradient_clip_val=1.0, fp16=False, use_gradient_checkpointing=False, smooth_factor=0.0, count_threshold=0, tokenizer='bert-base-cased', max_sen_len=512, fixed_tokenizer_length=True, hidden_common_dim=256, reinit_pooler=True, reinit_layers=2, chunk_trancate=True, max_total_chunks=3, text_input_ids_key='input_ids', text_attention_mask_key='attention_mask', primary_text_processing_steps=['dialogue_splitter', 'html_normalizer', 'emoji_remover', 'text_normalizer', 'dialogue_chunker', 'tokenizer'], secondary_text_processing_steps=['dialogue_splitter', 'text_normalizer', 'dialogue_chunker', 'tokenizer'], primary_hidden_common_dim=None, secondary_hidden_common_dim=None, fusion_hidden_dim=None, fusion_dropout=0.1, primary_reinit_pooler=None, primary_reinit_layers=None, secondary_reinit_pooler=None, secondary_reinit_layers=None)[source]¶

Bases: ModelHyperparameters

Hyperparameters for tri-modal model training with dual text and tabular modalities. Extends ModelHyperparameters to support multiple text inputs.

get_public_init_fields()[source]¶

Override get_public_init_fields to include tri-modal specific derived fields. Gets a dictionary of public fields suitable for initializing a child config.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

property trimodal_model_config_dict: Dict[str, Any]¶: Get complete tri-modal model configuration dictionary.

validate_trimodal_hyperparameters()[source]¶

Validate tri-modal specific hyperparameters and initialize derived fields.

model_class: str¶

primary_text_name: str¶

secondary_text_name: str¶

text_name: str | None¶

lr_decay: float¶

momentum: float¶

weight_decay: float¶

adam_epsilon: float¶

warmup_steps: int¶

run_scheduler: bool¶

val_check_interval: float¶

early_stop_metric: str¶

early_stop_patience: int¶

load_ckpt: bool¶

gradient_clip_val: float¶

fp16: bool¶

use_gradient_checkpointing: bool¶

smooth_factor: float¶

count_threshold: int¶

tokenizer: str¶

max_sen_len: int¶

fixed_tokenizer_length: bool¶

hidden_common_dim: int¶

reinit_pooler: bool¶

reinit_layers: int¶

chunk_trancate: bool¶

max_total_chunks: int¶

text_input_ids_key: str¶

text_attention_mask_key: str¶

primary_text_processing_steps: List[str]¶

secondary_text_processing_steps: List[str]¶

primary_hidden_common_dim: int | None¶

secondary_hidden_common_dim: int | None¶

fusion_hidden_dim: int | None¶

fusion_dropout: float¶

primary_reinit_pooler: bool | None¶

primary_reinit_layers: int | None¶

secondary_reinit_pooler: bool | None¶

secondary_reinit_layers: int | None¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class LightGBMModelHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='lightgbm', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, num_leaves, learning_rate, boosting_type='gbdt', num_iterations=100, max_depth=-1, min_data_in_leaf=20, min_sum_hessian_in_leaf=0.001, feature_fraction=1.0, bagging_fraction=1.0, bagging_freq=0, lambda_l1=0.0, lambda_l2=0.0, min_gain_to_split=0.0, categorical_feature=None, early_stopping_rounds=None, seed=None, min_data_per_group=100, cat_smooth=10.0, max_cat_threshold=32, use_native_categorical=True, **extra_data)[source]¶

Bases: ModelHyperparameters

Hyperparameters for the LightGBM model training, extending the base ModelHyperparameters.

get_public_init_fields()[source]¶

Override get_public_init_fields to include LightGBM-specific fields. Gets a dictionary of public fields suitable for initializing a child config.

property metric: List[str]¶: Get evaluation metrics derived from is_binary.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

property objective: str¶: Get objective derived from is_binary.

validate_lightgbm_hyperparameters()[source]¶

Validate LightGBM-specific hyperparameters

num_leaves: int¶

learning_rate: float¶

model_class: str¶

boosting_type: str¶

num_iterations: int¶

max_depth: int¶

min_data_in_leaf: int¶

min_sum_hessian_in_leaf: float¶

feature_fraction: float¶

bagging_fraction: float¶

bagging_freq: int¶

lambda_l1: float¶

lambda_l2: float¶

min_gain_to_split: float¶

categorical_feature: str | None¶

early_stopping_rounds: int | None¶

seed: int | None¶

min_data_per_group: int¶

cat_smooth: float¶

max_cat_threshold: int¶

use_native_categorical: bool¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class LightGBMMtModelHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='lightgbmmt', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, task_label_names, main_task_index, num_leaves=31, learning_rate=0.1, boosting_type='gbdt', num_iterations=100, max_depth=-1, min_data_in_leaf=20, min_sum_hessian_in_leaf=0.001, feature_fraction=1.0, bagging_fraction=1.0, bagging_freq=0, lambda_l1=0.0, lambda_l2=0.0, min_gain_to_split=0.0, categorical_feature=None, early_stopping_rounds=None, seed=None, loss_type='adaptive', loss_epsilon=1e-15, loss_epsilon_norm=0.0, loss_similarity_min_distance=0.0, loss_beta=0.2, loss_main_task_weight=1.0, loss_weight_lr=1.0, loss_patience=100, loss_weight_method=None, loss_weight_update_frequency=10, loss_delta_lr=0.01, loss_normalize_gradients=True, **extra_data)[source]¶

Bases: ModelHyperparameters

Hyperparameters for LightGBMMT (Multi-Task) model training.

Extends ModelHyperparameters directly (not LightGBMModelHyperparameters). Includes complete LightGBM parameters plus multi-task specific parameters. All loss function parameters are prefixed with ‘loss_’ to avoid naming conflicts.

Follows three-tier hyperparameter pattern: - Tier 1: Essential User Inputs (from ModelHyperparameters + LightGBM essentials) - Tier 2: System Inputs with Defaults (LightGBM + MT-specific parameters) - Tier 3: Derived Fields (enable_kd computed from loss_type, num_tasks from task_label_names)

Design Notes: - No separate LossConfig class - all loss parameters integrated here - Loss functions receive this hyperparameters object directly - Training parameters (max_epochs, batch_size) inherited from base - No TrainingConfig class - only TrainingState for runtime tracking

property enable_kd: bool¶: Whether knowledge distillation is enabled (derived from loss_type).

get_public_init_fields()[source]¶

Override to include MT-specific and LightGBM-specific derived fields.

property metric: list¶: Get evaluation metrics derived from is_binary.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

property num_tasks: int¶: Get number of tasks derived from task_label_names.

property objective: str¶: Get objective derived from is_binary.

validate_mt_hyperparameters()[source]¶

Validate multi-task and LightGBM-specific hyperparameters.

task_label_names: list[str]¶

main_task_index: int¶

model_class: str¶

num_leaves: int¶

learning_rate: float¶

boosting_type: str¶

num_iterations: int¶

max_depth: int¶

min_data_in_leaf: int¶

min_sum_hessian_in_leaf: float¶

feature_fraction: float¶

bagging_fraction: float¶

bagging_freq: int¶

lambda_l1: float¶

lambda_l2: float¶

min_gain_to_split: float¶

categorical_feature: str | None¶

early_stopping_rounds: int | None¶

seed: int | None¶

loss_type: Literal['fixed', 'adaptive', 'adaptive_kd']¶

loss_epsilon: float¶

loss_epsilon_norm: float¶

loss_similarity_min_distance: float¶

loss_beta: float¶

loss_main_task_weight: float¶

loss_weight_lr: float¶

loss_patience: int¶

loss_weight_method: Literal['tenIters', 'sqrt', 'delta', 'ema'] | None¶

loss_weight_update_frequency: int¶

loss_delta_lr: float¶

loss_normalize_gradients: bool¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class XGBoostModelHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='xgboost', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, num_round, max_depth, min_child_weight=1.0, booster='gbtree', eta=0.3, gamma=0.0, max_delta_step=0.0, subsample=1.0, colsample_bytree=1.0, colsample_bylevel=1.0, colsample_bynode=1.0, lambda_xgb=1.0, alpha_xgb=0.0, tree_method='auto', sketch_eps=None, scale_pos_weight=1.0, num_parallel_tree=None, base_score=None, seed=None, early_stopping_rounds=None, **extra_data)[source]¶

Bases: ModelHyperparameters

Hyperparameters for the XGBoost model training, extending the base ModelHyperparameters.

property eval_metric: List[str]¶: Get evaluation metrics derived from is_binary.

get_public_init_fields()[source]¶

Override get_public_init_fields to include XGBoost-specific fields. Gets a dictionary of public fields suitable for initializing a child config.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

property objective: str¶: Get objective derived from is_binary.

validate_xgboost_hyperparameters()[source]¶

Validate XGBoost-specific hyperparameters

num_round: int¶

max_depth: int¶

model_class: str¶

min_child_weight: float¶

booster: str¶

eta: float¶

gamma: float¶

max_delta_step: float¶

subsample: float¶

colsample_bytree: float¶

colsample_bylevel: float¶

colsample_bynode: float¶

lambda_xgb: float¶

alpha_xgb: float¶

tree_method: str¶

sketch_eps: float | None¶

scale_pos_weight: float¶

num_parallel_tree: int | None¶

base_score: float | None¶

seed: int | None¶

early_stopping_rounds: int | None¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class TemporalSelfAttentionHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='temporal_self_attention', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, n_embedding, n_cat_features, n_num_features, seq_len, seq_cat_key='x_seq_cat', seq_num_key='x_seq_num', seq_time_key='time_seq', engineered_key='x_engineered', dim_embedding_table=128, dim_attn_feedforward=512, num_heads=8, n_layers_order=2, n_layers_feature=2, dropout=0.1, use_moe=False, num_experts=4, expert_capacity_factor=1.25, expert_dropout=0.1, use_time_seq=True, time_encoding_dim=32, return_seq=False, use_key_padding_mask=True, loss='CrossEntropyLoss', loss_alpha=0.25, loss_gamma=2.0, loss_gamma_min=1.0, loss_gamma_max=3.0, loss_cycle_length=1000, loss_reduction='mean', weight_decay=0.0, adam_epsilon=1e-08, warmup_steps=300, run_scheduler=True)[source]¶

Bases: ModelHyperparameters

Hyperparameters for Temporal Self-Attention (TSA) model training, extending the base ModelHyperparameters.

get_public_init_fields()[source]¶

Override get_public_init_fields to include TSA-specific derived fields. Gets a dictionary of public fields suitable for initializing a child config.

get_trainer_config()[source]¶

Get trainer configuration dictionary for PyTorch Lightning. This combines various trainer-related settings.

Returns:: Configuration dictionary for trainer
Return type:: Dict[str, Any]

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_config_dict: Dict[str, Any]¶: Get complete model configuration dictionary derived from hyperparameters.

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

validate_tsa_hyperparameters()[source]¶

Validate TSA-specific hyperparameters and initialize derived fields.

n_embedding: int¶

n_cat_features: int¶

n_num_features: int¶

seq_len: int¶

model_class: str¶

seq_cat_key: str¶

seq_num_key: str¶

seq_time_key: str¶

engineered_key: str¶

dim_embedding_table: int¶

dim_attn_feedforward: int¶

num_heads: int¶

n_layers_order: int¶

n_layers_feature: int¶

dropout: float¶

use_moe: bool¶

num_experts: int¶

expert_capacity_factor: float¶

expert_dropout: float¶

use_time_seq: bool¶

time_encoding_dim: int¶

return_seq: bool¶

use_key_padding_mask: bool¶

loss: str¶

loss_alpha: float¶

loss_gamma: float¶

loss_gamma_min: float¶

loss_gamma_max: float¶

loss_cycle_length: int¶

loss_reduction: str¶

weight_decay: float¶

adam_epsilon: float¶

warmup_steps: int¶

run_scheduler: bool¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class DualSequenceTSAHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='dual_sequence_tsa', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, n_embedding, n_cat_features, n_num_features, seq_len, seq_cat_key='x_seq_cat', seq_num_key='x_seq_num', seq_time_key='time_seq', engineered_key='x_engineered', dim_embedding_table=128, dim_attn_feedforward=512, num_heads=8, n_layers_order=2, n_layers_feature=2, dropout=0.1, use_moe=False, num_experts=4, expert_capacity_factor=1.25, expert_dropout=0.1, use_time_seq=True, time_encoding_dim=32, return_seq=False, use_key_padding_mask=True, loss='CrossEntropyLoss', loss_alpha=0.25, loss_gamma=2.0, loss_gamma_min=1.0, loss_gamma_max=3.0, loss_cycle_length=1000, loss_reduction='mean', weight_decay=0.0, adam_epsilon=1e-08, warmup_steps=300, run_scheduler=True, seq1_cat_key='x_seq_cat_primary', seq1_num_key='x_seq_num_primary', seq1_time_key='time_seq_primary', seq2_cat_key='x_seq_cat_secondary', seq2_num_key='x_seq_num_secondary', seq2_time_key='time_seq_secondary', gate_embedding_dim=16, gate_hidden_dim=256, gate_threshold=0.05)[source]¶

Bases: TemporalSelfAttentionHyperparameters

Hyperparameters for Dual-Sequence Temporal Self-Attention (TSA) model training, extending TemporalSelfAttentionHyperparameters.

Adds support for dual-sequence processing with a gate function that dynamically weights the importance of primary vs secondary sequences.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property model_config_dict: Dict[str, Any]¶: Get complete model configuration including dual-sequence params. Extends parent’s model_config_dict with dual-sequence specific fields.

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

validate_dual_sequence_hyperparameters()[source]¶

Validate dual-sequence specific hyperparameters. Calls parent validator first, then adds dual-sequence specific checks.

model_class: str¶

seq1_cat_key: str¶

seq1_num_key: str¶

seq1_time_key: str¶

seq2_cat_key: str¶

seq2_num_key: str¶

seq2_time_key: str¶

gate_embedding_dim: int¶

gate_hidden_dim: int¶

gate_threshold: float¶

n_embedding: int¶

n_cat_features: int¶

n_num_features: int¶

seq_len: int¶

seq_cat_key: str¶

seq_num_key: str¶

seq_time_key: str¶

engineered_key: str¶

dim_embedding_table: int¶

dim_attn_feedforward: int¶

num_heads: int¶

n_layers_order: int¶

n_layers_feature: int¶

dropout: float¶

use_moe: bool¶

num_experts: int¶

expert_capacity_factor: float¶

expert_dropout: float¶

use_time_seq: bool¶

time_encoding_dim: int¶

return_seq: bool¶

use_key_padding_mask: bool¶

loss: str¶

loss_alpha: float¶

loss_gamma: float¶

loss_gamma_min: float¶

loss_gamma_max: float¶

loss_cycle_length: int¶

loss_reduction: str¶

weight_decay: float¶

adam_epsilon: float¶

warmup_steps: int¶

run_scheduler: bool¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class LSTM2RiskHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='lstm2risk', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, text_name, text_source_fields=None, max_sen_len=100, fixed_tokenizer_length=True, text_input_ids_key='input_ids', text_attention_mask_key='attention_mask', text_processing_steps=[], embedding_size=16, dropout_rate=0.2, hidden_size=128, n_embed=4000, n_lstm_layers=4, lr_decay=0.05, momentum=0.9, weight_decay=0.0, adam_epsilon=1e-08, warmup_steps=300, run_scheduler=True, val_check_interval=0.25, gradient_clip_val=1.0, fp16=False, use_gradient_checkpointing=False, early_stop_metric='val_loss', early_stop_patience=3, load_ckpt=False, smooth_factor=0.0, count_threshold=0, text_field_overwrite=False, chunk_trancate=True, max_total_chunks=3, **extra_data)[source]¶

Bases: ModelHyperparameters

Hyperparameters for LSTM2Risk bimodal fraud detection model.

This class extends the base ModelHyperparameters with LSTM-specific architecture parameters needed for the LSTM2Risk model which combines: - Bidirectional LSTM for text sequence encoding (names, emails) - MLP for tabular feature encoding - Bimodal fusion for fraud prediction

Inherits all base fields including: - Data field management (full_field_list, cat_field_list, tab_field_list) - Training parameters (lr, batch_size, max_epochs, optimizer) - Classification parameters (multiclass_categories, class_weights) - Derived properties (input_tab_dim, num_classes, is_binary)

Example Usage: ```python hyperparam = LSTM2RiskHyperparameters(

# Essential fields (Tier 1) - required full_field_list=[“name”, “email”, “age”, “income”, “label”], cat_field_list=[“name”, “email”], tab_field_list=[“age”, “income”], id_name=”customer_id”, label_name=”label”, multiclass_categories=[0, 1],

# LSTM-specific fields (Tier 2) - optional, using defaults embedding_size=16, hidden_size=128, n_embed=4000, n_lstm_layers=4, dropout_rate=0.2,

# Can also override base fields lr=3e-5, batch_size=32, max_epochs=5

)

# Access derived properties print(f”Input tabular dimension: {hyperparam.input_tab_dim}”) print(f”Number of classes: {hyperparam.num_classes}”) print(f”Is binary classification: {hyperparam.is_binary}”)

# Serialize for SageMaker config = hyperparam.serialize_config() ```

get_public_init_fields()[source]¶

Override get_public_init_fields to include bimodal-specific derived fields. Gets a dictionary of public fields suitable for initializing a child config.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

text_name: str¶

text_source_fields: List[str] | None¶

model_class: str¶

max_sen_len: int¶

fixed_tokenizer_length: bool¶

text_input_ids_key: str¶

text_attention_mask_key: str¶

text_processing_steps: List[str]¶

embedding_size: int¶

dropout_rate: float¶

hidden_size: int¶

n_embed: int¶

n_lstm_layers: int¶

lr_decay: float¶

momentum: float¶

weight_decay: float¶

adam_epsilon: float¶

warmup_steps: int¶

run_scheduler: bool¶

val_check_interval: float¶

gradient_clip_val: float¶

fp16: bool¶

use_gradient_checkpointing: bool¶

early_stop_metric: str¶

early_stop_patience: int¶

load_ckpt: bool¶

smooth_factor: float¶

count_threshold: int¶

text_field_overwrite: bool¶

chunk_trancate: bool¶

max_total_chunks: int¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

class Transformer2RiskHyperparameters(*, full_field_list, cat_field_list, tab_field_list, id_name, label_name, multiclass_categories, categorical_features_to_encode=<factory>, model_class='transformer2risk', device=-1, header=0, lr=3e-05, batch_size=2, eval_batch_size_multiplier=2.0, max_epochs=3, metric_choices=['f1_score', 'auroc'], optimizer='SGD', class_weights=None, text_name, text_source_fields=None, max_sen_len=100, fixed_tokenizer_length=True, text_input_ids_key='input_ids', text_attention_mask_key='attention_mask', text_processing_steps=[], embedding_size=128, dropout_rate=0.2, hidden_size=256, n_embed=4000, n_blocks=8, n_heads=8, lr_decay=0.05, momentum=0.9, weight_decay=0.0, adam_epsilon=1e-08, warmup_steps=300, run_scheduler=True, val_check_interval=0.25, gradient_clip_val=1.0, fp16=False, use_gradient_checkpointing=False, early_stop_metric='val_loss', early_stop_patience=3, load_ckpt=False, smooth_factor=0.0, count_threshold=0, text_field_overwrite=False, chunk_trancate=True, max_total_chunks=3, **extra_data)[source]¶

Bases: ModelHyperparameters

Hyperparameters for Transformer2Risk bimodal fraud detection model.

This class extends the base ModelHyperparameters with Transformer-specific architecture parameters needed for the Transformer2Risk model which combines: - Transformer encoder with self-attention for text sequence encoding - MLP for tabular feature encoding - Bimodal fusion for fraud prediction

Key architectural differences from LSTM2Risk: - Uses self-attention mechanism instead of recurrent connections - Larger embedding dimensions (128 vs 16) for richer representations - Fixed-length sequences with positional embeddings (vs variable-length LSTM) - Multi-head attention for parallel attention to different aspects

Example Usage: ```python hyperparam = Transformer2RiskHyperparameters(

# Essential fields (Tier 1) - required full_field_list=[“name”, “email”, “age”, “income”, “label”], cat_field_list=[“name”, “email”], tab_field_list=[“age”, “income”], id_name=”customer_id”, label_name=”label”, multiclass_categories=[0, 1],

# Transformer-specific fields (Tier 2) - optional, using defaults embedding_size=128, hidden_size=256, n_embed=4000, n_blocks=8, n_heads=8, block_size=100, dropout_rate=0.2,

# Can also override base fields lr=3e-5, batch_size=32, max_epochs=5

)

# Serialize for SageMaker config = hyperparam.serialize_config() ```

get_public_init_fields()[source]¶

Override get_public_init_fields to include bimodal-specific derived fields. Gets a dictionary of public fields suitable for initializing a child config.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', 'protected_namespaces': (), 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

validate_transformer_hyperparameters()[source]¶

Validate transformer-specific constraints.

text_name: str¶

text_source_fields: List[str] | None¶

model_class: str¶

max_sen_len: int¶

fixed_tokenizer_length: bool¶

text_input_ids_key: str¶

text_attention_mask_key: str¶

text_processing_steps: List[str]¶

embedding_size: int¶

dropout_rate: float¶

hidden_size: int¶

n_embed: int¶

n_blocks: int¶

n_heads: int¶

lr_decay: float¶

momentum: float¶

weight_decay: float¶

adam_epsilon: float¶

warmup_steps: int¶

run_scheduler: bool¶

val_check_interval: float¶

gradient_clip_val: float¶

fp16: bool¶

use_gradient_checkpointing: bool¶

early_stop_metric: str¶

early_stop_patience: int¶

load_ckpt: bool¶

smooth_factor: float¶

count_threshold: int¶

text_field_overwrite: bool¶

chunk_trancate: bool¶

max_total_chunks: int¶

full_field_list: List[str]¶

cat_field_list: List[str]¶

tab_field_list: List[str]¶

id_name: str¶

label_name: str¶

multiclass_categories: List[int | str]¶

categorical_features_to_encode: List[str]¶

device: int¶

header: int¶

lr: float¶

batch_size: int¶

eval_batch_size_multiplier: float¶

max_epochs: int¶

metric_choices: List[str]¶

optimizer: str¶

class_weights: List[float] | None¶

Modules

`hyperparameters_bimodal`
`hyperparameters_dual_sequence_tsa`
`hyperparameters_lightgbm`
`hyperparameters_lightgbmmt`	Hyperparameters for LightGBMMT (Multi-Task) model training.
`hyperparameters_lstm2risk`
`hyperparameters_transformer2risk`
`hyperparameters_trimodal`
`hyperparameters_tsa`
`hyperparameters_xgboost`
`hyperparameters_xgboost_mt`	Hyperparameters for XGBoost Multi-Task (one_output_per_tree) model training.