IAAR-Shanghai/phase_tree_models

PHASE-Tree Models

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

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

Path	Description
phase_tree_pretrained/	Hypernetwork pretrained on the PHASE-Tree character corpus. Used as the warm-start initialisation for the SFT run below.
sft/hyper_lora/	The anchor hyper-LoRA SFT run (warm-start, lr=5e-6, trainable heads). This is the checkpoint reported in the PHASE-Tree paper.

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

Checkpoint	Loader
Pretrained hypermod (phase_tree_pretrained/)	hyper_llm_modulator.hyper_modulator.load_hypermod_checkpoint(...)
Hyper-LoRA SFT (sft/hyper_lora/)	hyper_llm_modulator.hyper_modulator.load_hypermod_checkpoint(...)

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.