Reason in a discrete Physical Language first, render video second

The checkpoint layout tells you the architecture

PhiZero is described as a world model that reasons about future dynamics in a discrete Physical Language before rendering that reasoning as video. Seven authors are credited on the project page, and the paper sits on arXiv.

The repository layout is more informative than the prose. The ckpt/ directory holds two things: reasoner/, described as the Physical Language Reasoner checkpoint, and tokenizer/, containing tokenizer.safetensors and model_config.json. That safetensors file is not only a tokenizer: it also carries the conditioner and the DiT LoRA, and further on the context tail for the inverse FSQ. model_config.json is described as the checkpoint architecture.

The reasoner side therefore holds what learned dynamics, and the tokenizer side holds the discrete language plus the rendering adapter. Anyone reading the tree can see that the model is a reasoner feeding a video decoder rather than one monolithic model, and that the vocabulary was trained rather than hard-coded.

One file ordering requirement follows from that: model_config.json has to stay beside tokenizer.safetensors, because the decoder reads the architecture from it.

Two conda environments that cannot be merged

The installation reproduces the Linux x86-64 and CUDA 12.4 stack used for the released result, from environment files checked into the repository, and you point PHIZERO_CONDA at your Miniconda install:

PHIZERO_CONDA=/path/to/miniconda3/bin/conda

There are two environments, phizero-reasoner and phizero-decoder, each built from its own yml file plus a matching requirements file. The reasoner one imports PhysicalLanguageReasoner from swift.infer_engine, which is the training framework's inference module.

Both then build FlashAttention from source, with the same command in each:

PIP_CACHE_DIR=/tmp/phizero-pip-cache CUDA_HOME=/usr/local/cuda MAX_JOBS=8 \
  FLASH_ATTENTION_FORCE_BUILD=TRUE FLASH_ATTN_CUDA_ARCHS=80 \
  "${PHIZERO_CONDA}" run -n phizero-reasoner \
  python -m pip install --no-deps --no-build-isolation --no-binary flash-attn \
  "flash-attn==2.8.3"

The flags are the point. --no-deps and --no-build-isolation stop pip from resolving anything else, and building locally is what links flash-attn against the exact PyTorch ABI installed in that environment, which is why one wheel will not serve both.

Two hardware notes: CUDA_HOME must contain bin/nvcc, and FLASH_ATTN_CUDA_ARCHS=80 targets A100 while 90 targets H100. The reasoner trainer pins DeepSpeed 0.18.9, the same version used for the original full-SFT run.

The frozen Wan2.2 base model is not in the checkpoint

This is the fact most likely to catch someone out who reads the release announcement and starts downloading. The PhiZero tokenizer checkpoint contains the Physical Language modules and the rendering LoRA, but not the frozen base model. The Wan2.2-TI2V-5B weights come separately:

mkdir -p ckpt/wan2.2-ti2v-5b ckpt/wan2.2-vae

hf download Wan-AI/Wan2.2-TI2V-5B \
  --include 'diffusion_pytorch_model-*.safetensors' \
  --local-dir ckpt/wan2.2-ti2v-5b

Three DiT shards and one VAE, about 20 GB and about 1.4 GB respectively. The decoder environment already installs both the hf and the modelscope CLIs, which is why the VAE can be pulled from the DiffSynth-converted safetensors repository instead of the original release.

Then point the launchers at the local files:

export PHIZERO_VAE_PATH="${PWD}/ckpt/wan2.2-vae/Wan2.2_VAE.safetensors"

with PHIZERO_DIT_PATHS taking the same form for the three shards. If both variables are unset, DiffSynth resolves the same base models automatically, so the explicit paths are optional, and the README gives their reason: explicit local paths make offline and repeated runs reproducible. The same decoder environment also carries everything the video-only trainer and the Physical Language ground truth exporter need, so there is no third environment.

Five training steps, and step 2 is invalidated by a change in step 1

The training order is a dependency chain rather than a menu. First, train or fine-tune the Physical Language Tokenizer on videos. Second, freeze that tokenizer and extract Physical Language ground truth from captioned videos. Third, train the Physical Language Reasoner on the exported first-frame, caption and ground truth JSONL. Fourth, before cross-domain motion transfer, adapt the tokenizer and decoder on videos from the source-motion domain. Fifth, run reason-then-render inference, reconstruction or motion transfer.

