Appendix A — Complete Config Schema Reference

# ─────────────────────────────────────────────────────────────────────────────
# FullConfig schema — all fields
# Fields marked (required) must be present. Others are optional.
# ─────────────────────────────────────────────────────────────────────────────
paths:                                # (required)
  data_dir: /data                     # (required) data root with nodes/ and edges/
  output_dir: /workspace/output       # (required) where all outputs go
  partition_dir: /tmp/fraud_partitions  # (optional, default: /tmp/fraud_partitions)
  embedding_dir: /tmp/embeddings      # (optional, auto-generated if null)
  checkpoint_dir: null                # (optional) GNN checkpoint directory
  skip_partition: false               # (optional, default: false)
models:                               # (required) list; currently only first entry used
  - kind: GNN_XGBoost                 # (required) one of: GNN_XGBoost, GNN_XGBoost_NP, XGBoost
    gpu: multi                        # (required) "single" or "multi"
    num_gpus: 2                       # (required when gpu=multi)
    # ── GNN_XGBoost / GNN_XGBoost_NP hyperparameters ─────────────────────────
    hyperparameters:
      gnn:
        hidden_channels: 128          # default: 128
        num_gnn_layers: 2             # default: 2; must equal len(num_neighbors)
        num_neighbors: [25, 10]       # default: [25, 10]; one value per layer
        encoder: sage                 # default: sage; choices: sage|gat|transformer|general
        heads: 4                      # default: 4; gat/transformer only
        concat: true                  # default: true; gat/transformer only
        dropout: 0.0                  # default: 0.0; applied between conv layers
        epochs: 5                     # default: 5
        batch_size: 1024              # default: 1024
        learning_rate: 0.005          # default: 0.005
        focal_gamma: 0.0              # default: 0.0 (standard BCE); >0 down-weights easy negatives
        focal_alpha: null             # default: null; optional fraud-class weight in (0,1)
        skip_gnn_train: false         # default: false
        no_raw_node_features_in_embedding: false   # default: false
        only_raw_node_features_in_embedding: false # default: false
        inf_num_neighbors: null       # default: null (uses num_neighbors); cap for high-degree nodes
        inf_batch_size: null          # default: batch_size // 8
        # ── Node embedding export ─────────────────────────────────────────
        save_node_embeddings: false   # false (default) | true
                                      # true → after training, runs:
                                      #   reloads model_final.pt, fine-tunes on val+test,
                                      #   extracts GNN embeddings for all training nodes,
                                      #   writes node_embeddings/{type}/rank={r}_ids.pt + _emb.pt + _feat.pt
        final_fit_epochs: 2           # 0 = skip; > 0 = fine-tune on val+test edges
        final_fit_lr_scale: 0.1       # effective LR = learning_rate × final_fit_lr_scale
        node_emb_batch_size: null     # null → inf_batch_size if set, else batch_size // 8
        emb_dtype: float32            # float32 (default) | float16
                                      # float16 halves disk/RAM; upcasted to float32 at inference
        node_emb_cache_size: null     # null = OS page-cache only
                                      # set to e.g. 100000 for Python RAM LRU per node type
        merge_chunk_size: null        # null = load entire rank shard before writing
                                      # set to e.g. 1000000 to cap merge peak RAM
      xgb:
        num_boost_round: 256          # default: 256
        max_depth: 6                  # default: 6
        learning_rate: 0.1            # default: 0.1
        subsample: 1.0                # default: 1.0
        colsample_bytree: 1.0         # default: 1.0
        min_child_weight: 1           # default: 1
        gamma: 0.0                    # default: 0.0
        num_parallel_tree: 1          # default: 1
        base_score: 0.5               # default: 0.5; SET TO YOUR TRAINING FRAUD RATE (e.g. 0.10)
        scale_pos_weight: null        # default: null (auto-computed as (1-fraud_rate)/fraud_rate)
        prior_test: null              # default: null; set to production fraud rate for Bayes calibration
        eval_metric: [auc, aucpr, logloss]  # default: [auc, aucpr, logloss]; last drives early stopping
        early_stopping_rounds: 50     # default: 50; null to disable
        log_period: 10                # default: 10
        skip: false                   # default: false
        batched: false                # default: false
        batch_size: 65536             # default: 65536 (used only when batched: true)
        extmem: false                 # default: false (requires batched: true)
        memmap: false                 # default: false (requires batched: true)
        cache_host_ratio: null        # default: null (XGBoost decides)
    # ── XGBoost-only hyperparameters (kind=XGBoost) ───────────────────────────
    # data:
    #   label_column: fraud           # column name in the label CSV (default: fraud)
    #   feature_columns: null         # list of feature column names; null = all columns except label_column
    #   format: csv                   # csv | parquet | orc
    # hyperparameters:                # flat dict (no gnn sub-key)
    #   num_boost_round: 256
    #   max_depth: 6
    #   learning_rate: 0.1
    #   subsample: 1.0
    #   colsample_bytree: 1.0
    #   min_child_weight: 1
    #   gamma: 0.0
    #   num_parallel_tree: 1
    #   log_period: 10