README.md

---
license: cc-by-nc-4.0
base_model: Qwen/Qwen2.5-7B-Instruct
language:
  - en
  - zh
pipeline_tag: text-generation
library_name: peft
tags:
  - hypernetwork
  - hyper-lora
  - lora
  - role-play
  - character-impersonation
  - persona
  - dialogue
  - phase-tree
datasets:
  - IAAR-Shanghai/phase_tree_data
---

# 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:

```bash
# 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`](https://huggingface.co/Qwen/Qwen2.5-7B-Instruct).
The hyper-LoRA and pretrained-hypermod checkpoints additionally use
[`Qwen/Qwen3-Embedding-4B`](https://huggingface.co/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.