HCKT

Official PyTorch implementation of “Hint-Conditioned Knowledge Tracing: A Causal-Inspired View of Context-Dependent Hint Usage,” published at the 2026 IEEE International Conference on Data Mining (ICDM 2026).

HCKT is a hint-conditioned knowledge tracing framework that models hint-taking as a context-dependent learning-process signal under a causal-inspired chronological view. It constructs a behavior-enriched proxy context, jointly estimates hint-taking tendency and hint-conditioned response patterns, and injects the resulting model-estimated discrepancy between hint and non-hint conditions into the KT backbone through gated feature fusion and hint-aware attention modulation.

Motivating example: similar hint-requested correct responses can correspond to different latent mastery trajectories.

Repository structure

.
├── data/
│   ├── README.md                  # Data format and preparation notes
│   └── data_preprocessing.ipynb  # Reference preprocessing and simulation code
├── src/
│   ├── main.py                   # Training and evaluation entry point
│   ├── overall_perform.sh        # Real-world experiment command manifest
│   ├── simulation.sh             # Synthetic experiment command manifest
│   ├── run_exp.py                # Overall-experiment runner
│   ├── run_exp_simulation.py     # Simulation runner
│   ├── helpers/
│   │   ├── DataReader.py         # Sequence construction and fold generation
│   │   └── KTRunner.py           # Training, evaluation, and metric reporting
│   ├── models/
│   │   ├── HCKT.py               # Proposed model
│   │   ├── BaseModel.py          # Shared model interface
│   │   └── ...                   # Baselines used by the experiment manifests
│   └── utils/
│       └── utils.py
├── hckt_motivation.png            # Motivating example used above
├── requirements.txt
└── README.md

The included comparison implementations are DKT, AKT, DKVMN, LBKT, simpleKT, FoLiBiKT, HawkesKT, RobustKT, and LEFOKT-AKT.

Environment

Create an isolated Python environment and install the dependencies:

python -m venv .venv
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Activate the environment using the command appropriate for your operating system before running experiments. Training runs on CUDA automatically when a CUDA-enabled PyTorch installation and an available GPU are detected; otherwise it runs on CPU.

Data preparation

Raw datasets are not redistributed in this repository. Prepare each dataset as a tab-separated interactions.csv file under its experiment name:

data/
├── assist09/interactions.csv
├── assist12/interactions.csv
├── assist17/interactions.csv
├── junyi/interactions.csv
├── statics/interactions.csv
└── <synthetic-dataset>/interactions.csv

The dataset aliases must match the --dataset values in the command manifests. See data/README.md for the required fields and preprocessing notes. The first run creates a cached Corpus_<max_step>.pkl beside the processed interaction file.

Running HCKT

All commands below assume that the current directory is src, because the experiment code uses paths relative to that directory.

cd src
python main.py \
  --model_name HCKT \
  --dataset assist09 \
  --max_step 50 \
  --emb_size 64 \
  --num_layer 2 \
  --num_head 8 \
  --lr 3e-3 \
  --l2 5e-5 \
  --dropout 0.01 \
  --lambda_prop 0.3 \
  --lambda_outcome 0.05 \
  --random_seed 2025 \
  --kfold 5 \
  --fold 0

This command trains one fold. Change --fold from 0 to 4 for the five folds, or use the bundled runners below to execute a complete command manifest.

Outputs

Per-run logs are written to log/<model>/, model checkpoints to model/<model>/, and runner summaries to CSV files under log/. These generated artifacts are intentionally excluded from version control.

Code Credits

Part of this codebase is adapted from and extended upon HawkesKT, the official implementation of Temporal Cross-Effects in Knowledge Tracing (WSDM 2021). We thank the original authors for their open-source contribution.

Citation

If you use this code, please cite:

Hint-Conditioned Knowledge Tracing: A Causal-Inspired View of Context-Dependent Hint Usage. IEEE International Conference on Data Mining (ICDM), 2026.

The complete BibTeX entry should be taken from the final proceedings record.