The constraint that ties them together is stated once and it is strict: Physical Language targets must always be regenerated after changing the tokenizer used for a reasoner run. In practice this means the ground truth in step 2 is derived data, and a tokenizer tweak invalidates every reasoner checkpoint trained on it.

The tokenizer's own training input is plain CSV with one required column, video, holding absolute paths or paths relative to the CSV directory. Each clip is expected to be 4 seconds at 8 FPS, and the loader takes the first 33 frames and deterministically resizes them to 896x512, so the frame count and resolution are fixed by the loader rather than by your data.

There is also examples/PROMPT_GUIDANCE.txt in the repository, which is the file to read before writing reason-then-render prompts.

The examples directory is named by task, not by algorithm

Seven shell launchers sit in examples/, and each one wraps a set of cases from the paper. run_inference_cases.sh launches the 19 inference examples. run_motion_transfer.sh launches 11 transfer examples. run_motion_transfer_adaptation.sh covers source-only reconstruction adaptation, the step where a model is adapted to the source-motion domain before cross-domain transfer. run_reconstruction.sh launches 6 reconstruction examples, though the sentence describing it is cut off partway in the copy of the README available here.

The remaining three are pipeline stages rather than result sets: run_training.sh, run_reasoner_training.sh and run_physical_language_gt.sh for tokenizer training, reasoner training and ground truth export.

Reading the names in order gives you the paper's structure without opening the PDF: cases, transfer, adaptation, reconstruction, then the three training entry points. There is also a benchmarks/ directory at the root, which is where a comparison against other world models would live.

The tree also contains DiffSynth-Studio/ and ms-swift/ as directories, meaning both frameworks are vendored rather than installed from an index. That is consistent with the swift.infer_engine import and the pinned DeepSpeed version, and it is why a checkout is larger than a typical research repository.

Check the environments the way the README checks them

The verification step is documented rather than left to the reader, and it is worth copying because a broken flash-attn build produces import errors far from the cause.

For the reasoner, pip check followed by an import probe of deepspeed, flash_attn, torch and transformers together with PhysicalLanguageReasoner from swift.infer_engine, printing each version. For the decoder, the same pip check with DIFFSYNTH_ATTENTION_IMPLEMENTATION=flash_attention_2 in front of the command, so DiffSynth selects the same attention path it will use at run time rather than the library default.

The README states that both environments passed pip check and reproduced the released inference path. That is the bar to hold your own install to: if pip check fails, or flash_attn imports from a wheel that was never linked against your PyTorch, something upstream of your code is already wrong.

Nothing about this is automated for you. The commands are long enough that a typo in an environment variable name, which is what MAX_JOBS and the two FLASH_ATTENTION variables are, produces a build failure rather than a warning.

Versioning is by checkpoint and paper, not by release

There are no GitHub releases, so there is nothing to pin a dependency to. The artifacts are the checkpoints, which are hosted as a HuggingFace model repository rather than attached to the code:

hf download ShuyaoShang/PhiZero --local-dir ckpt

That single command produces the layout every training and inference entry point expects, with ckpt/reasoner and ckpt/tokenizer/tokenizer.safetensors appearing in the right places, and model_config.json landing beside the tokenizer file.

The last push was on 2026-08-29, and the repository description still reads as a promise that code and checkpoints are coming soon, which is a reminder that the surrounding text was written before the artifacts landed. What is in the tree today is a research release with a documented environment, documented checkpoints and documented example cases.

On licensing, a LICENSE file exists at the root, but neither the README nor the repository metadata names the licence, and this is a project built on Wan2.2 weights plus two vendored frameworks. Read that file before you build anything commercial on top of it.

Editorial conclusion

Adopt PhiZero if you are reproducing the paper's inference cases, since the checkpoint layout, the two environments and the frozen Wan2.2 base are all pinned to one Linux x86-64 and CUDA 12.4 stack that is documented as reproducing the released result. Do not adopt it as a turnkey library on a laptop, and read the licence file yourself because the README does not name one. Verify first that your GPU matches FLASH_ATTN_CUDA_ARCHS, since 80 targets A100 and 90 targets H100, and that the two environments build flash-attn from source rather than reusing a wheel.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. yaoyao-jpg/PhiZero on GitHub