IAAR-Shanghai/phase_tree_models

PHASE-Tree Models

     

Released model checkpoints for the PHASE-Tree project (Psychology-grounded Hierarchical Attribute-Structured Evolving Tree).

Please [cite this work](#citation) if you use these models for training, comparison, evaluation, or any other research purpose.

🔗 Resources:

• —📄 Paper: arXiv:2608.06975
• —📦 GitHub Repository: MemTensor/PHASE-Tree (code & documentation)
• —📊 Dataset: IAAR-Shanghai/LongEvoRoleBench
• —🤖 These Models: IAAR-Shanghai/phase_tree_models
• —📈 Results: Mathematics-Yang/phase_tree_results

Download

The PHASE-Tree codebase expects these checkpoints under PHASE-Tree/phase_tree_models/. The recommended way to obtain a working copy is therefore:

# From the repository root (i.e. inside the cloned PHASE-Tree project):
cd PHASE-Tree
hf download IAAR-Shanghai/phase_tree_models --local-dir phase_tree_models

This places every file under PHASE-Tree/phase_tree_models/, matching the relative paths used by every script in the codebase (e.g. phase_tree_models/sft/hyper_lora/hypermod.pt).

Alternative methods:

• —git clone https://huggingface.co/IAAR-Shanghai/phase_tree_models (run from the PHASE-Tree/ root; clones into phase_tree_models/ automatically).
• —Programmatic via huggingface_hub.snapshot_download(...) with local_dir="phase_tree_models".

This release contains the single recommended checkpoint for each of the two stages in the PHASE-Tree training pipeline. During development we ran a larger ablation grid (six hyper-LoRA SFT runs covering warm-start vs cold-start initialisation, two learning rates, and trainable vs frozen hypernet output heads, plus a separate One-PEFT-Per-User / OPPU baseline sweep). Only the checkpoints reported in the paper are bundled here; the ablations are kept locally for reproducibility but are not part of the release.

Layout

Each leaf folder is self-describing via its own README.md.

Recommended Checkpoint

For character-conditioned generation, load:

sft/hyper_lora/hypermod.pt

The pretrained hypermod (phase_tree_pretrained/hypermod.pt) is the upstream warm-start dependency of this anchor run, not an independently usable inference model. It is included so the training pipeline can be reproduced end-to-end.

phase_tree_pretrained/hypermod.pt   ──warm-start──▶   sft/hyper_lora/hypermod.pt
       (pretraining stage)                                  (anchor SFT, recommended)

Why a single SFT checkpoint?

Six hyper-LoRA SFT runs were trained during development, varying initialisation, learning rate, and whether the hypernet output heads are trainable. The released sft/hyper_lora/ is the cell selected by the LLM-as-judge character and semantic ratings together with Qwen3-Embedding-4B response-vs-reference cosine similarity on a held-out evaluation set; the other five cells are ablations and are not bundled.

Per-step intermediate checkpoints (it_5000 … it_40000) and the full post-hoc evaluation artefacts (eval_ckpt_judge_scores/, eval_ckpt_val_loss/) are likewise not bundled. To regenerate them you would need to re-run training (src/scripts/train_phase_tree_qwen_7b.sh) followed by the evaluation scripts under src/scripts/.

Base Model

All checkpoints are trained on top of `Qwen/Qwen2.5-7B-Instruct`. The hyper-LoRA and pretrained-hypermod checkpoints additionally use `Qwen/Qwen3-Embedding-4B` as the task-embedding encoder.

Loading

The hypermod loader expects a checkpoint directory layout identical to the one used here (hypermod.pt + sibling args.yaml + adapter_config.json). It reads the architecture from args.yaml automatically; no extra configuration is required at inference time.

Intended Use

These checkpoints are released as research artefacts for evaluating personalised and hypernetwork-based approaches to character-grounded dialogue generation. They are not intended for production user-facing applications without additional safety filtering.

Citation

If you use these models for training, comparison, evaluation, or any other research purpose, please cite:

@misc{tang2026phasetree,
  title         = {PHASE-Tree: Modeling Character-State Evolution in Long-Horizon Role-Playing Dialogue},
  author        = {Bo Tang and Jianan Yang and Junyi Zhu and Yiquan Wu and Rui Zhao and Zhengyu Yang and Yang Zhang and Feiyu Xiong and Zhiyu Li and Jiajun Shen},
  year          = {2026},
  eprint        = {2608.06975},
  archivePrefix = {arXiv},
  primaryClass  = {cs.CL},
  url           = {https://arxiv.org/abs/2608.06975},
}